Apache APISIX Admin API完全参考手册-优快云博客

Apache APISIX Admin API完全参考手册

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

概述

Apache APISIX Admin API是云原生API网关的核心管理接口，提供了完整的RESTful API用于动态配置和管理网关的所有资源。通过Admin API，您可以实现路由、上游服务、插件、SSL证书等资源的全生命周期管理。

快速开始

基础配置

Admin API默认监听端口9180，API前缀为/apisix/admin。安全配置如下：

deployment:
  admin:
    admin_key:
      - name: admin
        key: edd1c9f034335f136f87ad84b625c8f1
        role: admin
    allow_admin:
      - 127.0.0.0/24
    admin_listen:
      ip: 0.0.0.0
      port: 9180

认证方式

使用X-API-KEY头部进行认证：

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

核心资源管理

路由（Route）管理

路由是APISIX的核心概念，用于匹配客户端请求并转发到相应的上游服务。

创建路由

curl 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-route",
  "desc": "用户API路由",
  "methods": ["GET", "POST", "PUT", "DELETE"],
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "192.168.1.100:8080": 1,
      "192.168.1.101:8080": 2
    }
  },
  "plugins": {
    "limit-count": {
      "count": 100,
      "time_window": 60,
      "key_type": "var",
      "key": "remote_addr"
    }
  }
}'

路由匹配规则

匹配类型	参数	示例	说明
URI匹配	uri/uris	`"/api/*"`	支持通配符和正则
域名匹配	host/hosts	`"api.example.com"`	支持泛域名
方法匹配	methods	`["GET", "POST"]`	HTTP方法
IP匹配	remote_addr/remote_addrs	`"192.168.1.0/24"`	CIDR格式
变量匹配	vars	`[["arg_uid", "==", "1001"]]`	Nginx变量

高级路由配置

{
  "uri": "/api/*",
  "hosts": ["api.example.com", "*.test.com"],
  "methods": ["GET", "POST"],
  "priority": 10,
  "vars": [
    ["http_x_api_version", "==", "v2"],
    ["arg_debug", "!=", "true"]
  ],
  "filter_func": "function(vars) return tonumber(vars.arg_user_id) % 2 == 0 end",
  "timeout": {
    "connect": 3,
    "send": 5,
    "read": 10
  }
}

上游服务（Upstream）管理

上游服务定义后端服务的负载均衡策略和健康检查。

创建上游服务

curl http://127.0.0.1:9180/apisix/admin/upstreams/backend-service \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "type": "roundrobin",
  "nodes": {
    "192.168.1.100:8080": 30,
    "192.168.1.101:8080": 70
  },
  "checks": {
    "active": {
      "type": "http",
      "http_path": "/health",
      "timeout": 5,
      "concurrency": 10,
      "healthy": {
        "interval": 5,
        "successes": 2
      },
      "unhealthy": {
        "interval": 5,
        "http_failures": 3
      }
    }
  },
  "retries": 3,
  "timeout": {
    "connect": 3,
    "send": 5,
    "read": 10
  }
}'

负载均衡算法

mermaid

服务（Service）管理

服务是路由的抽象，用于复用公共配置。

curl http://127.0.0.1:9180/apisix/admin/services/user-service \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "plugins": {
    "limit-count": {
      "count": 1000,
      "time_window": 3600
    },
    "proxy-rewrite": {
      "uri": "/v1$uri"
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "user-service-1:8080": 1,
      "user-service-2:8080": 1
    }
  }
}'

消费者（Consumer）管理

消费者用于身份认证和权限控制。

curl http://127.0.0.1:9180/apisix/admin/consumers/api-client \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "username": "api-client",
  "desc": "第三方API客户端",
  "plugins": {
    "key-auth": {
      "key": "auth-key-123456"
    },
    "limit-count": {
      "count": 100,
      "time_window": 60
    }
  }
}'

插件管理

插件列表获取

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

常用插件配置示例

限流插件

{
  "limit-req": {
    "rate": 100,
    "burst": 50,
    "key": "remote_addr",
    "rejected_code": 503
  }
}

JWT认证插件

{
  "jwt-auth": {
    "key": "user-key",
    "secret": "my-secret-key",
    "algorithm": "HS256",
    "exp": 86400
  }
}

监控插件

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

高级功能

批量操作

# 批量创建路由
curl http://127.0.0.1:9180/apisix/admin/routes \
  -H "X-API-KEY: $ADMIN_KEY" -X POST -d '
[
  {
    "uri": "/api/v1/users",
    "upstream": {
      "nodes": {"user-service:8080": 1},
      "type": "roundrobin"
    }
  },
  {
    "uri": "/api/v1/products",
    "upstream": {
      "nodes": {"product-service:8080": 1},
      "type": "roundrobin"
    }
  }
]'

条件删除

# 强制删除（忽略引用检查）
curl "http://127.0.0.1:9180/apisix/admin/upstreams/1?force=true" \
  -H "X-API-KEY: $ADMIN_KEY" -X DELETE

配置验证

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}
  }
}'

V3新特性

分页查询

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

响应格式：

{
  "total": 150,
  "list": [
    {
      "id": "21",
      "uri": "/api/v1/users",
      "...": "..."
    }
  ]
}

过滤查询

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

错误处理

常见错误码

错误码	说明	解决方案
401	认证失败	检查X-API-KEY是否正确
404	资源不存在	检查资源ID是否正确
400	配置验证失败	检查请求体格式
409	资源冲突	检查资源是否已存在

错误响应示例

{
  "error_msg": "invalid configuration: property \"uri\" is required",
  "req_body": {
    "name": "test-route"
  }
}

最佳实践

安全配置

deployment:
  admin:
    admin_key_required: true
    allow_admin:
      - 192.168.1.0/24
      - 10.0.0.0/8
    admin_listen:
      ip: 127.0.0.1
      port: 9180

监控集成

# 启用Prometheus插件
curl http://127.0.0.1:9180/apisix/admin/routes/metrics \
  -H "X-API-KEY: $ADMIN_KEY" -X PUT -d '
{
  "uri": "/metrics",
  "plugins": {
    "prometheus": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {"127.0.0.1:9090": 1}
  }
}'

自动化脚本

#!/bin/bash
ADMIN_KEY="your-admin-key"
APISIX_HOST="127.0.0.1:9180"

deploy_route() {
  local route_id=$1
  local config_file=$2
  
  curl -s -H "X-API-KEY: $ADMIN_KEY" \
    -X PUT "http://$APISIX_HOST/apisix/admin/routes/$route_id" \
    -d @"$config_file"
}

# 部署多个路由
deploy_route "user-api" "configs/user-route.json"
deploy_route "product-api" "configs/product-route.json"

总结

Apache APISIX Admin API提供了强大而灵活的管理接口，通过本文档的全面参考，您可以：

✅ 掌握所有核心资源的CRUD操作
✅ 理解各种匹配规则和负载均衡策略
✅ 配置丰富的插件生态系统
✅ 实现自动化部署和监控
✅ 确保API网关的安全性和可靠性

建议结合实际业务场景，逐步深入使用APISIX的高级特性，构建高效可靠的API网关架构。

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

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