CICD 自动打包部署平台

切换主题

配置详解 ​

CICD 平台有三份配置文件，分别对应三个组件：

组件配置文件主要配置内容
管理端 cicd_serverbackend/config.yamlHTTP 服务、MySQL、鉴权与加密、调度、产物、存储、集群、Webhook、日志
执行端 cicd_agentagent/config.yaml管理端连接、本机工作目录、Git 密钥、构建工具路径、日志
部署节点 cicd_nodenode/config.yaml管理端连接、本机暂存目录、日志

三端都用 -c 指定配置文件路径，未指定时取当前目录的 config.yaml。安装与运行方式见 安装部署，跑通流程见 快速开始。

通用规则 ​

路径相对解析 ​

组件相对路径的基准目录
管理端agent.relayDir、artifact.dir 相对进程工作目录解析
执行端agent.workDir、agent.workspaceRoot、agent.gitKeyRoot 相对配置文件所在目录解析
部署节点node.workDir、node.tempDir 相对配置文件所在目录解析

执行端/部署节点统一按配置文件所在目录解析相对路径，避免系统服务模式下工作目录差异导致找不到工作目录。绝对路径原样使用。

环境变量覆盖（仅管理端） ​

管理端在读取 config.yaml 后会用以下环境变量覆盖对应键，适合在配置文件中写占位符、只把密钥放进环境变量：

环境变量覆盖的配置键
CICD_JWT_SECRETauth.jwtSecret
CICD_ENCRYPT_KEYauth.encryptKey
CICD_DB_PASSWORDdb.mysql.password
CICD_S3_ACCESS_KEYstorage.s3.accessKey
CICD_S3_SECRET_KEYstorage.s3.secretKey

此外，系统服务模式下的服务根目录由 CICD_SERVER_ROOT（管理端）/ CICD_AGENT_ROOT（执行端）/ CICD_NODE_ROOT（部署节点）指定。执行端与部署节点不做环境变量覆盖，密钥直接写在各自的 config.yaml。

敏感值加密存储 ​

  • 数据库中的敏感字段采用字段级 AES-GCM 加密，JSON 内以 enc:v1:<base64> 密文形式保存；密钥来自 auth.encryptKey（必须 32 字节）。
  • 前端接口永不回显密文；未修改敏感字段时提交 null 表示保留原值。
  • 执行端仅在内存中持有凭据明文，禁止写入本地日志与磁盘；日志输出对 password 等键做掩码。
  • masked=true 的任务变量在库中为密文，接口不回显，落库日志与任务日志前替换为 ******。
  • 生产环境务必修改 auth.jwtSecret 与 auth.encryptKey，并改用环境变量注入。

一、管理端 backend/config.yaml ​

server ​

键含义默认值说明
address监听地址0.0.0.0——
port监听端口（字符串）9866Web 控制台与 API 端口
gzip是否启用 gziptrueSSE 与下载接口不压缩
baseUrl对外访问地址""用于通知中的任务链接与项目 Webhook 端点地址；留空时按监听地址推断（0.0.0.0 视为 127.0.0.1，通常是内网地址，Git 平台/IM 客户端访问不到）。末尾不要带 /；反向代理/公网访问需显式配置，如 https://cicd.example.com

db.mysql ​

键含义默认值说明
hostMySQL 地址127.0.0.1——
portMySQL 端口3306——
user用户名无——
password密码""可用 CICD_DB_PASSWORD 覆盖
database数据库名cicd需提前创建，建议 utf8mb4
charset字符集utf8mb4——
maxOpenConns最大打开连接数20——
maxIdleConns最大空闲连接数5——
paramsDSN 参数parseTime=true&loc=Local&timeout=5s&readTimeout=10sparseTime=true 必需（时间列为 DATETIME）；程序会强制补齐 parseTime=true 与 loc=Local，但建议显式写全
dsn完整 DSN""非空时忽略以上字段

db.mysql 未配置 host/database 且未配 dsn 时启动报错。程序不会自动建表，需先执行 backend/mysql_schema.sql。

auth ​

键含义默认值说明
jwtSecretJWT 签名密钥无（必填）生产用 CICD_JWT_SECRET 注入；为空启动报错
tokenExpireHours登录 Token 有效期（小时）12<=0 时取 12
encryptKey凭据加密密钥无（必填）必须为 32 字节，用于 AES-256-GCM；长度不符启动报错；生产用 CICD_ENCRYPT_KEY 注入
scopeCacheSeconds数据权限本地缓存秒数00 表示不缓存。缓存为进程内缓存，集群下授权变更只能失效本实例，故默认关闭；单实例部署可设 30 省掉权限点查询
maxLoginFailures连续登录失败锁定阈值5达到该次数即锁定账号；显式配 0 表示关闭该策略（负数按 0 处理）
loginLockMinutes账号锁定时长（分钟）30到点自动解锁并从 0 重新计数；<=0 时取 30

