使用 Docker 部署禅道并实现自动化部署——从项目搭建到运维自动化的完整指南

🐳 使用 Docker 部署禅道并实现自动化部署------从项目搭建到运维自动化的完整指南

一篇讲透：用 Docker 容器化部署禅道项目管理软件，并结合脚本与 API 打造自动化数据流转闭环（附完整流程图与架构图）

📌 文章导览

禅道作为国内领先的开源项目管理软件，集成了产品管理、项目管理、质量管理、DevOps 等核心模块，完整覆盖软件研发项目的全生命周期。使用 Docker 部署禅道，不仅能显著降低安装门槛，还能为后续的自动化运维打下坚实基础。

本文涵盖：

✅ 两种 Docker 部署方案（docker run 与 docker-compose）

✅ 数据持久化配置与权限管理避坑指南

✅ 禅道基础配置与团队初始化

✅ 核心重点 ：基于脚本与 API 的禅道自动化部署体系

✅ 自动化数据备份与恢复策略

✅ 完整流程图 + 架构图（Mermaid 格式）

✅ 生产环境优化与常见问题排查

🧱 一、前置条件

项目	要求
操作系统	Linux（Ubuntu 20.04+ / CentOS 7+ / Debian）
Docker	版本 ≥ 20.10（含 docker-compose）
硬件配置	建议 2 核 4GB 以上、20GB 可用磁盘空间
浏览器	Chrome / Firefox / Edge 任一

💡 禅道官方从开源版 18.5 开始对 Docker 镜像进行了改版升级，更易于部署和使用。

🗺 二、端到端自动化部署流程总览

下面的流程图展示了从容器部署到自动化运维的完整路径：
自动化阶段
初始化阶段
部署阶段
docker run
docker-compose
数据维护
缺陷上报
用例导入
准备 Docker 环境
拉取禅道镜像
创建数据目录
选择部署方式
单容器命令运行
编写 compose.yaml
设置目录权限 777
启动容器
浏览器访问 Web 界面
禅道安装向导
配置数据库

（使用内置 MySQL）
设置管理员账号
选择管理模式

（产品/项目/测试分立）
自动化需求类型
自动化备份脚本

cron 定期执行
HTTP API 调用

JMeter/Postman
xmind2testcase

格式转换服务
完成自动化闭环

🐳 三、Docker 环境下部署禅道

3.1 拉取禅道 Docker 镜像

禅道的 Docker 镜像主要有两个来源：

镜像地址	说明
`hub.zentao.net/app/zentao`	禅道官方镜像仓库（推荐）
`easysoft/zentao`	Docker Hub 仓库镜像

使用以下命令拉取最新镜像：

bash 复制代码

# 方式一：从禅道官方仓库拉取（推荐）
docker pull hub.zentao.net/app/zentao:20.5

# 方式二：从 Docker Hub 拉取（如网络受限可尝试）
docker pull easysoft/zentao:latest

⚠️ 镜像大小约为 500MB，下载速度取决于网络环境。如果遇到下载缓慢的情况，可考虑配置国内镜像加速器。

3.2 创建数据持久化目录

bash 复制代码

# 创建用于持久化存储的数据目录
mkdir -p /data/zentao/data
# 设置目录权限（容器内外用户权限差异的避坑关键）
chmod 777 -R /data/zentao/

💡 为什么需要 777 权限？ 容器内的应用通常以特定用户（如 www-data）运行，而该用户在宿主机上可能没有对应账号。给予宽松权限可避免因权限不足导致的各类问题。

3.3 创建专用 Docker 网络

为禅道创建独立的网络环境，方便后续扩展和隔离：

bash 复制代码

docker network create --subnet=172.18.0.0/24 zentaonet

📚 标准私有 IP 范围：

10.0.0.0/8（10.0.0.0 - 10.255.255.255）

172.16.0.0/12（172.16.0.0 - 172.31.255.255）

192.168.0.0/16（192.168.0.0 - 192.168.255.255）

建议使用标准私有 IP 范围，避免潜在的网络冲突和路由问题。

3.4 方法一：使用 `docker run` 命令部署

bash 复制代码

