常见问题与故障处理

一个迁移任务可以迁移多个环境吗？

不可以。一个迁移任务只关联一个源实例中的一个环境和一个目标网关。需要迁移线上、预发、测试等多个环境时，请分别准备目标网关并创建迁移任务。

哪些源实例类型支持迁移？

迁移工具支持以专享实例或 Serverless 实例作为源实例，暂不支持集群实例。

选择 Serverless 实例时，当前账号在当前地域的全部 Serverless API 分组都会纳入评估，每个分组只迁移任务所选环境的配置。自定义域名、证书、App、授权关系、API 分组和 API 均按照对应规则迁移。Serverless 实例没有独立的网络入口，因此不迁移实例级 IP 访问控制配置。执行分组 API 配置迁移前，请确认目标网关能够访问各分组的后端服务。

创建迁移任务会影响源端业务吗？

不会。创建任务和执行评估只读取源端配置，不修改源端资源，也不切换流量。

为什么资源显示“部分支持”？

这表示资源可以迁移，但部分配置不会自动转换，或迁移后的生效效果与原 API 网关存在差异。请查看迁移说明和目标配置预览，将需要人工处理的内容加入发布和验证清单。

API 的迁移支持状态不包含插件兼容性。即使 API 显示为“支持”，也需要根据插件能力差异单独检查插件。

源端配置变更后需要怎么处理？

请重新执行评估，确认资源清单和目标配置预览已更新，再继续迁移。迁移期间建议冻结或减少源端配置变更。

可以只迁移部分资源吗？

可以。各迁移阶段支持按资源名称或资源 ID 搜索并选择资源执行。建议仍按实例配置、域名配置、App 配置、分组 API 配置的顺序迁移，以满足资源依赖。

搜索只筛选页面展示的资源。单击全部执行仍会执行当前阶段下的全部可迁移资源；仅迁移搜索结果时，请勾选目标资源并单击执行。

迁移失败后是否需要重新迁移全部资源？

通常不需要。如果修复的是目标网关权限、网络或资源依赖，可以直接重试失败资源；如果修改了原 API 网关中的配置，需要先重新评估，再返回迁移执行页面重新执行。已经成功的资源默认不会重复迁移。

迁移分组 API 配置时应选择哪种 API 类型？

