简介：本资源是面向项目管理初学者与中小型研发团队的《禅道使用手册（完整版）》，系统覆盖禅道项目管理工具的核心功能与实操路径，重点解决项目协作低效、需求跟踪混乱、Bug闭环不及时等典型痛点。手册内容结构清晰，涵盖基本介绍（含角色权限、登录流程、最简工作流）、个人事务管理（待办创建与浏览、我的任务/BUG、档案维护）、产品经理专属模块（产品维护、需求全生命周期管理、发布计划与统计报表）以及项目经理高频场景（项目组建、任务分解、燃尽图应用）等四大板块，知识点详实且具备强落地性。资源为单文件docx文档，大小4.02MB，格式规范、排版工整，便于查阅与打印。目前已有5210人学习下载，适合刚接触禅道的新手快速上手，也适合作为团队内部培训的标准参考材料。
1. 禅道不是“点开就能用”的项目管理软件：它是一套需要配置、校准和持续维护的协作操作系统
很多人第一次打开禅道，以为填几个需求、建两个任务、拉几个人进群就叫“上了禅道”。结果两周后发现：需求状态没人更新、Bug复现步骤写得像小说、测试报告里找不到对应版本号、研发说“没收到指派”，测试说“早就提了但没人理”——这不是禅道不好，而是跳过了它最核心的环节：初始化配置与角色语义对齐。
《禅道使用手册（完整版）》这个标题里的“完整版”三个字，恰恰暗示它覆盖的不是界面按钮怎么点，而是从数据库初始化、权限树构建、工作流建模、字段级定制，到日常巡检清单的全链路落地逻辑。它面向的不是单点操作者，而是团队中那个要为交付节奏兜底的人：可能是技术负责人、过程改进工程师，或是被临时推上前线的项目协调人。如果你正面临需求漏转、进度失真、跨角色扯皮反复发生，又不想靠人工表格+微信群硬扛，那这份手册真正要解决的，是让禅道从“系统在线”变成“语义在线”——所有人对“待处理”“已解决”“重新打开”这些状态的理解完全一致，对“需求优先级P0/P1”“Bug严重程度致命/严重/一般”的判定有据可依，且能被系统自动捕获、统计、预警。这才是“完整版”的真实分量。
2. 从零部署禅道：避开官方一键包的三大隐性代价
禅道官网提供 Windows/Linux 一键安装包，新手常直接双击运行。但某高校实验室在部署模拟项目X时发现：三个月后无法升级到新版本，自定义字段丢失，MySQL字符集报错频发。根本原因在于，一键包把 Apache、PHP、MySQL 全部打包进私有路径，导致后续所有运维动作都脱离标准 Linux 发行版管理逻辑。我们改用分离式部署，用系统原生包管理器控制基础组件，禅道仅作为 Web 应用部署，虽多花30分钟，但换来未来三年的可维护性。
2.1 用系统包管理器安装 LAMP 基础栈（以 Ubuntu 22.04 为例）
# 安装系统级组件（非一键包私有路径） sudo apt update && sudo apt install -y apache2 mysql-server php php-mysql php-gd php-curl php-xml php-mbstring php-zip # 配置 MySQL 字符集为 utf8mb4（关键！否则中文搜索、Emoji 会乱码） sudo sed -i '/\[mysqld\]/a\character-set-server = utf8mb4\ncollation-server = utf8mb4_unicode_ci' /etc/mysql/mysql.conf.d/mysqld.cnf sudo systemctl restart mysql # 创建禅道专用数据库（非默认的 zentao） mysql -u root -p -e "CREATE DATABASE zentao_prod CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"提示：
utf8mb4是必须项。禅道5.0+ 版本大量使用 JSON 字段存储动态表单，而 MySQL 的utf8实际只支持3字节 UTF-8 字符（不支持 Emoji 和部分生僻汉字），强行用utf8会导致json_encode()失败、页面白屏。这是新手部署后第二天就翻车的高频问题。
2.2 手动解压禅道源码并配置 Apache 虚拟主机
# 下载官方源码包（非一键包！取最新稳定版，如 18.6.stable） wget https://dl.cnezsoft.com/zentao/18.6.stable/zentao.zip unzip zentao.zip -d /var/www/html/zentao/ # 设置目录权限（Apache 用户 www-data 必须有写权限） sudo chown -R www-data:www-data /var/www/html/zentao/ sudo chmod -R 755 /var/www/html/zentao/ # 创建 Apache 虚拟主机配置（避免污染 default site） sudo tee /etc/apache2/sites-available/zentao.conf << 'EOF' <VirtualHost *:80> ServerAdmin webmaster@localhost DocumentRoot /var/www/html/zentao/www <Directory /var/www/html/zentao/www> Options FollowSymLinks AllowOverride All Require all granted </Directory> ErrorLog ${APACHE_LOG_DIR}/zentao_error.log CustomLog ${APACHE_LOG_DIR}/zentao_access.log combined </VirtualHost> EOF sudo a2ensite zentao.conf && sudo systemctl reload apache2参数说明：
AllowOverride All启用.htaccess重写规则，这是禅道 URL 路由（如/bug-view-123.html）生效的前提；DocumentRoot指向www/子目录而非根目录，因禅道源码结构中www/才是真正的 Web 入口，其他目录（lib/,module/）需严格禁止外部访问。
2.3 执行首次安装向导并禁用自动更新检查
浏览器访问http://your-server-ip/进入安装页后，务必在最后一步取消勾选“自动检查更新”。原因有三：
- 自动检查会向禅道官方服务器发送 IP、版本号、插件列表等信息，不符合内部系统安全策略；
- 检查请求超时（尤其在内网环境）会导致安装卡在“正在配置”界面长达2分钟，误判为失败；
- 后续所有升级必须走离线包手动导入，开启自动检查反而干扰升级流程。
安装完成后，立即修改/var/www/html/zentao/config/config.php，将'checkVersion' => true改为false，并添加'debug' => false关闭调试模式——生产环境开启 debug 会暴露 PHP 错误堆栈，构成信息泄露风险。
3. 权限体系不是“给个角色就行”：必须按职能切分三级权限组
禅道默认提供“管理员”“项目经理”“开发”“测试”等角色，但某公司上线初期直接套用，结果出现：测试人员能删除需求、开发能修改 Bug 严重等级、产品经理看不到燃尽图。问题根源在于，禅道的权限模型是对象级 + 行级 + 字段级三重叠加，而默认角色只是预设组合。我们必须基于 RACI 模型（Responsible, Accountable, Consulted, Informed）重建权限组。
3.1 创建三个核心权限组：执行组、决策组、协同组
| 组名 | 对应职能 | 关键权限差异点 |
|---|---|---|
| 执行组（Dev/QA） | 编码、测试执行 | 只能修改自己创建或被指派的 Bug/任务；不能编辑需求描述、不能关闭需求；Bug 状态只能流转为“已解决”“已关闭”，不能跳过“已确认”直接“已关闭” |
| 决策组（PM/PO） | 需求评审、排期决策 | 可编辑所有需求字段（含优先级、预计工时）；可强制关闭任何 Bug；可批量修改任务状态；但不能删除任何数据（防误操作） |
| 协同组（Scrum Master/BA） | 过程监督、文档归档 | 可查看全部数据；可导出报表；可修改“备注”“附件”字段；但不能修改状态、不能指派任务、不能编辑原始需求内容 |
注意：禅道不支持“只读角色”，所谓“只读”必须通过显式禁用所有写权限实现。例如，给协同组分配权限时，在后台 → 后台 → 权限 → 编辑组 → “产品”模块下，取消勾选全部操作项（创建、编辑、删除、导出），仅保留“查看”。
3.2 用 SQL 批量修正历史用户权限归属
安装后默认所有用户属于“admin”组，需批量迁移。以下 SQL 将邮箱域名匹配@dev.example.com的用户移入执行组（ID=5），@pm.example.com的移入决策组（ID=3）：
-- 先确认目标组ID（在后台 → 后台 → 用户 → 组 中查看URL参数gid） -- 假设执行组gid=5，决策组gid=3 UPDATE `zt_user` SET `role` = 'dev', `groups` = '5' WHERE `email` LIKE '%@dev.example.com'; UPDATE `zt_user` SET `role` = 'pm', `groups` = '3' WHERE `email` LIKE '%@pm.example.com'; -- 强制清除缓存（禅道权限缓存时间为1小时，需手动刷新） sudo rm -f /var/www/html/zentao/tmp/cache/*血泪经验：不要依赖后台界面逐个修改用户组！某项目有200+用户，界面操作耗时4小时且中途断连会丢失进度。SQL 直接操作数据库表（
zt_user.groups字段存逗号分隔的组ID字符串）是唯一可靠方案。操作前务必备份zt_user表：mysqldump -u root -p zentao_prod zt_user > zt_user_backup.sql
3.3 字段级权限：隐藏敏感字段，暴露关键字段
默认情况下，所有用户都能看到 Bug 的“重现步骤”“环境信息”字段，但实际工作中，这两项常包含内网IP、服务器路径等敏感信息。我们通过后台 → 后台 → 自定义 → 字段 → 编辑“Bug”模块，将steps（重现步骤）和env（环境）字段的“可见范围”设为“仅指派人、处理人、抄送人”，而将mailto（邮件通知）字段设为“所有人可见”——确保问题升级路径透明。
4. 避坑：禅道部署与权限配置的5个高发故障点
4.1 现象：安装完成后访问首页显示“500 Internal Server Error”，错误日志中出现PHP Fatal error: Uncaught Error: Call to undefined function mb_strlen()
原因：Ubuntu 22.04 默认安装的 PHP 8.1 不再内置mbstring扩展，而禅道核心类库大量依赖该扩展进行中文字符串截取。
解决：sudo apt install php-mbstring && sudo systemctl restart apache2
4.2 现象：创建需求后，状态始终卡在“草稿”，无法流转为“已确认”；点击状态下拉框无反应
原因：Apache 的mod_rewrite模块未启用，导致禅道前端路由（如/product-create.html）无法解析为真实 PHP 文件路径。
解决：sudo a2enmod rewrite && sudo systemctl restart apache2，并确认虚拟主机配置中AllowOverride All已生效。
4.3 现象：测试人员提交 Bug 后，研发人员收不到邮件通知，但系统日志显示“邮件发送成功”
原因：禅道邮件配置中的 SMTP 密码含特殊字符（如@、/），未进行 URL 编码，导致 PHPparse_url()解析失败，实际连接的是错误的 SMTP 服务器。
解决：将密码中的@替换为%40，/替换为%2F，再填入后台 → 后台 → 邮件 → SMTP 密码框。
4.4 现象：权限组配置后，用户仍能编辑已被锁定的需求，或删除他人创建的 Bug
原因：禅道的“删除”权限控制粒度极细——“删除需求”和“删除需求下的用例”是两个独立权限项，后台界面默认只勾选前者。
解决：进入权限组编辑页 → 展开“产品”模块 → 找到“需求”子项 →同时勾选“删除”和“删除用例”；同理，“Bug”模块下需同时勾选“删除”和“删除评论”。
4.5 现象：升级禅道到新版后，所有自定义字段消失，原有数据无法显示
原因：升级包未包含custom/目录（该目录存放所有字段定制配置），而官方升级脚本默认只覆盖www/、lib/等核心目录。
解决：升级前备份/var/www/html/zentao/custom/整个目录；升级后，将备份的custom/目录完整覆盖回原位置，并执行sudo chown -R www-data:www-data /var/www/html/zentao/custom/
5. 让禅道真正驱动协作：用“三张表”固化团队协作契约
部署和权限只是起点，禅道能否发挥价值，取决于是否把团队约定的协作规则，翻译成系统可执行、可审计、可追溯的配置。我们不用写SOP文档，而是用禅道内置的三张表，把模糊的“应该怎么做”变成明确的“系统不允许那样做”。
5.1 第一张表：需求状态机（State Machine）——定义“什么条件下才能变更状态”
默认禅道需求状态只有“草稿→已确认→已计划→进行中→已验收→已关闭”，但某跨平台系统要求：
- “已确认”需求必须关联至少1个测试用例，才能进入“已计划”；
- “进行中”需求若超过3天未更新进展，自动触发邮件提醒负责人；
- “已验收”状态只能由测试组长（非普通测试）设置。
这些规则无法靠人工监督，必须通过自定义工作流实现：
后台 → 后台 → 自定义 → 工作流 → 新建工作流 → 选择“需求”模块 → 在“已确认”节点下，添加条件：“关联用例数 ≥ 1”；在“进行中”节点下，添加定时规则：“停留时间 > 3天” → 动作：“发送邮件至指派人”。
5.2 第二张表：Bug 严重等级与响应时效对照表（SLA Table）——把“尽快修复”变成可度量指标
禅道 Bug 严重等级（致命/严重/一般/建议）本身无业务含义，必须绑定响应时效：
| 严重等级 | 响应时效 | 解决时效 | 自动升级规则 |
|---|---|---|---|
| 致命 | ≤15分钟 | ≤2小时 | 超时自动抄送CTO邮箱 |
| 严重 | ≤2小时 | ≤1工作日 | 超时自动创建阻塞任务 |
| 一般 | ≤1工作日 | ≤3工作日 | 超时自动标记为“延期” |
| 建议 | ≤3工作日 | ≤1周 | 无自动动作 |
此表通过自定义字段+定时任务落地：新增字段“SLA起始时间”（日期时间型），当 Bug 状态变为“已确认”时，用禅道API或数据库触发器自动写入当前时间；再用 Linux cron 每5分钟执行脚本，比对now() - SLA起始时间与上表阈值，触发邮件或状态变更。 |
5.3 第三张表：每日站会检查清单（Daily Standup Checklist）——用禅道任务反向驱动会议质量
很多团队站会变成“报流水账”，我们把它改造为“问题拦截器”：每天早10点，禅道自动创建一个名为“【站会】YYYY-MM-DD”的任务，指派给全体成员，截止时间设为10:15。该任务描述中嵌入结构化清单：
- ✅ 昨日承诺完成事项（链接至对应任务/Bug）
- ⚠️ 今日最大阻塞点（必须选择“阻塞类型”：环境/依赖/设计/其他）
- 📌 需要跨角色同步的关键信息（自动@相关角色）
成员必须填写完毕才能标记为“已完成”，否则任务始终显示为红色。连续3次未完成，系统自动推送至部门周报。这倒逼每个人提前整理信息，也让阻塞点在发生当天就被暴露。
我带过的每个团队，上线禅道后第1个月都在调这张表——不是调功能，是调人。当“已确认”需求必须关联用例才允许排期，当“致命Bug”超15分钟未响应就抄送高管，当站会任务不填完就影响个人KPI，系统就不再是工具，而成了团队共同遵守的契约。这种契约感不会来自一份PDF手册，只会来自你亲手配置的每一个字段、每一条规则、每一次对超时的干预。希望帮到你。
本文还有配套的精品资源，点击获取
