Jira迁移实战指南：从备份到故障排查的全链路避坑手册

迁移Jira系统就像在雷区跳舞——表面上看只是数据搬运，实际每个环节都暗藏杀机。上周我们团队刚完成一次从CentOS 7到新服务器的Jira 8.5迁移，过程中遭遇了附件消失、数据库拒绝握手、头像集体罢工等连环事故。本文将用血泪教训换来的经验，带你绕过那些官方文档从不会告诉你的深坑。

1. 迁移前的隐形准备工作

大多数人以为迁移就是从老服务器打个包扔到新环境，但真正的挑战往往始于准备阶段。我们第一次尝试时，备份文件虽然显示成功生成，恢复时却报错"corrupted backup"，后来发现是磁盘空间不足导致的静默失败。

必须检查的三个死亡陷阱：

• /var/atlassian/application-data/jira 目录需要至少两倍于当前使用空间
• 运行 df -h 确认/tmp分区剩余空间（Jira备份时会先解压到此）
• 用 du -sh attachments/ 统计附件实际大小，别相信管理界面显示的值

提示：在低峰期执行备份，避免有人上传大附件导致备份不一致

MySQL的版本兼容性也是个暗礁。虽然官方说支持5.7，但我们实测发现必须锁定在5.7.32-35之间。其他版本会出现如下症状：

症状表现	可能版本问题	解决方案
表结构导入失败	MySQL >5.7.35	降级到5.7.32
特殊字符乱码	字符集非utf8mb4	重建库指定字符集
索引丢失	不同小版本排序规则差异	导出时添加--hex-blob参数

2. 附件迁移的权限迷宫

当我们在新环境欢呼雀跃地看到项目列表完整恢复时，点击附件却只得到404错误。检查发现所有文件都在，但Jira就是拒绝展示——这是Linux权限系统的经典陷阱。

分步解决附件不可见问题：

1. 先用 ps aux | grep jira 确认运行用户（通常是jira）
2. 执行 chown -R jira:jira /var/atlassian/application-data/jira/attachments
3. 关键一步：chmod -R 750 而非755，否则可能触发安全限制

头像不显示的问题更隐蔽。除了检查avatars目录权限，还需要：

# 重建头像缓存（无任何输出但能解决问题）
curl -u admin:password -X POST http://localhost:8080/rest/api/2/user/avatar/rebuild

3. 数据库连接的地狱级难题

"Communications link failure"这个报错足以让任何运维人员血压飙升。我们花了三天时间才发现根本与网络、权限无关，而是MySQL Connector的SSL协议作祟。

终极解决方案矩阵：

尝试方案	效果评估	推荐指数
调整my.cnf等待超时参数	完全无效	★
降级JDK版本	可能引入其他兼容性问题	★★
禁用SSL连接	部分环境有效	★★★
替换connector-java版本	100%解决问题	★★★★★

实测有效的connector-java文件替换流程：

# 进入容器或安装目录
cd /opt/atlassian/jira/lib

# 备份原文件（重要！）
mv mysql-connector-java-*.jar mysql-connector-java.jar.bak

# 获取特定版本（必须5.1.49）
wget https://repo1.maven.org/maven2/mysql/mysql-connector-java/5.1.49/mysql-connector-java-5.1.49.jar

# 建立软链接
ln -s mysql-connector-java-5.1.49.jar mysql-connector-java.jar

4. 那些官方文档没写的配置陷阱

迁移后最常见的"基础URL不正确"错误，其实暗藏三个需要联动的配置点：

1. server.xml 中的Scheme和Proxy设置：

<Connector port="8080" 
           scheme="https" 
           proxyName="jira.yourdomain.com" 
           proxyPort="443"/>

2. 数据库中的base_url记录（需直接操作数据库）：

UPDATE propertystring SET propertyvalue = 'https://jira.yourdomain.com' 
WHERE id IN (SELECT id FROM propertyentry WHERE property_key = 'jira.baseurl');

3. 系统配置文件jira-config.properties：

jira.webserver.https.port=443
jira.webserver.http.port=80

5. 事后验证的黄金检查清单

完成所有步骤后，建议按此清单逐项验证：

• [ ] 所有项目附件可预览下载
• [ ] 用户头像在问题页面和仪表盘均正常显示
• [ ] 过滤器订阅邮件中的链接指向新域名
• [ ] 第三方插件（如ScriptRunner）的许可证未失效
• [ ] 定时任务历史记录完整迁移

最后分享一个救命技巧：在/var/atlassian/jira/logs/catalina.out中搜索"SEVERE"和"ERROR"，能提前发现90%的潜在问题。我们迁移后三天突然出现性能暴跌，就是靠这个发现有个插件在疯狂写调试日志。