Doris 平滑升级实战指南：从1.2.1到2.0的关键步骤与避坑技巧

1. 为什么需要升级到Doris 2.0？

最近很多团队都在考虑将Doris从1.2.1升级到2.0版本，这确实是个值得投入精力的重要升级。我在实际生产环境中完成过多次Doris版本升级，2.0版本带来的性能提升和功能改进确实让人眼前一亮。最明显的变化是查询性能提升了30%以上，特别是在复杂分析场景下效果更为显著。新版本还优化了内存管理机制，减少了OOM（内存溢出）的风险，这对于数据量大的团队来说简直是福音。

不过升级过程并非一帆风顺，我遇到过不少坑。比如有一次没做好元数据兼容性测试，差点导致生产环境数据异常。还有一次因为没关闭集群均衡功能，升级过程中触发了不必要的副本迁移，导致升级时间延长了好几倍。这些经验教训让我意识到，虽然Doris支持滚动升级，但准备工作不到位很容易翻车。

2. 升级前的关键准备工作

2.1 关闭集群自动均衡功能

这个步骤看似简单，但很多团队都会忽略。我建议在升级前至少预留30分钟来做这些准备工作。具体要执行以下命令：

# 关闭普通表副本均衡 mysql-client > admin set frontend config("disable_balance" = "true"); # 关闭colocation表副本均衡 mysql-client > admin set frontend config("disable_colocate_balance" = "true"); # 关闭副本调度逻辑 mysql-client > admin set frontend config("disable_tablet_scheduler" = "true");

注意：这些配置变更只在当前FE节点有效，如果FE有多个节点，需要在每个FE节点都执行一遍。建议把这些命令保存成脚本，方便升级后恢复。

2.2 元数据备份不容忽视

我见过最惨痛的教训就是升级过程中元数据损坏。Doris的元数据存储在FE节点的doris-meta目录下，建议直接打包备份整个目录：

tar -zcvf doris-meta-backup-$(date +%Y%m%d).tar.gz /path/to/doris-meta

备份完成后，最好在测试环境验证下备份文件是否能正常恢复。有次我们团队就遇到过备份文件损坏的情况，幸好发现得早。

3. BE节点升级实战

3.1 逐个升级BE节点

BE节点的升级要采用滚动方式，一次只升级一个节点。我通常的步骤是：

1. 选择一个负载较低的BE节点开始
2. 替换二进制文件（注意保留conf和storage目录）
3. 重启BE节点
4. 观察日志be.INFO确认启动成功
5. 验证该节点数据服务正常后再处理下一个

# 查看BE日志是否正常 tail -f /path/to/be/log/be.INFO | grep 'BE start successfully'

如果启动失败，千万不要慌张。我遇到过的常见问题包括端口冲突、Java UDF函数缺失等。可以先尝试用旧版本二进制文件回退，排查问题后再升级。

3.2 Java UDF函数处理

从1.2版本开始，Doris支持Java UDF函数，但这也带来了新的依赖项。升级时需要特别注意：

# 下载Java UDF支持包 wget https://download.doris.com/udf-java-2.0.0.jar -P /path/to/be/lib/

缺少这个JAR包会导致BE启动失败，我在第一次升级时就栽在这个问题上，现在想起来还记忆犹新。

4. FE元数据兼容性测试

4.1 搭建测试环境

元数据兼容性测试是升级过程中最关键也最容易出问题的环节。我建议在独立环境中进行：

1. 准备一台测试机器（不要用生产环境的FE节点）
2. 修改fe.conf中的端口配置
3. 添加cluster_id=123456配置
4. 设置metadata_failure_recovery=true

# 测试环境fe.conf示例 http_port=8031 rpc_port=9021 query_port=9031 cluster_id=123456 metadata_failure_recovery=true

4.2 测试流程详解

完整的测试流程需要严格按步骤进行：

1. 拷贝生产环境的doris-meta到测试环境
2. 修改VERSION文件中的cluster_id
3. 启动测试FE并观察日志
4. 确认无严重错误后停止测试FE

# 修改cluster_id sed -i 's/cluster_id=.*/cluster_id=123456/' doris-meta/image/VERSION # 启动测试FE sh bin/start_fe.sh --daemon # 查看启动日志 tail -f log/fe.log | grep 'transfer from'

我曾经遇到过因为cluster_id没改导致测试FE意外连接到生产环境的情况，差点造成数据混乱。所以这个测试环节一定要谨慎。

5. 正式升级操作指南

5.1 文件替换注意事项

正式升级时，文件替换要特别注意：

• 保留conf目录（配置不变）
• 保留doris-meta目录（FE元数据）
• 保留storage目录（BE数据）
• 替换其他所有目录

我习惯用rsync来同步文件，可以避免误删：

rsync -av --exclude='conf' --exclude='doris-meta' \ /path/to/new/version/ /path/to/old/version/

5.2 节点重启顺序

经过多次实践，我总结出最稳妥的重启顺序：

1. 先升级所有BE节点（一次一个）
2. 然后升级Observer节点
3. 最后升级Follower和Master节点

每个节点重启后，建议等待5-10分钟确认状态正常再处理下一个。有次我们赶时间连续重启多个节点，结果导致集群短暂不可用，这个教训值得记取。

6. 常见问题解决方案

6.1 BE启动失败处理

如果BE启动失败，可以尝试以下步骤：

1. 检查日志中的具体错误
2. 确认Java UDF JAR包是否存在
3. 验证端口是否被占用
4. 检查文件权限是否正确

# 检查端口占用 netstat -tulnp | grep 9060 # 检查文件权限 ls -l /path/to/be/storage

6.2 FE元数据损坏恢复

万一遇到元数据损坏，可以尝试：

1. 使用备份恢复
2. 启用metadata_failure_recovery模式
3. 从健康节点同步元数据

# 恢复模式启动FE sh bin/start_fe.sh --daemon --metadata_failure_recovery=true

7. 升级后验证要点

升级完成后，我通常会进行以下验证：

1. 执行简单查询验证基本功能
2. 检查所有表的数据完整性
3. 验证UDF函数是否正常
4. 监控系统运行指标

-- 检查表数据量是否正常 SELECT count(*) FROM important_table; -- 验证UDF函数 SELECT my_udf_function(test_column) FROM test_table LIMIT 10;

有次升级后没仔细验证，结果一周后才发现某个UDF函数异常，导致报表数据不准。所以这个验证环节千万不能省。