GitLab CI 驱动禅道自动化部署：从零构建企业级 CI/CD 流水线

身如柳絮随风扬2026-05-27 13:59

GitLab CI 驱动禅道自动化部署：从零构建企业级 CI/CD 流水线

1. 引言

禅道（ZenTao）作为国内领先的开源项目管理软件，已在无数研发团队中扮演着"枢纽"角色------产品经理提需求，开发团队领任务，测试人员报 Bug，所有角色的信息汇聚于此。然而，传统模式下，代码提交、构建、测试、部署这一整套 CI/CD 流程与禅道是割裂的：开发者将代码推送到 GitLab，在终端手动执行部署脚本，再回到禅道更新任务状态，整个链路充满了重复劳动和人为失误。

本文致力于消除这一隔阂，通过 GitLab CI（即 GitLab 内置的 CI/CD 工具）与禅道的深度集成，搭建一条完全自动化的交付流水线。当你提交代码的那一刻，后续的构建、测试、部署乃至禅道中的任务状态更新都将自动完成。你将掌握以下技能：

  • ✅ 禅道与 GitLab 的双向关联配置
  • ✅ 基于 Docker 的 GitLab Runner 部署与注册
  • ✅ 编写生产级 .gitlab-ci.yml 流水线，覆盖构建、测试、部署各环节
  • ✅ 集成 ZTF 自动化测试框架，打通测试闭环
  • ✅ 配置 Webhook 触发、构建产物存储、回滚等生产特性

完成本文后，你将亲手打造一条从"代码提交"直通"禅道任务"的自动化高速公路，彻底拥抱 DevOps 效率革命。

2. 核心架构：禅道如何与 GitLab CI 双向对话？

先看图理解整体的数据流向：
部署服务器
禅道服务器
GitLab
开发者工作区
git push
触发
拉取执行
构建/测试
调用 ZTF 执行测试
提交测试结果
通过 Webhook 通知
同步任务状态
关联 GitLab 提交
开发者
代码仓库
GitLab Runner
CI/CD Pipeline
Webhook 触发器
禅道项目管理
ZTF 自动化测试框架
容器化部署环境

这张图描述的是一个双向闭环：开发者提交代码后，GitLab CI 自动构建、部署、执行测试，同时将测试结果和任务状态同步回禅道，实现真正的"项目管理"与"持续交付"一体化。

3. 环境准备

在开始集成之前，需要先确保以下组件均已部署就绪：

组件 推荐配置 说明
GitLab 自托管（Self-hosted）版本 15.0+ 需具备管理员权限
禅道 开源版 18.5+（建议最新） 需开启 DevOps 模块
GitLab Runner v15.0+ 推荐 Docker 执行器
Docker 20.10+ Runner 主机需安装
禅道服务器 Ubuntu 20.04 / CentOS 7+ 用于部署禅道容器

⚠️ 如果禅道版本过低（低于 18.5），Docker 镜像可能不支持通过环境变量选择是否启用内置 MySQL，建议升级至新版以获得更好的 DevOps 集成体验。

此外，当禅道与 GitLab 部署在不同服务器上时，请确保两者之间网络互通，特别是 Webhook 通信端口和 API 访问端口不会被防火墙阻断。

4. 配置禅道与 GitLab 的集成

4.1 生成 GitLab Access Token

集成之前，禅道需要一个 Token 来访问 GitLab API。登录 GitLab 后：

  1. 点击右上角头像 → Edit profile。
  2. 选择左侧导航 Access Tokens。
  3. 输入 Token 名称（如 zentao-integration），过期时间建议设置为 Never。
  4. 在 Select scopes 中勾选 api（允许完整 API 访问）和 read_repository（允许读取仓库）。
  5. 点击 Create personal access token ，然后立即复制生成的 Token（离开页面后将无法再次查看）。

4.2 在禅道中关联 GitLab 代码库

登录禅道，切换到 DevOps 视图（顶部导航栏），选择 GitLab 标签页，然后点击「添加 GitLab」。填写以下信息：

配置项 说明 示例
名称 自定义标识 内部 GitLab
服务地址 GitLab 的访问地址 https://gitlab.yourcompany.com
Token 上一步生成的 Access Token glpat-xxxxxxxxxxxx
API 版本 固定选择 v4 ---

点击保存后，禅道会验证 Token 的有效性，验证通过后即可在下拉菜单中选择需要关联的 GitLab 项目。

4.3 关联禅道任务与 GitLab 提交

