禅道使用手册完整版：从文档到可复现的研发管理流程落地指南

简介：这份《禅道使用手册（完整版）》面向项目经理、产品经理、开发与测试人员，以及正在引入项目管理工具的中小团队，用于解决项目进度跟踪、任务分配、需求与缺陷协同等日常协作问题。手册以角色为主线组织内容，从基本介绍、用户角色、最简使用与登录流程讲起，再依次展开个人管理中的待办创建与浏览、我的任务与我的BUG关注、个人档案维护，以及产品经理维护产品、创建评审与变更需求、需求状态阶段、产品模块、发布计划与统计报表，并延伸至项目经理建立项目、组建团队、确定需求列表、任务分解与燃尽图查看等模块。资源包共1个docx文件，约4.02MB，目录层级清晰，便于按章节检索查阅。目前已有5210人学习下载，适合作为团队落地禅道时的操作参考与培训材料。

1. 禅道使用手册（完整版）.docx：从一份文档到一套可复现的研发管理流程

很多团队第一次拿到「禅道使用手册（完整版）.docx」时，第一反应是把它当成一份产品说明书来读——翻一遍目录，知道有哪些菜单，然后关掉。结果就是：文档躺在共享盘里吃灰，团队依然在用聊天工具派活、用表格追进度、用口头确认需求。真正的问题不在于手册写得全不全，而在于没人把它翻译成「我们团队明天该怎么用」。

这份手册的价值，是把禅道从「一个装好的系统」变成「一套能跑起来的研发管理流程」。它覆盖需求、任务、Bug、测试用例、版本、发布这几条主线，适合三类人：刚接手禅道配置的研发负责人、需要把流程落地的项目经理、以及被要求「把禅道用起来」的一线开发。下面我不复述手册目录，而是按「先立住概念、再动手配置、最后避坑」的顺序，把这份文档拆成能照着做的步骤。

2. 禅道核心概念与角色权限：先搞清楚谁在什么位置干什么

禅道最容易翻车的地方，不是功能不会点，而是角色和权限没理清。一个新人进来，看到「产品」「项目」「测试」三套菜单，不知道点哪个；一个开发被给了管理员权限，结果误删了需求。所以动手之前，先把概念和权限这两件事定下来。

2.1 产品、项目、执行三层结构到底怎么分

禅道的组织逻辑是「产品 → 项目 → 执行」三层。产品管的是「做什么」，也就是需求池和发布计划；项目管的是「什么时候做完」，也就是一个阶段的交付目标；执行管的是「谁在几天内做完哪件事」，也就是任务和Bug的落地单元。

常见做法是：一个产品线对应一个产品，一个季度对应一个项目，一个迭代对应一个执行。比如某公司做一款后台管理系统，产品叫「运营后台」，项目叫「2024 Q3 迭代」，执行叫「Sprint 12」。需求挂产品，任务挂执行，Bug可以挂执行也可以挂产品。这样分层的好处是：需求变更不影响任务排期，任务延期能追溯到具体执行。

我一般会建议团队先画一张三层对照表，把现有工作项往里塞，塞不进去的说明流程本身有问题。手册里对这三层的定义写得很清楚，但真正落地时要结合团队规模——五个人的团队可以产品项目合一，二十人以上就必须分开，否则需求池会变成一锅粥。

2.2 角色权限矩阵：别让开发拥有删除需求的权限

禅道内置了管理员、产品经理、项目经理、研发、测试、访客等角色。默认权限比较宽松，很多团队直接沿用，结果就是开发能改需求状态、测试能关Bug、访客能看所有项目。这不是禅道的问题，是权限没配。

下面这张表是我在多个团队落地后总结的最小权限矩阵，可以直接对照后台「组织 → 权限」去配：

配置路径是「后台 → 组织 → 权限 → 分组」，先建分组再挂用户。注意一点：禅道的权限是「分组继承」，如果一个人同时在多个分组，权限会叠加。所以不要把一个人塞进多个分组，宁可单独建一个定制分组。

提示：配完权限后，用每个角色的测试账号实际点一遍，确认「不该看到的菜单确实看不到」，这一步比看配置页面靠谱得多。

3. 需求到任务到Bug的闭环：把手册里的流程变成可执行步骤