docker run -d \
  --name zentao \
  -p 80:80 \
  --network=zentaonet \
  --ip 172.18.0.10 \
  -e MYSQL_INTERNAL=true \
  -v /data/zentao/data:/data \
  hub.zentao.net/app/zentao:20.5

关键参数说明：

参数	作用
`-d`	后台运行容器
`--name zentao`	容器名称
`-p 80:80`	端口映射（宿主机端口 : 容器端口）
`--network=zentaonet`	指定使用专用网络
`--ip 172.18.0.10`	指定容器固定 IP
`-e MYSQL_INTERNAL=true`	使用容器内置 MySQL（无需外部数据库）
`-v /data/zentao/data:/data`	数据持久化挂载
`hub.zentao.net/app/zentao:20.5`	镜像名称与版本

3.5 方法二：使用 `docker-compose` 部署（推荐）

编写 docker-compose.yml 文件：

yaml 复制代码

version: '3.9'

services:
  zentao:
    image: hub.zentao.net/app/zentao:20.5
    container_name: zentao
    restart: always
    ports:
      - "80:80"
    networks:
      - zentaonet
    volumes:
      - /data/zentao/data:/data
    environment:
      - MYSQL_INTERNAL=true

networks:
  zentaonet:
    driver: bridge
    ipam:
      config:
        - subnet: 172.18.0.0/24

启动容器：

bash 复制代码

docker-compose up -d

停止容器：

bash 复制代码

docker-compose down

💡 使用 docker-compose 可以将部署配置声明化管理，方便版本控制和迁移。

3.6 验证容器运行状态

bash 复制代码

# 查看容器运行状态
docker ps | grep zentao

# 查看实时日志
docker logs -f zentao

# 进入容器内部
docker exec -it zentao /bin/bash

🌐 四、禅道初始化与基础配置

4.1 Web 安装向导

容器启动成功后，打开浏览器访问 http://<服务器IP> 进入禅道安装向导。

安装流程：

点击 〖开始安装〗 按钮
阅读并同意禅道使用协议，点击 〖下一步〗
系统自动检查环境配置，确认无误后点击 〖下一步〗
数据库配置 ：由于我们使用了 MYSQL_INTERNAL=true，使用的是容器内置的 MySQL 数据库，保持默认配置即可（内建数据库用户名为 root，默认密码为空或 123456）
选择安装模式 ：选择 〖全新项目管理模式〗 并点击 〖下一步〗
填写公司信息和管理员信息：按照提示填写组织名称、管理员账号及密码
完成安装 ：点击 〖登录禅道管理系统〗，使用管理员账号登录

4.2 初始化流程配置

首次登录后，系统会引导进行流程配置，可根据团队管理模式选择：
测试管理
项目管理
产品管理
产品经理维护需求池
创建迭代/发版计划
按需拆分为具体任务

指定前端/后端/测试人员
测试人员编写用例
执行测试并验证Bug修复

推荐管理模式：按 产品 → 迭代/项目 → 迭代 的方式进行管理，使用 需求 + 任务 衡量每个版本的研发效能。

🔧 五、配置 Docker 容器支持 Shell 脚本联动

为了实现自动化部署，Docker 部署的禅道需要能被外部脚本轻松访问。以下配置确保各种自动化操作畅通无阻：

确保端口可访问 ：检查系统防火墙是否放行 Web 端口 -p 80:80 映射的宿主机端口，使 HTTP 请求可以到达应用服务。
数据目录可写 ：确认 /data/zentao/data 目录权限为 777，以确保自动化上传文件、生成报告等操作不被拒绝。
提供脚本执行环境：以下自动化操作在宿主机上执行，只需满足 curl 可用、cron 已启动即可，无需进入容器。

🤖 六、禅道自动化部署体系

Docker 容器化部署完成后，我们可以在此基础上构建一套完整的自动化运维体系，包括：

自动化备份与恢复脚本
基于 HTTP API 的缺陷自动上报
测试用例自动化导入

6.1 自动化备份与恢复（脚本 + cron）

禅道提供了内置的数据备份功能，但手动操作效率低下。通过在宿主机编写自动化备份脚本并配合 cron 定时任务，可实现无人值守的定期备份。

备份脚本 `/opt/zentao-backup.sh`：

bash 复制代码

#!/bin/bash

