API 中转站接口限流、日志监控配置实操指南

针对 API 中转站的限流与日志监控配置，核心思路是：**限流根据业务场景选择维度与算法，日志监控则需兼顾调试便利性与存储成本**。以下是实操层面的配置指南。

### 限流配置实操

限流配置需要先明确两个问题：**限制谁**（维度）和 **限制多快**（算法与阈值）。

**1. 选择限流维度**

常见的限流维度包括：

- **按 IP 限制**：适合公开 API，防止单一来源刷量。Oracle API Gateway 支持按客户端 IP（IPv4 按单地址，IPv6 按 /64 前缀）进行限流 。

- **按 API Key / 用户限制**：适合需要区分用户等级或计费的场景，如开源项目 api-proxy-service 即支持基于 API 和登录的层级限流 。

- **全局限制**：保护后端整体容量，适合所有请求共享一个池子的场景。

**2. 选择限流算法与阈值**

**令牌桶算法**是主流选择，因为它允许一定程度的突发流量。腾讯云 API 网关的配置示例中，`rate` 表示每秒生成的令牌数（稳态速率），`burst` 表示桶容量（可容忍的瞬时并发）。例如，`rate: 1000, burst: 300` 意味着稳态 QPS 控制在 1000，但允许瞬间冲到 1300。

**配置示例（YAML 片段）**：

```yaml

trafficControl:

 unit: MINUTE

 apiDefault:

   rate: 1000      # 稳态速率

   burst: 300      # 突发容量

 specialApis:

   - api: /generate

     rate: 200     # 针对高消耗接口单独限流

     burst: 50

```

**3. 注意分布式限流的一致性**

如果网关部署了多个实例，**务必使用集中式计数器（如 Redis）**。否则每个实例独立计数，总放行量会超出预期。Apigee 文档明确指出，非分布式配额会导致后端实际承受的流量是配置值的数倍 。

### 日志监控配置实操

日志配置的关键在于**分级**和**结构化**。

**1. 日志分级与用途**

参考 Oracle API Gateway 的实践，日志通常分为两类 ：

- **访问日志**：记录每个请求的摘要（时间、客户端 IP、路径、状态码、延迟）。用于流量分析和监控告警。

- **执行日志**：记录网关内部处理细节（认证结果、路由匹配、后端连接状态）。用于排查特定请求的失败原因。

执行日志应设置级别以控制开销：**Info**（记录处理步骤摘要）、**Warning**（仅记录瞬时错误如连接重置）、**Error**（仅记录持久性错误如内部错误或 404）。

**2. 结构化日志格式**

为了便于后续用 ELK、Loki 等工具检索，日志应输出为 **JSON 格式**。KrakenD 支持 `logstash` 格式，自动将 `@timestamp`、`level`、`message` 等字段结构化 。

对于中转站，建议至少包含以下字段：

- `client_ip`、`api_key_prefix`（脱敏后）

- `method`、`path`、`status_code`

- `latency_ms`、`upstream_latency_ms`

- `error`（失败时的具体错误）

**3. 基于日志的告警**

日志不仅是事后排查工具，也可以驱动实时告警。阿里云 API 网关支持将日志投递到 SLS（日志服务），并基于日志字段（如 `errorMessage`）设置检查频率和触发条件来创建告警规则 。Google Apigee 也支持通过 Logs Explorer 编写查询，一键从查询结果创建基于日志的告警策略 。

**4. 注意流式响应日志的特殊处理**

如果中转站转发的是 SSE（Server-Sent Events）等流式响应，日志记录需要特别处理。Apinizer 的方案是：**在整个流连接关闭时生成一条完整的日志记录**，而非每个 chunk 一条，避免日志量爆炸。同时受 `LOGGING_TRAFFIC_MAX_BODY_SIZE` 限制，超出部分截断并标记 。