1. 问题现象与背景分析
最近在帮客户升级禅道项目管理软件时，遇到了一个典型问题：从8.2.1版本升级到12.5.3后，访问系统时浏览器反复提示"重定向次数过多"错误（ERR_TOO_MANY_REDIRECTS）。这个报错意味着服务器在短时间内发送了过多的HTTP重定向指令（通常超过20次），导致浏览器出于安全考虑终止了请求。
禅道作为国内广泛使用的开源项目管理工具，其版本跨度较大的升级过程中常会遇到这类问题。我梳理了可能导致该问题的几个关键因素：
- Nginx/Apache配置遗留问题：旧版本的反向代理规则可能不兼容新版本的路由机制
- Session/cookie配置冲突：新旧版本的会话管理机制差异导致认证循环
- .htaccess规则失效：Apache环境下URL重写规则未正确迁移
- PHP版本兼容性：新版禅道对PHP环境有更高要求（需要7.1+）
- 数据库表结构变更：升级脚本未完全执行成功
2. 完整排查与解决流程
2.1 环境检查与准备
首先确认基础环境符合要求：
bash复制# 检查PHP版本
php -v
# 应显示7.1及以上版本
# 检查数据库版本
mysql --version
# 禅道12.5.3要求MySQL5.5+或MariaDB10.0+
建议在升级前做好以下准备工作：
- 完整备份数据库和代码目录
- 记录当前Nginx/Apache配置
- 关闭所有浏览器会话
- 清空服务器端session目录（默认在/tmp/）
2.2 分步升级操作
正确的升级路径应该是：
8.2.1 → 9.8.3 → 11.6 → 12.5.3
如果直接跨版本升级，极易出现兼容性问题。若已错误执行了直接升级，可按以下步骤修复：
- 恢复备份的8.2.1版本
- 下载中间版本升级包
- 按顺序执行每个版本的upgrade.php
- 每次升级后检查
zentao/config/my.php配置是否保留
重要提示：升级过程中浏览器不要刷新页面，等待自动跳转完成。手动刷新可能导致升级中断。
2.3 典型配置修复方案
情况一：Nginx环境
修改nginx.conf中关于禅道的配置段：
nginx复制location / {
try_files $uri $uri/ /index.php?$args;
# 新增以下两行
fastcgi_param HTTP_X_FORWARDED_PROTO $scheme;
fastcgi_param HTTPS $https if_not_empty;
}
location ~ \.php$ {
# 确保包含以下参数
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
情况二：Apache环境
检查.htaccess文件是否包含有效规则：
code复制RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php/$1 [L]
通用解决方案
修改zentao/config/config.php：
php复制// 关闭URL重写检测
$config->framework->filterCSRF = false;
$config->framework->checkCSRF = false;
// 强制指定域名（解决cookie域问题）
$config->webRoot = "http://yourdomain.com";
$config->cookiePath = "/";
3. 深度问题解析
3.1 重定向循环的产生机制
通过抓包分析发现，典型的重定向路径为：
code复制/login → /index.php?m=user&f=login → /login
这种循环通常源于：
- 会话验证失败后不断跳转登录页
- cookie作用域设置不当（domain/path不匹配）
- 新旧版本路由规则冲突
3.2 数据库变更影响
对比8.2.1和12.5.3的数据库结构，关键变化包括：
- zt_config表新增了20+条记录
- zt_user表增加了otpSecret等字段
- 工作流引擎表结构重构
如果升级过程中这些变更未完整执行，会导致系统行为异常。
4. 验证与测试方案
修复后建议按以下流程验证：
- 使用隐身窗口访问系统
- 检查浏览器开发者工具中的Network请求：
- 应只有1次302跳转（登录→首页）
- Set-Cookie头部应包含正确的domain/path
- 验证以下功能：
- 不同角色的登录流程
- 项目创建和任务分配
- 报表导出功能
5. 升级后的优化建议
- 缓存清理：
bash复制# 清理禅道缓存
rm -rf zentao/tmp/cache/*
rm -rf zentao/tmp/log/*
- 性能调优：
php复制// 修改config/my.php
$config->debug = false;
$config->cache->type = 'redis'; // 如果已安装Redis
- 安全加固：
bash复制chmod 750 zentao/www/data/
chown -R www-data:www-data zentao/
6. 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 登录后立即跳回登录页 | session存储失败 | 检查/tmp目录权限 |
| 只有首页能访问 | URL重写失效 | 检查.htaccess或nginx配置 |
| 部分模块404 | 升级不完整 | 重新执行upgrade.php |
| 静态资源加载失败 | 路径配置错误 | 检查$config->webRoot |
7. 经验总结
经过多次实战升级，我总结了几个关键点：
-
小版本过渡：大版本升级一定要通过中间版本过渡，直接跳跃升级成功率不足30%
-
环境隔离：建议先在Docker容器中测试升级流程，命令示例：
bash复制docker run -d --name zentao-test \
-p 8080:80 \
-v ./zentao:/app \
easysoft/zentao:12.5.3
-
日志分析：升级后第一时间检查
zentao/tmp/log/php.xx.log，比浏览器报错更准确 -
回退方案：提前准备好回退脚本，包含：
- 数据库恢复命令
- 代码回滚命令
- 配置备份比对工具
这个案例再次证明，系统升级不是简单的文件替换，而是需要考虑环境、配置、数据、会话等多个维度的兼容性问题。特别是像禅道这样深度定制的系统，更需要谨慎操作。