# 回滚至先前 KCL 版本
<a name="kcl-migration-rollback"></a>

本主题介绍如何将 KCL 3.5.x\+ 使用者应用程序回滚到 KCL 1.x。回滚过程取决于您的应用程序当前所处的迁移阶段。

## 从第 1 阶段回滚到 KCL 1.x
<a name="kcl-migration-rollback-phase1"></a>

如果您的应用程序处于第 1 阶段 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1`)，则可以通过重新部署之前的代码来回滚到 KCL 1.x。第 1 阶段与 KCL 1.x 向后兼容，并且没有在租约表中创建任何特定于迁移的条目。无需迁移工具。要从第 1 阶段回滚，请将包含您的 KCL 1.x 版本的代码重新部署到所有工作线程。

**重要**  
第 2 阶段 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X`) 是一项破坏性变更，无法直接回滚。一旦您的应用程序进入第 2 阶段，就会将非租约条目（`WORKER_METRIC_STATS` 和 `Migration3.0`）写入租约表，而这些条目不向后兼容 KCL 1.x。这会永久阻止直接回滚到 KCL 1.x。我们强烈建议您在第 1 阶段中对应用程序运行足够长时间的烘焙测试，以验证其稳定性，然后再进入第 2 阶段。

## 从第 2 阶段回滚到第 1 阶段
<a name="kcl-migration-rollback-phase2"></a>

如果您的应用程序处于第 2 阶段 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X`)，则必须使用 GitHub 网站上的 [KCL 迁移工具](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)来回滚到第 1 阶段 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1`)。这是一个包括两个步骤的过程：

1. 运行 GitHub 网站上的 [KCL 迁移工具](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)。

1. 使用第 1 阶段的配置来重新部署代码（可选）。

**重要**  
您无法回滚两个级别（从第 2 阶段回滚到第 1 阶段，然后再回滚到 KCL 1.x）。KCL 迁移工具仅处理从第 2 阶段到第 1 阶段的回滚。该工具不会从租约表中删除非租约条目。这些条目不向后兼容 KCL 1.x，这就是为什么无法从第 2 阶段直接两级回滚到 KCL 1.x。

## 步骤 1：运行 KCL 迁移工具
<a name="kcl-migration-rollback-step1"></a>

需要从第 2 阶段 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X`) 回滚到第 1 阶段 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1`) 时，请运行 KCL 迁移工具。该工具执行以下任务：
+ 它移除 DynamoDB 中租约表上的全局二级索引（LeaseOwnerToLeaseKeyIndex）。此索引由 KCL 3.5.x\+ 创建，但在回滚到第 1 阶段时并不需要。
+ 它使所有工作线程均在与 KCL 1.x 兼容的模式下运行，并开始使用先前 KCL 版本中使用的负载均衡算法。如果 KCL 3.5.x\+ 中的新负载均衡算法存在问题，这将立即解决问题。

**重要**  
在迁移、回滚和前滚过程中，不得删除租约表中的协调器状态条目 (`Migration3.0`)。

**注意**  
使用者应用程序中的所有工作线程在给定时间均必须使用相同的负载均衡算法。KCL 迁移工具可确保 KCL 3.5.x\+ 使用者应用程序中的所有工作线程都切换到 KCL 1.x 兼容模式，以便在部署回滚到阶段 1 期间，所有工作线程都运行相同的负载均衡算法。

您可以在 [KCL GitHub 存储库](https://github.com/awslabs/amazon-kinesis-client/tree/master)的 scripts 目录中下载 [KCL Migration Tool](https://github.com/awslabs/amazon-kinesis-client/blob/master/amazon-kinesis-client/scripts/KclMigrationTool.py)。从任意工作线程或任意具备所需权限（写入和更新租约表的权限）的主机上运行该脚本。确保为 KCL 使用者应用程序配置了适当的 [IAM permissions](https://docs.amazonaws.cn/streams/latest/dev/kcl-iam-permissions.html)。每个 KCL 应用程序只能运行该脚本一次。使用以下命令运行 KCL 迁移工具：

```
python3 ./KclMigrationTool.py --region {{region}} --mode rollback [--application_name {{applicationName}}] [--lease_table_name {{leaseTableName}}]
```

### 参数
<a name="kcl-migration-rollback-parameters"></a>

`--region`  
将{{区域}}替换为您的 Amazon Web Services 区域。

`--application_name`  
如果您为租约表使用默认名称，则此参数为必需。如果您为租约表指定了自定义名称，则可以忽略此参数。将 {{applicationName}} 替换为实际的 KCL 应用程序名称。如果未提供自定义名称，该工具将使用此名称来派生默认表名称。

`--lease_table_name`  
如果您在 KCL 配置中为租约表设置了自定义名称，则需要此参数。如果您使用的是默认表名称，则可以忽略此参数。将 {{leaseTableName}} 替换为您为租约表指定的自定义表名称。

## 步骤 2：使用第 1 阶段的配置来重新部署代码（可选）
<a name="kcl-migration-rollback-step2"></a>

运行 KCL 迁移工具从第 2 阶段回滚到第 1 阶段后，您将看到以下消息之一：

消息 1  
“回滚已完成。应用程序正在运行第 2 阶段（兼容 2x）功能。请使用第 1 阶段的配置部署 KCL 3.5.x 应用程序，以回滚到第 1 阶段。”  
**必需操作：**您的工作线程运行在 KCL 1.x 兼容模式下（第 2 阶段尚未自动过渡到完整的 3.x 负载均衡）。请使用第 1 阶段的配置 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1`) 将您的 KCL 3.5.x\+ 应用程序重新部署到工作线程。

消息 2  
“回滚已完成。您的 KCL 应用程序在运行第 2 阶段（3x）功能，并已回滚到第 2 阶段（兼容 2x）模式。如果您在短时间内未看到缓解，请使用第 1 阶段配置部署 KCL 3.5.x 应用程序，以回滚到第 1 阶段。”  
**必需操作：**您的工作线程已自动过渡到完整的 KCL 3.x 负载均衡，但 KCL 迁移工具已将其切换回 KCL 1.x 兼容模式。如果问题已解决，则无需重新部署。如果问题仍然存在，请使用第 1 阶段的配置 (`CLIENT_VERSION_CONFIG_COMPATIBLE_WITH_2X_PHASE1`) 将您的 KCL 3.5.x\+ 应用程序重新部署到工作线程。