建立了项目关联后，开发者可以在一线实现"任务---代码"的双向链接。提交代码时，在 Commit Message 中包含 Story #123 或 Task #456，该提交记录将自动显示在禅道对应需求/任务页面的"代码"标签页中。反之，禅道中需求、任务、Bug 等页面上也会直接显示关联的 GitLab 合并请求和分支。

4.4 配置禅道 Webhook 触发 GitLab 流水线（进阶）

此配置可以实现双向联动------在禅道中更新任务状态时自动触发 GitLab 流水线。

  • 在 GitLab 中配置 Webhook ：进入项目 → Settings → Webhooks ，添加禅道 Webhook 地址，可勾选 Push events 和 Merge request events 作为触发条件。

  • 在禅道中添加 GitLab 流水线：在 DevOps 视图中，通过引擎下拉菜单选择 GitLab 流水线，关联对应代码库，即可让流水线执行结果同步回禅道。

5. 安装与注册 GitLab Runner（Docker 模式）

Runner 是 CI/CD 的执行引擎，负责拉取并执行 .gitlab-ci.yml 中定义的任务。本节将搭建 Docker 执行器，获得干净、隔离的作业执行环境。

5.1 在 Runner 主机安装 Docker

若 Runner 主机尚未安装 Docker，按以下步骤安装：

bash 复制代码 
# Ubuntu/Debian
sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl enable docker --now

# CentOS 7+
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io
sudo systemctl enable docker --now

5.2 使用 Docker 容器运行 GitLab Runner

这是官方推荐的部署方式，能以容器形式运行 Runner 而不影响宿主机环境。

bash 复制代码 
docker run -d --name gitlab-runner \
  --restart always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /srv/gitlab-runner/config:/etc/gitlab-runner \
  gitlab/gitlab-runner:latest

关键挂载说明：

  • /var/run/docker.sock：让容器内的 Runner 可以调用宿主机 Docker 守护进程，从而执行 DinD（Docker-in-Docker）等操作。
  • /srv/gitlab-runner/config：Runner 配置文件持久化，防止容器删除后配置丢失。

5.3 注册 Runner

注册 Runner 的目的是将它绑定到你的 GitLab 项目或群组。

bash 复制代码 
docker exec -it gitlab-runner gitlab-runner register

根据提示依次输入：

  • GitLab instance URL ：自托管实例地址，如 https://gitlab.yourcompany.com
  • Registration token ：进入 GitLab 项目 → Settings → CI/CD → Runners 可获取
  • Runner description ：如 zentao-deploy-runner
  • Tags （可选）：建议指定为 docker
  • Executor ：输入 docker

⚠️ 若需要使用 docker-in-docker（DinD）模式（在容器内再启动子容器），请在 Runner 的 config.toml 中添加 privileged = true，并将执行器设为 docker，image 指定为 docker:dind。

6. 编写 .gitlab-ci.yml：全功能流水线

现在进入核心环节------编写 .gitlab-ci.yml，存放于项目根目录。以下模板集成了版本锁定、构建、测试、部署、产物归档，覆盖禅道部署流水线的完整生命周期。

yaml 复制代码 
# 流水线阶段定义，按顺序执行
stages:
  - build
  - test
  - deploy

# 全局缓存，加速依赖安装
cache:
  paths:
    - vendor/

# 变量集中管理（关键信息不要明文暴露，应使用 CI/CD 变量）
variables:
  MYSQL_ROOT_PASSWORD: ${ZENTAO_MYSQL_PASSWORD}
  IMAGE_TAG: ${CI_COMMIT_SHORT_SHA}
  DEPLOY_SERVER: "user@your-deploy-server"

### 构建阶段 ###
build_job:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  script:
    # 构建禅道定制化镜像
    - docker build -t $CI_REGISTRY_IMAGE:${IMAGE_TAG} .
    - docker push $CI_REGISTRY_IMAGE:${IMAGE_TAG}
  only:
    - main
    - develop
  tags:
    - docker

