AILab/docs/open-api-kong-setup.md

开放接口统计：Kong 3.9.1 配置清单

Ktor 统计接收地址：

http://<Ktor内网地址>:8089/internal/open-api/statistics/ingest

生产环境部署 Ktor 时必须设置：

OPEN_API_LOG_TOKEN=<高强度随机Token>

Kong HTTP Log 中配置的 Bearer Token 必须与该环境变量一致。

1. Key Auth

先查询目标 Service 或 Route 上的 Key Auth 插件：

curl http://127.0.0.1:8001/services/<service-name>/plugins

更新插件：

curl -X PATCH http://127.0.0.1:8001/plugins/<key-auth-plugin-id> \
  --data "config.hide_credentials=true" \
  --data "config.key_in_header=true" \
  --data "config.key_in_query=false" \
  --data "config.key_in_body=false"

确认返回配置中：

{
  "hide_credentials": true,
  "key_in_header": true,
  "key_in_query": false,
  "key_in_body": false
}

2. HTTP Log

推荐挂载到开放接口对应的 Route。若一个 Service 只有开放接口，也可挂载到 Service。

curl -X POST http://127.0.0.1:8001/routes/<route-id>/plugins \
  -H "Content-Type: application/json" \
  -d '{
    "name": "http-log",
    "config": {
      "http_endpoint": "http://<Ktor内网地址>:8089/internal/open-api/statistics/ingest",
      "method": "POST",
      "content_type": "application/json",
      "headers": {
        "Authorization": "Bearer <OPEN_API_LOG_TOKEN>"
      },
      "timeout": 3000,
      "keepalive": 60000,
      "queue": {
        "max_entries": 10000,
        "max_batch_size": 50,
        "max_coalescing_delay": 1,
        "max_retry_time": 60
      }
    }
  }'

建议配置范围：

• 票通 /api/open/v1
• AI 后端 /api/public
• 核心 Ktor /traceability/public
• 其他需要统计的开放 Route

不要将回调地址配置为经过 Kong 的公网域名，避免日志回调再次触发 HTTP Log。

3. 验收

每类 Route 至少执行以下测试：

1. 有效 API Key 调用成功。
2. 不带 API Key，Kong 返回 401。
3. 使用错误 API Key，Kong 返回 401。
4. 同一个 Consumer 从不同 IP 调用。
5. 不同 Consumer 调用同一个接口。
6. 动态发票号被归入同一个路径模板。

在前端“开放接口中心”检查：

• 有效 Key 显示 Kong Consumer。
• 无效或缺失 Key 显示匿名调用方和来源 IP。
• 小时调用量与测试次数一致。
• 页面中不出现 API Key、请求体、发票号或图片内容。