私有化项目管理平台二次开发与接口对接指南

私有化部署的项目管理平台，数据留在企业自己的内网里，权限、网络和升级节奏都可控。代价是，当企业要把禅道和 CI/CD、报表系统、OA、即时通讯打通，或者想按自己的流程改造功能时，没有现成的 SaaS 开关可用，得自己完成二次开发和接口对接。这篇指南面向负责这套系统的技术负责人、后端和运维工程师，讲清三条可选路径各自适合什么、动手前要准备什么、接口怎么对接、扩展怎么写，以及上线后怎么验证和回退。

私有化项目管理平台二次开发的三条技术路径

私有化环境里的二次开发，落到动作上无非三条路：调接口、改扩展、读数据库。它们能解决的问题和引入的风险差别很大，先选对路径，后面的返工能少很多。

下面这张表对照三条路径的适用场景、改动范围、升级影响和主要风险，帮你先做一次取舍。

取舍的顺序是：数据交换优先用 API，必须改功能时走扩展开发，只有前两者覆盖不到、并且能接受只读与结构变动风险时，才考虑直连数据库。

什么时候该走 API，什么时候必须动扩展

判断标准只有一条：需求只涉及把数据拿出去或写进来，用 API；需求涉及界面、字段、流程、审批逻辑本身要变，就动扩展。让代码提交记录自动关联到缺陷，用 API 或 Webhook 就能完成；给需求加一组企业特有的评审字段，并让状态按自定义规则流转，就属于扩展开发。禅道本身带工作流配置能力，一部分流程调整不写代码也能完成，动手前值得先确认工作流配置是否已经覆盖。

数据库直读的边界

数据库直读适合离线数仓抽取和自建报表，但有明确边界。禅道的表结构会随版本升级调整，直接写库还可能绕过业务校验，留下不一致数据。确实需要直连时，只读、只取、不写是底线，同时记录所依赖的表和字段对应的版本。

动手前的环境与权限准备

私有化环境里的一次改动，影响的是企业自己正在用的系统。开工前有几件事先落定，能避免在联调阶段卡住。

先核对版本，再选文档

禅道在不同时期提供过不同的接口形式。较新版本提供 RESTful 风格 API，路径通常形如 /api.php/v2/...；更早的版本使用 zentaoPHP 原生的页面 JSON 调用和超级 model 接口。先确认自己环境的版本，再决定照哪套文档对接，不要拿一套版本的调用方式套到另一套上。版本和接口清单以官方《禅道二次开发手册》为准。

建最小权限的服务账号

调用 API 和超级 model 接口，都要用专门的服务账号，并按需开通权限，超级 model 接口需要单独授权。按最小权限建号：只做报表的账号不给写权限，做集成的账号只开必要模块，出问题时便于定位和回收。

测试环境与备份

任何改动先在测试环境跑通，再上生产。上生产前备份代码目录和数据库，记录当前版本号，想清楚回退动作。选择私有化部署的企业，升级和回滚都掌握在自己手里，这一步不能省。

用 RESTful API 完成接口对接

接口对接最常走 RESTful API 这条路，流程分三步：拿凭证、带凭证调用、解析响应。

第一步：获取 Token

较新版本的禅道 API v2 采用 Token 认证。以官方二次开发手册的登录接口为例，向 /api.php/v2/users/login 发 POST 请求，请求体带账号和密码，响应里的 token 字段就是后续要用的凭证。

{    "account": "admin",    "password": "123Qwe!@#"}

成功时返回：

{    "status": "success",    "token": "llb8ocefb0kbgklif53j839k6l"}

Token 等同于账号身份，不要写死在前端代码或明文配置里，用服务端环境变量或密钥管理保存，并安排定期轮换。

第二步：带 Token 调用业务接口