# ==================== 配置区域 ====================
BACKUP_DIR="/data/zentao-backup"
ZENTAO_DATA_DIR="/data/zentao/data"
RETENTION_DAYS=30
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
# =================================================

# 创建备份目录
mkdir -p "$BACKUP_DIR"

# 1. 停止容器以确保数据一致性
echo "正在停止禅道容器..."
docker stop zentao

# 2. 备份数据目录
echo "正在备份数据目录..."
tar -czf "$BACKUP_DIR/zentao_data_$TIMESTAMP.tar.gz" -C "$ZENTAO_DATA_DIR" .

# 3. 重新启动容器
echo "正在重新启动禅道容器..."
docker start zentao

# 4. 使用禅道内置备份功能导出数据库（可选，依赖容器内 PHP 环境）
# 此步骤需容器内禅道正常运行，建议在备份策略中二选一
echo "正在执行禅道内置备份..."
curl -s -X POST "http://localhost/index.php?m=backup&f=backup" \
     -H "Cookie: zentaosid=$(cat /data/zentao/data/tmp/session/session_* | head -1)" \
     || echo "内置备份跳过（需配置 Session Cookie）"

# 5. 清理超过保留天数的旧备份
echo "清理超过 $RETENTION_DAYS 天的旧备份..."
find "$BACKUP_DIR" -name "zentao_data_*.tar.gz" -mtime +$RETENTION_DAYS -delete

echo "备份完成: $BACKUP_DIR/zentao_data_$TIMESTAMP.tar.gz"

配置定时任务：

bash 复制代码

# 编辑 crontab
crontab -e

# 添加每日凌晨 2 点执行备份
0 2 * * * /bin/bash /opt/zentao-backup.sh >> /var/log/zentao-backup.log 2>&1

恢复脚本 `/opt/zentao-restore.sh`：

bash 复制代码

#!/bin/bash

# ==================== 配置区域 ====================
BACKUP_FILE="$1"  # 需要恢复的备份文件路径
ZENTAO_DATA_DIR="/data/zentao/data"
# =================================================

if [ -z "$BACKUP_FILE" ]; then
    echo "用法: $0 <备份文件路径.tar.gz>"
    exit 1
fi

if [ ! -f "$BACKUP_FILE" ]; then
    echo "错误: 备份文件 $BACKUP_FILE 不存在"
    exit 1
fi

echo "正在停止禅道容器..."
docker stop zentao

