企业官网建设流程全解析

APISIX Admin API 实战手册：5 个接口搞定路由、负载均衡与鉴权

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

不停服把流量切到新服务版本、给后端加健康检查、按消费者限流——这些日常动作都能靠Apache APISIX Admin API完成。这是一组跑在网关上的 REST 接口，路由、上游、Service、Consumer、插件都可以动态增删改查，适合写脚本的开发者和维护网关的运维直接上手。

准备篇：环境要求与 APISIX Admin API 认证怎么配

这一节解决"第一条 curl 怎么发出去才不报 401"。Admin API 默认监听9180端口，所有接口都挂在/apisix/admin前缀下；调用时必须在请求头带上X-API-KEY，值就是配置里的 admin_key。key 和监听地址都写在conf/config.yaml（可参考 conf/config.yaml.example）：

deployment: role: traditional role_traditional: config_provider: etcd admin: admin_key: - name: admin key: 8a2d71c5b4e9f60d3a17c2e8f5b90d4a # 生产环境务必更换，并妥善保管 role: admin allow_admin: - 10.0.0.0/8 # 只放行内网网段访问管理接口 admin_listen: ip: 0.0.0.0 port: 9180

把 key 放进环境变量，之后所有请求都复用同一组变量；下面这条是验证认证是否生效的最短命令：

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

返回{"list":[],"total":0}即说明认证和连通性都没问题。

任务一：APISIX 创建路由（最小 PUT 示例 + 匹配规则速查）

这一节解决"一条流量从哪进、往哪走"。路由的创建和更新是同一个接口：PUT到/apisix/admin/routes/{id}，ID 可以是数字或字符串。下面是最小可运行的路由——匹配/v1/users，转发到两个节点：

curl http://127.0.0.1:9180/apisix/admin/routes/101 \ -H "X-API-KEY: $ADMIN_KEY" -X PUT -d ' { "uri": "/v1/users", "upstream": { "type": "roundrobin", "nodes": { "10.0.4.11:8080": 1, "10.0.4.12:8080": 1 } } }'

成功时返回 HTTP 200 和{"action":"create","node":{"key":".../routes/101",...}}。同一路由再加字段（如 plugins、priority）再 PUT 一次即可覆盖更新。

匹配规则速查——命中任意一条即可能选中该路由，多条命中时按priority（默认 0，越大越优先）决胜：

任务二：APISIX 上游服务负载均衡与健康检查配置

这一节解决"后端怎么挑、挂了你怎么办"。把 upstream 单独建一条资源，就能被多条路由复用；下面这条挂了权重，并开启主动健康检查：

curl http://127.0.0.1:9180/apisix/admin/upstreams/pay-cluster \ -H "X-API-KEY: $ADMIN_KEY" -X PUT -d ' { "type": "roundrobin", "nodes": { "10.0.4.21:8080": 100, "10.0.4.22:8080": 100 }, "checks": { "active": { "type": "http", "http_path": "/livez", # 后端健康检查探针 "healthy": { "interval": 10, "successes": 2 }, "unhealthy": { "interval": 10, "http_failures": 3 } } } }'

健康检查失败的节点会被摘除，恢复后自动加回。四种type一句话对比：

任务三：用 Service 收敛公共配置、用 Consumer 做鉴权限流

这一节解决"同一套配置为什么要在每条路由里复制粘贴"。Service 是路由的公共配置层：挂在路由上的service字段生效后，其 plugins、upstream 与路由级配置合并。下面这条给一组路由共享限流和重写：

curl http://127.0.0.1:9180/apisix/admin/services/user-svc \ -H "X-API-KEY: $ADMIN_KEY" -X PUT -d ' { "plugins": { "limit-count": { "count": 500, "time_window": 60, "key_type": "var", "key": "remote_addr" } } }'

Consumer 代表"谁在调用网关"，把凭证直接写进它的plugins字段；之后用 consumer-restriction 等插件把它关联到路由上，就能做到按调用方限流鉴权：

curl http://127.0.0.1:9180/apisix/admin/consumers/mobile-app \ -H "X-API-KEY: $ADMIN_KEY" -X PUT -d ' { "username": "mobile-app", "plugins": { "key-auth": { "key": "m0b1le-c4ll-9f3a" }, "limit-count": { "count": 200, "time_window": 60, "rejected_code": 429 } } }'

插件速查：APISIX 常用插件最小配置

这一节给出三个出现频率最高的插件，配置都塞在plugins字段里，挂在路由、Service 或 Consumer 任意一级。完整插件清单可运行GET /apisix/admin/plugins/list查看。

效率技巧：批量、分页、过滤、校验

这一节把重复劳动压到最少。

Admin API 批量创建路由——POST 不带 ID，请求体为 JSON 数组，一次落地多条：

curl http://127.0.0.1:9180/apisix/admin/routes -H "X-API-KEY: $ADMIN_KEY" -X POST -d '[ { "uri": "/v1/users", "upstream": { "nodes": {"10.0.4.11:8080": 1}, "type": "roundrobin" } }, { "uri": "/v1/products", "upstream": { "nodes": {"10.0.4.15:8080": 1}, "type": "roundrobin" } } ]'

分页查询——GET 加page与page_size（取值 10~500），返回体带total和切片后的list：

curl "http://127.0.0.1:9180/apisix/admin/routes?page=2&page_size=20" -H "X-API-KEY: $ADMIN_KEY"

条件过滤——name、label、uri支持 AND 组合过滤，先缩小范围再翻页：

curl "http://127.0.0.1:9180/apisix/admin/routes?name=user&label=env:prod" -H "X-API-KEY: $ADMIN_KEY"

schema 校验——改动先过一遍格式关卡，不用真写进集群：

curl http://127.0.0.1:9180/apisix/admin/schema/validate/routes -H "X-API-KEY: $ADMIN_KEY" -X POST -d '{"uri": "/v1/*"}'

强制删除——带force=true跳过引用检查，用于清理被引用卡住的资源，动手前确认没有路由还在用它：

curl "http://127.0.0.1:9180/apisix/admin/upstreams/99?force=true" -H "X-API-KEY: $ADMIN_KEY" -X DELETE

排错对照：常见 4xx 错误码处理

这一节解决"接口报错先查哪三处"。

典型错误响应长这样，error_msg里直接给出缺的字段：

{ "error_msg": "invalid configuration: property \"uri\" is required" }

避坑清单

• admin_key 留空时 APISIX 会自动生成并回写 config.yaml，生成后立刻收好备份，丢了只能重建。
• PUT 更新路由是整体覆盖，脚本里建议先 GET 出旧配置合并新字段，避免漏字段把 plugins 冲掉。
• 路由、Service、Consumer 的插件会合并生效，同名插件的字段冲突时排查起来很费时间，尽量分层：路由放路由专属的，通用能力上提到 Service。
• 健康检查interval别设太激进，高频探测对后端是额外压力；http_failures留 2~3 次容错，避免网络抖动把节点误摘。
• 批量脚本失败时 Admin API 会把error_msg原样返回，把每步的返回体落盘，排障时比翻网关日志快得多。

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