APISIX Admin API 实战指南如何从零连上并完成路由、负载均衡与鉴权限流【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixApache APISIX Admin API 是网关的运维入口用 HTTP 请求就能改动路由、负载均衡与鉴权限流。本文覆盖如何连上端口并完成鉴权、路由转发、健康检查、限流三个核心任务以及分页、校验与生产环境的用法。先连上发出第一条管理请求这一节解决端口在哪、身份怎么证明的问题。Admin API 默认监听9180端口路径前缀是/apisix/admin。认证只有一个X-API-KEY请求头值取自conf/config.yaml中deployment.admin段的admin_key.key。这些字段改什么、会发生什么看这张表配置字段改它会发生什么默认值admin_listen.port管理端口迁到你指定的端口避免与node_listen冲突9180admin_key.key替换每个请求必须携带的令牌示例配置里为空必须自己填—admin_key.role改成viewer后这把 key 只能读配置不能写adminallow_admin只放行列表内的来源 IP其他来源直接被拒127.0.0.0/24admin_api_version取v3时才有分页、过滤查询和新响应格式v3把 key 放进环境变量后第一条管理请求用列出所有路由最合适——只读、无副作用跑通即说明端口、前缀、key 三样都对export ADMIN_KEY你的admin_key curl -i http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: $ADMIN_KEY返回 HTTP 200 且 body 形如{list:[...],total:N}就通了返回 401 说明 key 不对或allow_admin挡住了你的来源 IP。把请求路由到后端最小路由配置这一节解决客户端请求该往哪里去的问题。路由Route是 APISIX 里最小的转发单元它按规则匹配请求再交给上游。最简路由只需要一个uri和一个upstream。下面创建一条把/user/*转发到本地 8080 端口的路由curl http://127.0.0.1:9180/apisix/admin/routes/user-api \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { name: user-api, uri: /user/*, methods: [GET, POST], upstream: { type: roundrobin, nodes: { 127.0.0.1:8080: 1 } } }创建成功返回201 Created之后发curl http://127.0.0.1:9080/user/hello9080 是网关代理端口命中即说明路由生效。改uri会换掉匹配的路径改nodes里127.0.0.1:8080后面的数字会改这台节点分到的流量权重不想删路由只想临时下线把status改成0即可。其余常用字段字段改它会发生什么示例uris一次匹配多个 URI与uri二选一[/user/*,/profile/*]hosts只放行列表内的域名支持*.foo.com泛域名[api.example.com]priority多条路由匹配同一 URI 时数值大者优先10vars按 Nginx 变量自定义匹配如请求头、参数[[arg_uid,,1001]]upstream_id复用已单独创建的 Upstream比内联upstream更适合多路由共享后端user-api-uptimeout覆盖上游的 connect/send/read 超时秒{connect:3,read:10}给后端配负载均衡与健康检查这一节解决多台后端怎么分流量、坏节点怎么自动摘除的问题。单独创建一个 Upstream 资源路由再通过upstream_id引用它curl http://127.0.0.1:9180/apisix/admin/upstreams/user-api-up \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { type: roundrobin, nodes: { 10.0.0.11:8080: 3, 10.0.0.12:8080: 1 }, retries: 2, checks: { active: { type: http, http_path: /status, timeout: 3, concurrency: 10, healthy: { interval: 5, http_successes: 2 }, unhealthy: { interval: 5, http_failures: 3 } } } }创建后给路由打补丁换成引用对PATCH /apisix/admin/routes/user-api发送{upstream_id: user-api-up}。流量随即按 3:1 的权重在两台节点间轮询健康检查每 5 秒向/status发请求连续 2 次成功才把节点标记为健康连续 3 次失败就把它摘出流量池。改http_successes会改变恢复上线所需的连续成功次数改unhealthy.interval会改变故障节点被探活的频率。为接口挂上鉴权与限流联动消费者与路由这一节解决怎么知道调用方是谁、怎么防止单个调用方把接口打爆的问题。鉴权在 APISIX 里是消费者 插件的联动Consumer 资源存凭据路由上的插件决定拦不拦。以key-auth为例客户端把 key 放在请求头apikey里即可。# 1) 创建消费者把密钥发给调用方 tom curl -i http://127.0.0.1:9180/apisix/admin/consumers -X PUT \ -H X-API-KEY: $ADMIN_KEY -d { username: tom, plugins: { key-auth: { key: sK2m9xQpLw7vT4zB } } } # 2) 路由上同时打开 key-auth 与 limit-count curl -i http://127.0.0.1:9180/apisix/admin/routes/user-api -X PATCH \ -H X-API-KEY: $ADMIN_KEY -d { plugins: { key-auth: {}, limit-count: { count: 50, time_window: 60, key_type: var, key: remote_addr, rejected_code: 429 } } } # 3) 验证无 key 返回 401带 key 返回 20060 秒内第 51 次请求返回 429 curl -i http://127.0.0.1:9080/user/hello curl -i http://127.0.0.1:9080/user/hello -H apikey: sK2m9xQpLw7vT4zB改limit-count的count会直接改变限流阈值把rejected_code从 429 改回默认 503客户端感知到的拒绝码就跟着变key默认按remote_addr限流换成var指定的其他变量如http_x_api_key就能按调用方而不是 IP 限流。想给不同消费者不同限额把limit-count挂到消费者身上而不是路由上。参数速查匹配规则、负载均衡算法、插件与错误码这一节把前文分散的字段收口成四张表写配置时不用来回翻。路由匹配规则字段作用取值uri/uris按路径匹配支持通配符字符串 / 字符串数组host/hosts按域名匹配域名支持*.泛域名remote_addr/remote_addrs按客户端 IP 匹配IPv4、IPv6、CIDRmethods按 HTTP 方法匹配不填则放行全部方法vars按任意 Nginx 变量匹配[[var, op, val], ...]labels给路由打标签供过滤查询键值对负载均衡算法upstream.type算法改用它会发生什么roundrobin按权重轮询默认算法chash一致性哈希相同hash_on特征如 ip、cookie稳定落到同一节点ewma按近期响应时间加权响应快的节点分到更多流量least_conn总是发给当前活跃连接最少的节点常用插件插件用途关键字段key-auth消费者携带静态 key消费者侧必填keylimit-count按时间窗计数限流count、time_window必填limit-req按速率限流rate、burstprometheus暴露指标prefer_nametrue 时按路由名打标签错误码与处理现象原因处理401X-API-KEY无效对照conf/config.yaml的admin_key404资源不存在检查 id / username 拼写400配置未过 schema 校验读error_msg改字段后重试409资源 id 已存在换 id或改用 PATCH 更新can not delete this upstream被路由引用拒绝删除确认后果后加?forcetrue强删效率特性批量写入、分页过滤与配置校验这一节解决配置量大时如何少做重复操作的问题。批量创建向集合端点 POST 一个 JSON 数组不填 id 的条目会自动分配适合一次性灌入一批路由curl http://127.0.0.1:9180/apisix/admin/routes -X POST \ -H X-API-KEY: $ADMIN_KEY -d [ { uri: /v1/order, upstream: { type: roundrobin, nodes: { 10.0.0.11:8080: 1 } } }, { uri: /v1/pay, upstream: { type: roundrobin, nodes: { 10.0.0.12:8080: 1 } } } ]分页与过滤v3GET /apisix/admin/routes?page2page_size50翻页page_size取值 10–500?nameuserlabelenv:prod按name、label过滤路由还可加uri过滤多个过滤条件取交集。上线前校验POST /apisix/admin/schema/validate/routes把要发布的配置放请求体里做 dry-run只校验不写入避免坏配置直接落到 etcd。生产建议安全加固、监控与自动化脚本这一节列出上生产前必须处理的几件事。密钥与白名单admin_key.key绝不能沿用文档示例值配置里支持${ADMIN_KEY}语法从环境变量注入key 不落盘admin_listen.ip指向内网网卡allow_admin收窄到运维网段给只读监控工具单独发一把role: viewer的 key避免全员共用 admin 权限。监控接入给业务路由挂上prometheus插件并设prefer_name: true指标按路由名打标签便于在 Grafana 里按路由看 QPS 与延迟指标默认从127.0.0.1:9091/metrics暴露。自动化脚本把每份路由配置存成 JSON 文件用函数统一 PUT失败即退出#!/usr/bin/env bash # deploy-route.sh把本地 JSON 文件作为路由发布 set -euo pipefail ADMINhttp://127.0.0.1:9180/apisix/admin ADMIN_KEY${ADMIN_KEY:?请先 export ADMIN_KEY} deploy_route() { curl -fsS -X PUT $ADMIN/routes/$1 \ -H X-API-KEY: $ADMIN_KEY -d $2 } deploy_route user-api configs/user-api.json deploy_route order-api configs/order-api.json记这几件事就够上手所有变更都经 Admin API 写入 etcd热生效、不重启网关PUT 建或覆盖PATCH 局部改DELETE 删除。起步阶段upstream直接内联在路由里多条路由共享同一后端时拆成独立 Upstream 再用upstream_id引用。鉴权与限流是联动关系消费者携带凭据路由上的插件决定是否拦截两边缺一不可。发布前先用schema/validate端点 dry-run被引用资源删除受阻时再考虑forcetrue。想深入字段级完整定义看 docs/en/latest/admin-api.md部署项示例在 conf/config.yaml.example 的deployment.admin段管理端实现源码在 apisix/admin/插件源码在 apisix/plugins/管理 API 的行为测试在 t/admin/跑一遍测试就是最快的排错参考。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 APISIX Admin API 实战指南：如何从零连上并完成路由、负载均衡与鉴权限流
APISIX Admin API 实战指南如何从零连上并完成路由、负载均衡与鉴权限流【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixApache APISIX Admin API 是网关的运维入口用 HTTP 请求就能改动路由、负载均衡与鉴权限流。本文覆盖如何连上端口并完成鉴权、路由转发、健康检查、限流三个核心任务以及分页、校验与生产环境的用法。先连上发出第一条管理请求这一节解决端口在哪、身份怎么证明的问题。Admin API 默认监听9180端口路径前缀是/apisix/admin。认证只有一个X-API-KEY请求头值取自conf/config.yaml中deployment.admin段的admin_key.key。这些字段改什么、会发生什么看这张表配置字段改它会发生什么默认值admin_listen.port管理端口迁到你指定的端口避免与node_listen冲突9180admin_key.key替换每个请求必须携带的令牌示例配置里为空必须自己填—admin_key.role改成viewer后这把 key 只能读配置不能写adminallow_admin只放行列表内的来源 IP其他来源直接被拒127.0.0.0/24admin_api_version取v3时才有分页、过滤查询和新响应格式v3把 key 放进环境变量后第一条管理请求用列出所有路由最合适——只读、无副作用跑通即说明端口、前缀、key 三样都对export ADMIN_KEY你的admin_key curl -i http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: $ADMIN_KEY返回 HTTP 200 且 body 形如{list:[...],total:N}就通了返回 401 说明 key 不对或allow_admin挡住了你的来源 IP。把请求路由到后端最小路由配置这一节解决客户端请求该往哪里去的问题。路由Route是 APISIX 里最小的转发单元它按规则匹配请求再交给上游。最简路由只需要一个uri和一个upstream。下面创建一条把/user/*转发到本地 8080 端口的路由curl http://127.0.0.1:9180/apisix/admin/routes/user-api \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { name: user-api, uri: /user/*, methods: [GET, POST], upstream: { type: roundrobin, nodes: { 127.0.0.1:8080: 1 } } }创建成功返回201 Created之后发curl http://127.0.0.1:9080/user/hello9080 是网关代理端口命中即说明路由生效。改uri会换掉匹配的路径改nodes里127.0.0.1:8080后面的数字会改这台节点分到的流量权重不想删路由只想临时下线把status改成0即可。其余常用字段字段改它会发生什么示例uris一次匹配多个 URI与uri二选一[/user/*,/profile/*]hosts只放行列表内的域名支持*.foo.com泛域名[api.example.com]priority多条路由匹配同一 URI 时数值大者优先10vars按 Nginx 变量自定义匹配如请求头、参数[[arg_uid,,1001]]upstream_id复用已单独创建的 Upstream比内联upstream更适合多路由共享后端user-api-uptimeout覆盖上游的 connect/send/read 超时秒{connect:3,read:10}给后端配负载均衡与健康检查这一节解决多台后端怎么分流量、坏节点怎么自动摘除的问题。单独创建一个 Upstream 资源路由再通过upstream_id引用它curl http://127.0.0.1:9180/apisix/admin/upstreams/user-api-up \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { type: roundrobin, nodes: { 10.0.0.11:8080: 3, 10.0.0.12:8080: 1 }, retries: 2, checks: { active: { type: http, http_path: /status, timeout: 3, concurrency: 10, healthy: { interval: 5, http_successes: 2 }, unhealthy: { interval: 5, http_failures: 3 } } } }创建后给路由打补丁换成引用对PATCH /apisix/admin/routes/user-api发送{upstream_id: user-api-up}。流量随即按 3:1 的权重在两台节点间轮询健康检查每 5 秒向/status发请求连续 2 次成功才把节点标记为健康连续 3 次失败就把它摘出流量池。改http_successes会改变恢复上线所需的连续成功次数改unhealthy.interval会改变故障节点被探活的频率。为接口挂上鉴权与限流联动消费者与路由这一节解决怎么知道调用方是谁、怎么防止单个调用方把接口打爆的问题。鉴权在 APISIX 里是消费者 插件的联动Consumer 资源存凭据路由上的插件决定拦不拦。以key-auth为例客户端把 key 放在请求头apikey里即可。# 1) 创建消费者把密钥发给调用方 tom curl -i http://127.0.0.1:9180/apisix/admin/consumers -X PUT \ -H X-API-KEY: $ADMIN_KEY -d { username: tom, plugins: { key-auth: { key: sK2m9xQpLw7vT4zB } } } # 2) 路由上同时打开 key-auth 与 limit-count curl -i http://127.0.0.1:9180/apisix/admin/routes/user-api -X PATCH \ -H X-API-KEY: $ADMIN_KEY -d { plugins: { key-auth: {}, limit-count: { count: 50, time_window: 60, key_type: var, key: remote_addr, rejected_code: 429 } } } # 3) 验证无 key 返回 401带 key 返回 20060 秒内第 51 次请求返回 429 curl -i http://127.0.0.1:9080/user/hello curl -i http://127.0.0.1:9080/user/hello -H apikey: sK2m9xQpLw7vT4zB改limit-count的count会直接改变限流阈值把rejected_code从 429 改回默认 503客户端感知到的拒绝码就跟着变key默认按remote_addr限流换成var指定的其他变量如http_x_api_key就能按调用方而不是 IP 限流。想给不同消费者不同限额把limit-count挂到消费者身上而不是路由上。参数速查匹配规则、负载均衡算法、插件与错误码这一节把前文分散的字段收口成四张表写配置时不用来回翻。路由匹配规则字段作用取值uri/uris按路径匹配支持通配符字符串 / 字符串数组host/hosts按域名匹配域名支持*.泛域名remote_addr/remote_addrs按客户端 IP 匹配IPv4、IPv6、CIDRmethods按 HTTP 方法匹配不填则放行全部方法vars按任意 Nginx 变量匹配[[var, op, val], ...]labels给路由打标签供过滤查询键值对负载均衡算法upstream.type算法改用它会发生什么roundrobin按权重轮询默认算法chash一致性哈希相同hash_on特征如 ip、cookie稳定落到同一节点ewma按近期响应时间加权响应快的节点分到更多流量least_conn总是发给当前活跃连接最少的节点常用插件插件用途关键字段key-auth消费者携带静态 key消费者侧必填keylimit-count按时间窗计数限流count、time_window必填limit-req按速率限流rate、burstprometheus暴露指标prefer_nametrue 时按路由名打标签错误码与处理现象原因处理401X-API-KEY无效对照conf/config.yaml的admin_key404资源不存在检查 id / username 拼写400配置未过 schema 校验读error_msg改字段后重试409资源 id 已存在换 id或改用 PATCH 更新can not delete this upstream被路由引用拒绝删除确认后果后加?forcetrue强删效率特性批量写入、分页过滤与配置校验这一节解决配置量大时如何少做重复操作的问题。批量创建向集合端点 POST 一个 JSON 数组不填 id 的条目会自动分配适合一次性灌入一批路由curl http://127.0.0.1:9180/apisix/admin/routes -X POST \ -H X-API-KEY: $ADMIN_KEY -d [ { uri: /v1/order, upstream: { type: roundrobin, nodes: { 10.0.0.11:8080: 1 } } }, { uri: /v1/pay, upstream: { type: roundrobin, nodes: { 10.0.0.12:8080: 1 } } } ]分页与过滤v3GET /apisix/admin/routes?page2page_size50翻页page_size取值 10–500?nameuserlabelenv:prod按name、label过滤路由还可加uri过滤多个过滤条件取交集。上线前校验POST /apisix/admin/schema/validate/routes把要发布的配置放请求体里做 dry-run只校验不写入避免坏配置直接落到 etcd。生产建议安全加固、监控与自动化脚本这一节列出上生产前必须处理的几件事。密钥与白名单admin_key.key绝不能沿用文档示例值配置里支持${ADMIN_KEY}语法从环境变量注入key 不落盘admin_listen.ip指向内网网卡allow_admin收窄到运维网段给只读监控工具单独发一把role: viewer的 key避免全员共用 admin 权限。监控接入给业务路由挂上prometheus插件并设prefer_name: true指标按路由名打标签便于在 Grafana 里按路由看 QPS 与延迟指标默认从127.0.0.1:9091/metrics暴露。自动化脚本把每份路由配置存成 JSON 文件用函数统一 PUT失败即退出#!/usr/bin/env bash # deploy-route.sh把本地 JSON 文件作为路由发布 set -euo pipefail ADMINhttp://127.0.0.1:9180/apisix/admin ADMIN_KEY${ADMIN_KEY:?请先 export ADMIN_KEY} deploy_route() { curl -fsS -X PUT $ADMIN/routes/$1 \ -H X-API-KEY: $ADMIN_KEY -d $2 } deploy_route user-api configs/user-api.json deploy_route order-api configs/order-api.json记这几件事就够上手所有变更都经 Admin API 写入 etcd热生效、不重启网关PUT 建或覆盖PATCH 局部改DELETE 删除。起步阶段upstream直接内联在路由里多条路由共享同一后端时拆成独立 Upstream 再用upstream_id引用。鉴权与限流是联动关系消费者携带凭据路由上的插件决定是否拦截两边缺一不可。发布前先用schema/validate端点 dry-run被引用资源删除受阻时再考虑forcetrue。想深入字段级完整定义看 docs/en/latest/admin-api.md部署项示例在 conf/config.yaml.example 的deployment.admin段管理端实现源码在 apisix/admin/插件源码在 apisix/plugins/管理 API 的行为测试在 t/admin/跑一遍测试就是最快的排错参考。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考