默认选择 REST API。普通路径和明确请求方法均可以迁移为 REST API；源 API 使用 ANY 请求方法或以 /* 匹配所有子路径时，如需保留对应行为，请选择 HTTP API。选择 REST API 会跳过这些 API。

查看目标配置预览和执行迁移时，请选择相同的 API 类型。该选项只对本次执行生效，重复执行同一分组时也应保持 API 类型一致。

目标端已经存在同名资源怎么办？

对于同名 IP 访问控制策略、域名和 Consumer，默认会复用目标资源而不修改已有配置。如需使用迁移后的配置更新目标资源，请在执行时选择遇到同名目标资源时允许更新。已有同名证书只会被复用，不会被迁移工具覆盖。

对于同名且类型相同的 API，默认不会修改现有 API，本次资源显示为已跳过。如需更新，请在执行时选择遇到同名目标 API 时允许更新。启用该选项前，请核对目标配置预览和目标端现有配置。

同名 API 的类型与本次选择的 API 类型不同时，迁移工具不会跨类型复用或更新已有 API，本次分组迁移会失败。请处理目标端的同名 API，或选择其他目标网关后重试。

函数计算 2.0 后端如何迁移？

• 函数计算 2.0 HTTP 函数会转换为 DNS Service，并使用原 HTTP 触发器地址和完整调用 Path。迁移后请验证目标网关到该地址的网络连通性和实际调用结果。

• 函数计算 2.0 Event 函数不支持迁移，使用该后端的源 API 不会迁移。如需迁移，请先将后端调整为支持的类型，然后重新评估。

为什么资源显示迁移成功，但完整性显示不一致？

迁移状态表示资源迁移操作是否完成，完整性表示目标端实际匹配的配置数量是否符合本次迁移预期，两者相互独立。资源迁移成功后，如果目标端缺少域名绑定、凭证、后端服务、插件、策略、Operation 或 Route 等配置，完整性可能显示为不一致。

请单击完整性旁的查看，比较各检查项的预期数量和实际匹配数量。处理目标端差异后，单击重新检查刷新结果；如果需要重新写入迁移配置，请重新执行对应资源。

为什么建议最后迁移分组 API 配置？

分组 API 配置会引用目标端域名和 Consumer。先迁移域名和 App，可以避免 API 导入后缺少域名绑定或调用方授权。

单击“完成迁移”后会自动切流吗？

不会。“完成迁移”只标记配置迁移阶段完成。您仍需发布目标 API、完成直连验证，并通过 DNS 权重切换业务流量。

取消或删除任务会回滚目标资源吗？

不会。取消或删除任务不会自动删除已经迁移至目标网关的资源，也不会恢复被复用资源或已更新的同名 API 的原配置。请先记录执行结果，再决定是否人工清理目标资源。

迁移成功后为什么目标 API 仍然无法访问？

请依次检查：

1. API 是否已经发布。

2. 自定义域名是否已绑定至对应的 API 或 Route，证书是否有效。

3. Consumer 凭证及其对 Operation 或 Route 的授权关系是否正确。

4. 目标网关到后端服务的网络是否连通。

5. IP 访问控制、限流、认证或其他插件是否拒绝了请求。

6. 请求 Host、路径、方法和参数是否与目标 API 定义一致。

如何在不修改 DNS 的情况下验证目标网关？

目标网关入口为 IP 地址时，可以使用 hosts、测试 DNS 或 curl --resolve；目标网关入口为域名时，可以使用 curl --connect-to。HTTPS 请求应继续使用业务域名，以便正确携带 Host 和 TLS SNI。具体命令请参见验证并通过 DNS 切换流量。

签名认证失败怎么处理？

检查 Consumer 凭证、签名算法、请求时间、参与签名的 Header 和 Query 参数，以及特殊字符编码方式。建议使用真实客户端或官方 SDK 回归测试，不要只使用简单健康检查请求。

后端返回结果与原 API 网关不一致怎么处理？

检查参数映射、常量参数、请求应答改写、后端签名、错误码映射及多个插件组合生效后的结果。对照目标配置预览和插件能力差异逐项调整并重新测试。

为什么 DNS 权重与实际请求比例不完全一致？

DNS 权重通常作用于解析请求或客户端，而不是每一个 HTTP 请求。递归 DNS、客户端缓存、长连接和不同 DNS 服务的调度算法都会导致实际流量比例偏差。

调整 DNS 后多久可以进入下一阶段？

建议至少观察两个 TTL 周期，并满足业务约定的最短观察时长。涉及多类 DNS 记录时，请按照其中最长的 TTL 计算。只有未触发任何预设回滚条件，并且数据一致性检查通过时，才继续扩大目标网关权重。

使用 IPv4 和 IPv6 双栈访问时需要注意什么？

如果业务域名分别配置了 A 和 AAAA 记录，请将两类记录纳入同一切流计划，在每个阶段使用相同的目标流量比例，并分别确认 IPv4 和 IPv6 请求量及业务指标。回滚时也需要同时恢复两类记录。

如何快速回滚？

将本次切流涉及的原 API 网关 DNS 记录权重全部恢复为 100%，将目标网关 DNS 记录权重全部调整为 0%，并持续观察缓存过期和流量回落。DNS 和客户端缓存可能导致回滚延迟，因此切流期间必须保留原 API 网关的配置和容量。

完成全量切流后需要恢复 TTL 吗？

需要。全量流量稳定并完成预设观察后，请将迁移前临时降低的 TTL 恢复为业务正常值。

什么时候可以下线原 API 网关？

当本次切流涉及的全部 DNS 记录均已全量指向目标网关，并经过充分观察确认没有残余流量、固定 IP 调用、其他域名入口或外部产品依赖后，再按照业务下线流程处理原 API 网关。不要在刚完成 DNS 调整后立即释放源端资源。