管理员可在「用户管理 → 登录状态 → 解锁」提前放行被锁账号。

agent（执行机与调度） ​

键含义默认值说明
heartbeatTimeoutSeconds心跳超时（秒）30超过视为离线。执行端心跳 10s，容错 3 次丢包；离线由 5s 一轮的巡检收敛，最坏约 35s 反映到列表
commandWaitSeconds长轮询挂起时长（秒）25<=0 时取 25
commandExpireMinutes指令超时（分钟）10超时未 ack 的指令置 expired
taskRetentionDays任务与日志保留天数300 表示不清理
logRetentionDays日志分片额外保留天数0兜底清理，0 表示不清理
probeTimeoutSeconds同步探测等待（秒）45<=0 时取 45
dispatchIntervalSeconds队列派发扫描间隔（秒）1<=0 时取 1
dispatchBatchSize单轮最多派发的任务数50<=0 时取 50
queueLimit全局排队上限50超出时新触发直接失败并提示「队列已满」；<=0 时取 50
relayDir部署节点中转产物落盘目录work/relay相对进程工作目录；storage.relay=s3 时不使用
relayTimeoutSeconds执行机等待部署节点完成单阶段超时（秒）600<=0 时取 600
relayRetentionMinutes中转产物保留时长（分钟）180超过后由巡检清理（含磁盘文件）

artifact（任务产物归档） ​

键含义默认值说明
dir归档落盘目录work/artifacts相对进程工作目录，按 项目ID/任务ID 分层；storage.artifact=s3 时不使用
retentionDays保留天数30超过后由巡检清理（含磁盘文件）；<=0 时按 30 处理（无法通过配 0 关闭清理）
maxTaskBytes单任务产物总量上限（字节）2147483648（2GB）超出后拒绝上传（413），任务本身不受影响；<=0 不限制
maxTotalBytes全部产物总量上限（字节）21474836480（20GB）超出后按最旧优先回收；<=0 不限制

storage（产物存储后端） ​

键含义默认值说明
artifact任务产物归档写入后端locallocal（本机磁盘）| s3（对象存储）；填写其它值启动报错
relay部署中转产物写入后端local同上
s3.endpoint自定义端点""MinIO/OSS 等兼容服务；留空用 AWS 官方端点
s3.region区域""如 ap-east-1；兼容服务填任意非空值（如 us-east-1）
s3.bucket存储桶""选择 s3 时必填
s3.accessKey访问密钥""可用 CICD_S3_ACCESS_KEY 覆盖；选择 s3 时必填
s3.secretKey访问密钥""可用 CICD_S3_SECRET_KEY 覆盖；选择 s3 时必填
s3.sessionToken临时凭据会话令牌""可选
s3.prefix对象键前缀""可选，如 cicd，便于与其他数据共用同一存储桶
s3.pathStyle按路径寻址falseMinIO 等自建服务通常需要 true

DB 中保存的引用以 s3:// 开头即表示对象存储，其余按本机路径处理，因此两种后端可以共存——切换后端后历史产物仍可下载与清理。选择 s3 时必须在 storage.s3 中配置 bucket、accessKey 与 secretKey，否则启动报错。

cluster（管理端多实例） ​

键含义默认值说明
leaseSeconds领导者租约时长（秒）30多实例下仅领导者执行派发与巡检；本实例按 1/3 租约续期，进程异常退出到其它实例接管不超过该时长
instanceId实例标识""租约 holder、实例注册用，多实例下必须全局唯一；留空用「主机名-IP-端口」派生（重启不变、可区分同名主机）。IP 会变（DHCP/容器重建）或想更直观时显式指定，如 node-1
ip本实例对外 IP""注册到 cluster_instance 供「集群信息」页展示，同时参与实例标识派生；留空自动探测（优先默认路由出口地址）。NAT/多出口/VPN 建议显式配置

多实例前提

各实例必须共享同一 MySQL；auth.jwtSecret / auth.encryptKey 各实例必须完全一致；产物存储请改用对象存储（storage.artifact/relay=s3），否则跨实例下载会 404。租约表 cluster_leader 缺失时自动退化为单实例模式。健康检查：GET /api/health 为存活探针（额外回报 version 服务版本号，前端据此展示），GET /api/ready 为就绪探针（数据库不可用或实例退出时 503），负载均衡请用 /api/ready。

webhook ​

键含义默认值说明
limitPerMinute单项目每分钟投递上限120超出返回 429；<=0 时取 120
maxBodyKB请求体上限（KB）1024<=0 时取 1024
debounceSeconds默认防抖窗口（秒）5项目配置可覆盖；<=0 时取 5
deliveryRetentionDays投递记录保留天数300 表示不清理

log ​

