
简介本资源是面向项目管理初学者与中小型研发团队的《禅道使用手册完整版》系统覆盖禅道项目管理工具的核心功能与实操路径重点解决项目协作低效、需求跟踪混乱、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 webmasterlocalhost 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的用户移入执行组ID5pm.example.com的移入决策组ID3-- 先确认目标组ID在后台 → 后台 → 用户 → 组 中查看URL参数gid -- 假设执行组gid5决策组gid3 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.sql3.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 apache24.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手册只会来自你亲手配置的每一个字段、每一条规则、每一次对超时的干预。希望帮到你。本文还有配套的精品资源点击获取