echo "正在清空现有数据目录..."
rm -rf "$ZENTAO_DATA_DIR"/*
mkdir -p "$ZENTAO_DATA_DIR"

echo "正在恢复数据..."
tar -xzf "$BACKUP_FILE" -C "$ZENTAO_DATA_DIR"

echo "正在重新启动容器..."
docker start zentao

echo "恢复完成！"

6.2 基于 HTTP API 的自动化集成（缺陷上报）

禅道提供了基于 HTTP 协议的 API 接口，可用于与测试、DevOps 等系统联动，实现需求、缺陷、测试用例的增删改查。这在自动化测试流程中至关重要：当测试脚本检测到致命 Bug 时，可调用 API 自动上报，无需人工介入。

API 认证与基础信息

禅道的 RESTful API 有两种认证方式：

Bearer Token：推荐方式，更安全
Basic Auth：传统方式，使用用户名密码

Request 方法遵循标准 HTTP 语义：

GET → 查询数据
POST → 新增数据
PUT → 更新数据
DELETE → 删除数据

API 基础 URL 格式为：http://<禅道服务器IP>/api.php/v1/

响应码说明：

200：请求成功
401：未授权（Token 无效或过期）
404：资源不存在
其他：根据具体报错参照 HTTP 标准排查

配置步骤

获取 API Token ：登录禅道，进入 后台 → 人员管理 → 用户 ，为用户生成或获取 API Token（禅道 R

2.0 支持在用户个人资料中生成 Token，若无相关入口，可先用管理员账号进行 Basic Auth 验证）。

验证 API 可用性：

bash 复制代码

# 以用户列表查询为例，验证 Token 是否有效
curl -X GET "http://localhost/api.php/v1/users" \
     -H "Authorization: Bearer YOUR_TOKEN"

通过编写 Python 脚本实现自动上报缺陷：

python 复制代码

import requests
import json
import sys
import subprocess

# ==================== 配置区 ====================
ZENTAO_URL = "http://localhost"
API_TOKEN = "YOUR_API_TOKEN_HERE"  # 从禅道后台获取
PRODUCT_ID = 1  # 您的产品 ID
# ===============================================

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_TOKEN}"
}

def upload_bug(title, severity, description, steps="", product_id=PRODUCT_ID):
    """
    自动上报 Bug 到禅道
    :param title: Bug 标题
    :param severity: 严重程度（如 high, medium, low）
    :param description: 问题描述
    :param steps: 复现步骤
    :param product_id: 所属产品 ID
    """
    url = f"{ZENTAO_URL}/api.php/v1/bugs"
    payload = {
        "product": product_id,
        "title": title,
        "severity": severity,
        "steps": steps,
        "desc": description
    }

    try:
        response = requests.post(url, headers=headers, json=payload)
        if response.status_code == 201:
            print(f"✅ Bug 上报成功: {title}")
            return response.json()
        else:
            print(f"❌ Bug 上报失败: {response.status_code}")
            print(f"响应内容: {response.text}")
            return None
    except Exception as e:
        print(f"❌ 网络异常: {e}")
        return None

def get_bug_list(product_id=PRODUCT_ID):
    """查询指定产品下的 Bug 列表"""
    url = f"{ZENTAO_URL}/api.php/v1/bugs"
    params = {"product": product_id}
    response = requests.get(url, headers=headers, params=params)
    return response.json() if response.status_code == 200 else None

if __name__ == "__main__":
    # 示例：自动上报一个严重 Bug
    upload_bug(
        title=f"[自动化测试] HTTP 接口返回 500 错误 - {subprocess.check_output(['hostname']).decode().strip()}",
        severity="high",
        description="自动化测试在执行 /api/user/login 接口时返回了 500 服务器错误，需要紧急修复。",
        steps="1. 执行登录接口测试用例\n2. 预期返回 200\n3. 实际返回 500\n4. 错误信息: Internal Server Error"
    )

自动化测试集成场景

在 Jenkins、JMeter 或 Postman 的自动化测试流程中，可结合上述脚本实现：
无缺陷时记录
有缺陷时上报
CI/CD 流水线
失败
通过
自动化测试执行
测试结果
调用 API 创建 Bug
禅道生成 Bug 记录
调用 API 更新用例状态
测试报告归档
开发人员接收通知

6.3 测试用例自动化导入

对于习惯使用 XMind 编写测试用例的团队，禅道官方登录页面支持 XMind 文件直接导入并自动转换为用例，无需手动转换格式。在日常使用中，可直接在禅道的 测试 → 用例 → 导入 功能中选择上传 XMind 文件完成批量导入。

🏗 七、整体架构图（UML 部署图）

外部
宿主机
自动化工具链
Docker 网络: zentaonet
挂载
提供API
提供Web界面
触发
HTTP API调用
触发
测试结果上报
可选外挂
代码变更
Docker 引擎
禅道容器

hub.zentao.net/app/zentao:20.5

端口:80
可选: 外部 MySQL

（MYSQL_INTERNAL=false时）
/data/zentao/data
自动化脚本

备份/恢复/API调用
cron 定时器
Python API 脚本

缺陷自动上报
Jenkins / GitLab CI

持续集成平台
用户浏览器

HTTP访问
Git 仓库
测试自动化框架

JMeter/Postman

📐 此图展示了禅道容器与宿主机数据目录的挂载关系，以及自动化脚本、备份系统、CI/CD 平台与禅道 API 的交互逻辑。

🔧 八、常见问题排查与优化建议

8.1 容器无法启动或频繁退出

现象：docker ps 显示容器状态为 Exited。

解决方案：

查看详细日志：docker logs zentao
检查宿主机内存是否不足（禅道需要至少 2GB 可用内存）
确认 -v 挂载的目录是否有读写权限

8.2 无法访问 Web 界面

现象：浏览器访问 http://<服务器IP> 无响应。

解决方案：

检查防火墙是否放行了映射的端口（如 80、8080 等）
确认容器是否正常运行：docker ps -a
查看容器日志定位问题：docker logs zentao
检查 SELinux 是否导致端口阻塞：sudo setenforce 0（临时关闭测试）

8.3 数据库连接失败

现象：安装向导或运行时提示数据库连接错误。

解决方案：

确认环境变量 MYSQL_INTERNAL=true 已正确设置
检查 /data 目录是否有足够磁盘空间
尝试重启容器：docker restart zentao
如需使用外部 MySQL，需将 MYSQL_INTERNAL 设为 false 并配置 MYSQL_HOST、MYSQL_PORT 等参数

8.4 文件上传失败

现象：附件或图片上传时提示错误。

解决方案：

确认挂载目录 /data/zentao/data 权限为 777
检查宿主机磁盘空间是否充足
查看 PHP 上传限制（通常在 php.ini 中配置）

8.5 API 调用返回 401 未授权

现象：执行 Python 脚本调用 API 时返回 401 状态码。

解决方案：

确认 API Token 是否正确生成且未过期
检查禅道版本是否支持选择的 API 版本（禅道 2.0 从开源版 21.7.8 起正式支持）
如使用 Basic Auth，确认用户名密码包含在请求头 Authorization: Basic base64(username:password) 中并验证是否可正常登录禅道前端
稍等片刻后重试，或登出旧会话后重新获取 Token

8.6 生产环境安全强化清单

类别	推荐实践
网络隔离	将禅道置于专用 Docker 网络（如 `zentaonet`），避免与其他服务混用
数据库加固	生产环境建议使用外部 MySQL，并仅允许源自 ZenTao 容器的访问
数据备份	每晚定期执行自动化备份，备份文件异地存储至少保留 30 天
权限最小化	`/data/zentao/data` 权限可收紧至 `755` 并搭配合适的用户属组，减少安全风险
访问控制	配置 HTTPS 访问，启用禅道的登录验证码与登录失败锁定策略
API 安全	使用 Bearer Token 认证代替 Basic Auth，定期轮换 Token

📝 九、总结

本文系统地介绍了使用 Docker 部署禅道并构建自动化运维体系的完整路径：

章节	核心收获
三、部署禅道	掌握 `docker run` 和 `docker-compose` 两种容器化部署方式，理解数据持久化与目录权限设置
四、初始化配置	完成禅道 Web 安装向导，根据团队管理模式配置产品/项目/测试分立流程
六、自动化体系	学会编写自动化备份脚本，掌握禅道 HTTP API 的调用方法
七、架构图	理解容器化部署架构及自动化工具的协同关系
八、常见问题	积累生产环境下的故障排查经验

完成本教程后，你将拥有一套由 Docker 驱动的禅道运行平台，并可实现：

✅ 定期自动化备份：每日无人值守完成数据保护
✅ Bug 自动上报：自动化测试流程中发现的缺陷即时录入禅道
✅ 测试用例批量导入：XMind 格式一键导入
✅ 数据灵活恢复：任意历史版本一键恢复

📎 十、快速命令参考集

bash 复制代码

# 1. 拉取禅道镜像
docker pull hub.zentao.net/app/zentao:20.5

# 2. 创建数据目录并设置权限
mkdir -p /data/zentao/data && chmod 777 -R /data/zentao/

# 3. 创建专用网络
docker network create --subnet=172.18.0.0/24 zentaonet

# 4. 启动容器
docker run -d --name zentao -p 80:80 --network=zentaonet --ip 172.18.0.10 \
  -e MYSQL_INTERNAL=true -v /data/zentao/data:/data \
  hub.zentao.net/app/zentao:20.5

# 5. 备份数据
docker stop zentao && tar -czf zentao_$(date +%Y%m%d).tar.gz /data/zentao/data && docker start zentao

# 6. 恢复数据
docker stop zentao && rm -rf /data/zentao/data/* && tar -xzf backup.tar.gz -C /data/zentao/data/ && docker start zentao

# 7. 查看实时日志
docker logs -f zentao

# 8. 进入容器调试
docker exec -it zentao /bin/bash

# 9. 停止并删除容器（保留数据目录）
docker stop zentao && docker rm zentao

使用 Docker 部署禅道并实现自动化部署——从项目搭建到运维自动化的完整指南