禅道系统升级必须严格遵循覆盖安装与在线迁移双阶段流程：先全量备份数据库、附件及配置文件，再覆盖新版本程序文件，最后通过upgrade.php执行Web端数据库迁移；Docker环境需切换镜像并复用数据卷；项目集模式需人工完成历史数据归并。

如果您当前运行的禅道系统版本较低，需更新至更高稳定版本以获得功能增强与安全修复，则升级过程必须严格遵循覆盖安装与在线迁移双阶段流程。以下是完成禅道系统版本升级的具体步骤：

一、升级前全量备份

备份是升级操作不可跳过的前置保障，用于在升级异常时快速回滚至可用状态。需同时保存数据库文件、附件目录及程序配置文件。

1、确认数据库默认路径：/opt/zbox/data/mysql（Linux ZBOX集成环境）或通过禅道后台【后台→系统设置→备份】执行一键备份。

2、手动备份附件目录：/opt/zbox/app/zentao/www/data/upload，使用命令：cp -rp /opt/zbox/app/zentao/www/data/upload /backup/upload_$(date +%Y%m%d)。

3、备份整个禅道程序目录：/opt/zbox/app/zentao，执行：mkdir zbox_$(date +%Y%m%d) && cp -rp /opt/zbox/app/zentao zbox_$(date +%Y%m%d)/。

二、覆盖新版本程序文件

升级本质是用新版源码覆盖旧版程序逻辑，禁止移动旧目录或解压嵌套子目录，否则将导致路径错误与功能失效。

1、从禅道官网下载对应版本的.zip结尾的源码包（专业版用户须联系客服获取专用升级包，严禁使用.exe安装包）。

2、解压获得zentaopms文件夹，进入该目录：unzip ZenTaoPMS-21.7.6-php7.4.zip。

3、执行覆盖操作：cp -rf zentaopms/* /opt/zbox/app/zentao/（注意末尾斜杠，确保内容而非文件夹被复制）。

4、验证覆盖完整性：检查/opt/zbox/app/zentao/www/index.php等核心文件修改时间是否已更新为当前时间。

三、执行Web端升级向导

程序文件覆盖后，数据库结构与业务数据仍为旧版格式，需通过upgrade.php触发SQL迁移与索引重建。

1、浏览器访问：http://[服务器IP]:[端口]/zentao/upgrade.php（如使用ZBOX默认端口则为80或81）。

2、页面提示创建ok.txt文件于/opt/zbox/app/zentao/www/目录下，执行：touch /opt/zbox/app/zentao/www/ok.txt。

3、点击“下一步”，系统自动识别原版本并列出待执行SQL语句，确认无误后提交执行。

4、根据提示分步删除指定临时文件（实践中常需重复删除+刷新两次），直至显示“升级成功”。

四、Docker环境专项升级

对于容器化部署的禅道实例，升级需切换镜像并保留挂载卷数据，避免容器重建导致数据丢失。

1、停止当前容器：docker stop zentao（假设容器名为zentao）。

2、拉取新版本镜像：docker pull hub.zentao.net/app/zentao:21.7.6。

3、确认数据卷挂载路径（如/data/zentao），确保新容器启动时复用同一卷。

4、以相同参数启动新镜像容器：docker run -d --name zentao-new -p 8080:80 -v /data/zentao:/data/zentao hub.zentao.net/app/zentao:21.7.6。

5、访问新容器地址，按upgrade.php流程完成剩余迁移步骤。

五、项目集模式迁移适配

若目标版本（如20.0+）启用全新项目集管理模式，升级后需人工介入完成历史数据归并，系统不自动转换。

1、登录升级后的禅道，进入【后台→自定义→模式】，选择全新项目集管理模式并保存。

2、访问【后台→数据迁移】，根据实际组织结构选择迁移方案：以产品线组织的产品和迭代、以产品组织的迭代、独立的迭代或关联多个产品的迭代。

3、在每种方案中，分别指定目标项目集、目标项目，并配置访问权限与基本信息。

4、勾选待迁移条目，点击开始迁移，等待后台任务完成。