概念理清之后，进入真正的落地环节。禅道的核心价值在于「需求 → 任务 → Bug → 版本」这条闭环，任何一环断了，数据就不可信。这一章按操作顺序拆成可抄的步骤。

3.1 需求创建与评审：字段怎么填才不会被返工

需求是闭环的起点。禅道需求表单里有几个字段经常被乱填：来源、优先级、预计工时、验收标准。来源要写清楚是「用户反馈」「竞品分析」还是「内部规划」，否则后期追溯时找不到依据；优先级建议只用「高/中/低」三档，不要用数字，数字容易引发争论；预计工时是给项目经理排期用的，不是给开发承诺的，填个大概即可；验收标准必须写，而且要写成「可验证的句子」，比如「点击导出按钮后，10秒内生成包含全部字段的Excel文件」，而不是「导出功能正常」。

操作步骤：进入「产品 → 需求 → 新增需求」，填写标题、描述、验收标准，选择来源和优先级，指派给产品经理自己，状态设为「草稿」。然后走评审：由项目经理和研发负责人确认后，状态改为「激活」。评审不通过就改回「草稿」并注明原因。

-- 查询某产品下所有未评审的需求，用于每日站会同步 SELECT id, title, pri, status, openedBy, openedDate FROM zt_story WHERE product = 1 AND status = 'draft' AND deleted = '0' ORDER BY pri ASC, openedDate DESC;

这段SQL直接查禅道数据库的zt_story表，product = 1换成实际产品ID，status = 'draft'筛出草稿状态的需求。逻辑是：站会前跑一遍，把未评审的需求列出来，避免需求池里堆着没人管。参数说明：pri是优先级，1最高；deleted = '0'表示未删除。注意不要在生产库直接改数据，查询用只读账号。

3.2 任务拆解与工时登记：颗粒度控制在半天以内

需求激活后，项目经理要把它拆成任务。禅道的任务是挂在执行下的，一个需求可以拆多个任务。拆解的颗粒度建议控制在半天以内，超过一天的继续拆。原因很简单：任务太大，进度就是黑匣子；任务太小，管理成本超过收益。

操作路径：「执行 → 任务 → 批量新增」，选择所属需求，填写任务名称、预计工时、指派给具体开发。开发每天下班前更新「已消耗工时」和「剩余工时」，这两个数字是燃尽图的数据源。很多团队燃尽图不准，就是因为工时是周末补填的，不是每天填的。

# 用禅道API批量创建任务（需替换实际域名和Token） curl -X POST "https://zentao.example.com/api.php/v1/tasks" \ -H "Token: your-api-token" \ -H "Content-Type: application/json" \ -d '{ "execution": 12, "name": "完成用户列表分页接口", "story": 34, "estimate": 4, "assignedTo": "dev_a", "type": "devel" }'

这段命令调用禅道REST API创建任务。execution是执行ID，story是关联需求ID，estimate是预计工时（小时），assignedTo是禅道用户名。逻辑说明：批量创建时把任务信息写成JSON数组循环调用即可。参数说明：Token在「后台 → 二次开发 → API」里生成，注意Token权限要限制，不要用管理员Token做自动化。如果返回403，先检查Token是否过期或权限不足。

3.3 Bug流转与解决验证：状态机不能跳步

Bug是闭环里最容易乱的一环。禅道Bug状态有「激活 → 已解决 → 已关闭」，中间还有「已确认」「已延期」等。常见错误是开发直接点「关闭」，跳过了测试验证。正确流程是：测试提交Bug（激活）→ 开发解决（已解决）→ 测试验证（关闭或重新激活）。

操作上，测试提交Bug时要写清楚「重现步骤」「期望结果」「实际结果」，最好附截图。开发解决时填「解决方案」和「解决版本」。测试验证不通过就点「重新激活」，并注明原因。这样每个Bug都有完整轨迹，后期复盘时能查到是谁在哪个版本引入的。

注意：如果团队用Git提交代码，可以在commit message里写「fix #BugID」，禅道支持通过集成自动关联提交记录，省去手动填写的麻烦。

4. 禅道部署与数据维护：手册里没细说的运维细节

手册通常重点讲功能，但部署和数据维护才是长期使用的根基。这一章讲三个实操点：环境选择、备份策略、性能调优。

