主题
启动参数与配置文件
命令行参数
bash
deploy-server -listen 127.0.0.1:10055 -data-dir /srv/deploy/data -web-root /srv/deploy/workspaces| 参数 | 说明 | 默认值 |
|---|---|---|
-config | 配置文件路径;显式指定但文件不存在时直接报错退出 | 自动查找(见下节) |
-listen | HTTP 监听地址 | 127.0.0.1:10055 |
-data-dir | 数据目录:数据库、日志、密钥 | data(相对当前目录) |
-web-root | 项目工作目录默认根,脚本里用 ${WORKSPACE_ROOT} 引用 | workspaces |
-server-url | 对外地址的启动默认值,注入给脚本的 DEPLOY_SERVER_URL | 由 listen 推导 |
版本查询不加载配置,可在任何环境下直接调用(打包脚本、容器探针都可用):
bash
deploy-server version # 也接受 -v 与 --version
# deploy-server 0.1.0dataDir 与 webRoot 启动时会解析为绝对路径,避免后续工作目录变化导致错位。
配置文件查找顺序与优先级
YAML 配置文件按以下顺序查找,命中第一个即停止:
-config显式指定的路径(不存在则报错,不会回落);- 当前目录下的
./deploy-server.yaml; <dataDir>/deploy-server.yaml(dataDir 先由参数/环境变量确定,再找文件)。
四层合并,后一层覆盖前一层:
text
默认值 → 配置文件 → 环境变量 → 命令行参数注意:命令行参数只有 -listen/-data-dir/-web-root/-server-url 四个能覆盖 配置文件的对应项;其余配置项只能走文件或环境变量。
全部配置项
| 配置项(YAML) | 默认值 | 说明 | 环境变量 |
|---|---|---|---|
listen | 127.0.0.1:10055 | 监听地址 | DEPLOY_LISTEN |
dataDir | data | 数据目录,必须可写 | DEPLOY_DATA_DIR |
webRoot | workspaces | 工作区默认根 | DEPLOY_WEB_ROOT |
serverUrl | 由 listen 推导 | 对外地址启动默认值 | DEPLOY_SERVER_URL |
jwtSecret | 空(自动生成) | JWT 签名密钥;空则读/建 data/jwt.key | DEPLOY_JWT_SECRET |
secretKey | 空(自动生成) | AES-GCM 加密密钥;空则读/建 data/secret.key | DEPLOY_SECRET_KEY |
tokenTtlHours | 168(7 天) | 登录 JWT 有效期 | — |
maxConcurrentRuns | 5 | 全局并发运行上限 | DEPLOY_MAX_CONCURRENT_RUNS |
logRetentionDays | 30 | 运行记录与日志保留天数,0 表示不清理 | — |
logMaxBytes | 104857600(100MB) | 单次运行日志大小上限 | — |
hookRateLimitPerMinute | 60 | 每个 Hook 每分钟触发上限 | — |
visibility | allReadable | allReadable / ownerOnly,见 03 | DEPLOY_VISIBILITY |
allowRegistration | false | 预留项,当前版本无自助注册接口 | — |
gitPrepareTimeoutSec | 600 | Git 准备阶段超时(秒) | — |
shell | auto | 脚本解释器偏好:auto/bash/sh/pwsh/cmd | — |
另有环境变量 DEPLOY_LOG_LEVEL=debug 可开启服务端自身的调试日志 (仅识别 debug,其余值一律按 info 处理),它不是 YAML 配置项。
非法值会被归一化:数值项 <=0 回退默认值(logRetentionDays 例外,负数归零), visibility 非法时回退 allReadable。密钥文件权限 0600,目录 0750。
配置文件示例:
yaml
listen: 127.0.0.1:10055
dataDir: /srv/deploy/data
webRoot: /srv/deploy/workspaces
serverUrl: https://deploy.example.com
maxConcurrentRuns: 5
logRetentionDays: 30
visibility: allReadable
shell: auto不建议把 jwtSecret/secretKey 明文写进配置文件,留空让服务端生成 独立密钥文件更安全,详见 02 数据目录与日志存储。
serverUrl 与 DEPLOY_SERVER_URL 注入
serverUrl 只是启动默认值:未显式配置时按监听地址推导为 http://<listen>;监听 0.0.0.0 或 [::] 时退化为 http://127.0.0.1:<端口> (脚本本机回连可用,真正对外地址请管理员补填)。
生效值 = 系统设置里的 serverUrl(存数据库)优先,未设置才用启动默认值。 每次运行都重新读取,因此:
- 在系统设置页修改后,对变量预览与后续运行立即生效,无需重启;
- 设置页留空表示回退到启动配置(
-server-url/DEPLOY_SERVER_URL/ 配置文件); - 必须是绝对 http(s) URL,结尾
/会被去掉,避免脚本拼出双斜杠。
该值以 DEPLOY_SERVER_URL 环境变量注入项目脚本,常用于健康检查回连、 生成回调地址等。项目级变量见环境变量与 Secret。
哪些项热生效,哪些要重启
系统设置页(admin)可热改的项,存数据库并覆盖启动配置:
| 项 | 热生效方式 |
|---|---|
serverUrl | 每次运行重新读取 |
maxConcurrentRuns | 直接调整并发闸门,范围 1–100 |
logRetentionDays | 清理任务每轮读取 |
logMaxBytes | 每次运行创建日志写入器时读取 |
hookRateLimitPerMinute | 每次 Hook 触发时读取 |
visibility | 每次权限判断时读取 |
| 通知设置(notify) | 每次运行结束时读取 |
必须改配置文件/参数并重启的项:listen、dataDir、webRoot、shell、 tokenTtlHours、jwtSecret、secretKey、gitPrepareTimeoutSec、 allowRegistration。这是有意设计:影响进程本身的配置不允许在页面上改, 避免「设置显示 A、进程实际跑在 B」的错位。
监听地址的安全建议与反代配置见 05 systemd 部署与反向代理。