APISIX Admin API 完整教程：6步从认证到限流，搭好第一套网关配置

APISIX Admin API 完整教程：6步从认证到限流，搭好第一套网关配置

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

Apache APISIX 是一款云原生 API 网关，而APISIX Admin API就是它的管理入口：一个内置的 RESTful 接口，路由、上游、消费者、插件这些网关里的东西，用一条 curl 就能增删改查。这篇文章按"你要完成的任务"来走：先把 Admin API 跑通并完成认证，然后配路由、配负载均衡、给调用方发凭证、上插件，最后处理批量操作和常见报错，跟着做完就是完整的一次 API 网关管理实践。

第一步：让 Admin API 跑起来并完成认证

先说清楚这件事是什么：Admin API 就是网关的"控制面板"，默认监听 9180 端口，所有请求都走/apisix/admin这个前缀。没有合法钥匙，任何请求都会被拒之门外。

上手前确认三件事：

• 在部署配置里设置deployment.admin.admin_key，拿一个admin角色的密钥，配置样例可以参考 conf/config.yaml.example；
• 密钥通过请求头X-API-KEY传递；
• 用allow_admin限定允许调用的来源 IP，建议只放办公网段或内网段。

认证验证就这两行：

export ADMIN_KEY="edd1c9f034335f136f87ad84b625c8f1" curl -H "X-API-KEY: $ADMIN_KEY" http://127.0.0.1:9180/apisix/admin/routes

返回路由列表（哪怕是空数组）就说明认证通过了，之后所有操作都用这一个请求头。⚠️ 易错提示：返回 401 基本都是密钥没带或写错；另外别漏了路径必须带/apisix/admin前缀，直接打:9180/routes是进不去的。

第二步：配置 APISIX 路由，让请求落到正确的后端

路由回答一个问题："什么样的请求，转发给哪个后端？"一句话版本——路由是请求的入口，网关按匹配规则把它交给对应的上游服务。

写一段路由 JSON，PUT 到/apisix/admin/routes/{id}，立即生效：

{ "uri": "/api/users/*", "name": "user-api-route", "methods": ["GET", "POST"], "upstream": { "type": "roundrobin", "nodes": { "192.168.1.100:8080": 1, "192.168.1.101:8080": 1 } } }

常用匹配维度其实就几类：uri/uris匹配路径（支持通配符和正则），host/hosts匹配域名（泛域名也支持），methods限定 HTTP 方法，remote_addr/remote_addrs按客户端 IP 识别（CIDR 写法），vars则是拿 Nginx 变量写表达式，比如按某个 header 或参数分流。要更细的控制，还有priority调多条路由的先后、filter_func写自定义 Lua 判断、timeout分别设 connect/send/read 三段超时。

同样的事也可以在 APISIX Dashboard 的可视化界面里完成，表单会一步步引导你定义请求：

⚠️ 易错提示：多条路由能匹配同一个请求时，priority高的生效；如果你发现请求"跑"到了错误的后端，先查这里的优先级设置。

第三步：给后端加上 APISIX 负载均衡与健康检查

上一步的路由里挂了两个后端节点，但流量到底怎么分？某台机器挂了怎么自动踢掉？这就是上游服务（Upstream）干的事。

负载均衡 APISIX 内置四种算法可选：roundrobin 按权重轮转，适合大多数场景；least_conn 每次挑连接数最少的机器，长连接业务更稳；chash 一致性哈希，按请求特征把同类请求固定到同一台后端；ewma 会记录响应时间，把流量往快的机器上引。选哪个只改type一个字段。

健康检查放在checks.active里：发 HTTP 请求探一个/health这样的路径，设healthy（连续几次成功算健康）和unhealthy（连续几次失败算不健康），再配interval、timeout、concurrency这些节奏参数。不健康的节点会被自动摘出，恢复后自动加回，全程不用人工介入。另外retries可以设上游重试次数，timeout微调超时。上游是独立资源，走/apisix/admin/upstreams/{id}管理，路由按 ID 引用它——以后换机器只动上游，路由完全不用碰。

⚠️ 易错提示：nodes里地址后面的数字是权重，不是机器台数。写{"192.168.1.100:8080": 30}的意思是这台机器承担约三成流量，不是三台机器。

第四步：给调用方发身份凭证——APISIX 消费者管理

路由和后端都通了，下一个问题是：谁来调、调了多少，你说不说得清？答案是消费者（Consumer）——网关里的"调用方身份档案"。一句话版本：建一个消费者，通过认证插件（比如 key-auth）给它发一把凭证，以后没带凭证的请求直接被拒。

操作就是 PUT 一段配置到/apisix/admin/consumers/{username}，写上消费者名字，然后在plugins里挂认证插件。以最简单的 key-auth 为例，给它一个key，调用方每次请求把这个 key 带上就行。顺手还能在消费者身上挂限流插件，实现"按调用方"定配额，而不是按整个接口。

⚠️ 易错提示：消费者名字是它的唯一标识；而且凭证只在开启了相应认证插件的路由上才有效——路由没挂 key-auth，你发的 key 就只是一张空头支票。

第五步：用 APISIX 插件做限流、认证与监控

插件是网关的"应用商店"。一句话版本：你想给请求加的任何能力——限流、鉴权、日志、回放——基本都有现成插件，写几个参数就能生效。

先看有什么：GET /apisix/admin/plugins/list返回全部可用插件，插件实现代码都在 plugins/ 目录下可以翻阅。用得最多的三类：

• 限流：limit-count按时间窗口计数，count加time_window，用key_type选按 IP 还是按调用方统计；limit-req是漏桶式限速，rate加burst，超了直接返回 503；
• 认证：jwt-auth校验 JWT（配secret、algorithm、exp），key-auth、basic-auth、hmac-auth各有适用场景；
• 可观测：prometheus暴露监控指标，接上 Grafana 就是一套完整大盘。

用法统一：把插件名和参数写进路由、服务或消费者的plugins字段，就在对应范围生效。同一插件可以在多个范围共存，策略层层叠加。

⚠️ 易错提示：写在消费者里的插件只影响认证为该消费者的请求；想让某个策略覆盖全部流量，得挂到路由或全局规则上。

第六步：批量操作与常见报错处理

规模上来之后，一条条管理太慢，给你三个提速手段：

• 批量创建：向/apisix/admin/routes发一个 JSON 数组的 POST 请求，一批路由一次建好；
• 强制删除：被其他资源引用的资源默认拒绝删除，在DELETE /apisix/admin/upstreams/{id}上追加?force=true可以强删；
• 预校验：把配置先 POST 到/apisix/admin/schema/validate/routes，让网关先体检一遍，通过了再真正下发。

V3 的列表接口还支持分页（page+page_size）和过滤（按name搜索、按label筛，比如label=env:prod），资源多了也好找。

报错也别慌，记住四个高频码：401是密钥不对，查X-API-KEY；404是资源 ID 找错了；400是请求体没通过校验，错误信息一般直接点名问题字段；409是资源已存在。响应里的error_msg说什么就按什么改，基本不用翻文档猜。

接下来可以做什么

到这里，你其实已经能独立完成 API 网关管理的日常操作了：改路由、加后端、发凭证、开限流，全程分钟级生效、不用重启进程。

给你两个下一步建议：一是把 docs/ 里各资源的字段说明过一遍，养成重要配置先走schema/validate预校验再下发的习惯；二是等你上手熟练后，试试把"认证 → 限流 → 监控"串成完整链路，或者用 serverless 类插件写自己的 Lua 逻辑。网关的配置说到底都是数据，把 APISIX Admin API 用熟之后，管理网关和写代码没多大区别。

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