禅道开源版 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
硬性规则：每升级完成一个版本，必须完整备份；优先搭建测试服务器完整跑通全部流程，再操作生产环境！
一、环境差异重大提醒（极易踩坑）
- 禅道 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 startWindows 一键包：直接复制整个
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/，路径嵌套会直接报错！
- Linux 一键包：
- 启动 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 不存在字段典型跳版本升级导致数据库结构不兼容，只能回滚，严格按顺序升级
七、补充提问（你回复我，可以给你针对性命令 / 排错）
- 当前部署方式：Linux 一键包 / Windows 一键包 / 源码独立部署（宝塔等）？
- 当前 PHP、MySQL 版本？
- 是否有自定义插件、二次开发代码？
- 是否有第三方系统调用禅道 API？