当前位置：首页 > news >正文

禅道开源版 11.5 → 22.4 完整升级方案

news 2026/8/5 2:52:00

⚠️最重要前置结论

一、环境差异重大提醒（极易踩坑）

二、升级前标准准备（必做）

1. 完整备份（每一步升级前都执行）

2. 下载对应版本【源码包 ZIP】

3. 业务窗口

三、通用单版本升级操作流程（每个过渡版本重复这套操作）

四、分段升级重点注意事项

① 11.5 → 12.5.3

② 12.5.3 → 16.5

③ 16.5 → 17.8【最重要分水岭！】

④ 17.8 → 18.13

⑤ 18.13 → 22.4

五、更稳妥的备选方案（强烈推荐生产环境优先考虑）

六、高频故障预案

七、补充提问（你回复我，可以给你针对性命令 / 排错）

⚠️最重要前置结论

11.5 不能直接一步升级到 22.4！跨 1 个大版本，数据库结构、PHP 语法、框架全部重构，必须分段过渡升级。官方推荐过渡路线（经过大量社区验证最稳路线）：

11.5 → 12.5.3 → 16.5 → 17.8 → 18.13 → 22.4

硬性规则：每升级完成一个版本，必须完整备份；优先搭建测试服务器完整跑通全部流程，再操作生产环境！

一、环境差异重大提醒（极易踩坑）

禅道 11.5
- PHP：5.6 / 7.0
- MySQL：5.5 / 5.6
12.5.3 /16.5
- PHP7.1~7.4
17.x ~ 18.13
- PHP 最低 7.4，推荐 7.4~8.1
- MySQL 建议 ≥5.7
禅道 22.4
- PHP：7.4 ~ 8.2（不再支持 PHP5.x）
- MySQL：5.7 / 8.0（强烈建议 MySQL8.0，utf8mb4）

关键：如果你是官方一键安装包（Windows/Linux zbox）前期 11.5→12.5.3 可以使用内置环境；升级到 17.8 前后，旧环境内置 PHP5.6/MySQL5.6 会无法继续！两种选择：方案 A（推荐）：升级到 18.13 之后，新建 22.4 一键包，导出 18.13 数据库 + 附件迁移到新环境方案 B：分步替换 zbox 集成环境，风险更高。

二、升级前标准准备（必做）

1. 完整备份（每一步升级前都执行）

两种备份同时做，双重保险： 1）禅道后台备份：后台 → 系统 → 备份（下载 sql、附件文件包） 2）命令行物理备份（Linux 一键包示例）

# 停止服务 /opt/zbox/zbox stop # 备份整个zbox目录 cp -r /opt/zbox /opt/zbox_11.5_backup # 数据库单独导出 /opt/zbox/bin/mysqldump -u root -p zentao > zentao_11.5.sql /opt/zbox/zbox start

Windows 一键包：直接复制整个xampp/zbox文件夹作为完整备份。

2. 下载对应版本【源码包 ZIP】

❗不要下载一键安装包 exe/tar！升级只用 ZenTaoPMS.x.x.stable.zip（源码包）下载地址：https://www.zentao.net/download.html 搜索版本号需要下载：

ZenTaoPMS.12.5.3.stable.zip
ZenTaoPMS.16.5.stable.zip
ZenTaoPMS.17.8.stable.zip
ZenTaoPMS.18.13.stable.zip
ZenTaoPMS.22.4.stable.zip

3. 业务窗口

选择无人使用时段，升级期间禁止所有人操作禅道。

三、通用单版本升级操作流程（每个过渡版本重复这套操作）

适用于：Linux 一键包 / Windows 一键包

停止禅道服务
解压源码包，得到文件夹zentaopms
覆盖文件
- Linux 一键包：cp -rf zentaopms/* /opt/zbox/app/zentao/
- Windows 一键包：把 zentaopms 内全部文件复制到xampp\zentao\✅重点：不要复制成/zentao/zentaopms/，路径嵌套会直接报错！
启动 Apache+MySQL 服务
浏览器访问升级地址：http://你的地址/zentao/upgrade.php
按照页面向导执行数据库升级，等待 SQL 脚本执行完毕，不要中途关闭页面
升级成功后登录禅道，检查：项目、bug、任务、附件、文档是否正常
立刻再次完整备份！确认无误，再进行下一个版本升级

四、分段升级重点注意事项

① 11.5 → 12.5.3

12.x 是重要分水岭，大量数据表结构调整
升级后登录检查附件链接是否有效
若 PHP 是 5.6，可以正常运行到此版本

② 12.5.3 → 16.5

功能模块重构，注意自定义视图、自定义字段
旧插件大概率失效，升级前全部禁用第三方插件

③ 16.5 → 17.8【最重要分水岭！】

17.0 开始启用全新【项目集架构】，旧项目结构迁移关键点
PHP5.6 彻底不再支持！

⚠️如果你使用老旧一键安装包内置 PHP5.6：升级到 17.8 一定会报 PHP 语法错误！解决办法二选一：方式 1：新建搭载 PHP7.4+MySQL5.7 的禅道一键包，把 16.5 备份导入新环境，再升级 17.8 方式 2：升级 zbox 集成环境（操作复杂，不推荐新手）

④ 17.8 → 18.13

稳定过渡版本，建议停留验证 1~2 天，确认所有业务正常

⑤ 18.13 → 22.4

22 系列前端全面重构，UI 大改版；API、权限体系调整升级完成后：

清理缓存：zentao/tmp/下 cache 目录清空
管理员进入后台，检查角色权限，部分权限会重置
旧客户端、第三方集成接口（api）需要测试适配

五、更稳妥的备选方案（强烈推荐生产环境优先考虑）

不原地逐级升级，采用「迁移升级法」，故障回滚最简单

测试服务器原地逐级升级：11.5 →12.5.3→16.5→17.8→18.13→22.4，验证全部数据、附件、功能正常
生产环境操作： 1）停机，完整备份 11.5 数据 2）全新部署禅道 22.4 一键安装包3）在测试环境把数据逐级升到 22.4，导出最终 SQL + www/upload 附件目录 4）导入到新 22.4 环境优点：旧环境完整保留，一旦新版有问题，随时切回旧 11.5；避免生产环境长时间逐级升级风险。

六、高频故障预案

upgrade.php 空白 / 500 错误
- PHP 版本不匹配；文件覆盖路径错误；目录权限不足
- Linux：chmod -R 755 /opt/zbox/app/zentao && chmod -R 777 /opt/zbox/app/zentao/tmp
升级页面执行 SQL 报错不要强行刷新！恢复上一个版本备份，核对升级顺序是否跳版本
附件打不开、图片裂图检查www/upload文件夹完整复制，权限读写开启
登录成功，页面功能报错 SQL 不存在字段典型跳版本升级导致数据库结构不兼容，只能回滚，严格按顺序升级