CICD 自动打包部署平台

切换主题

快速开始 ​

本页给出从零跑通第一个项目的最短路径。整个链路是：管理端（Web 控制台 + MySQL）→ 构建机上的执行端 agent →（可选）目标机上的部署节点 node。

阅读本页前请先按 安装部署 完成三端二进制的构建与数据库初始化；三端的可配置项见 配置详解。

前提

  • 已构建出 cicd_server / cicd_agent / cicd_node（或用源码直接运行）。
  • 已创建好 MySQL 数据库，并执行过 backend/mysql_schema.sql（程序不会自动建表）。
  • 管理端所在主机与构建机之间网络互通（执行端主动连接管理端，构建机不需要暴露端口）。

端到端流程 ​

1. 初始化数据库 ​

程序不会自动建表，必须先手动执行建表脚本（脚本幂等，末尾会初始化管理员账号 admin）：

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

已有数据库需要增量升级时改跑 backend/mysql_upgrade.sql。建表与升级的适用场景、增量内容见 安装部署。

2. 启动管理端并登录 ​

bash
cd backend
../release/cicd_server_linux_amd64 -c config.yaml

浏览器访问 http://<host>:9866（默认端口），用初始管理员登录：

项值
用户名admin
密码admin123

首次登录后立即改密

登录后请在右上角「修改密码」修改 admin 的初始密码。连续登录失败达到 auth.maxLoginFailures（默认 5）次会锁定账号 auth.loginLockMinutes（默认 30）分钟。遗忘密码的处理方式见 安装部署。

3. 新建执行机，复制一次性 Token ​

进入「执行机」页面 →「新建」，输入名称后保存，复制页面展示的一次性 Token（仅展示一次，关闭后无法再次查看，只能重置）。

Token 与这台执行机记录绑定，是执行端接入管理端的凭据。

4. 配置并启动执行端 ​

在构建机上放置 cicd_agent 二进制与 agent/config.yaml，填入管理端地址与上一步复制的 Token：

yaml
server:
  url: "http://<管理端地址>:9866"   # 管理端地址
  token: "<上一步复制的一次性 Token>"

启动执行端（源码方式进入 agent 目录运行 start-agent.bat，或直接运行 cicd_agent 二进制；配置文件默认取当前目录的 config.yaml，也可用 -c 指定）。

启动后回到管理端「执行机」页面，该执行机状态应变为「在线」。执行端主动连接管理端（Token 鉴权 + 长轮询取指令），不需要在构建机上开放任何入站端口。

5. 添加 Git 公钥 ​

管理端「执行机 → Git 密钥」中查看执行端自动生成的公钥（私钥只存在于构建机本地，从不上报、不入库），把它添加到 Git 平台：

  • GitHub / GitLab / Gitee 的 Deploy Key，或 SSH Key；
  • 公钥信息可复制，配置完成后可在「项目 → 代码获取 → 测试连接」验证连通性。

6. 探测构建环境 ​

在执行机详情中点击「探测」，确认构建机上的 JDK / Node / Docker / Git 等构建工具可用。探测结果用于后续登记环境资源。

7. 登记环境资源与目标服务器 ​

  • 环境资源：在「环境资源」中登记一套构建环境（安装目录、可执行文件、额外环境变量等）。一套同配置资源可关联多台执行机。
  • 目标服务器：在「目标服务器」中登记部署目标，连接方式可选：
    • ssh（默认）：执行机打包后通过 SSH 上传产物到目标机并执行启停脚本；
    • node：由目标机上注册的部署节点在本机落地产物，目标机无需开放 SSH（见下方提示）。

部署节点（可选）

如需目标机免 SSH，可在目标服务器上放置 cicd_node 与 node/config.yaml，在管理端「执行机 → 部署节点」新建并复制一次性 Token 填入配置后启动节点；再在目标服务器编辑时把「连接方式」选为部署节点并选择该节点。详见 执行机与部署节点。

8. 新建项目 ​

在「项目」页面新建项目，项目必须选择分组（project.group_id 为 NOT NULL），并依次完成：