### 测试阶段 ###
test_job:
  stage: test
  image: hub.zentao.net/app/zentao:latest
  services:
    - mysql:5.7
  script:
    # 调用 ZTF 执行自动化测试（详见 7.1 节）
    - ./ztf --exec-file ./test_suites/zentao_suite.xml --report-url ${CI_API_V4_URL}
    # 可选：执行单元测试
    - composer test
  only:
    - merge_requests
    - develop
  artifacts:
    when: always
    paths:
      - test-reports/
    reports:
      junit: test-reports/*.xml

### 部署阶段 ###
deploy_production:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client docker
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh && chmod 700 ~/.ssh
  script:
    # 通过 SSH 在部署服务器上执行远程部署命令
    - ssh ${DEPLOY_SERVER} "
        docker pull $CI_REGISTRY_IMAGE:${IMAGE_TAG} &&
        docker stop zentao || true &&
        docker rm zentao || true &&
        docker run -d --name zentao \
          -p 80:80 \
          -v /data/zentao:/data \
          -e MYSQL_INTERNAL=true \
          $CI_REGISTRY_IMAGE:${IMAGE_TAG}
      "
  only:
    - main
  environment:
    name: production
    url: https://zentao.yourcompany.com
  tags:
    - deploy

7. 扩展与高级特性

基础流水线已经能够覆盖常规部署场景，但若你的团队对代码质量、流程安全有更高要求，可以继续接入以下能力。

7.1 集成 ZTF 自动化测试框架

ZTF 是禅道团队自研的开源自动化测试框架，与禅道平台原生集成，能将禅道中的测试用例和测试脚本进行双向同步，执行结果自动提交到禅道并生成测试报告。

在 GitLab CI 中集成 ZTF 的典型方式：

bash 复制代码 
# 1. 在流水线的测试阶段下载 ZTF 二进制
wget https://ztf.zentao.net/download/ztf-linux-amd64.tar.gz
tar -xzf ztf-linux-amd64.tar.gz && chmod +x ztf

# 2. 执行测试脚本（需事先配置好禅道 API Token）
./ztf --exec-file ./test_cases/zentao_tests.xml \
      --report-url ${CI_API_V4_URL} \
      --user ${ZENTAO_USER} \
      --token ${ZENTAO_TOKEN}

执行成功后，测试结果将自动提交到禅道相应用例，失败的用例甚至可以在禅道中直接创建 Bug 记录，形成"代码提交 → 自动测试 → 测试报告回流 → 用例失败自动创建 Bug"的完整闭环。

7.2 多环境部署（Dev → Staging → Production）

生产级的流水线通常不会直接部署到线上，而是采用渐进式部署策略。推荐采用多阶段部署模式：

环境 触发分支 部署场景
dev develop 自动部署至开发环境，供团队日常联调
staging release/* 或手动触发 准生产验收环境，用于回归测试和业务验收
production main（需审批） 正式线上发布，通常结合手动审批

实现这种模式，需要在 .gitlab-ci.yml 中定义多个 deploy 任务，并为每个任务指定不同的 environment 字段，同时通过 only 和 when 精确控制触发条件。

7.3 手动审批与受保护环境

生产环境部署前加入人工审批，是许多企业安全合规的基本要求。在 GitLab CI 中，可以通过 受保护环境（Protected Environments） 结合 审批规则（Approval Rules） 实现：

  1. 在 GitLab 项目 → Settings → CI/CD → Protected Environments 中将 production 设为受保护环境。
  2. 设置部署策略为「需要来自至少一名审批人的批准（Require approval from at least one member of a group）」。
  3. 在 .gitlab-ci.yml 的 deploy_production 任务中添加 needs: []（避免受之前任务的影响），使其在部署阶段等待人工按钮点击。

8. 生产最佳实践与监控

8.1 配置运行监控

为了确保流水线的健康度和部署成功率，建议配置以下监控指标：

  • Runner 健康检查：定期探测 Runner 主机的 Docker 服务状态，确保可用。
  • 构建耗时监控：记录每个 Stage 的执行时长，及时发现性能退化。
  • 失败率告警：利用 Prometheus + Alertmanager 对流水线失败率进行阈值告警。
  • 部署回滚计时器：监控从镜像构建完成到部署成功的时间窗口。

8.2 减少流水线噪声：only/except 策略精调

将流水线配置为仅在必要的分支和场景下触发，可有效节省计算资源并降低日志干扰。常规优化策略：

yaml 复制代码 
only:
  - main
  - develop
  - merge_requests
except:
  - tags
  - /^wip-/

8.3 变更原子性与回滚预案

每个部署动作都应该是可逆的。在流水线中增加以下回滚能力：

  • 保留前 N 个版本镜像：在构建阶段保留最近 5 个成功的镜像 Tag，为回滚储备靶点。
  • 蓝绿部署：部署时同时运行新旧两个集群，验证完成后才切换流量。
  • 回滚 Job ：定义一个 rollback Stage，一键将环境回退到上一个稳定版本：
yaml 复制代码 
rollback_production:
  stage: deploy
  script:
    - ssh ${DEPLOY_SERVER} "
        docker pull $CI_REGISTRY_IMAGE:${PREVIOUS_TAG} &&
        docker stop zentao && docker rm zentao &&
        docker run -d --name zentao ... $CI_REGISTRY_IMAGE:${PREVIOUS_TAG}
      "

9. 部署流程全景图（集成版）

develop
main
开发者提交代码
GitLab 触发 CI 流水线
Runner 执行 .gitlab-ci.yml
构建阶段：生成 Docker 镜像并推送到仓库
测试阶段：执行 ZTF 自动化测试
测试结果回流禅道
环境判定
自动部署到 dev 环境
等待人工审批
生产环境部署
部署后健康检查
完成上线

10. 常见问题与排查

问题 排查方向 解决方案
Runner 执行器报错 Cannot connect to the Docker daemon Runner 容器未挂载 Docker Socket 添加 -v /var/run/docker.sock:/var/run/docker.sock 并重启 Runner
禅道 DevOps 模块找不到 GitLab 项目 Token 权限不足或项目未公开 确认 Token 包含 api Scope，禅道和 GitLab 部署在互联的网络中
ZTF 测试结果无法回传禅道 禅道 API Token 配置错误或网络不通 在流水线变量中正确配置 ZENTAO_URL、ZENTAO_TOKEN，并允许 Runner 主机访问禅道 API 端口
流水线触发后没有日志输出 Runner Tag 与 job 不匹配 检查 job 中的 tags 字段和 Runner 注册时设置的 tag 是否一致
容器内执行 docker 命令提示权限不足 DinD 容器未以 privileged 模式运行 在 Runner 的 config.toml 中添加 privileged = true 并重启 Runner

11. 总结与最佳实践

通过 GitLab CI 对禅道进行自动化部署，本质上是将 DevOps 最佳实践与项目管理工具进行了深度融合。回顾整个流水线的设计，有几个关键原则值得持续遵守：

  • ✅ 配置版本化 ：.gitlab-ci.yml 是 CI/CD 的设计蓝图，必须纳入 Git 版本管理。
  • ✅ 测试左移：将测试阶段尽可能前置到构建与合并之前，提前发现缺陷，从源头提升禅道中用例的质量。
  • ✅ 最小化权限 ：GitLab Access Token 只授予禅道必要的 api 和 read_repository 权限，生产环境的 SSH 密钥妥善保管，以环境变量的形式注入流水线，绝不可明文提交。
  • ✅ 可观测性：利用 GitLab 内置的 Metrics、Prometheus 集成，配合禅道 DevOps 报表，实时掌握发布质量与团队效率。
  • ✅ 持续优化触发策略：避免不必要的流水线运行，节省计算资源的同时减少日志噪声。

GitLab CI 与禅道的集成，远不止自动部署这一个应用场景。它是研发管理中"代码变更"与"项目管理"两大核心系统的粘合剂------每一次提交、每一次部署、每一个失败的测试用例，都能在禅道中留下完整的痕迹。

相关推荐
一点事4 小时前
docker：安装oracle 19c
docker·oracle·容器
qq_452396237 小时前
第四篇：《Docker 镜像：分层结构、拉取与推送》
运维·docker·容器
身如柳絮随风扬7 小时前
Docker 部署 Nginx：从入门到生产级配置实战
nginx·docker·容器
木雷坞7 小时前
dwz-server Docker 部署短链接服务：多域名、A/B 测试和统计配置
运维·docker·容器
亚空间仓鼠8 小时前
Docker容器化高可用架构部署方案（十六）
docker·容器·架构
星空8 小时前
docker
linux·运维·docker
木雷坞8 小时前
vLLM 服务上线前压测记录：镜像缓存、GPU 利用率和 p95
人工智能·机器学习·docker
AI服务老曹9 小时前
解耦异构算力与多协议接入：基于 Docker 部署的企业级 GB28181/RTSP 边缘计算 AI 视频管理平台架构解析（附源码交付）
人工智能·docker·边缘计算
热门推荐
01GitHub 镜像站点02Codex 接入 DeepSeek API 完整配置文档03【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法04【AI】2026 年具身智能模型和世界模型总结05裂开！ChatGPT 居然开始要手机号验证，附详细解决方法06CC-Switch & Claude 基于 Linux 服务器安装使用指南07Codegraph 实战：用知识图谱让 AI 编程效率翻倍08Codex使用DeepSeek API的方法（cc switch + codex bridge方案）09LLM Wiki：让大模型替你打理知识库的完整指南10给 Claude Code 装上“技能库”和“眼睛”：配置 Skills 与图片识别实战