APISIX Admin API 实践指南：从首次连接到流量治理的完整流程-CSDN博客

APISIX Admin API 实践指南：从首次连接到流量治理的完整流程

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

Apache APISIX 是一款云原生 API 网关，它的 Admin API 是控制网关行为的"驾驶舱"：路由、上游、消费者、插件全部通过这套 RESTful 接口动态下发，改完即时生效、无需重启。本文按真实上手顺序带你走完一遍：先完成认证并发起第一个请求，再配出第一条订单服务路由，接着搞定上游与健康检查，然后用限流、JWT 认证、Prometheus 监控三个插件完成流量治理，最后学会批量操作、分页过滤以及排错和加固技巧。跟着做完，你就能独立维护一套生产可用的 APISIX 实例。

第一次连接 Admin API：认证怎么过

这一章解决一个问题：你拿到一台装好的 APISIX，第一步怎么证明自己有权限，又怎么验证连接是通的。

Admin API 默认监听 127.0.0.1:9180，所有接口都挂在 /apisix/admin 前缀下。它靠请求头 X-API-KEY 做身份认证，key 来自配置文件 conf/config.yaml 里的 deployment.admin.admin_key 列表，每个 key 绑定一个名字和角色：

deployment:
  admin:
    admin_key_required: true   # 强制所有请求携带 key
    admin_key:
      - name: admin            # 最高权限
        key: a58a3845034120e739b1585307c1b720
        role: admin
      - name: viewer           # 只读，适合交给运维看板系统
        key: b7f3...           # 省略
        role: viewer
    allow_admin:
      - 127.0.0.1/32            # 只允许本机访问管理端口

三种角色分工很清晰：admin 什么都能写，probe 只用于健康探测（/apisix/admin/status），viewer 只能读。把 key 存进环境变量，避免手滑提交到仓库：

export ADMIN_KEY="a58a3845034120e739b1585307c1b720"

# 最简连通性验证：列出全部路由，空列表说明连接和认证都通了
curl -s -H "X-API-KEY: $ADMIN_KEY" \
  http://127.0.0.1:9180/apisix/admin/routes
# 预期输出: {}

如果返回 401，先核对 key 是否复制完整；如果压根连不上，检查 admin_listen 绑定的 IP 和 allow_admin 是否放行了你的来源网段。传统部署下，Admin API 与数据面（9080/9443 代理端口）是同一个进程的两条入口，管理流量和转发流量互不干扰，架构如下图所示：

如何配置第一条路由：5 分钟让请求跑起来

