API 网关

API 网关负责统一路由、全局限流、访问日志、Webhook 事件推送和审计日志，所有接口均为管理员专用。

9.1 路由管理

路由规则列表

GET /admin/v1/gateway/routes

{
  "code": 0,
  "data": {
    "items": [
      {
        "route_id": "route_001",
        "name": "AI 网关路由",
        "path_prefix": "/api/v1/chat/",
        "upstream": "http://ai-gateway:8001",
        "methods": ["POST"],
        "status": "active",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

添加路由规则

POST /admin/v1/gateway/routes

{
  "name": "业务后端路由",
  "path_prefix": "/api/v1/",
  "upstream": "http://business:8000",
  "methods": ["GET", "POST", "PUT", "DELETE"],
  "strip_prefix": false,
  "timeout_ms": 30000
}

更新路由规则

PUT /admin/v1/gateway/routes/{route_id}

删除路由规则

DELETE /admin/v1/gateway/routes/{route_id}

9.2 全局限流

限流规则列表

GET /admin/v1/gateway/rate-limits

{
  "code": 0,
  "data": {
    "items": [
      {
        "limit_id": "rl_global_001",
        "name": "全局 IP 限流",
        "dimension": "ip",
        "requests_per_minute": 300,
        "requests_per_day": 50000,
        "action": "reject",
        "status": "active"
      }
    ]
  }
}

创建限流规则

POST /admin/v1/gateway/rate-limits

{
  "name": "API Key 每分钟限流",
  "dimension": "api_key",
  "requests_per_minute": 60,
  "requests_per_day": 10000,
  "action": "reject"
}

dimension 枚举：ip / api_key / user_id
action 枚举：reject / queue

更新限流规则

PUT /admin/v1/gateway/rate-limits/{limit_id}

删除限流规则

DELETE /admin/v1/gateway/rate-limits/{limit_id}

9.3 访问日志

访问日志列表

GET /admin/v1/gateway/logs

{
  "code": 0,
  "data": {
    "items": [
      {
        "log_id": "log_01HX...",
        "method": "POST",
        "path": "/api/v1/chat/completions",
        "status_code": 200,
        "latency_ms": 1240,
        "api_key_id": "key_01HX...",
        "user_id": "u_01HX...",
        "ip": "1.2.3.4",
        "request_size": 1024,
        "response_size": 4096,
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "total": 125000
  }
}

指定 API Key 流量统计

GET /admin/v1/gateway/stats/apikey/{key_id}

{
  "code": 0,
  "data": {
    "key_id": "key_01HX...",
    "period": "today",
    "request_count": 1250,
    "success_count": 1230,
    "error_count": 20,
    "success_rate": "98.4%",
    "avg_latency_ms": 980,
    "p99_latency_ms": 3200
  }
}

网关流量统计

GET /admin/v1/gateway/stats

{
  "code": 0,
  "data": {
    "period": "today",
    "total_requests": 128500,
    "success_rate": "99.1%",
    "avg_qps": 1.49,
    "peak_qps": 45.2,
    "avg_latency_ms": 890,
    "p99_latency_ms": 2800,
    "rate_limited_count": 234
  }
}

9.4 Webhook 管理

Webhook 端点列表

GET /admin/v1/gateway/webhooks

{
  "code": 0,
  "data": {
    "items": [
      {
        "webhook_id": "wh_01HX...",
        "name": "充值成功通知",
        "url": "https://partner.example.com/webhooks/recharge",
        "event_types": ["recharge.success", "balance.low"],
        "status": "active",
        "secret": "whsec_****",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

创建 Webhook

POST /admin/v1/gateway/webhooks

{
  "name": "充值成功通知",
  "url": "https://partner.example.com/webhooks/recharge",
  "event_types": ["recharge.success", "balance.low"],
  "secret": "my_webhook_secret"
}

可订阅的事件类型（event_types）：

更新 Webhook

PUT /admin/v1/gateway/webhooks/{webhook_id}

删除 Webhook

DELETE /admin/v1/gateway/webhooks/{webhook_id}

发送测试事件

POST /admin/v1/gateway/webhooks/{webhook_id}/test

{ "event_type": "recharge.success" }

Webhook 投递日志

GET /admin/v1/gateway/webhooks/{webhook_id}/logs

{
  "code": 0,
  "data": {
    "items": [
      {
        "log_id": "whl_001",
        "event_type": "recharge.success",
        "status": "success",
        "response_code": 200,
        "latency_ms": 245,
        "retry_count": 0,
        "sent_at": "2024-01-01T12:05:00Z"
      }
    ]
  }
}

9.5 审计日志

GET /admin/v1/gateway/audit-logs

{
  "code": 0,
  "data": {
    "items": [
      {
        "log_id": "audit_01HX...",
        "user_id": "u_01HX...",
        "user_email": "user@example.com",
        "action": "apikey.delete",
        "resource_type": "api_key",
        "resource_id": "key_01HX...",
        "ip": "1.2.3.4",
        "user_agent": "Mozilla/5.0...",
        "result": "success",
        "detail": { "key_name": "生产环境" },
        "created_at": "2024-01-01T12:00:00Z"
      }
    ]
  }
}

常见操作类型（action）：