alibabacloud-cksync-plan

ClickHouse 同步计划（cksync-plan）

用于规划 ClickHouse 集群数据迁移方案的技能，包括迁移计划、风险和注意事项。

适用场景

• 在不同的 ClickHouse 集群之间迁移数据
• 对 ClickHouse 集群进行水平扩容（添加或移除节点）
• 降级磁盘
• 跨可用区迁移
• 升级为多副本、多可用区部署

工作流

步骤 1：收集源集群信息

询问用户源集群类型：

• 自建 ClickHouse 或非阿里云 ClickHouse
• 阿里云 ClickHouse 社区版
• 阿里云 ClickHouse 企业版

询问用户源集群版本（例如：20.8、22.8、23.8、24.3）：

• 版本会影响迁移方法的兼容性
• BACKUP/RESTORE 要求版本 ≥22.8
• 增量 cksync 迁移要求目标版本 ≥20.8

步骤 2：收集目标集群信息

询问用户目标集群类型：

• 阿里云 ClickHouse 社区版
• 阿里云 ClickHouse 企业版
• 待确定

步骤 3：收集集群详情（必需）

此步骤为必需步骤。 在选择迁移计划前，必须收集数据库和表信息。

必需信息

1. 数据库列表及其引擎
2. 表列表，包括引擎、分区数、数据大小和写入速度

选项 A：由用户执行 SQL

提供 references/sql.md 第 1 节中的 SQL 查询，供用户执行：

1. 数据库信息——查询 system.databases，获取数据库名称和引擎
2. 表信息——综合查询，包含表名、引擎、engine_full（用于 TTL）、分区数、数据大小和写入速度

需要收集的关键字段：

• engine_full：包含 TTL 子句（例如：TTL event_time + INTERVAL 7 DAY）
• part_count：每个表的分区数
• data_bytes：每个分片的数据大小
• write_speed_bytes_per_sec：根据 part_log 计算的写入速度

完整 SQL 查询请参阅 references/sql.md 第 1 节。

选项 B：通过 HTTP 直接查询

向用户索取连接信息：

• HOST_NAME：集群端点（例如：cc-xxx.clickhouse.rds.aliyuncs.com）
• HTTP_PORT：HTTP 端口（默认值：8123）
• USER_NAME：数据库用户名
• PASSWORD：数据库密码

使用 references/sql.md 第 5 节中的安全凭证处理方式和 HTTP 查询示例。

分析检查清单

收集数据后，确认：

• 所需元数据完整（数据库引擎、表引擎、engine_full、分区、数据大小、写入速度）
• 已使用 references/plans.md 完成迁移兼容性检查（特定方法的条件）
• 已将版本和只读时间窗口限制对应到候选方法
• 已识别风险并制定缓解措施，且记录在计划中

步骤 4：业务需求

询问允许的只读时间：

• 0 分钟
• 30 分钟以内
• 1 天以内
• 暂不确定

第 5 步：选择并提供迁移计划

根据收集的信息，分析并从以下迁移方式中给出建议：

方式	适用场景	最短只读时间
控制台（cksync）	大多数迁移到 Alibaba Cloud 的场景	~10 分钟
BACKUP/RESTORE	大量数据、相同版本类型、版本 ≥22.8	视数据量而定
INSERT FROM REMOTE	需要灵活控制、中小规模数据	每批次约 10 分钟
业务双写	要求零停机	0
Kafka 双写	已有 Kafka 管道，或业务写入已切换到 Kafka	0
大集群联邦	大规模、复杂场景	0

硬性要求：必须输出计划，绝不能输出空内容。

即使信息不完整，也必须输出一份临时迁移计划。 临时计划必须包含：

• 使用的假设，
• 缺失信息清单，
• 置信度和主要不确定因素，
• 用户提供缺失信息后完善建议的后续步骤。

迁移方式概述

1. 控制台（cksync）迁移

适用于大多数 Alibaba Cloud 迁移场景，尤其是原地操作。 有关支持范围、引擎限制、TTL/写入速度检查、合并风险和资源前提条件，请参阅 references/plans.md 第 1 节。

2. BACKUP/RESTORE 迁移

适用于可接受完整备份/恢复工作流的相同版本迁移。 有关版本/版本类型限制、支持的引擎、命令模式和进度监控，请参阅 references/plans.md 第 2 节。

3. INSERT FROM REMOTE 迁移

适用于需要精细控制表/分区/时间范围的场景。 有关适用范围和操作限制，请参阅 references/plans.md 第 3 节。 有关 SQL 模板和详细步骤，请参阅 references/sql.md 第 2 节。

4. 业务双写

当要求零停机且可在应用侧实现双写时使用。 有关详细条件，请参阅 references/plans.md 第 4 节。

5. Kafka 双写

当可通过 Kafka 切换双消费者时使用，包括已有 Kafka 管道，以及可先将业务写入切换到 Kafka 的场景。 有关详细条件，请参阅 references/plans.md 第 5 节。

6. 大集群联邦

适用于需要业务和技术团队紧密协作的大规模/复杂迁移的高级方案。

• 社区版 + 企业版：请参阅 references/big-cluster-community-enterprise.md
• 自建 + 云端：请参阅 references/big-cluster-self-built-community.md

输出格式

默认交付内容：仅提供一份迁移计划。按照 assets/migration-plan-template.md 组织内容，并包含以下关键章节（集群信息和命令可以直接写在计划中，这仍算作单份交付内容）。

**仅在用户要求时提供额外文件：**除非客户明确要求，否则不要为集群信息文档、脚本或 SQL 创建单独文件。如有要求，使用 assets/cluster-info-template.md 编写集群文档，并按要求将脚本/SQL 放入名称明确的文件中。

迁移计划的关键章节：

1. 执行摘要 - 方式、数据量、时长、停机时间
2. 源集群分析 - 数据库、表、兼容性检查
3. 迁移方式选择 - 原因和备选方案
4. 迁移步骤 - 准备/执行/后续步骤及命令
5. 风险与缓解措施 - 包含概率和影响
6. 回滚计划 - 触发条件和步骤
7. 时间线 - 含负责人的阶段安排
8. 参考链接 - 文档 URL

方法选择参考

如需快速了解场景与方法的对应关系，以及特定方法的限制（包括原地迁移优先级和 Enterprise → Enterprise 选项），请参阅 references/plans.md 中的“方法选择优先级”部分及相关方法章节。

其他资源

• references/plans.md - 详细的迁移计划条件
• references/sql.md - SQL 模板和命令
• references/stop-merge-storm.md - 如何停止同步后的合并风暴
• references/big-cluster-community-enterprise.md - Community + Enterprise 联邦
• references/big-cluster-self-built-community.md - 自建 + 云端联邦