Apache APISIX Control API 完全指南内部状态暴露与数据平面控制【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixControl API 是 Apache APISIX 中独立于 Admin API 与普通数据面流量的一套内部接口专门用于暴露 APISIX 实例的内部状态如插件 Schema、健康检查状态、插件元数据、路由/上游/服务配置快照并控制单个数据平面节点的行为如触发 GC、热加载插件。本文以 docs/zh/latest/control-api.md 为骨架结合仓库源码apisix/control/v1.lua、apisix/control/router.lua与测试用例系统讲解 Control API 的配置方法、内置端点、返回格式与底层实现原理帮助你快速掌握利用 Control API 进行故障排查、状态观测与节点级运维控制的实战能力。Control API 是什么定位与用途Control API 服务于两类核心诉求暴露 APISIX 内部状态信息例如当前实例实际生效的 JSON Schema、各健康检查器的实时状态、插件的元数据Plugin Metadata、以及内存中的路由/上游/服务配置快照控制单个 APISIX 数据平面节点的行为例如触发一次全量 GC、热加载重载插件。它并不承担普通网关转发职责也不用于业务配置管理那是 Admin API 的职责。从源码上看Control API 与数据面完全隔离在 apisix/init.lua 中http_control阶段函数调用control_api_router.match(get_var(uri))完成路由分发与普通请求的http_access_phase等数据面执行链相互独立。因此它非常适合在本机进行调试、观测与运维操作而不应暴露到外部网络。启用与配置 Control API默认情况下Control API 是启用的监听127.0.0.1:9090。配置位于apisix/conf/config.yaml对应仓库中的 conf/config.yaml.example的apisix段apisix: ... enable_control: true control: ip: 127.0.0.1 port: 9090配置项说明配置项默认值说明enable_controltrue是否启用 Control API server。置为false将完全关闭该服务control.ip127.0.0.1Control API 监听地址control.port9090Control API 监听端口两个需要注意的点默认不支持参数匹配插件注册的 Control API 默认不支持 URL 参数匹配。如果想启用可以在control段添加router: radixtree_uri_with_parameter。该选项在 apisix/control/router.lua 中被读取当conf.apisix.control.router为该值时with_parameter trueControl API 路由将由resty.radixtree构建从而支持带参数的 URI 匹配否则使用基于apisix.utils.router的普通匹配器。安全红线Control API server不应该被配置成监听公网地址。它暴露的是节点内部状态与控制能力一旦暴露到公网任何人都可能读取内部配置快照甚至触发 GC / 插件热加载等操作存在严重安全隐患。Control API 的路由与分发机制从源码结构看Control API 的路由由 apisix/control/router.lua 统一管理其核心逻辑如下遍历当前已启用的插件plugin_mod.plugins若插件实现了control_api()函数则将其返回的路由注册到路由表中apisix/control/router.lua若配置了服务发现discovery模块且其实现了control_api也会以/v1/discovery/模块名/...的前缀注册对应接口apisix/control/router.lua内置的/v1/*接口统一以子路由v1_router的方式挂载apisix/control/router.lua这部分接口实现在 apisix/control/v1.lua 中声明方法、URI、handler 三元组路由表带有缓存版本plugin_mod.load_times当插件发生重载时路由表会自动重建apisix/control/router.lua。这意味着通过插件添加的 Control API 是动态的——只有被启用的插件其control_api才会被注册。因此下文“独立于插件的 Control API”所列的/v1/*内置接口始终可用而插件接口则取决于你启用了哪些插件。通过插件添加的 Control APIAPISIX 中一些插件自带 Control API。典型的两个例子server-info 插件在 apisix/plugins/server-info.lua 中注册了GET /v1/server_info用于返回当前节点的服务器信息etcd 版本、主机名、节点 id、APISIX 版本、启动时间等。该信息同时会被周期性地写入 etcd 的/data_plane/server_info/路径见 apisix/plugins/server-info.lua。example-plugin 插件在 apisix/plugins/example-plugin.lua 中注册了GET /v1/plugin/example-plugin/hello演示了插件如何以methods uris handler的结构声明自己的 Control API。如果你对某个插件的 Control API 感兴趣请直接参阅对应插件的文档。独立于插件的 Control API以下接口由 apisix/control/v1.lua 内置提供不依赖任何插件启用状态。GET /v1/schema引入自 2.2 版本返回当前 APISIX 实例实际使用的 JSON Schema格式如下{ main: { route: { properties: {...} }, upstream: { properties: {...} }, ... }, plugins: { example-plugin: { consumer_schema: {...}, metadata_schema: {...}, schema: {...}, type: ..., priority: 0, version: 0.1 }, ... }, stream-plugins: { mqtt-proxy: { ... }, ... } }从 apisix/control/v1.lua 的实现看返回结构分为三部分main核心资源 Schema包括consumer、consumer_group、global_rule、plugin_config、plugins、proto、route、service、ssl、stream_route、upstream以及upstream_hash_header_schema、upstream_hash_vars_schema等均来自core.schemapluginsHTTP 插件的元信息通过plugin.get_all一次性获取每个插件的version、priority、schema、metadata_schema、consumer_schema、type、scopestream_plugins四层stream插件的同样元信息。只有启用了的插件才会出现在plugins/stream_plugins部分。部分插件可能缺失consumer_schema或type字段这取决于插件自身的定义。该接口常用于第三方工具如控制台、代码生成器动态获取当前实例的校验规则测试见 t/control/schema.t。GET /v1/healthcheck引入自 2.3 版本返回当前所有健康检查health check的状态格式如下[ { nodes: [ { ip: 52.86.68.46, counter: { http_failure: 0, success: 0, timeout_failure: 0, tcp_failure: 0 }, port: 80, status: healthy }, { ip: 100.24.156.8, counter: { http_failure: 5, success: 0, timeout_failure: 0, tcp_failure: 0 }, port: 80, status: unhealthy } ], name: /apisix/routes/1, type: http } ]每个 entry 的字段含义name资源 ID即健康检查的报告对象如/apisix/routes/1、/apisix/upstreams/1type健康检查类型取值为[http, https, tcp]nodes被检查的节点列表nodes[i].ip节点 IP 地址nodes[i].port节点端口nodes[i].status节点状态取值为[healthy, unhealthy, mostly_healthy, mostly_unhealthy]nodes[i].counter.success成功计数器nodes[i].counter.http_failureHTTP 访问失败计数器nodes[i].counter.tcp_failureTCP 连接或读写失败计数器nodes[i].counter.timeout_failure超时计数器。从 apisix/control/v1.lua 的实现看/v1/healthcheck会遍历内存中的 routes、services、upstreams 三个配置源凡配置了checks主动/被动健康检查的条目都会纳入统计type由checks.active.type或checks.passive.type推导apisix/control/v1.lua。查询指定健康检查器GET /v1/healthcheck/{src_type}/{src_id}可以通过GET /v1/healthcheck/$src_type/$src_id获取指定 health checker 的状态其中src_type取routes/services/upstreams之一。例如GET /v1/healthcheck/upstreams/1返回{ nodes: [ { ip: 52.86.68.46, counter: { http_failure: 0, success: 2, timeout_failure: 0, tcp_failure: 0 }, port: 80, status: healthy }, { ip: 100.24.156.8, counter: { http_failure: 5, success: 0, timeout_failure: 0, tcp_failure: 0 }, port: 80, status: unhealthy } ], type: http, name: /apisix/routes/1 }实现上该接口解析 URI 中的src_type与src_idapisix/control/v1.luasrc_type非法时返回400资源不存在或未配置 checks 时返回404。:::note只有一个上游满足以下条件时它的健康检查状态才会出现在结果里面上游配置了健康检查上游在任何一个 worker 进程处理过客户端请求。:::一个实用的细节如果你使用浏览器访问该 API请求头携带Accept: text/html将直接得到一个可读的 HTML 状态页面。该逻辑在 apisix/control/v1.lua 中通过resty.template渲染内嵌的 HTML 模板实现模板会为healthy/mostly_healthy之外的节点行标记红色背景便于快速发现异常节点截图对应的模板定义见 apisix/control/v1.lua健康检查的完整配置方法可参考 docs/zh/latest/tutorials/health-check.md相关端到端测试见 t/control/healthcheck.t。POST /v1/gc引入自 2.8 版本在 HTTP 子系统中触发一次全量 GC。实现非常直接_M.trigger_gc()调用 Lua 的collectgarbage()apisix/control/v1.lua。典型使用场景是排查内存增长问题后手动回收 Lua 侧内存测试 t/control/gc.t 演示了分配大量临时表后调用/v1/gc验证内存回落超过 90% 的过程。注意当你启用 stream proxy 时APISIX 将为 stream 子系统运行另一个独立的 Lua 虚拟机POST /v1/gc不会触发该 Lua 虚拟机中的全量 GC源码中对应注释见 apisix/control/v1.lua。如需对 stream 子系统做内存回收需要另行处理。GET /v1/plugin_metadatas引入自 3.0.0 版本打印当前实例中所有已启用插件的元数据Plugin Metadata[ { log_format: { upstream_response_time: $upstream_response_time }, id: file-logger }, { ikey: 1, skey: val, id: example-plugin } ]实现见 apisix/control/v1.lua遍历本地配置local_conf().plugins中声明的插件名通过plugin.plugin_metadata(name)取到元数据后组装返回。这里的id字段即插件名其余字段来自通过 Admin API 为插件设置的 Plugin Metadata。GET /v1/plugin_metadata/{plugin_name}引入自 3.0.0 版本打印指定插件的元数据例如GET /v1/plugin_metadata/file-logger返回{ log_format: { upstream_response_time: $upstream_response_time }, id: file-logger }实现见 apisix/control/v1.lua若指定插件没有配置元数据返回404。测试见 t/control/plugin-metadata.t其中也覆盖了batch-requests等插件的元数据查询场景。从源码与测试看 Control API 的完整路由清单结合 apisix/control/v1.lua 的路由声明内置接口汇总如下方法URI说明引入版本GET/v1/schema返回实例当前使用的完整 JSON Schema2.2GET/v1/healthcheck返回所有健康检查状态支持Accept: text/html输出 HTML 页面2.3GET/v1/healthcheck/{src_type}/{src_id}返回指定 health checker 状态src_type为 routes/services/upstreams2.3POST/v1/gc在 HTTP 子系统触发一次全量 GC2.8GET/v1/plugin_metadatas返回所有已启用插件的元数据3.0.0GET/v1/plugin_metadata/{plugin_name}返回指定插件的元数据3.0.0GET/v1/routes转储内存中全部路由配置内置GET/v1/route/{id}转储指定路由配置内置GET/v1/services转储内存中全部服务配置内置GET/v1/service/{id}转储指定服务配置内置GET/v1/upstreams转储内存中全部上游配置内置GET/v1/upstream/{id}转储指定上游配置内置PUT/v1/plugins/reload热加载重载插件内置值得说明的是文档正文重点描述了前六个接口而routes/services/upstreams的转储接口与PUT /v1/plugins/reload也已内置在 apisix/control/v1.lua 与 apisix/control/v1.lua 中可直接作为内存配置快照排查工具使用。其中PUT /v1/plugins/reload通过事件系统events:post广播control-api-plugin-reload事件apisix/control/router.lua 中注册的处理器会调用plugin_mod.load()完成插件热加载这也解释了为何插件重载后 Control API 路由会自动重建。实战一次典型的 Control API 使用流程结合以上接口给出一个本机运维排查的完整示例# 1. 查看当前实例实际生效的 Schema排查校验失败问题时定位规则 curl http://127.0.0.1:9090/v1/schema # 2. 查看所有健康检查器状态JSON 格式 curl http://127.0.0.1:9090/v1/healthcheck # 3. 用浏览器打开以下地址获得人类可读的 HTML 状态页 # http://127.0.0.1:9090/v1/healthcheck # 4. 精确查看某个上游的健康状态 curl http://127.0.0.1:9090/v1/healthcheck/upstreams/1 # 5. 转储内存中的路由 / 上游配置快照与 etcd 侧配置做对比 curl http://127.0.0.1:9090/v1/routes curl http://127.0.0.1:9090/v1/upstreams # 6. 查看插件元数据确认 Plugin Metadata 是否已生效 curl http://127.0.0.1:9090/v1/plugin_metadatas curl http://127.0.0.1:9090/v1/plugin_metadata/file-logger # 7. 排查内存问题时手动触发一次全量 GC仅 HTTP 子系统 curl -X POST http://127.0.0.1:9090/v1/gc使用建议与限制所有接口都应在本机或受信内网访问切勿将 Control API 监听地址配置为公网地址/v1/gc只作用于 HTTP 子系统的 Lua VMstream 子系统需另行考虑/v1/healthcheck的结果依赖 worker 进程实际处理过请求新配置的、尚无流量的上游不会出现在结果中插件类 Control API如server-info的/v1/server_info仅在对应插件启用后可用。总结Control API 是 APISIX 数据平面节点级的“体检与维修通道”/v1/schema让你拿到实例真实的校验规则/v1/healthcheck与/v1/healthcheck/{src_type}/{src_id}让你随时掌握各上游节点的健康状态还附带 HTML 可视化页面/v1/plugin_metadatas与/v1/plugin_metadata/{plugin_name}帮助你核对插件元数据而/v1/gc、PUT /v1/plugins/reload以及 routes/services/upstreams 转储接口则提供了节点级的内存控制与配置快照能力。理解其路由注册机制插件control_api()动态注册 /v1/*内置子路由后你甚至可以参考 apisix/plugins/example-plugin.lua 为自己的插件扩展专属 Control API把节点内部的诊断能力沉淀为团队可复用的运维资产。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考