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

目录

⚠️最重要前置结论

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

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

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

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

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

关键：如果你是官方一键安装包（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 一键包

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

① 11.5 → 12.5.3

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

② 12.5.3 → 16.5

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

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

⚠️如果你使用老旧一键安装包内置 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）需要测试适配

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

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

六、高频故障预案

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