CICD 自动打包部署平台

切换主题

安装部署 ​

本页说明三端组件的安装包获取、数据库初始化、部署目录、启动方式与系统服务托管。运行时无需任何编译，拿到对应平台的二进制即可部署；跑通第一个项目见 快速开始，配置项逐条说明见 配置详解。

平台由三个独立的二进制组件构成：

组件二进制说明
管理端cicd_server唯一的 Web 服务与控制台（前端已嵌入二进制），独占 MySQL；负责配置管理、权限、队列派发、Webhook 与通知
执行端cicd_agent部署在构建机上，主动连接管理端（Token 鉴权 + 长轮询取指令），不连数据库；负责 Git 密钥自建、拉码、构建、上传与远程部署
部署节点cicd_node部署在目标服务器上（可选），同样主动注册并长轮询取指令；部署时由它在本机落地产物，目标机无需开放 SSH

运行环境

运行时只需要 对应平台的二进制 + MySQL，不需要安装 Go 或 Node；管理端已内嵌前端静态资源，无需单独部署 Web 服务。

三端怎么选

管理端必装、全局唯一；执行端至少一台（构建机，负责拉码与构建）；部署节点可选，仅当希望目标机免开 SSH、由目标机自己从管理端拉取产物落地时安装。

1. 环境要求 ​

依赖版本用途
操作系统Linux / Windows / macOS（amd64、arm64）运行三端二进制
MySQL5.7 / 8.0，字符集需 utf8mb4仅管理端使用
浏览器现代浏览器（Chrome / Edge / Firefox 等）访问管理控制台

2. 获取安装包 ​

发行产物为按平台交叉编译好的二进制，命名规则为 <组件>_<os>_<arch>[.exe]：

平台管理端执行端部署节点
Windows x64cicd_server_windows_amd64.execicd_agent_windows_amd64.execicd_node_windows_amd64.exe
Linux x64cicd_server_linux_amd64cicd_agent_linux_amd64cicd_node_linux_amd64
Linux ARM64cicd_server_linux_arm64cicd_agent_linux_arm64cicd_node_linux_arm64
macOS Intelcicd_server_darwin_amd64cicd_agent_darwin_amd64cicd_node_darwin_amd64
macOS Apple Siliconcicd_server_darwin_arm64cicd_agent_darwin_arm64cicd_node_darwin_arm64

把二进制放到各自的部署目录（三端各一个目录，互不影响），Linux / macOS 下补上可执行权限：

bash
chmod +x cicd_server_linux_amd64

下文命令统一使用重命名后的短名 cicd_server / cicd_agent / cicd_node（Windows 为 .exe）；直接用对应平台的文件名执行亦可。

3. 初始化数据库 ​

数据库由管理端独占。程序不会自动建表，必须先手动执行建表脚本。

3.1 全新安装：mysql_schema.sql ​

先建库：

sql
CREATE DATABASE IF NOT EXISTS cicd DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

再导入建表脚本：

bash
mysql -h<host> -P<port> -u<user> -p <database> < mysql_schema.sql

脚本幂等（CREATE TABLE IF NOT EXISTS），可重复执行。

缺失表会直接启动失败

管理端启动时会校验必需表是否齐全，缺少任意一张表都会直接启动失败并提示缺失的表名与建表命令，不会自动创建：

数据库表结构不完整，缺少 N 张表：...
程序不会自动建表，请先手动执行建表脚本：
  mysql -h<host> -P<port> -u<user> -p <database> < mysql_schema.sql

3.2 已有数据库升级：mysql_upgrade.sql ​

结构变更同样不会自动执行，需手动跑增量脚本：

bash
mysql -h<host> -P<port> -u<user> -p <database> < mysql_upgrade.sql

每条语句只执行一次；若不慎重复执行，报 Duplicate column name 可忽略。

当前增量内容（全新安装无需执行，mysql_schema.sql 已包含以上结构）：

