如何把 Apache APISIX 配置为 Decoupled 模式分离控制面与数据面？

如何把 Apache APISIX 配置为 Decoupled 模式分离控制面与数据面？

【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix

在 Apache APISIX 3.0.0 中引入了多种部署模式，其中 Decoupled 模式把网关拆成两类独立实例：一台control plane（控制面）只负责 Admin API，另一台data plane（数据面）只负责处理用户请求。两者通过同一个 etcd 配置中心共享路由配置——控制面写入配置，数据面读取配置。本文基于项目文档 deployment-modes.md 和仓库内的 CLI 测试脚本，说明如何分别配置这两种实例，并给出仓库自身使用的验证方法。

前置条件

按文档给出的模式说明，Decoupled 模式要求：

• APISIX 版本为 3.0.0 及以上。升级指南 upgrade-guide-from-2.15.x-to-3.0.0.md 明确写道："3.0.0 also introduces multiple deployment modes"，其中 Decoupled 模式的描述是 "the data plane and the control plane are separated. You can deploy an instance of APISIX either as a control plane or a data plane"。
• 一个可访问的 etcd 集群，作为两种实例共同的配置中心（本文主路径使用config_provider: etcd）。
• 两个独立的 APISIX 安装实例（可以是两台机器或两个目录），分别修改各自的conf/config.yaml。

注意：conf/config.yaml.example文件头部提示 "DO NOT MODIFY DEFAULT CONFIGURATIONS IN THIS FILE. Keep the custom configurations inconf/config.yaml"，所以只编辑conf/config.yaml，不要改 example 文件。

配置控制面实例

控制面的职责来自文档原文：

The instance of APISIX deployed as the control plane will:

1. Listen on port9180and handle Admin API requests.

在控制面实例的conf/config.yaml中加入以下配置（取自 deployment-modes.md 的 Decoupled 章节）：

deployment: role: control_plane role_control_plane: config_provider: etcd etcd: host: - https://<etcd_IP>:<etcd_Port> prefix: /apisix timeout: 30 #END

说明：

• role: control_plane声明该实例是控制面；role_control_plane.config_provider: etcd指定配置中心为 etcd。
• <etcd_IP>:<etcd_Port>需要替换为你自己的 etcd 地址和端口。文档示例用https://，如果你的 etcd 未启用 TLS，可用http://（文档中 Traditional 模式示例即使用http://${etcd_IP}:${etcd_Port}）。
• 控制面的 Admin API 监听端口由deployment.admin.admin_listen控制，config.yaml.example 中的默认值是port: 9180；deployment.admin.admin_key中配置了 Admin API 的密钥，请求时需要用X-API-KEY头携带。

配置数据面实例

数据面的职责是处理用户请求（文档原文：数据面实例 "Once the service is started, it will handle the user requests"）。在其conf/config.yaml中配置：

deployment: role: data_plane role_data_plane: config_provider: etcd etcd: host: - https://<etcd_IP>:<etcd_Port> prefix: /apisix timeout: 30 #END

仓库中的测试脚本 test_deployment_data_plane.sh 使用了同样的结构（deployment下为role: data_plane+role_data_plane.config_provider: etcd+etcd连接段）。

关键点：两台实例必须指向同一个 etcd 集群、同一个 prefix（/apisix），这样控制面写入的路由配置才能被数据面读到。默认情况下数据面监听9080端口处理用户请求（apisix.node_listen的默认值，见 config.yaml.example）。

另外，config.yaml.example 中role_data_plane.config_provider的注释表明它支持etcd、xds或yaml三种取值；其中yaml对应的是 Standalone 模式（不走 etcd），本文不展开。

启动两种实例

在 APISIX 安装目录下用 Make 入口启动和停止（仓库的 CLI 测试脚本即采用这一方式）：

make run

停止则使用：

make stop

先启动控制面，再启动数据面即可。两种角色都是 APISIX 实例本身，无需额外进程。

验证控制面：Admin API 可用、不代理请求

仓库测试脚本 test_deployment_control_plane.sh 的验证逻辑可以直接复用。admin_key取自conf/config.yaml中deployment.admin.admin_key的第一个 key 值：

# 检查 Admin API：期望返回 HTTP 200 curl -o /dev/null -s -w %{http_code} \ http://127.0.0.1:9180/apisix/admin/routes \ -H "X-API-KEY: <admin_key>"

如果输出是200，说明控制面已启用 Admin API（测试脚本断言 "control_plane should enable Admin API"）。

控制面不应该代理业务请求。测试脚本向9180端口发送一个普通请求并期望得到404：

# 期望返回 404，说明请求代理已禁用 curl -o /dev/null -s -w %{http_code} http://127.0.0.1:9180/c -H "X-API-KEY: <admin_key>"

通过控制面创建路由，由数据面生效

控制面配置就绪后，用 Admin API 创建路由。测试脚本中的示例请求如下（文档示例，httpbin.org:80为测试用的上游地址，可替换为你自己的上游）：

curl -i http://127.0.0.1:9180/apisix/admin/routes/1 \ -H "X-API-KEY: <admin_key>" \ -X PUT \ -d ' { "upstream": { "nodes": { "httpbin.org:80": 1 }, "type": "roundrobin" }, "uri": "/*" }'

写入成功后，该路由进入 etcd；数据面实例通过config_provider: etcd从同一 etcd 读取配置，之后用户请求经数据面9080端口进入并按此路由转发。

验证数据面：不启用 Admin API、不写 etcd

数据面实例启动后，用仓库测试脚本 test_deployment_data_plane.sh 中的两项检查确认行为：

# 数据面不应启用 Admin API：期望返回 404 curl -o /dev/null -s -w %{http_code} \ http://127.0.0.1:9080/apisix/admin/routes \ -H "X-API-KEY: <admin_key>"

测试脚本断言 "data_plane should not enable Admin API"，即9080上的 Admin API 路径返回404。

第二项检查确认数据面是只读配置消费者的。测试脚本先清空 etcd（etcdctl del / --prefix，会删除该 etcd 中所有数据，仅在专用测试集群上执行），启动数据面后执行：

etcdctl get / --prefix | wc -l

期望输出0，即 "data_plane does not write data to etcd"。这条命令依赖本机已安装etcdctl且能访问该 etcd。

限制与注意事项

• etcd TLS 证书默认校验：数据面默认校验 etcd 的 TLS 证书。测试脚本中，当 etcd 使用https://且未配置可信证书时，make run会失败，日志包含failed to load the configuration: https://127.0.0.1:12379: certificate verify failed。如果你的 etcd 是自签名证书，需要按 etcd TLS 配置提供cert/key，或在测试环境将deployment.etcd.tls.verify设为false（测试脚本 test_deployment_data_plane.sh 即采用此方式）。
• 配置来源是 etcd：Decoupled 模式下数据面不直接保存业务配置，路由、插件等全部经由控制面的 Admin API 写入 etcd 生效；数据面本身不提供 Admin API，也无法在本地修改配置。
• 端口冲突：控制面与数据面是独立实例，admin_listen（默认9180）与node_listen（默认9080）分别属于各自实例，同一台机器上部署多个实例时需自行避开端口冲突。

完成以上配置与验证后，你就得到了一组分离的 APISIX 部署：控制面在9180管理配置，数据面在9080代理流量，两者通过 etcd 保持配置同步。

【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix