背景
云原生 API 网关是云原生网关的升级产品，在实现流量网关、微服务网关和安全网关三合一的基础上，额外增加了 API 全生命周期管理的能力。本文介绍从云原生网关迁移到云原生 API 网关的流程。
迁移前检查清单
开始迁移前，请确认以下项目：
已了解云原生 API 网关的产品特性和优势
已评估当前云原生网关实例的容量范围
已确认后端服务类型是否支持迁移
已规划好测试环境和测试流程
已准备好迁移过程中可能出现问题的回滚方案
已确认团队成员已掌握云原生 API 网关的操作方法
迁移流程
迁移步骤
实例创建
创建云原生 API 网关实例时，注意：
参考创建网关实例了解云原生 API 网关实例创建的细节
创建云原生 API 网关实例时，专有网络请务必和云原生网关实例保持一致，以免云原生 API 网关实例无法访问后端服务
验证检查点：
实例创建成功并处于运行状态
实例规格满足业务需求
专有网络配置正确，可以访问后端服务
规则迁移
路由管理迁移
域名
不同于云原生网关，云原生 API 网关的域名是公共资源，不直接归属于某个云原生 API 网关实例。域名会在 API 发布时被绑定到对应的网关实例上。
云原生 API 网关完全覆盖云原生网关的域名管理能力，参考 创建域名在云原生 API 网关创建使用的域名。和云原生网关一样，在云原生 API 网关上添加域名不会自动进行 域名注册及DNS 解析，需要自行完成域名注册，以及到实例访问入口之间的解析设置。
来源&服务
和云原生网关一样，云原生 API 网关的来源和服务是在实例内管理。根据下表判定后端服务是否可以迁移到云原生 API 网关。
在云原生 API 网关中管理来源参考：服务来源管理
在云原生 API 网关中管理服务参考：服务
表1：来源支持对比
来源类型 | 云原生 API 网关 | 云原生网关 | 备注 |
容器服务 | 支持 | 支持 | |
MSE Nacos | 支持 | 支持 | |
MSE ZooKeeper | 不支持 | 支持 | |
SAE 内置注册中心 | 不支持 | 支持 | |
EDAS 内置注册中心 | 不支持 | 支持 | |
SAE Kubernetes 服务 | 不支持 | 支持 | 云原生 API 网关无需创建 SAE Kubernetes 服务来源，可直接添加服务 |
表2：服务支持对比
服务类型 | 云原生 API 网关 | 云原生网关 | 备注 |
容器服务 | 支持 | 支持 | |
MSE Nacos | 支持 | 支持 | |
MSE ZooKeeper | 不支持 | 支持 | |
SAE 内置注册中心 | 不支持 | 支持 | |
EDAS 内置注册中心 | 不支持 | 支持 | |
SAE Kubernetes 服务 | 支持 | 支持 | 云原生 API 网关无需创建 SAE Kubernetes 服务来源 |
固定地址 | 支持 | 支持 | |
DNS 域名 | 支持 | 支持 | |
函数计算 FC | 支持 | 支持 | 云原生 API 网关支持函数计算 3.0，云原生网关支持函数计算 2.0 |
云工作流 CloudFlow | 支持 | 不支持 |
路由
API 是云原生 API 网关中的"一等公民"。在云原生 API 网关中，云原生网关的路由通过 API 来承载（主要是 HTTP API 和 REST API）：
HTTP API
基于 HTTP 协议的接口，以路由为中心。适用于 K8s Ingress、微服务架构、AI（SSE）等场景，实现服务的对外快速暴露。
业务系统间若不需要精细化的 API 粒度管理，可通过配置路由的方式，定义特定的请求应该由哪个后端服务来处理。路由路径相比 API 接口往往粒度较粗，如 /user/*，这样可快速配置访问路径，实现系统间的交互。HTTP API 主要面向开发或运维团队，通过路由可以快速实现业务逻辑的拆分和服务的交互，有较高的灵活性，简化业务系统间的调用逻辑。
REST API
基于 HTTP 协议的接口，以资源为导向，通过标准 HTTP 方法（如 GET、POST 等）对资源进行操作。适用于 API First、跨团队协作、API 精细化管控等场景。
API First：是一种软件开发方法论，它强调在设计和开发应用程序时，首先从 API 的设计开始。这种方法鼓励开发者通过定义和创建 API 来定义系统边界和服务之间的交互，然后再构建后端服务来实现这些接口。
API 精细化管理：往往应用于对上下游合作伙伴开放、内外部系统接入及协作的使用场景。在这种场景下，服务提供者需要将特定的接口对外开放，并配置接口层级的流量策略，同时需要对消费者提供较为完善的 API 文档。
REST API 主要面向以业务为中心的开发团队，促进跨团队协作，增强系统的灵活性，并推动业务的快速迭代和敏捷开发。
根据业务的实际情况决定迁移到 HTTP API 或 REST API，还可以根据需要灵活地将云原生网关的路由拆分到多个 API 中，部分使用 HTTP API，部分使用 REST API，以便于独立管理。
迁移到 HTTP API，参考创建HTTP API。参考路由策略为 HTTP API 配置策略。
迁移到 REST API，参考创建REST API并添加接口。参考配置策略与插件为 REST API 配置策略。
验证检查点：
域名创建成功并解析正确
来源和服务配置完成，可以正常访问后端服务
路由配置成功，请求能够正确转发到后端服务
安全管理迁移
黑白名单
云原生 API 网关完全覆盖云原生网关的黑白名单能力，粒度覆盖网关全局、域名级、路由级。此外，云原生 API 网关还提供网关全局维度的四层黑白名单，可以直接拒绝指定 IP 的连接，进一步节省网关上的资源。
完成路由管理部分的迁移后即可进行黑白名单的迁移，具体操作请参考：设置网关IP黑白名单
全局认证鉴权
云原生 API 网关兼容云原生网关主流的认证鉴权类型，支持情况和迁移流程可以参考下表。
表3：全局认证鉴权支持对比
认证鉴权类型 | 云原生 API 网关 | 云原生网关 | 迁移流程 |
JWT | 支持 | 支持 | |
OIDC | 支持 | 支持 | |
IDaaS | 不支持 | 支持 | - |
自建的鉴权服务 | 支持 | 支持 |
消费者鉴权
云原生 API 网关中的消费者独立于网关实例存在，只需要配置一次消费者信息，即可在授权时在不同网关实例、不同 API 上复用。作为 API 管理中的重要环节，云原生 API 网关针对消费者管理做了进一步升级，支持更多认证方式，包括 API Key、JWT、HMAC。
验证检查点：
黑白名单规则生效，能够正常拒绝或允许指定 IP 访问
全局认证鉴权配置正确，认证功能正常
消费者创建成功，授权范围配置正确
插件迁移
云原生 API 网关完全兼容云原生网关的插件体系，包括自定义插件（Wasm 和 Lua）。可以轻松将云原生网关中的插件配置规则迁移到云原生 API 网关中。
不同于云原生网关，云原生 API 网关的插件独立于网关实例存在。在网关上使用插件前需要将插件安装到网关实例上。参考管理插件进行插件的安装和卸载。完成安装后即可在API和接口列表中配置插件规则。
官方插件
云原生 API 网关兼容云原生网关中绝大部分官方插件。参考下表判定使用的官方插件是否可以被迁移到云原生 API 网关。
表4：官方插件支持对比
云原生网关插件 | 云原生 API 网关是否支持 | 对应插件名称 |
key-auth | 支持 | Key 认证 |
basic-auth | 支持 | Basic 认证 |
hmac-auth | 支持 | HMAC 认证 |
jwt-auth | 支持 | JWT 认证 |
edas-service-auth | 不支持 | - |
oauth | 支持 | OAuth2 认证 |
jwt-logout | 支持 | jwt-logout |
opa | 支持 | OPA |
ext-auth | 支持 | 外部认证 |
key-rate-limit | 支持 | 基于 Key 限流 |
traffic-tag | 支持 | traffic-tag |
http-real-ip | 支持 | http-real-ip |
hsts | 支持 | hsts |
canary-header | 支持 | canary-header |
request-validation | 支持 | 请求校验 |
cluster-key-rate-limit | 支持 | 基于 Key 集群限流 |
try-path | 不支持 | - |
custom-response | 支持 | 自定义应答 |
http2-misdirect | 不支持 | - |
transformer | 支持 | 请求/响应转换 |
de-graphql | 支持 | DeGraphQL |
frontend-gray | 支持 | 前端灰度 |
cache-control | 支持 | 浏览器缓存控制 |
response-cache | 支持 | 通用响应缓存 |
request-block | 支持 | 请求屏蔽 |
bot-detect | 支持 | 机器人拦截 |
waf | 支持 | WAF 防护 |
cors | 支持 | 跨域资源共享 |
ip-restriction | 支持 | IP 限制 |
geo-ip | 不支持 | - |
自定义插件
云原生 API 网关完全兼容云原生网关的自定义插件，参考上传插件将在云原生网关上使用的自定义 Wasm 插件上传到云原生 API 网关中。若使用自定义 Lua 插件，参考使用Lua插件，将其迁移到云原生 API 网关。
云原生 API 网关还提供了在线编写插件的 IDE。若需要开发新的插件，参考WebIDE编写插件，在云原生 API 网关控制台即可快速完成原型开发。
验证检查点：
官方插件安装成功并配置正确，功能正常
自定义插件上传成功，功能正常
插件规则配置正确，能够按预期生效
可观测能力迁移
链路追踪
云原生 API 网关同样集成了可观测链路 OpenTelemetry 版来支持链路追踪，并完全兼容云原生网关上所有的链路追踪协议。参考开启网关链路追踪在云原生 API 网关上进行配置。
日志
类似云原生网关，云原生 API 网关同样支持日志投递，参考开启网关日志投递进行配置，从而将网关的访问日志投递到账号下指定的日志服务 Project 中。
告警
云原生 API 网关集成了云监控以支持告警能力。参考创建告警规则在云原生 API 网关中创建所需的告警。
验证检查点：
链路追踪配置正确，能够正常追踪请求
日志投递配置正确，日志能够正常投递到日志服务
告警规则配置正确，能够按预期触发告警
参数配置迁移
云原生 API 网关兼容云原生网关绝大部分参数，二者的参数名完全一致。参考修改网关参数调整云原生 API 网关实例的参数。
云原生 API 网关不支持的参数包括：
EnableXffTrustedCidrs
PreserveExternalRequestID
LiteMetrics
EnableK8sSourceWorkloadFilter
验证检查点：
参数配置正确，网关性能符合预期
不支持的参数已确认并评估影响
功能验证
完成全部的规则迁移后，开始进行功能验证。推荐使用以下方式验证：
使用测试域名
在云原生 API 网关中添加一个测试域名，将其 DNS 记录 CNAME 到网关实例的接入点，并将其绑定到要测试的 API 上，通过该测试域名进行测试。
配置 host
修改测试环境机器的 hosts，将网关绑定的域名解析到网关实例的接入点，即可在测试机器上直接使用生产域名进行测试。
流量迁移
完成所有功能的验证后，开始进行流量迁移。在过程中严格进行灰度，确保在遇到问题时可以快速将流量回滚到原有的云原生网关实例。
通过修改正式业务域名解析权重的方式将生产业务逐渐迁移到云原生 API 网关。若使用阿里云云解析 DNS 产品来配置生产域名的 DNS，参考权重配置来进行 DNS 权重迁移。若使用其他 DNS 产品，参考相应的权重配置文档。
迁移的整体流程为：
在云原生 API 网关实例的接入点页面获取到网关实例的接入域名
为生产域名做 DNS 权重配置，强烈建议权重从 1% 开始，之后逐步增加权重
观察业务是否正常，结合云原生 API 网关的观测分析能力，通过业务监控、访问日志等来辅助判断
若业务符合预期，在 DNS 解析中逐步增加云原生 API 网关的权重，直到流量完全迁移；若业务不符合预期，通过调整 DNS 权重来进行回滚
回滚预案
在迁移过程中，若遇到以下情况，需要立即执行回滚：
业务响应时间明显增加
错误率超过阈值
出现功能异常或数据不一致
网关性能指标异常（CPU、内存、网络等）
回滚步骤：
立即将云原生 API 网关的 DNS 权重调整为 0%
将所有流量切回原云原生网关实例
监控业务恢复情况，确认异常消失
分析问题原因，修复后重新开始灰度迁移
回滚注意事项：
DNS 生效时间受 TTL 设置影响，需提前设置较小的 TTL 值（如 60 秒）
回滚过程中密切监控业务指标
记录回滚原因和问题现象，便于后续分析