键含义默认值说明
level日志级别infodebug | info | warn | error
max-size单个日志文件上限（MB）64输出到 logs/app.log（部署=程序目录；go run=配置文件所在目录）
max-backups保留的历史日志文件数7——
max-age历史日志保留天数30——
level-files按级别输出到独立文件无可选；默认仅 app.log
yaml
log:
  level: "info"
  max-size: 64
  max-backups: 7
  max-age: 30
  # 可选：按级别输出到独立文件
  # level-files:
  #   - level: "warn"
  #     filename: "app-warn.log"
  #   - level: "error"
  #     filename: "app-error.log"

二、执行端 agent/config.yaml ​

server ​

键含义默认值说明
url管理端地址http://127.0.0.1:9866必填；如 http://127.0.0.1:9866，用 https 时管理端需配置证书
token执行机令牌无（必填）管理端「执行机」页面新建后复制，仅展示一次；与执行机记录绑定，重置后需同步更新并重启
insecureSkipVerify跳过 TLS 校验false管理端使用 HTTPS 自签证书时置 true
timeoutSecondsHTTP 请求超时（秒）30<=0 时取 30

agent ​

键含义默认值说明
name执行机名称主机名建议与管理端执行机记录同名，便于识别
ip注册上报的本机 IP""留空自动探测（优先默认路由出口地址，可避开虚拟网卡）；NAT/多出口/VPN 建议显式指定
labels调度标签无示例 ["java", "frontend", "maven"]；覆盖注册时上报的默认值
capacity本机最大并发任务数1超出则任务排队（不派发到本机）；<=0 时取 1
heartbeatSeconds心跳间隔（秒）10<=0 时取 10
workDir构建产物与临时归档目录work相对配置文件所在目录
workspaceRoot项目工作目录根workspace每个项目一个子目录，目录名固定为项目 ID；可填绝对路径，相对路径按配置文件所在目录解析
workspaceTtlDays工作目录兜底清理天数00 表示不自动清理
gitKeyRootGit 密钥与 known_hosts 存放根目录gitkeys相对配置文件所在目录
gitKeyType自建 Git 密钥算法ssh-ed25519ssh-ed25519 | ssh-rsa；其它值启动报错
gitPathgit 可执行文件git默认走 PATH
gitCloneDepth默认浅克隆深度10 表示完整克隆
javaHomeJDK 安装目录""本机环境默认值，供探测与兜底
mavenPathMaven 可执行文件""供探测与兜底；项目侧不再单独配置 mvn 路径
goPathgo 可执行文件（或 GOROOT/bin 目录）""留空走 PATH
nodePathnode 可执行文件""留空走 PATH
npmPathnpm 可执行文件""留空走 PATH
dockerPathdocker 可执行文件""留空走 PATH
hbuilderxPathHBuilderX 安装目录""目录内含 cli（Linux）/ cli.exe（Windows）；主要用于环境探测，App 云打包的 cli 路径优先取项目引用的 HBuilderX 环境资源
maxLogLineBytes单行日志截断上限（字节）8192<=0 时取 8192

执行端自建 Git 密钥的私钥仅存于本机（{gitKeyRoot} 下，权限 0600），上报给管理端的只有公钥与指纹。

log ​

与管理端 log 段一致：level / max-size / max-backups / max-age，默认 info / 64 / 7 / 30，输出到 logs/app.log。

三、部署节点 node/config.yaml ​

部署节点与管理端复用同一套接入链路（注册 / 心跳 / 长轮询），因此 server 段与执行端同构，本机参数只有产物暂存目录。

server ​

键含义默认值说明
url管理端地址http://127.0.0.1:9866必填
token节点令牌无（必填）管理端「执行机 → 部署节点」新建后复制，仅展示一次；重置后需同步更新并重启节点进程
insecureSkipVerify跳过 TLS 校验false管理端使用 HTTPS 自签证书时置 true
timeoutSecondsHTTP 请求超时（秒）30<=0 时取 30

node ​

键含义默认值说明
name节点名称主机名建议与管理端部署节点名称一致，便于识别
ip注册上报的本机 IP""留空自动探测；NAT/多出口/VPN 建议显式指定
labels标签无示例 ["prod", "web"]；供筛选与展示
heartbeatSeconds心跳间隔（秒）10<=0 时取 10
workDir节点工作目录（中转产物下载与暂存）work相对配置文件所在目录
tempDir部署暂存目录""留空取 {workDir}/tmp

log ​

与执行端一致：level / max-size / max-backups / max-age，默认 info / 64 / 7 / 30。

节点删除前需先解除目标机绑定（target_server.mode=node）；重置令牌后需同步更新节点 config.yaml 并重启节点进程。执行端/部署节点不监听任何端口，仅主动出站连接管理端。

相关 ​

Copyright © 2024-2026