这一章带你用 API 网关路由配置中最核心的动作——创建路由，把 /orders/* 的请求转发到指定的后端。

先说大白话：路由就是"什么样的请求"配"转发到哪里"的一对匹配规则。APISIX 收到请求后，在已发布的路由里按优先级找到第一条命中的，再执行转发。匹配规则支持 URI、域名、方法、客户端 IP 和 Nginx 变量，速查如下：

想匹配什么	字段	例子	特点
路径	`uri` / `uris`	`/orders/*`	支持通配符与正则
域名	`host` / `hosts`	`api.example.com`	支持泛域名 `*.example.com`
方法	`methods`	`["GET", "POST"]`	只放行列出的方法
来源 IP	`remote_addr` / `remote_addrs`	`10.10.0.0/16`	CIDR 写法
任意变量	`vars`	`[["arg_trace_id", "~", "^t-"]]`	`==`、`~` 等比较
命中顺序	`priority`	`10`	数值越大越先匹配

给订单服务建一条路由，用 PUT 并指定 ID（字符串 ID 更好认，比如 order-svc）：

curl -s http://127.0.0.1:9180/apisix/admin/routes/order-svc \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "uri": "/orders/*",                    // 匹配所有 /orders 子路径
  "name": "order-svc",
  "methods": ["GET", "POST"],            // 只接受读和写
  "priority": 10,                        // 优先级高于默认 0
  "upstream": {                          // 内联上游，最简转发
    "type": "roundrobin",                // 轮询
    "nodes": {
      "10.0.20.11:8080": 1,              // 权重 1
      "10.0.20.12:8080": 2               // 权重 2，承载双倍流量
    }
  }
}'
# 成功返回 {"action":"create"}

验证一下：curl http://127.0.0.1:9080/orders/42，流量应到达 10.0.20.11/12 这两台机器且 12 号机器命中两次、11 号命中一次。

如果匹配规则没写对、请求 404 了，别急着改——先用 schema 校验接口预检配置，它只校验不落库，非常适合贴进 CI：

curl -s http://127.0.0.1:9180/apisix/admin/schema/validate/routes \
  -H "X-API-KEY: $ADMIN_KEY" -X POST -d '
{
  "uri": "/orders/*",
  "upstream": { "type": "roundrobin", "nodes": { "10.0.20.11:8080": 1 } }
}'

上游怎么配：服务器组、负载均衡与健康检查

这一章解决第二个问题：当后端不止一两台机器时，怎么组织服务器组、挑选负载均衡算法、开启健康检查让坏节点自动下线。

上游（Upstream）说白了就是"服务器组 + 流量分配规则 + 健康检查策略"。相比上一节内联在路由里的小上游，独立的 Upstream 资源可以被多条路由共享，改一次节点列表，所有引用它的路由同步生效：

curl -s http://127.0.0.1:9180/apisix/admin/upstreams/order-backend \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "type": "roundrobin",                 // 轮询
  "nodes": {
    "10.0.20.11:8080": 1,
    "10.0.20.12:8080": 1,
    "10.0.20.13:8080": 1
  },
  "retries": 3,                          // 单次失败后换节点重试 3 次
  "timeout": { "connect": 2, "send": 5, "read": 8 },
  "checks": {                            // 主动健康检查
    "active": {
      "http": { "http_path": "/healthz" },  // 探测路径
      "healthy":    { "interval": 3, "successes": 2 },
      "unhealthy":  { "interval": 3, "http_failures": 3 }
    }
  }
}'

四种常用算法怎么选：

roundrobin（默认）：按权重轮流分发，后端能力一致时首选；
least_conn：优先派给当前活跃连接最少的节点，适合后端处理时间差异大的场景；
chash：一致性哈希，配合 hash_on（如 vars.remote_addr 或请求头）把同一客户端固定打到同一节点，有会话粘滞需求时用；
ewma：按近期响应时间加权，慢的节点自然少接流量，追求低延迟时使用。

创建后让路由引用它，upstream 字段直接填 ID：

{ "uri": "/orders/*", "upstream": "order-backend" }

健康检查开启后，APISIX 会持续探测每个节点：连续 2 次 /healthz 通过则标记健康，连续 3 次失败则摘除流量。除了主动探测，被动检查（checks.passive）会根据真实请求的 5xx 比例自动降级故障节点，两者叠加覆盖更完整。上游、路由的完整字段定义可以查阅官方文档 docs/admin-api.md 和 apisix/schema_def.lua。

插件实战：限流、JWT 认证与 Prometheus 监控

这一章给出三个高频插件的最小可用配置，覆盖"挡洪水、验身份、看指标"三件事。所有插件都挂在路由（或 Service、Consumer）的 plugins 字段下，格式是 "插件名": {配置}。

1. 限流插件：limit-count 管"固定窗口内多少次"，limit-req 管"每秒多少速率"。给订单接口限制每个客户端 IP 每分钟 60 次：

{
  "plugins": {
    "limit-count": {
      "count": 60,                  // 时间窗内允许的请求数
      "time_window": 60,           // 窗口长度（秒）
      "key": "remote_addr",        // 按客户端 IP 计数
      "rejected_code": 429         // 超限时返回 429 而非默认 503
    }
  }
}

单节点用默认的 local 策略即可；多节点网关要全局一致计数时，把 policy 改成 redis 并附上 Redis 连接信息。插件源码见 apisix/plugins/limit-count.lua 和 apisix/plugins/limit-req.lua。

2. JWT 认证：JWT 认证是声明式的——认证配置写在**消费者（Consumer）**上，路由上只挂一个开关。Consumer 相当于"一个调用方账号"，先把账号建好：

curl -s http://127.0.0.1:9180/apisix/admin/consumers/order-client \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "username": "order-client",          // 全局唯一的账号名
  "plugins": {
    "jwt-auth": {
      "key": "oc-2024",                // 该消费者使用的 JWT key
      "secret": "s3cr3t-of-order-app", // HS256 签名密钥
      "algorithm": "HS256"
    }
  }
}'

再在订单路由上启用 jwt-auth，此后没带合法 token 的请求会被直接挡在 401：

{ "uri": "/orders/*", "plugins": { "jwt-auth": {} } }

需要换用非对称算法时，把 algorithm 设为 RS256 或 ES256 并给出 public_key/private_key。插件实现位于 apisix/plugins/jwt-auth.lua。

3. 监控插件：给任何一条路由挂上 prometheus 插件，APISIX 就开始按 route_id 维度上报请求数、状态码分布、上游延迟等指标；prefer_name 为 true 时标签用路由名而非 ID，可读性更好：

{ "plugins": { "prometheus": { "prefer_name": true } } }

指标统一从数据面的 /apisix/prometheus 端点暴露，Prometheus 定时抓取即可，配合 Grafana 就是完整的可观测链路。

批量操作、分页与过滤查询：管理上百条路由

这一章解决规模化运维问题：路由多了以后，怎么一次下发一批、按条件筛选、翻着页看全量列表。

批量写操作直接让请求体变成 JSON 数组，对同一个集合端点发 PUT（创建或更新）、DELETE（删除）即可，一批数据要么都成功要么整体回滚：

# 一次创建两条路由
curl -s http://127.0.0.1:9180/apisix/admin/routes \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
[
  {
    "name": "order-create",
    "uri": "/orders",
    "methods": ["POST"],
    "upstream": "order-backend"
  },
  {
    "name": "order-query",
    "uri": "/orders/*",
    "methods": ["GET"],
    "upstream": "order-backend"
  }
]'

V3 版本增强了查询体验。分页查询让万级路由不再一次全量吐出：

# 第 2 页，每页 20 条；响应形如 {"total": 47, "list": [...]}
curl -s "http://127.0.0.1:9180/apisix/admin/routes?page=2&page_size=20" \
  -H "X-API-KEY: $ADMIN_KEY"

配合过滤参数，能按字段直接圈定目标，比如找出所有打了 env:prod 标签的路由：

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

删除引用了某上游的路由/路由引用的上游时，Admin API 默认会做引用保护、拒绝误删；确认要连带清理时加 force=true：

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

批量 + 过滤 + 分页，是写自动化同步脚本（比如从服务注册中心镜像路由）的基础三件套。

错误码速查、常见坑与安全加固

这一章把排错手册和安全基线合在一起，放在最后方便你随时翻。

遇到返回体里的 error_msg 时，按下表先自查一遍：

状态码	含义	高频原因与对策
401	认证失败	key 抄错、key 对应角色权限不够（viewer 不能写）
404	资源不存在	集合名或 ID 拼错，注意路由 ID 支持字符串
400	配置校验失败	看 `error_msg` 里的字段路径，先跑 schema/validate 预检
409	资源冲突	同 ID 重复创建，或引用保护拦截，必要时 `force=true`
503	网关自身过载/无可用上游	健康检查把所有节点摘除了，看上游 checks 配置

几个新手最容易踩的坑：

改了 9180 却测了 9080：Admin API 与数据面端口不同，验证路由要走 9080；
限流不生效：多副本部署下 limit-count 默认 local 策略只算单节点计数，全局限流必须切 redis 策略；
JWT 一直 401：secret 或 algorithm 必须与签发 token 一侧完全一致，HS256 用 secret，RS256/ES256 用 public_key + private_key。

安全基线方面，生产环境建议做四件事：

deployment:
  admin:
    admin_key_required: true     # 1. 强制认证，杜绝匿名访问
    admin_listen:
      ip: 127.0.0.1              # 2. 管理端口只绑本机，
      port: 9180                 #    经 SSH 隧道或内网访问
    allow_admin:
      - 10.0.0.0/8               # 3. 白名单只留运维网段
    admin_key:
      - name: admin
        key: <定期轮换的强随机值>  # 4. key 定期轮换、按角色分权

自动化部署时，把每个资源的 JSON 配置拆成独立文件、用脚本按"上游 → 路由 → 消费者"的顺序 PUT，失败即停，比一次性大脚本好排错得多。

总结

到这里你已经把 APISIX Admin API 的主线完整走了一遍：用 X-API-KEY 通过认证完成首次连接，创建了带优先级与匹配规则的订单服务路由，配置了共享上游、负载均衡与健康检查，挂上限流、JWT 认证与 Prometheus 三个插件，最后掌握了批量写入、分页过滤和强制删除。剩下的是把这套流程沉淀进你自己的发布脚本与监控告警里。字段级的完整参考可继续查阅官方文档 docs/admin-api.md，插件全目录见 docs/zh/latest/plugins/。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考