4.1 部署方式选择：一键安装包还是源码部署

禅道提供一键安装包和源码部署两种方式。一键安装包适合五十人以下团队，内置Apache、MySQL、PHP，解压即用，缺点是升级麻烦、目录结构固定。源码部署适合有运维能力的团队，可以自定义PHP版本、数据库参数、域名和HTTPS。

我一般会建议：如果团队没有专职运维，直接用一键安装包，把精力放在流程上而不是环境上。如果有运维，源码部署更灵活。部署时注意三点：数据目录要单独挂盘，方便备份和扩容；PHP的memory_limit调到256M以上，否则大附件上传会失败；MySQL的max_allowed_packet调到16M以上，避免导入大数据时中断。

4.2 备份策略：数据库和附件必须一起备

禅道的数据分两部分：数据库（需求、任务、Bug等）和附件（上传的图片、文档）。只备数据库不备附件，恢复后附件全丢；只备附件不备数据库，数据全丢。所以备份脚本要同时处理两者。

#!/bin/bash # 禅道每日备份脚本：数据库+附件，保留最近7天 BACKUP_DIR="/data/zentao_backup" DATE=$(date +%Y%m%d) ZENTAO_DIR="/opt/zentao" # 备份数据库 mysqldump -uzentao -p'your_password' zentao | gzip > "$BACKUP_DIR/db_$DATE.sql.gz" # 备份附件目录 tar -czf "$BACKUP_DIR/attachments_$DATE.tar.gz" "$ZENTAO_DIR/www/data/upload" # 删除7天前的备份 find "$BACKUP_DIR" -name "*.gz" -mtime +7 -delete echo "Backup completed: $DATE"

脚本逻辑：先mysqldump导出数据库并压缩，再tar打包附件目录，最后用find清理过期文件。参数说明：-uzentao -p'your_password'换成实际数据库账号；zentao是数据库名；附件路径根据实际部署调整，一键安装包通常在/opt/zentao/www/data/upload。注意把脚本加入crontab，每天凌晨执行，并且定期做恢复演练——备份不验证等于没备份。

4.3 性能调优：数据量大了之后怎么不卡

禅道用了一两年后，需求、任务、Bug表可能几十万行，页面开始变慢。常见优化手段有三个：给zt_story、zt_task、zt_bug的product、execution、status字段加索引；定期归档已关闭的Bug和已完成的任务到历史表；关闭不必要的插件和统计报表。

-- 为常用查询字段添加索引 ALTER TABLE zt_bug ADD INDEX idx_product_status (product, status); ALTER TABLE zt_task ADD INDEX idx_execution_status (execution, status); ALTER TABLE zt_story ADD INDEX idx_product_status (product, status);

这段SQL给三张核心表加联合索引。逻辑说明：禅道列表页最常用的查询是「某产品下某状态的Bug」「某执行下某状态的任务」，联合索引能显著减少扫描行数。参数说明：加索引前先用EXPLAIN看执行计划，确认确实走了全表扫描再加；加索引会锁表，建议在低峰期操作。如果数据量特别大，考虑分表或归档，不要一味加索引。

5. 避坑与常见问题：那些手册不会写的血泪经验

这一章是我在多个团队落地禅道时踩过的坑，每条按「现象 → 原因 → 解决」写，希望能帮你省下一些后悔药。

现象一：燃尽图一直是一条直线，没有任何下降趋势。原因：开发没有每天登记工时，或者任务预计工时填得太大，导致剩余工时变化不明显。解决：强制要求每天下班前更新工时，任务拆解到半天以内，项目经理每天站会检查工时登记情况。如果连续三天没更新，直接在站会上点名。

现象二：需求状态混乱，有的已发布还在改，有的已关闭又被激活。原因：没有定义状态流转规则，谁都能改状态。解决：在「后台 → 流程 → 需求」里自定义状态流转，限制只有产品经理能激活和关闭需求，研发只能查看。同时约定：已发布的需求如果要改，必须新建一个需求并关联原需求，不能直接改。

现象三：Bug解决后测试没验证就关闭了，上线后问题复现。原因：开发图省事直接关闭，或者测试没收到验证通知。解决：在权限里去掉研发的「关闭Bug」权限，只保留「解决」；配置邮件通知，Bug状态变为「已解决」时自动通知测试负责人。另外约定：关闭Bug必须填写「验证结果」，否则不允许提交。

