> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 从 Apache Kafka 迁移到 AutoMQ

> AutoMQ 提供成本更优、弹性更强的 Kafka Server 方案，兼容所有 Apache Kafka 版本，助力轻松完成迁移，实现业务无缝转移。

本文详细介绍从 Apache Kafka 迁移到 AutoMQ 的方案以及实施流程。

<Tip>
  AutoMQ 企业版提供了 [Kafka Linking 工具](https://docs.automq.com/automq-cloud/migrate-to-automq/overview#overview-of-kafka-linking)，支持 Byte to Byte 消息同步（同步前后消息位点完全一致）和不停机迁移。如果您的业务场景需要更平滑的迁移方案，可以通过 [此处表单](https://www.automq.com/contact) 联系 AutoMQ 团队获取必要的协助和最佳实践。
</Tip>

## 前置条件

### 功能列表

目前 AutoMQ 仅提供 Kafka Server 组件，暂未提供其他生态组件。因此，迁移到 AutoMQ 之前需要确认如下功能是否使用，并参考如下指引进行处理：

* **Kafka Server：** AutoMQ 提供成本更优、弹性更强的 Kafka Server 方案，**兼容 Apache Kafka 0.9.x ～ 3.9.x 版本** ，如果当前使用的 Apache Kafka Server 版本不在支持范围中，请联系我们获取支持和更新。

* **Kafka Client：** AutoMQ 兼容 Apache Kafka 原有 Client SDK，只需确认原有 SDK 版本在**0.9.x ～ 3.9.x 之间** ，即可兼容。

* **Kafka Connector：** AutoMQ 兼容 Apache Kafka Connector，如果当前使用了 Kafka Connector，建议继续维持原有服务，只需将 Connector 配置的 Kafka Server 接入点替换为 AutoMQ 实例接入点即可。

### 业务范围

生产环境中从 Apache Kafka 迁移到 AutoMQ，一般建议分批次逐步迁移，即逐步筛选源集群中的 Topic、ConsumerGroup，按照业务链路和业务范围分批次迁移。

因此建议按照如下流程进行业务范围梳理：

1. **盘点源集群资源列表：** 建议使用 Kafka Admin CLI 或其他工具导出源集群所有的 Topic 和 ConsumerGroup，按业务系统进行分类整理。提前清理无效、无人认领的 Topic、ConsumerGroup 资源。

<Tip>
  建议检查源集群中的 Topic，提前清理长时间无写入和订阅的 Topic、ConsumerGroup，缩小待迁移范围。
</Tip>

1. **按业务系统划分批次：** 生产环境中建议按业务系统规划迁移批次，首先迁移离线类、非核心系统业务，逐步扩大迁移范围，避免非预期风险。

2. **协调业务方人员配合迁移：** Apache Kafka 迁移到 AutoMQ 的过程中需要业务方配合更换接入点重启应用。因此执行迁移计划前需要协调业务方人员进行配合。

<Info>
  Apache Kafka Client 在建立服务端连接后即不会断开源集群的连接。因此，即使使用域名访问服务端，也仍然需要重启客户端应用才能连接到 AutoMQ 新集群。
</Info>

## 迁移流程

从 Apache Kafka 迁移到 AutoMQ，主要考虑如下工作：

* **消息数据迁移：** Kafka 存储了历史已消费和未消费的消息数据，迁移集群需要保证消息数据按需复制到新集群，不能丢失消息。

* **消费进度元数据迁移：** Kafka 消费者在源集群已经消费处理的消费进度等元数据需要在新集群重建，以免切换到新集群后丢失进度重新消费，产生大量重复。

* **生产者切换：** 迁移工作除去数据同步，还需要在合适的时机切换生产者应用，使生产者连接目标集群生产新的消息。

* **消费者切换：** 迁移工作除去数据同步，还需要在合适的时机切换消费者应用，使消费者连接目标集群接续之前的消费进度继续消费消息。

整体迁移方案参考下图的流程：

<img src="https://mintcdn.com/automq/kFvm7Lwf3ab0EBuj/zh/automq/migration/migrating-from-apache-kafka-to-automq/1.webp?fit=max&auto=format&n=kFvm7Lwf3ab0EBuj&q=85&s=cea5d1493357307c78aa8466aa7b42c6" width="2560" height="904" data-path="zh/automq/migration/migrating-from-apache-kafka-to-automq/1.webp" />

### 步骤 1：**创建迁移任务，同步数据**

参考[概述▸](/zh/automq-cloud/migrate-to-automq/overview)，AutoMQ 推荐每个批次任务使用独立的 MirrorMaker2 Connector 来执行数据同步，以便更好隔离。其中，需要根据实际情况填写如下参数：

* **源集群：** 指定需要迁移的源集群。

* **目标集群：** 指定迁移的目标集群，此处选择 AutoMQ 集群。

* **待同步 Topic 列表** ：设置迁移任务覆盖的 Topic 列表。该列表支持通配符输入，可以一次性配置多个 Topic。

<Tip>
  AutoMQ 迁移工具支持自动同步 Topic 动态更新功能，一旦创建同步任务后，无论是新建 Topic 还是更改现有 Topic 的分区数，只要符合当前列表条件，都会自动同步到目标集群。
</Tip>

* **是否同步消费进度：** 建议开启，开启后迁移任务会将源集群 ConsumerGroup 的消费进度映射到目标集群，确保消费者切换后可以接续之前的进度继续消费，从而避免大量的重复处理。

<Callout>
  需要注意的是，MirrorMaker2 同步的两端集群消息的位点是不一致的，因此源集群的消费进度会重新映射到目标集群。该过程可能会有少量的位点回退。
</Callout>

* **待排除 Topic 列表：** 如果在**待同步 Topic 列表** 中使用了通配符，但又需要排除掉部分 topic 不希望同步，可以设置待排除 Topic，去除相关 topic 的同步。

### 步骤 2：**观察同步进度，等待同步接近完成**

MirrorMaker2 支持 JMX 指标查看同步延迟情况。用户需观察同步任务的同步延迟指标，等待指标接近于 0。

<Tip>
  观察同步接近完成是为了缩短后续切换应用的观察等待时间。
</Tip>

MirrorMaker2 中同步延迟是指迁移 Topic 的消息从源集群生产到同步完成的耗时，一个迁移任务内涉及到多个 Topic 时，取所有 Topic 延迟的最大值。

参考迁移方案的描述，需要定期观察迁移任务的同步延迟和同步堆积数指标。建议当**同步延迟小于 1 分钟** 时准备下一步骤的应用切换。

### 步骤 3：**停止源集群消费者**

切换应用需要先切换消费者，建议先停止消费者应用，等待源集群的消费进度数据同步到目标集群后再切换到目标集群。

<Tip>
  建议等待一段时间，使消费进度尽可能同步完成。该时间默认为 60s，也可以在迁移任务的高阶配置中自定义。

  应用也可先在目标集群启动相同 Consumer Group 的新消费者，然后再停止源集群的消费者。这样会导致一段时间内两端同时消费：
</Tip>

### 步骤 4：切换消费者到目标集群

步骤 3 完成后，修改消费者配置中的接入点，替换为 AutoMQ 实例提供的接入点，重启应用。

<Info>
  根据 MirrorMaker2 的技术实现，步骤 3 和步骤 4 过程中消费者可能会产生一定的消费重复。如果期望降低重复概率，可以在迁移任务的高阶参数中自定义配置。
</Info>

### 步骤 5：停止源集群生产者

对于每一个 Topic，需要确保重复步骤 3 和步骤 4 将当前 Topic 的所有消费者都已经切换完成，即可停止源集群生产者，等待所有的消息数据同步到目标集群。

<Callout>
  停止生产者是为了避免目标集群同时接收来自生产者和 MirrorMaker2 的消息写入，这可能导致消息乱序。
</Callout>

<Tip>
  切换生产者过程必须完全停机，以确保消息不会乱序。AutoMQ 企业版提供了 [Kafka Linking 工具](https://docs.automq.com/automq-cloud/migrate-to-automq/overview#overview-of-kafka-linking)，支持 Byte to Byte 消息同步（同步前后消息位点完全一致）和不停机迁移。如果您的业务场景需要更平滑的迁移方案，可以通过 [此处表单](https://www.automq.com/contact) 联系 AutoMQ 团队获取必要的协助和最佳实践。
</Tip>

### 步骤 6：切换生产者到目标集群

观察迁移任务的同步延迟，确认同步延迟为 0 后，即可重新使用新的接入点地址启动生产者，连接到 AutoMQ 目标集群，完成整个迁移任务。

<Callout>
  切换生产者后，需要持续观察 Topic 的上下游应用，确认是否符合预期。
</Callout>

### 步骤 7：重复执行步骤 3～步骤 6，直到完成迁移，删除迁移任务

1. **重复检查所有 Topic 迁移是否完成。** 步骤 3 到步骤 6 是按照 Topic 和 Topic 关联的生产者、消费者应用的粒度进行操作。因此，需要重复检查直到当前迁移任务中所有的 Topic 都已经完成迁移。

2. **删除迁移任务。** 完成所有 Topic 的迁移后，点击确认删除任务， AutoMQ 会清理底层的机器资源和配置信息。

<Callout>
  删除迁移任务后，无法恢复，即使重新创建相同 Topic 的迁移任务，也将被视为全新任务，不会继续之前的迁移状态。因此，在删除任务之前，请确保当前迁移任务已成功完成工作。
</Callout>

## 回滚流程

针对迁移流程中各阶段，如果出现非预期异常且无法短时间定位原因，用户可以按照如下流程尝试回滚操作并关注回滚带来的影响。

<table>
  <thead>
    <tr>
      <th colspan="1" rowspan="1">
        <strong>迁移阶段</strong>

        <br />
      </th>

      <th colspan="1" rowspan="1">
        <strong>回滚方案</strong>

        <br />
      </th>

      <th colspan="1" rowspan="1">
        <strong>回滚影响</strong>

        <br />
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td colspan="1" rowspan="1">
        步骤 1，创建任务

        <br />
      </td>

      <td colspan="1" rowspan="2">
        <ul>
          <li>删除任务</li>

          <li>删除目标实例的 Topic、ConsumerGroup，清理已经同步的数据</li>
        </ul>
      </td>

      <td colspan="1" rowspan="2">
        该阶段由于尚未切换应用，对应用无影响

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        步骤 2，观察同步进度

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        步骤 3，已经停止源集群消费者

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>恢复源集群消费者，回滚到步骤 2 阶段</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        数据不影响，仅造成消费暂停和延迟

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        步骤 4，已经切换消费者到目标集群

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>停止目标集群消费者，切换回源集群接入点，回滚到步骤 2 阶段</li>
        </ul>
      </td>

      <td colspan="1" rowspan="2">
        回滚到源集群会重复消费切换期间的数据

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        步骤 5，已经停止源集群生产者

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>恢复源集群生产者，回滚到步骤 4 阶段</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        步骤 6，已经切换生产者到目标集群

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>停止目标集群生产者，切换回源集群接入点，回滚到步骤 4 阶段</li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        步骤 6 期间生产到目标集群的消息无法反向同步回源集群，需要应用处理

        <br />
      </td>
    </tr>

    <tr>
      <td colspan="1" rowspan="1">
        步骤 7，已经删除迁移任务

        <br />
      </td>

      <td colspan="1" rowspan="1">
        <ul>
          <li>
            删除任务后
            <strong>无法回滚</strong>
          </li>
        </ul>
      </td>

      <td colspan="1" rowspan="1">
        不涉及

        <br />
      </td>
    </tr>
  </tbody>
</table>