升级集群

升级 ClickHouse 集群到新版本。仅 mode = deploy 的集群支持。

前置条件

• 已经上传目标版本的安装包到 CKMAN（顶部"安装包管理"页面）
• 当前集群健康，所有节点 green 状态
• 重要数据已备份

操作步骤

集群详情 → Upgrade Cluster 下拉选择目标版本 → 点击 Upgrade：

升级策略

策略	行为
Full（全量升级）	停服 → 全部节点替换 → 启动。停服时间长，但操作简单
Rolling（滚动升级）	ClickHouse 节点按 shard 分批升级，尽量保留服务能力

使用独立 ClickHouse Keeper 的集群

未勾选“跳过升级 Keeper”时，CKMAN 会先处理 Keeper，再升级 ClickHouse。当前 Keeper 阶段会处理完整 Keeper 节点列表，不按 Rolling 逐台升级；执行前应安排维护窗口并确认 Keeper 的可用性方案。勾选跳过 Keeper 后，只升级 ClickHouse。升级生成的 Keeper 拓扑仍使用完整节点列表。

如何选

• 业务可停服且节点少：Full
• 业务不可停服或节点多：Rolling
• 跨大版本（例如 21.x → 23.x）：建议先在测试环境 Full 验证，再生产 Rolling

跳过相同版本

升级开始前 CKMAN 会实时查询各节点的版本号。勾选 Skip same version 后：

• 已经是目标版本的节点会被跳过，不重复升级
• 数据库无法连接的节点会强制升级（按异常处理）

未勾选则所有节点强制升级。

失败回滚

升级失败时：

• CKMAN 不会自动回滚
• 任务进入 failed 状态，可在任务管理查看每个节点的具体错误
• 需要手工排查（常见：磁盘空间、安装包损坏、SSH 不通、依赖库版本不匹配）
• 修复后重新触发升级（CKMAN 会跳过已升级成功的节点，仅处理失败节点）

升级后

• 在 Web 界面看版本号是否切换为新版本
• 运行一次 Distributed DDL Queue 查看是否有积压
• 看慢查询、表合并是否有异常
• 业务侧验证读写正常