后续请求都带上 token，调用创建任务、查询缺陷、拉取测试用例结果等接口。禅道对需求、任务、缺陷、测试用例、版本发布都有对应接口。先用只读接口确认鉴权打通，再切写接口，这样能把鉴权问题和业务参数问题分开定位。如果对接的是代码管理与流水线，可以一并了解禅道的 DevOps 对接能力，减少自己造轮子。

第三步：用超级 model 接口补齐未覆盖的数据

RESTful API 没覆盖的字段或方法，老的 zentaoPHP 还留着超级 model 调用接口，可以直接调某个模块 model 的公开方法。使用时通过 m=api&f=getModel 指定模块名和方法名，再传入参数。这类接口要求账号先开通超级 model 权限。

用 zentaoPHP 扩展机制做不改源码的定制

需求一旦落到功能本身，就进入扩展开发。zentaoPHP 采用“核心加扩展”的思路，正常做法是把改动写进扩展目录，升级时不被覆盖。

扩展目录的约定

禅道按模块组织代码，每个模块下可以放各自的 ext 目录，用来扩展控制器、模型、视图、语言包和配置。按框架的目录结构和命名约定写，框架会自动加载，不必改入口文件。这样做的价值是：升级时核心代码被替换，扩展目录里的内容保留，你只需要针对接口变化做少量适配。

新增独立模块

要加的是禅道原本没有的功能，可以在插件目录 extension/custom 下新建子目录，按约定分别实现 control、model、view、lang 等部分，就得到一个独立模块。模块名和控制器文件名必须用小写，命名不规范会直接导致模块加载失败。

覆盖核心逻辑的正确姿势

有些改动绕不开核心行为。zentaoPHP 提供了覆盖、钩子和 class 扩展等手段，让改动仍然写在扩展目录内。能用钩子就别整体覆盖，覆盖的核心逻辑越多，升级时要重新适配的面越大。

数据层对接：读懂禅道数据库结构

直连数据库做报表或抽取数据，先要读懂表设计。禅道的表名以 zt_ 开头，命名偏直白：zt_story 存需求，zt_task 存任务，zt_bug 存缺陷，zt_case 与 zt_testresult 分别存测试用例和执行结果，zt_project、zt_team 存项目和团队成员，组织相关的是 zt_user、zt_group、zt_grouppriv。

最新版本可以在后台的“二次开发 - 数据库”入口查看表说明。以当前环境的表结构为准，不要照搬旧版本文章里的表清单。

抽取建议做成只读账号加定时任务的组合，把结果落到独立报表库，不让查询直接压在生产库上。如果目的只是研发效能度量，先评估禅道自带的效能分析能力是否够用，能用现成看板解决的，不必另建一条数据链路。

上线验证、回退与常见故障排查

改动上线后要有可观察的验证结果，出问题能快速退回。

上线前的验证清单

• 接口连通性：用测试账号跑通登录、读接口、写接口各一条
• 数据一致性：对比接口返回与页面显示的关键字段
• 权限边界：用只读账号尝试写操作，应被拒绝
• 扩展生效：对应功能按预期变化，其他模块不受影响

回退方案

上线前备份代码目录和数据库；扩展改动记录文件清单；升级禅道前先在测试环境验证扩展兼容性。出现异常时按备份回滚，再定位问题，不要在生产环境边调边改。

常见故障对照

下面这张表汇总几类高频故障的现象、常见原因和处理方向，便于排查时快速定位。

排查顺序建议从鉴权到业务参数、再到扩展加载逐层缩小，多数问题落在版本不匹配和命名不规范两类原因上。

参考资料

• 禅道二次开发手册《获取 Token》：https://www.zentao.net/book/api/post-users-login-2142.html
• 禅道使用手册《禅道的数据库结构》：https://www.zentao.net/book/zentaopmshelp/157.html
• 禅道二次开发手册《API 机制简介》：https://www.zentao.net/book/extension-new/api-intro-1261.html
• 禅道二次开发手册《新增独立模块》：https://www.zentao.net/book/extension-new/module-1253.html