APISIX Admin API 实操指南：改配置不重启

APISIX Admin API 实操指南改配置不重启【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix改路由、换后端、加限流用 APISIX Admin API 发一条 curl 就能完成网关立即生效进程不用重启。本文带你按顺序打通这套管理接口从冒烟测试一路做到上线检查清单。 五分钟打通 APISIX Admin API端口、前缀与认证APISIX 默认把管理接口开在 9180 端口URL 前缀是/apisix/admin后面跟资源名比如/routes、/upstreams。路由、上游、服务、消费者、SSL 证书、插件元数据全部走这一套 RESTful 接口。认证只认admin_key一个 32 位十六进制串配在conf/config.yaml的deployment.admin.admin_key下每次请求通过X-API-KEY请求头带上它。deployment: admin: admin_key: - name: admin key: 1a2b3c4d5e6f708192a3b4c5d6e7f809 role: admin拿一条最短的请求做冒烟测试curl -H X-API-KEY: 1a2b3c4d5e6f708192a3b4c5d6e7f809 \ http://127.0.0.1:9180/apisix/admin/routes返回空数组[]说明链路通了端口、前缀、密钥三者都对。管理接口的实现就在 apisix/admin/ 目录一个资源一个文件routes.lua、upstreams.lua等想看字段校验规则可以直接翻源码。避坑allow_admin默认只放行本机网段远程调用前先把对端 IP 段加进白名单否则请求会被直接拒绝。创建第一条路由APISIX 路由匹配规则速查路由Route负责把进来的请求分发给对应的后端先按规则匹配命中后交给上游。最小可运行配置只有两块uri和upstream。curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $ADMIN_KEY -X PUT -d { uri: /pay/*, upstream: { type: roundrobin, nodes: {10.10.1.11:8081: 1} } }注意这里用 PUT 且路径带 id这里是 1同一个 id 再次 PUT 就是覆盖更新天然幂等脚本重跑不会产生重复路由。常用匹配参数如下参数写法示例说明uri / uris/pay/*路径匹配支持前缀通配与正则host / hostspay.shop.com域名匹配支持泛域名*.shop.commethods[GET,POST]限定 HTTP 方法vars[[arg_env,,prod]]按 Nginx 变量组合匹配priority10数值越大越先命中vars适合做精细条件比如按 header 或 query 参数组合匹配priority决定同一请求命中多条路由时谁先赢。如果你习惯表单Dashboard 里的 Create Route 页面和这套 JSON 字段一一对应下面是官方文档里的截图可对照着理解各字段含义更多字段细节可查 官方 Admin API 文档。避坑多条路由可能同时命中一条请求别只靠直觉把priority显式设出来行为才可预期。配置上游负载均衡算法与健康检查怎么设置上游Upstream就是后端服务集群的抽象一组节点加权重再加一个负载均衡算法。建成独立资源后多条路由都能复用同一个 upstream改一处全网生效。curl http://127.0.0.1:9180/apisix/admin/upstreams/pay-core -H X-API-KEY: $ADMIN_KEY -X PUT -d { type: roundrobin, nodes: {10.10.1.11:8081: 3, 10.10.1.12:8081: 1}, checks: { active: { type: http, http_path: /ping, healthy: {successes: 2, interval: 10}, unhealthy: {http_failures: 3, interval: 10} } } }节点的 value 是权重3 和 1 表示两台机器大约按 3:1 分流量。算法怎么选看请求特征roundrobin默认轮询流量均匀绝大多数场景够用least_conn请求耗时差异大或长连接时用挑当前连接数最少的节点chash需要同一用户始终落到同一后端缓存、会话配合hash_on指定 IP 或某个 headerewma按近期响应时间加权后端机器性能参差时分发更公平。健康检查分主动和被动两条线checks.active是 APISIX 定期请求/ping连续成功 2 次视为健康连续失败 3 次摘除被动检查则观察真实流量的 5xx。节点状态不是一刀切的状态机在 healthy、mostly_healthy、unhealthy 之间迁移避坑http_path指向的健康接口要轻量、不依赖数据库否则后端一抖动检查会把全量节点摘光。用 Service 复用配置用 Consumer 做调用方鉴权Service公共配置复用Service 是把一个业务抽象出来的命名容器上游和插件都放进去路由通过service_id引用不用再复制粘贴。curl http://127.0.0.1:9180/apisix/admin/services/pay -H X-API-KEY: $ADMIN_KEY -X PUT -d { upstream: {nodes: {10.10.1.11:8081: 1}, type: roundrobin}, plugins: { proxy-rewrite: {uri: /api/pay$uri} } }路由上配了同名插件时路由级配置优先没配的自动继承 Service 里的。Consumer调用方身份与 key-authConsumer 代表一个 API 调用方本身不干活靠鉴权插件key-auth、jwt-auth、basic-auth 等发钥匙。curl http://127.0.0.1:9180/apisix/admin/consumers/shop-app -H X-API-KEY: $ADMIN_KEY -X PUT -d { username: shop-app, plugins: { key-auth: {key: sk-9f21c7ab34de5678} } }然后在路由的plugins里加key-auth: {}启用校验请求带着 key 才放行否则 401。避坑key 属于敏感凭据别下发到前端调用方泄露时 DELETE 对应 consumer 即完成吊销。三个最常用的插件limit-req、jwt-auth、prometheus插件是挂在路由、服务或消费者上的行为开关在plugins对象里写一个键就启用。下面三个是生产环境出场率最高的。limit-req按令牌桶限流保护后端。rate是每秒放行数burst是突发额度key按remote_addr区分调用方超了直接回 503。{ plugins: { limit-req: { rate: 100, burst: 20, key: remote_addr, rejected_code: 503 } } }jwt-auth校验请求里的 JWT token拦住过期或伪造的身份。消费方用 secret 签 token路由侧只声明校验哪个 key。{ plugins: { jwt-auth: { key: shop-app } } }prometheus把网关指标暴露出来。在一条路由通常专门建/metrics启用后Prometheus 抓取/apisix/prometheus/metrics请求量、延迟、状态码全都有。{ plugins: { prometheus: { prefer_name: true } } }避坑limit-req的 key 别写固定字符串否则限流变成全局限流prometheus 全局开一次即可不用每条路由都挂。批量创建路由与分页、过滤查询批量创建POST /routes带数组一次下发多条id 由 APISIX 自动分配。curl http://127.0.0.1:9180/apisix/admin/routes -H X-API-KEY: $ADMIN_KEY -X POST -d [ {uri: /cart/*, upstream: {nodes: {10.10.1.21:9000: 1}}}, {uri: /order/*, upstream: {nodes: {10.10.1.22:9000: 1}}} ]分页与过滤是 V3 的新能力page从 1 开始page_size在 10~500 之间响应是{total, list}结构过滤支持name、label、uri三个参数组合起来精确捞取。curl http://127.0.0.1:9180/apisix/admin/routes?page2page_size20 -H X-API-KEY: $ADMIN_KEY curl http://127.0.0.1:9180/apisix/admin/routes?namepaylabelenv:prod -H X-API-KEY: $ADMIN_KEY顺带一提被路由引用的 upstream 直接 DELETE 会被挡下确认要删就加?forcetrue。APISIX Admin API 排错速查常见错误码出错时响应体里都有error_msg照着改就行。四个高频状态码状态码含义怎么办401认证失败检查X-API-KEY是否拼对、角色够不够400配置校验失败对照error_msg修字段404资源不存在确认 id 或名称拼写409资源冲突同名资源已存在换个 id典型返回长这样{ error_msg: invalid configuration: property \uri\ is required, req_body: {name: pay-route} }req_body会回显你的原始请求体方便定位是哪个字段没过 schema 校验。改大配置前也可以先打/schema/validate/routes做预校验不写入直接拿结果。✅ 上线前检查清单把admin_key换成自生成的 32 位强密钥别沿用初始自动生成的旧值allow_admin只放行运维网段管理端口不暴露公网内网访问也建议套 TLS给排查问题的同学发只读角色role: readonly的 key写操作留审计核心上游配上主动健康检查健康路径不依赖数据库节点状态可观测全局启用 prometheus接上 Prometheus 抓取与 Grafana 告警延迟和 5xx 都设阈值路由、上游的 JSON 全部进 Git 仓库CI 里循环 PUT 下发禁止手工 curl 改生产脚本固定资源 id同 id 的 PUT 覆盖更新删除前先 GET 确认慎用 force。按这个顺序走完你就把 APISIX Admin API 的日常操作全摸清了资源随时增删改查配置秒级生效重启这件事可以从此忘掉。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考