Skip to content

启动参数与配置文件 ​

命令行参数 ​

bash
deploy-server -listen 127.0.0.1:10055 -data-dir /srv/deploy/data -web-root /srv/deploy/workspaces
参数说明默认值
-config配置文件路径;显式指定但文件不存在时直接报错退出自动查找(见下节)
-listenHTTP 监听地址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.0

dataDir 与 webRoot 启动时会解析为绝对路径,避免后续工作目录变化导致错位。

配置文件查找顺序与优先级 ​

YAML 配置文件按以下顺序查找,命中第一个即停止:

  1. -config 显式指定的路径(不存在则报错,不会回落);
  2. 当前目录下的 ./deploy-server.yaml;
  3. <dataDir>/deploy-server.yaml(dataDir 先由参数/环境变量确定,再找文件)。

四层合并,后一层覆盖前一层:

text
默认值 → 配置文件 → 环境变量 → 命令行参数

注意:命令行参数只有 -listen/-data-dir/-web-root/-server-url 四个能覆盖 配置文件的对应项;其余配置项只能走文件或环境变量。

全部配置项 ​

配置项(YAML)默认值说明环境变量
listen127.0.0.1:10055监听地址DEPLOY_LISTEN
dataDirdata数据目录,必须可写DEPLOY_DATA_DIR
webRootworkspaces工作区默认根DEPLOY_WEB_ROOT
serverUrl由 listen 推导对外地址启动默认值DEPLOY_SERVER_URL
jwtSecret空(自动生成)JWT 签名密钥;空则读/建 data/jwt.keyDEPLOY_JWT_SECRET
secretKey空(自动生成)AES-GCM 加密密钥;空则读/建 data/secret.keyDEPLOY_SECRET_KEY
tokenTtlHours168(7 天)登录 JWT 有效期—
maxConcurrentRuns5全局并发运行上限DEPLOY_MAX_CONCURRENT_RUNS
logRetentionDays30运行记录与日志保留天数,0 表示不清理—
logMaxBytes104857600(100MB)单次运行日志大小上限—
hookRateLimitPerMinute60每个 Hook 每分钟触发上限—
visibilityallReadableallReadable / ownerOnly,见 03DEPLOY_VISIBILITY
allowRegistrationfalse预留项,当前版本无自助注册接口—
gitPrepareTimeoutSec600Git 准备阶段超时(秒)—
shellauto脚本解释器偏好: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 部署与反向代理。