← 返回文档中心

API 网关

API 网关

优先级: P0（基础设施模块）
开发周期: 1 周

目标

统一入口，处理所有外部请求的鉴权、限流、日志、路由转发，是平台安全和高可用的第一道防线。

核心功能

功能 描述
路由转发 请求路由到对应的后端服务
身份认证 API Key + JWT 双重认证
访问授权 基于角色的权限控制（RBAC）
限流熔断 多维度限流（IP/代理商/全局），熔断保护
请求缓存 GET 请求缓存，减少后端压力
日志追踪 请求/响应日志，TraceID 全链路追踪
监控指标 QPS、延迟、错误率等实时指标
文档路由 Swagger UI 自动文档

网关架构

Client Request
    │
    ▼
┌─────────────────────────────────┐
│         Nginx (前置)            │
│  SSL终止 / 静态资源 / 基础限流  │
└──────────┬──────────────────────┘
           │
           ▼
┌─────────────────────────────────┐
│      Kong API Gateway           │
│  ┌──────────────────────────┐  │
│  │ 1. IP 黑名单检查          │  │
│  │ 2. API Key 验证           │  │
│  │ 3. JWT 解析+权限检查       │  │
│  │ 4. 限流 (Rate Limiting)   │  │
│  │ 5. 请求日志               │  │
│  │ 6. 路由转发               │  │
│  │ 7. 响应缓存 (可选)        │  │
│  └──────────────────────────┘  │
└──────────┬──────────────────────┘
           │
           ▼
    后端微服务 (Gin)

MVP 简化方案: 不使用 Kong，直接在 Go 应用层用 Gin 中间件实现所有网关功能。减少运维复杂度。

数据模型

-- API 密钥表 (关联 agents 表)
CREATE TABLE api_keys (
    id              BIGSERIAL PRIMARY KEY,
    agent_code      VARCHAR(32) NOT NULL REFERENCES agents(agent_code),
    key_id          VARCHAR(32) NOT NULL UNIQUE,     # 可公开的 Key ID
    key_secret_hash VARCHAR(128) NOT NULL,            # 密钥哈希(不可逆)

    rate_limit_rpm  INT DEFAULT 60,                   # 每分钟请求限制
    rate_limit_rpd  INT DEFAULT 10000,                # 每天请求限制

    allowed_apis    JSONB DEFAULT '["*"]',             # 允许访问的 API 列表
    ip_whitelist    JSONB,                            # IP 白名单

    status          VARCHAR(20) DEFAULT 'active',     -- active/suspended/revoked
    last_used_at    TIMESTAMPTZ,
    expires_at      TIMESTAMPTZ,

    created_at      TIMESTAMPTZ DEFAULT NOW(),
    revoked_at      TIMESTAMPTZ
);

-- 请求日志表 (ClickHouse 或 PG)
CREATE TABLE request_logs (
    id              BIGSERIAL PRIMARY KEY,
    trace_id        VARCHAR(64) NOT NULL,

    request_method  VARCHAR(16) NOT NULL,
    request_path    VARCHAR(512) NOT NULL,
    query_params    TEXT,
    request_body    TEXT,                             # 脱敏后
    client_ip       VARCHAR(45),
    user_agent      VARCHAR(512),

    agent_code      VARCHAR(32),
    api_key_id      VARCHAR(32),

    response_status SMALLINT NOT NULL,
    response_ms     INT NOT NULL,

    error_message   TEXT,

    created_at      TIMESTAMPTZ DEFAULT NOW()
);

-- 限流配置表
CREATE TABLE rate_limits (
    id              SERIAL PRIMARY KEY,
    limit_type      VARCHAR(32) NOT NULL,     -- global/ip/agent/api
    limit_key       VARCHAR(64) NOT NULL,     # 具体限流对象
    requests_per_minute INT NOT NULL,
    requests_per_day INT,
    burst_size      INT DEFAULT 10,           # 突发容量
    enabled         BOOLEAN DEFAULT true,
    created_at      TIMESTAMPTZ DEFAULT NOW()
);

接口设计

API 网关本身提供的管理接口：

# API Key 管理
POST   /api/v1/admin/api-keys                 # 创建 API Key
GET    /api/v1/admin/api-keys                 # 列表
PUT    /api/v1/admin/api-keys/:id/status      # 启用/禁用
POST   /api/v1/admin/api-keys/:id/rotate      # 轮换密钥

# 限流管理
GET    /api/v1/admin/rate-limits              # 限流规则列表
POST   /api/v1/admin/rate-limits              # 创建规则
PUT    /api/v1/admin/rate-limits/:id          # 更新规则

# 日志查询
GET    /api/v1/admin/logs/requests            # 请求日志查询

# 健康检查
GET    /health                                # 健康检查
GET    /ready                                 # 就绪检查
GET    /metrics                               # Prometheus 指标

认证流程

请求 → 携带 X-API-Key + X-Signature + Timestamp
    → 网关从 DB/Redis 获取 API Key
    → HMAC-SHA256 签名验证
    → 检查 Key 状态和有效期
    → 解析出 agent_code，注入请求上下文
    → 转发到后端服务

与其他模块的关系

关联模块 关系
所有业务模块 统一入口，所有外部请求必经网关
销售管理 API Key 认证数据
风控体系 限流规则、IP 黑名单

技术选型建议