配置说明
分组必选；项目分组可提供分组级任务变量、可选的部署目标范围与通知配置
代码获取仓库地址、分支、认证方式、浅克隆与缓存选项
构建选择用到的环境资源 + 构建步骤（Java / Go / 前端 / Docker）
部署部署目标服务器、远端目录、部署文件（产物条目）、停/部/启脚本、人工卡点等

项目不需要选择执行机

项目只引用环境资源；触发执行时，管理端按「项目引用资源所关联执行机的交集」自动匹配一台可用机器（最闲优先）。若某个项目引用的多个资源没有共同关联的执行机，任务会直接失败并提示「没有匹配的执行机」，此时请检查资源关联的执行机是否重叠。

新建项目页提供「快速开始」模板（Go 服务 / Vue·Node 前端 / Java 服务 / Docker 镜像），可一键填充构建与部署配置，套用后自行选择环境资源与目标服务器。详见 项目与模板。

9. 触发任务并查看日志与产物 ​

在项目页触发任务后：

  • 实时日志：任务日志落库，由控制台通过 SSE 实时展示，支持按 fromSeq 断点续传；
  • 任务产物：每个构建步骤的主产物（Java target/*.jar、前端 dist、Go 产物等）会在打包阶段由执行端自动归档到管理端磁盘长期保留，可在项目详情与任务详情下载（目录产物下载为 .tar.gz；Docker 步骤产出的是镜像引用，不归档）；
  • 保留策略：默认保留 30 天（artifact.retentionDays），单任务上限 2GB（artifact.maxTaskBytes），总量上限 20GB（artifact.maxTotalBytes，超出按最旧优先回收）。详见 配置详解。

完整示例：Java 服务打包并部署 ​

以「Spring Boot 应用 → jar 落地 → 启停脚本」为例，串起一份可运行的最小配置：

  1. 环境资源：登记一套 JDK 资源（安装目录、java / mvn 可执行文件），关联到构建用执行机。
  2. 目标服务器：登记生产机（连接方式 ssh，用户名 + 密码或私钥），远端目录填 /srv/demo。
  3. 内容模板：新建一个「应用启停脚本」（文件名 app.sh、目录留空、权限 0755），内容用 Java 启停脚本示例，并分配给项目所属分组。
  4. 项目：
    • 代码获取：仓库地址 + 分支，认证方式 SSH；
    • 构建：选 JDK 资源，一个 java 步骤（clean package -DskipTests，产物 target/*.jar）；
    • 部署：目标服务器选第 2 步的机器，远端目录 /srv/demo；产物条目来源 target/*.jar、目标名称 app.jar；脚本文件选第 3 步的模板；停 / 部 / 启脚本按下表填写；
    • 任务变量：APP_ENV=prod（可选 JAVA_OPTS 覆盖默认 JVM 参数）。
bash
# 部署前（停止）
sh ${remoteDir}/app.sh stop

# 部署（可选，文件已落地）
sh ${remoteDir}/app.sh status

# 部署后（启动）
sh ${remoteDir}/app.sh start

触发任务后：app.jar 落到 /srv/demo/app.jar，启停脚本由内容模板生成到 /srv/demo/app.sh 并自动赋权 0755。注意此处 ${remoteDir} 是部署占位符（部署脚本用），而 app.sh 正文用的是 {{ }} 模板语法，两者不要混用，详见 构建与部署。

常见问题速查 ​

现象处理
启动报「数据库表结构不完整，缺少 N 张表」先执行 backend/mysql_schema.sql
启动报配置加载失败确认工作目录下存在 config.yaml，或用 -c 指定路径
执行机一直离线检查 server.url 是否可达、server.token 是否正确或已被重置
拉码失败确认执行机公钥已添加到 Git 平台，并用「代码获取 → 测试连接」验证
任务卡在「部署」阶段中转等待节点结果，默认超时 600 秒（agent.relayTimeoutSeconds）；确认目标机绑定的节点在线且磁盘可写
时间显示异常确认 db.mysql.params 包含 parseTime=true&loc=Local

更多模块说明见 平台功能 与 系统管理。

Copyright © 2024-2026