现象四：禅道页面越来越慢，列表页要等十几秒。原因：数据量增长后没有加索引，或者附件目录放在系统盘导致IO瓶颈。解决：按上一章的SQL加索引，附件目录迁移到独立数据盘，定期归档历史数据。如果还慢，检查MySQL的慢查询日志，找出具体拖慢的SQL。

现象五：团队成员不愿意用，还是回到聊天工具派活。原因：禅道操作比聊天工具麻烦，而且没有和现有工作流打通。解决：把禅道通知接入团队常用的沟通工具，减少切换成本；项目经理带头在禅道里更新任务，而不是在聊天里问进度；初期可以只要求开发更新任务状态，不要求填工时，降低抵触。等大家习惯了再逐步加要求。

提示：避坑的核心不是记住这些条目，而是建立「数据可信」的文化。禅道只是工具，如果团队不认真填，再好的工具也是摆设。

6. 进阶技巧：用API和Webhook把禅道接进现有工作流

禅道用顺之后，下一步是把它接进现有工作流，减少手动操作。这一章讲两个具体技巧：用API自动同步任务状态，用Webhook把Bug通知推到沟通工具。

6.1 用API做每日进度同步

很多团队每天早上要手动整理进度发日报，其实可以用禅道API自动拉取。下面这段Python脚本拉取指定执行下的任务状态，生成简版日报。

import requests import json from datetime import date BASE_URL = "https://zentao.example.com/api.php/v1" TOKEN = "your-api-token" EXECUTION_ID = 12 headers = {"Token": TOKEN} # 拉取执行下的任务列表 resp = requests.get(f"{BASE_URL}/executions/{EXECUTION_ID}/tasks", headers=headers) tasks = resp.json().get("tasks", []) # 按状态分组统计 summary = {} for t in tasks: status = t.get("status", "unknown") summary.setdefault(status, []).append(t.get("name")) # 输出日报 print(f"日期：{date.today()}") for status, names in summary.items(): print(f"\n[{status}] 共{len(names)}项") for n in names: print(f" - {n}")

脚本逻辑：调用/executions/{id}/tasks接口拉取任务列表，按status字段分组，输出每个状态下的任务名称。参数说明：TOKEN换成实际Token，EXECUTION_ID换成当前迭代ID。注意API有频率限制，不要每秒调用；建议每天定时跑一次，结果推送到沟通工具。如果返回数据为空，检查执行ID是否正确、Token是否有该执行的查看权限。

6.2 用Webhook把Bug通知推到沟通工具

禅道支持Webhook，可以在Bug创建、解决、关闭时触发HTTP请求。配置路径：「后台 → 通知 → Webhook → 添加」。填写回调地址（沟通工具的机器人Webhook），选择触发事件，保存后测试。

{ "msgtype": "markdown", "markdown": { "content": "**禅道Bug通知**\n> 项目：运营后台\n> Bug：登录页验证码不刷新\n> 状态：激活\n> 指派：dev_a\n> [查看详情](https://zentao.example.com/bug-view-123.html)" } }

这段JSON是推送到沟通工具的报文格式。逻辑说明：禅道Webhook会把Bug信息以变量形式传入，需要在Webhook配置里用{title}、{status}等占位符替换。参数说明：msgtype根据沟通工具调整，content里的链接要换成实际禅道地址。注意Webhook地址要加白名单，避免被滥用；如果通知太频繁，可以在禅道里设置「合并通知」或只对高优先级Bug触发。

6.3 一个我坚持了多年的习惯

我每接手一个新团队，第一件事不是配禅道，而是先跟团队一起把「需求、任务、Bug」三个词的定义对齐。定义不清楚，配再多权限、写再多脚本都是白搭。第二件事是每周五花十分钟看一遍禅道的统计报表，重点看「未关闭Bug数」和「任务延期率」，这两个指标能提前暴露问题。第三件事是每季度做一次数据清理，把已关闭超过半年的Bug归档，保持列表页清爽。

这些习惯看起来简单，但坚持下来，禅道就不再是一个「被迫使用的系统」，而是团队自己的进度看板。希望帮到你。

本文还有配套的精品资源，点击获取