企业官网建设流程全解析

APISIX Admin API 实战指南：如何从零连上并完成路由、负载均衡与鉴权限流

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

Apache APISIX Admin API 是网关的运维入口，用 HTTP 请求就能改动路由、负载均衡与鉴权限流。本文覆盖如何连上端口并完成鉴权、路由转发、健康检查、限流三个核心任务，以及分页、校验与生产环境的用法。

先连上：发出第一条管理请求

这一节解决"端口在哪、身份怎么证明"的问题。

Admin API 默认监听9180端口，路径前缀是/apisix/admin。认证只有一个X-API-KEY请求头，值取自conf/config.yaml中deployment.admin段的admin_key.key。这些字段改什么、会发生什么，看这张表：

把 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/hello（9080 是网关代理端口），命中即说明路由生效。改uri会换掉匹配的路径；改nodes里127.0.0.1:8080后面的数字会改这台节点分到的流量权重；不想删路由只想临时下线，把status改成0即可。

其余常用字段：

给后端配负载均衡与健康检查

这一节解决"多台后端怎么分流量、坏节点怎么自动摘除"的问题。

单独创建一个 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 返回 200，60 秒内第 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挂到消费者身上而不是路由上。

参数速查：匹配规则、负载均衡算法、插件与错误码

这一节把前文分散的字段收口成四张表，写配置时不用来回翻。

路由匹配规则

负载均衡算法（upstream.type）

常用插件

错误码与处理

效率特性：批量写入、分页过滤与配置校验

这一节解决"配置量大时如何少做重复操作"的问题。

批量创建：向集合端点 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 } } } ]'

分页与过滤（v3）：GET /apisix/admin/routes?page=2&page_size=50翻页，page_size取值 10–500；?name=user&label=env: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 ADMIN="http://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"

记这几件事就够上手

1. 所有变更都经 Admin API 写入 etcd，热生效、不重启网关；PUT 建或覆盖，PATCH 局部改，DELETE 删除。
2. 起步阶段upstream直接内联在路由里；多条路由共享同一后端时，拆成独立 Upstream 再用upstream_id引用。
3. 鉴权与限流是联动关系：消费者携带凭据，路由上的插件决定是否拦截，两边缺一不可。
4. 发布前先用schema/validate端点 dry-run，被引用资源删除受阻时再考虑force=true。

想深入：字段级完整定义看 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