变更不执行的后果
sys_user 增加登录失败锁定所需两列（failed_login_count / locked_until）用户列表与登录接口报 Unknown column
sys_user_scope.permission 注释补充 manage 档位；project.group_id 改为 NOT NULL（先创建「默认分组」并把历史未分组项目归入其中）新建/编辑项目与导入会因 group_id 约束失败或行为不一致
project 唯一键由 uk_project_name (name) 改为 uk_project_group_id_name (group_id, name)（项目名称改为分组内唯一）项目名称仍受旧的全局唯一键限制，不同分组下无法创建同名项目
新增 task_artifact 表（任务产物归档）上传产物、项目详情与产物下载报 Table 'cicd.task_artifact' doesn't exist
agent.kind、target_server.mode/node_id、task.target_node_id/target_node_name（部署节点双模式）部署节点相关功能不可用
新增 task_relay_artifact（部署中转产物）、docker_registry（镜像仓库凭据）对应功能不可用
task.status 增加 waiting 与 waiting_at（人工卡点）人工卡点功能不可用
project_group 增加 env / target_ids / notify（分组级任务变量、目标范围、通知）分组相关配置不可用
project_template 增加 quick_start / sort_no 并预置内置快速开始模板新建项目页「快速开始」区域为空
新增 cluster_leader / cluster_instance / cluster_setting 与 agent_command.result（管理端集群）集群表缺失时退化为单实例模式，不阻塞启动
新增 content_template / content_template_group（内容模板）内容模板功能不可用
task.image（Docker 交付的完整镜像引用）Docker 项目任务详情与通知内容中的镜像字段取值缺失

3.3 初始管理员与改密 ​

mysql_schema.sql 末尾已内置初始管理员，执行脚本后即可登录：

项值
用户名admin
密码admin123
角色admin（不受数据权限约束）
  • 该 INSERT 幂等（ON DUPLICATE KEY UPDATE username = username），重复执行脚本不会覆盖已改过的密码。
  • 首次登录后必须立即改密（右上角「修改密码」）。
  • 管理员账号仅由建表脚本写入，程序不会自动初始化账号。

3.4 遗忘管理员密码 ​

用管理端二进制的辅助命令生成新哈希（不连库、不需配置），再手动更新：

bash
cicd_server -hash-password '你的新密码'
# 输出：$2a$10$....
sql
UPDATE sys_user SET password = '$2a$10$....' WHERE username = 'admin';

4. 部署目录与配置 ​

三端各用一个独立目录，二进制与 config.yaml 必须同级：

cicd_server/                     # 管理端部署目录
├── cicd_server_linux_amd64      # 管理端二进制（Windows 为 .exe）
├── config.yaml                  # 管理端配置（见配置详解）
└── logs/app.log                 # 运行日志（首次启动自动创建）

cicd_agent/                      # 执行端部署目录（构建机）
├── cicd_agent_linux_amd64
├── config.yaml
├── logs/app.log
└── data/                        # 工作目录根、构建临时目录、Git 密钥目录（按配置生成）

cicd_node/                       # 部署节点部署目录（目标机，可选）
├── cicd_node_linux_amd64
├── config.yaml
├── logs/app.log
└── node-data/                   # 节点工作目录（临时文件、落地暂存）
  • 配置文件默认取当前工作目录下的 config.yaml，也可用 -c 指定路径。
  • 相对路径的解析基准：管理端按进程工作目录；执行端与部署节点按配置文件所在目录（系统服务方式下同样如此）。

首次部署至少要确认以下配置（完整配置项见 配置详解）：

