终端里管理 APISIXAdmin API 从入门到生产的实操指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix如果你刚接手一套基于 Apache APISIX 的 API 网关最先碰到的需求往往是这样的业务方要改一条路由的转发目标或者给某个接口临时加个限流。而 Apache APISIX Admin API 就是干这个的——它把网关的路由、上游、插件、证书等全部配置都开放成了 REST 接口改完即生效不用重启网关进程。下面这篇内容不讲大而全的字段字典而是按一个项目从启动到上线的顺序把你每天真正会敲的那几条命令讲透。启动前的三件事密钥、白名单、端口Admin API 默认跑在9180 端口路径前缀是/apisix/admin。在第一次调用之前conf/config.yaml里有三处配置值得确认对应 官方配置说明deployment: admin: admin_key: - name: admin key: edd1c9f034335f136f87ad84b625c8f1 role: admin # admin 可读写还有只读的 viewer allow_admin: - 127.0.0.0/24 # 来源 IP 白名单 admin_listen: ip: 0.0.0.0 port: 9180用白话说就是三句话admin_key是你的门禁卡每次请求都要带allow_admin限制哪些来源 IP 能调这个接口不配等于全网放开生产上一定要收敛admin_listen决定监听地址注意别和代理数据面的node_listen默认 9080/9443撞端口。认证方式是 HTTP 头X-API-KEY直接贴 key 值即可建议放进环境变量export ADMIN_KEYedd1c9f034335f136f87ad84b625c8f1第一次调用跑通创建—查询—删除闭环先验证连通性列出当前所有路由curl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: $ADMIN_KEY返回一个 JSON 数组就是通了。接下来创建一条路由注意用的是PUTcurl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { uri: /api/users/*, name: user-api, upstream: { type: roundrobin, nodes: { 192.168.1.100:8080: 1, 192.168.1.101:8080: 2 } } }这里有个容易忽略的点PUT 是幂等的——同样的请求发一遍和发十遍结果一样ID 是1就始终覆盖1这条路由。这让你的自动化脚本可以放心重试不会重复建出两条路由。# 查询单条 curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $ADMIN_KEY # 删除 curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $ADMIN_KEY -X DELETE对路由、上游、服务这些资源来说这套 PUT 写入 → GET 验证 → DELETE 清理 的套路是通用的后面所有操作都在这上面做文章。一条请求的路径Route、Service、Upstream、Consumer 各管什么新人最容易困惑的是这几个资源到底谁干什么。看这张图会更直观拆开来看一次请求的完整动线是这样的资源职责一句话类比Route匹配uri、host、method、vars 等规则命中请求前台分诊决定这单归谁管Service复用把上游、插件配置从路由里抽出来共享公共模板多条路由引用同一份配置Upstream转发负载均衡算法 节点权重 健康检查外卖骑手调度池Consumer鉴权key-auth、JWT 等认证插件挂在消费者上客户档案证明你是谁如果路由少、结构简单upstream直接内联在 route 里最省事等同一批路由共享相同后端和限流策略时再抽成独立的Service和Upstream资源。比如把公共限流提到 Service 上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: 1000, time_window: 3600 } } }消费者侧则是把认证凭据挂到 Consumer 上比如 key-authcurl http://127.0.0.1:9180/apisix/admin/consumers/api-client \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { username: api-client, plugins: { key-auth: { key: auth-key-123456 } } }匹配规则这边补充几个常用字段uris是 uri 列表单个用uri、hosts支持泛域名如*.test.com、methods限定 HTTP 方法、vars用[变量名, 运算符, 值]三元组做更细的匹配、priority控制命中优先级。复杂逻辑还可以写filter_func一段 Lua 函数做兜底匹配。上游健康检查怎么写Upstream 是APISIX 上游健康检查配置的主战场。内联写法和独立资源写法一致独立资源的好处是支持主动探测。一个典型的写法curl http://127.0.0.1:9180/apisix/admin/upstreams/backend-svc \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { type: roundrobin, nodes: { 192.168.1.100:8080: 1, 192.168.1.101:8080: 1 }, checks: { active: { type: http, http_path: /health, timeout: 5, healthy: { interval: 1, successes: 2 }, unhealthy: { interval: 1, http_failures: 3 } } } }理解这段配置只需要记住两组参数healthy决定节点判活要连续成功几次unhealthy决定连续失败几次后摘除interval是两次探测的间隔timeout是单次探测超时。type可以是http按状态码判断、https或tcp。摘除的节点会在再次判活后自动回到流量池不需要人工介入。type字段还可以切换负载均衡算法roundrobin默认轮询、least_conn最少连接、chash一致性哈希配合hash_on用变量做哈希键、ewma按响应耗时加权。三个高频插件限流、JWT、PrometheusAPISIX 的插件配置遵循统一模式在资源的plugins字段下插件名对应一段 JSON 配置同一个插件可以同时挂在路由、服务、消费者、全局规则global_rules不同层级上层层叠加生效。挑三个最常被问到的场景讲。 按 IP 限流挡住刷量的客户端业务问题某个接口被单机 IP 疯狂重试想一分钟最多放行 100 次。{ plugins: { limit-count: { count: 100, time_window: 60, key_type: var, key: remote_addr } } }关键就在key_type: varkey: remote_addr这一对组合它决定了计数按哪个维度累加改成consumer就是按认证用户维度。验证方法连续打超过 100 次请求第 101 次应该返回 429limit-count默认拒绝码。 JWT 鉴权先签发再验签jwt-auth 的玩法是先在 Consumer 里存 secret再在路由上开启校验。先给消费者配签发/验签密钥{ plugins: { jwt-auth: { key: user-key, secret: my-secret, algorithm: HS256 } } }然后在需要鉴权的路由上加{ plugins: { jwt-auth: { secret: my-secret } } }之后客户端带着合法签名的Authorization: Bearer jwt头访问即可通过非法 token 直接 401。验证时可以先不带 token 打一次预期 401再带正确 token 打一次预期 200两步都符合预期才说明配置正确。 Prometheus 监控让网关指标可观测在路由上启用 prometheus 插件即可暴露指标{ plugins: { prometheus: { prefer_name: true } } }prefer_name为 true 时指标用路由的name而不是 ID 做标签读起来友好得多。拉一次/apisix/prometheus/metrics能看到请求数、状态码分布、耗时直方图——接入 Grafana 之后网关是不是APISIX 网关动态配置改坏了看曲线就知道。批量与高效查询让配置管理不靠人肉配置量上来之后单条 curl 就难以为继了v3 版 Admin API配置里admin_api_version: v3提供了几件趁手工具批量创建对资源列表地址发 POSTbody 直接传数组一次落地多条curl http://127.0.0.1:9180/apisix/admin/routes \ -H X-API-KEY: $ADMIN_KEY -X POST -d [ { uri: /api/v1/users, upstream: { type: roundrobin, nodes: { user-svc:8080: 1 } } }, { uri: /api/v1/products, upstream: { type: roundrobin, nodes: { product-svc:8080: 1 } } } ]分页查询路由多了之后列表请求会拖慢page/page_size每页 10–500 条按需取curl http://127.0.0.1:9180/apisix/admin/routes?page2page_size20 -H X-API-KEY: $ADMIN_KEY返回结构从数组变成了{ total: ..., list: [...] }脚本解析时注意一下。过滤查询按name、label、uri筛选多个条件之间取交集。label是资源上自建的键值对如{env: prod}非常适合在多环境共用一个 APISIX 实例时圈定范围curl http://127.0.0.1:9180/apisix/admin/routes?nametestlabelenv:prod \ -H X-API-KEY: $ADMIN_KEYSchema 预校验正式提交前可以先问一句这份配置合不合法不写 etcd 就能得到校验结果curl http://127.0.0.1:9180/apisix/admin/schema/validate/routes \ -H X-API-KEY: $ADMIN_KEY -X POST -d { uri: /api/*, upstream: { type: roundrobin, nodes: { backend:8080: 1 } } }CI 流水线里把这个调用插在部署步骤前面能拦下相当一部分低级配置错误。强制删除默认情况下 Admin API 会检查资源间的引用关系被引用的资源删不掉。确认要连带清理时给 DELETE 加forcetrue慎用因为它跳过的是保护机制。出问题时怎么自查报错响应体长这样error_msg是重点req_body会把你发的原文回显出来方便定位{ error_msg: invalid configuration: property \uri\ is required, req_body: { name: test-route } }按排查顺序走基本能覆盖 90% 的问题401—— key 不对或没带X-API-KEY头。注意确认你用的是哪一把 keyadmin/viewer 两把权限不同以及请求来源 IP 是否在allow_admin白名单内白名单不通过时同样会被拒400—— 请求体没通过 schema 校验error_msg里会写明具体哪个字段有问题改完用schema/validate预检再提交404—— 资源 ID 拼错或者资源类型路径不对是/routes不是/route409—— 资源冲突典型场景是 PUT 写入时发现版本冲突或 POST 批量创建时 ID 撞了已有资源。还有一个隐蔽问题改了不生效。先确认 etcd 是连通的配置变更都落到 etcd再确认数据面 worker 有没有收到配置推送最后才怀疑自己的 JSON 写错——顺序反了会白排查半天。生产环境上线清单上线前过一遍下面这份清单比事后救火便宜得多安全加固admin_key_required: true保持开启allow_admin收敛到堡垒机/内网网段admin_listen.ip能绑内网就不要绑0.0.0.0有外部管理需求时开启https_admin走 mTLSkey 用环境变量或配置中心注入别写死在 git 里的 yaml 中。监控接入给/metrics相关路由挂上 prometheus 插件把 5xx 比例、P99 耗时接进告警插件配置本身也纳入配置中心统一管理。自动化部署配置即代码。把每条路由/上游/消费者存成 JSON 文件脚本里封装一个幂等的部署函数PUT 天然支持重试失败直接重跑#!/bin/bash ADMIN_KEY$ADMIN_KEY; HOST127.0.0.1:9180 deploy() { curl -s -H X-API-KEY: $ADMIN_KEY -X PUT \ http://$HOST/apisix/admin/$1/$2 -d $3 } deploy routes user-api configs/user-route.json deploy routes product-api configs/product-route.json配合前文讲的label过滤圈定环境schema/validate预检 分页批量写入就是一条完整的发布流水线雏形。回到开头的场景现在把视角拉回开篇业务方说把 /api/users 的转发目标换掉再加个限流。你的操作是——PUT 一条路由或更新 Service 上的 upstream 节点顺手在plugins里加上 limit-countGET 验证一下返回体完事。全程没有重启改动秒级生效。这正是 Admin API 存在的意义把网关从改配置要发布的基础设施变成curl 一下就能变的动态资源。建议的下一步先用 官方 Admin API 文档 把本文没展开的 SSL、stream_routes、secrets 等资源过一遍再到 插件列表 里找业务真正需要的插件按业务问题 → 配置字段 → 验证生效的路子一个个落地。网关配置管理做得好不好不看功能多少而看你的变更流程是不是全部收敛到了这条 API 通道上。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 终端里管理 APISIX：Admin API 从入门到生产的实操指南
终端里管理 APISIXAdmin API 从入门到生产的实操指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix如果你刚接手一套基于 Apache APISIX 的 API 网关最先碰到的需求往往是这样的业务方要改一条路由的转发目标或者给某个接口临时加个限流。而 Apache APISIX Admin API 就是干这个的——它把网关的路由、上游、插件、证书等全部配置都开放成了 REST 接口改完即生效不用重启网关进程。下面这篇内容不讲大而全的字段字典而是按一个项目从启动到上线的顺序把你每天真正会敲的那几条命令讲透。启动前的三件事密钥、白名单、端口Admin API 默认跑在9180 端口路径前缀是/apisix/admin。在第一次调用之前conf/config.yaml里有三处配置值得确认对应 官方配置说明deployment: admin: admin_key: - name: admin key: edd1c9f034335f136f87ad84b625c8f1 role: admin # admin 可读写还有只读的 viewer allow_admin: - 127.0.0.0/24 # 来源 IP 白名单 admin_listen: ip: 0.0.0.0 port: 9180用白话说就是三句话admin_key是你的门禁卡每次请求都要带allow_admin限制哪些来源 IP 能调这个接口不配等于全网放开生产上一定要收敛admin_listen决定监听地址注意别和代理数据面的node_listen默认 9080/9443撞端口。认证方式是 HTTP 头X-API-KEY直接贴 key 值即可建议放进环境变量export ADMIN_KEYedd1c9f034335f136f87ad84b625c8f1第一次调用跑通创建—查询—删除闭环先验证连通性列出当前所有路由curl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: $ADMIN_KEY返回一个 JSON 数组就是通了。接下来创建一条路由注意用的是PUTcurl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { uri: /api/users/*, name: user-api, upstream: { type: roundrobin, nodes: { 192.168.1.100:8080: 1, 192.168.1.101:8080: 2 } } }这里有个容易忽略的点PUT 是幂等的——同样的请求发一遍和发十遍结果一样ID 是1就始终覆盖1这条路由。这让你的自动化脚本可以放心重试不会重复建出两条路由。# 查询单条 curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $ADMIN_KEY # 删除 curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $ADMIN_KEY -X DELETE对路由、上游、服务这些资源来说这套 PUT 写入 → GET 验证 → DELETE 清理 的套路是通用的后面所有操作都在这上面做文章。一条请求的路径Route、Service、Upstream、Consumer 各管什么新人最容易困惑的是这几个资源到底谁干什么。看这张图会更直观拆开来看一次请求的完整动线是这样的资源职责一句话类比Route匹配uri、host、method、vars 等规则命中请求前台分诊决定这单归谁管Service复用把上游、插件配置从路由里抽出来共享公共模板多条路由引用同一份配置Upstream转发负载均衡算法 节点权重 健康检查外卖骑手调度池Consumer鉴权key-auth、JWT 等认证插件挂在消费者上客户档案证明你是谁如果路由少、结构简单upstream直接内联在 route 里最省事等同一批路由共享相同后端和限流策略时再抽成独立的Service和Upstream资源。比如把公共限流提到 Service 上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: 1000, time_window: 3600 } } }消费者侧则是把认证凭据挂到 Consumer 上比如 key-authcurl http://127.0.0.1:9180/apisix/admin/consumers/api-client \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { username: api-client, plugins: { key-auth: { key: auth-key-123456 } } }匹配规则这边补充几个常用字段uris是 uri 列表单个用uri、hosts支持泛域名如*.test.com、methods限定 HTTP 方法、vars用[变量名, 运算符, 值]三元组做更细的匹配、priority控制命中优先级。复杂逻辑还可以写filter_func一段 Lua 函数做兜底匹配。上游健康检查怎么写Upstream 是APISIX 上游健康检查配置的主战场。内联写法和独立资源写法一致独立资源的好处是支持主动探测。一个典型的写法curl http://127.0.0.1:9180/apisix/admin/upstreams/backend-svc \ -H X-API-KEY: $ADMIN_KEY -X PUT -d { type: roundrobin, nodes: { 192.168.1.100:8080: 1, 192.168.1.101:8080: 1 }, checks: { active: { type: http, http_path: /health, timeout: 5, healthy: { interval: 1, successes: 2 }, unhealthy: { interval: 1, http_failures: 3 } } } }理解这段配置只需要记住两组参数healthy决定节点判活要连续成功几次unhealthy决定连续失败几次后摘除interval是两次探测的间隔timeout是单次探测超时。type可以是http按状态码判断、https或tcp。摘除的节点会在再次判活后自动回到流量池不需要人工介入。type字段还可以切换负载均衡算法roundrobin默认轮询、least_conn最少连接、chash一致性哈希配合hash_on用变量做哈希键、ewma按响应耗时加权。三个高频插件限流、JWT、PrometheusAPISIX 的插件配置遵循统一模式在资源的plugins字段下插件名对应一段 JSON 配置同一个插件可以同时挂在路由、服务、消费者、全局规则global_rules不同层级上层层叠加生效。挑三个最常被问到的场景讲。 按 IP 限流挡住刷量的客户端业务问题某个接口被单机 IP 疯狂重试想一分钟最多放行 100 次。{ plugins: { limit-count: { count: 100, time_window: 60, key_type: var, key: remote_addr } } }关键就在key_type: varkey: remote_addr这一对组合它决定了计数按哪个维度累加改成consumer就是按认证用户维度。验证方法连续打超过 100 次请求第 101 次应该返回 429limit-count默认拒绝码。 JWT 鉴权先签发再验签jwt-auth 的玩法是先在 Consumer 里存 secret再在路由上开启校验。先给消费者配签发/验签密钥{ plugins: { jwt-auth: { key: user-key, secret: my-secret, algorithm: HS256 } } }然后在需要鉴权的路由上加{ plugins: { jwt-auth: { secret: my-secret } } }之后客户端带着合法签名的Authorization: Bearer jwt头访问即可通过非法 token 直接 401。验证时可以先不带 token 打一次预期 401再带正确 token 打一次预期 200两步都符合预期才说明配置正确。 Prometheus 监控让网关指标可观测在路由上启用 prometheus 插件即可暴露指标{ plugins: { prometheus: { prefer_name: true } } }prefer_name为 true 时指标用路由的name而不是 ID 做标签读起来友好得多。拉一次/apisix/prometheus/metrics能看到请求数、状态码分布、耗时直方图——接入 Grafana 之后网关是不是APISIX 网关动态配置改坏了看曲线就知道。批量与高效查询让配置管理不靠人肉配置量上来之后单条 curl 就难以为继了v3 版 Admin API配置里admin_api_version: v3提供了几件趁手工具批量创建对资源列表地址发 POSTbody 直接传数组一次落地多条curl http://127.0.0.1:9180/apisix/admin/routes \ -H X-API-KEY: $ADMIN_KEY -X POST -d [ { uri: /api/v1/users, upstream: { type: roundrobin, nodes: { user-svc:8080: 1 } } }, { uri: /api/v1/products, upstream: { type: roundrobin, nodes: { product-svc:8080: 1 } } } ]分页查询路由多了之后列表请求会拖慢page/page_size每页 10–500 条按需取curl http://127.0.0.1:9180/apisix/admin/routes?page2page_size20 -H X-API-KEY: $ADMIN_KEY返回结构从数组变成了{ total: ..., list: [...] }脚本解析时注意一下。过滤查询按name、label、uri筛选多个条件之间取交集。label是资源上自建的键值对如{env: prod}非常适合在多环境共用一个 APISIX 实例时圈定范围curl http://127.0.0.1:9180/apisix/admin/routes?nametestlabelenv:prod \ -H X-API-KEY: $ADMIN_KEYSchema 预校验正式提交前可以先问一句这份配置合不合法不写 etcd 就能得到校验结果curl http://127.0.0.1:9180/apisix/admin/schema/validate/routes \ -H X-API-KEY: $ADMIN_KEY -X POST -d { uri: /api/*, upstream: { type: roundrobin, nodes: { backend:8080: 1 } } }CI 流水线里把这个调用插在部署步骤前面能拦下相当一部分低级配置错误。强制删除默认情况下 Admin API 会检查资源间的引用关系被引用的资源删不掉。确认要连带清理时给 DELETE 加forcetrue慎用因为它跳过的是保护机制。出问题时怎么自查报错响应体长这样error_msg是重点req_body会把你发的原文回显出来方便定位{ error_msg: invalid configuration: property \uri\ is required, req_body: { name: test-route } }按排查顺序走基本能覆盖 90% 的问题401—— key 不对或没带X-API-KEY头。注意确认你用的是哪一把 keyadmin/viewer 两把权限不同以及请求来源 IP 是否在allow_admin白名单内白名单不通过时同样会被拒400—— 请求体没通过 schema 校验error_msg里会写明具体哪个字段有问题改完用schema/validate预检再提交404—— 资源 ID 拼错或者资源类型路径不对是/routes不是/route409—— 资源冲突典型场景是 PUT 写入时发现版本冲突或 POST 批量创建时 ID 撞了已有资源。还有一个隐蔽问题改了不生效。先确认 etcd 是连通的配置变更都落到 etcd再确认数据面 worker 有没有收到配置推送最后才怀疑自己的 JSON 写错——顺序反了会白排查半天。生产环境上线清单上线前过一遍下面这份清单比事后救火便宜得多安全加固admin_key_required: true保持开启allow_admin收敛到堡垒机/内网网段admin_listen.ip能绑内网就不要绑0.0.0.0有外部管理需求时开启https_admin走 mTLSkey 用环境变量或配置中心注入别写死在 git 里的 yaml 中。监控接入给/metrics相关路由挂上 prometheus 插件把 5xx 比例、P99 耗时接进告警插件配置本身也纳入配置中心统一管理。自动化部署配置即代码。把每条路由/上游/消费者存成 JSON 文件脚本里封装一个幂等的部署函数PUT 天然支持重试失败直接重跑#!/bin/bash ADMIN_KEY$ADMIN_KEY; HOST127.0.0.1:9180 deploy() { curl -s -H X-API-KEY: $ADMIN_KEY -X PUT \ http://$HOST/apisix/admin/$1/$2 -d $3 } deploy routes user-api configs/user-route.json deploy routes product-api configs/product-route.json配合前文讲的label过滤圈定环境schema/validate预检 分页批量写入就是一条完整的发布流水线雏形。回到开头的场景现在把视角拉回开篇业务方说把 /api/users 的转发目标换掉再加个限流。你的操作是——PUT 一条路由或更新 Service 上的 upstream 节点顺手在plugins里加上 limit-countGET 验证一下返回体完事。全程没有重启改动秒级生效。这正是 Admin API 存在的意义把网关从改配置要发布的基础设施变成curl 一下就能变的动态资源。建议的下一步先用 官方 Admin API 文档 把本文没展开的 SSL、stream_routes、secrets 等资源过一遍再到 插件列表 里找业务真正需要的插件按业务问题 → 配置字段 → 验证生效的路子一个个落地。网关配置管理做得好不好不看功能多少而看你的变更流程是不是全部收敛到了这条 API 通道上。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考