组件配置项说明
管理端db.mysql.*MySQL 连接；params 必须包含 parseTime=true&loc=Local
管理端auth.jwtSecret / auth.encryptKey生产环境务必修改；encryptKey 必须为 32 字节
管理端server.port / server.baseUrl监听端口（默认 9866）；baseUrl 用于生成通知里的任务链接与 Webhook 端点地址
执行端server.url / server.token管理端地址；执行机令牌，在管理端「执行机」新建后复制（仅展示一次）
执行端agent.workspaceRoot / workDir / gitKeyRoot项目工作目录根、构建临时目录、Git 密钥目录
部署节点server.url / server.token管理端地址；节点令牌，在管理端「执行机 → 部署节点」新建后复制（仅展示一次）
部署节点node.workDir节点工作目录（临时文件、落地暂存），留空相关子项取默认值

敏感配置可用环境变量覆盖：CICD_JWT_SECRET、CICD_ENCRYPT_KEY（管理端）。

5. 启动与系统服务 ​

5.1 前台启动 ​

bash
./cicd_server -c config.yaml
./cicd_agent -c config.yaml
./cicd_node -c config.yaml

Windows 下运行对应 .exe（双击或命令行）。管理端启动后浏览器访问 http://<host>:9866，用 admin / admin123 登录。

5.2 系统服务托管（推荐） ​

三端均内置系统服务管理命令，Windows 下同样支持，命令名一致（服务名分别为 cicd_server / cicd_agent / cicd_node）：

bash
./cicd_server install -c /etc/cicd/config.yaml   # 注册为系统服务
./cicd_server start                              # 启动
./cicd_server stop                               # 停止
./cicd_server restart                            # 重启
./cicd_server status                             # 查看状态
./cicd_server uninstall                          # 卸载服务

执行端与部署节点同理，把命令名换成 cicd_agent / cicd_node 即可。服务模式下相对目录统一按配置文件所在目录解析，也可用环境变量显式指定服务根目录：

环境变量适用组件
CICD_SERVER_ROOT管理端
CICD_AGENT_ROOT执行端
CICD_NODE_ROOT部署节点

6. 日志 ​

三端业务日志统一输出到 logs/app.log：

  • 日志根目录默认取程序目录（部署形态）；
  • 按大小与天数轮转（log.max-size / log.max-backups / log.max-age），支持按级别分文件，Authorization、X-Agent-Token、密码等敏感字段自动掩码。

没有控制台输出

业务日志不向控制台输出：前台运行时终端只会看到路由表之类的启动信息，排查问题请直接看上述文件；只有启动阶段读配置失败等致命错误才会打印到控制台。

任务执行日志（打包 / 部署输出）不走文件日志，而是落库后由控制台通过 SSE 实时展示，支持按 fromSeq 断点续传；上传与拉取进度同样会写入实时日志。

7. 三端一览 ​

组件监听端口配置文件安装包日志
管理端 cicd_serverHTTP server.port（默认 9866）config.yamlrelease/cicd_server_<os>_<arch>[.exe]<程序目录或配置目录>/logs/app.log
执行端 cicd_agent无（仅主动出站连接）config.yamlrelease/cicd_agent_<os>_<arch>[.exe]同上
部署节点 cicd_node无（仅主动出站连接）config.yamlrelease/cicd_node_<os>_<arch>[.exe]同上

执行端与部署节点不监听任何端口，由内向外主动连接管理端，因此构建机与目标机无需放行入站端口。

8. 常见问题 ​

现象处理
启动报「数据库表结构不完整，缺少 N 张表」执行 mysql_schema.sql（见第 3 节）
启动报配置加载失败确认工作目录下存在 config.yaml，或用 -c 指定路径
用户列表 / 登录报 Unknown column已有库未执行 mysql_upgrade.sql
执行机一直离线检查 server.url 是否可达、server.token 是否正确或是否被重置
部署节点一直离线同上，另确认节点 node.workDir 可写、节点与管理端网络互通
找不到日志前台运行无业务日志输出，请查看程序目录（或配置目录）下的 logs/app.log
时间显示异常db.mysql.params 缺少 parseTime=true&loc=Local
控制台页面为旧版强制刷新（Ctrl / Cmd + F5）清理浏览器缓存；仍无效则更换为当前发布版本的管理端二进制

Copyright © 2024-2026