API统计页面

2026-07-27 10:16:24 +08:00
parent 89f6944e65
commit 38efd8ef1a
21 changed files with 3554 additions and 123 deletions
@@ -0,0 +1,99 @@
+# 开放接口统计：Kong 3.9.1 配置清单
+
+Ktor 统计接收地址：
+
+```text
+http://<Ktor内网地址>:8089/internal/open-api/statistics/ingest
+```
+
+生产环境部署 Ktor 时必须设置：
+
+```text
+OPEN_API_LOG_TOKEN=<高强度随机Token>
+```
+
+Kong HTTP Log 中配置的 Bearer Token 必须与该环境变量一致。
+
+## 1. Key Auth
+
+先查询目标 Service 或 Route 上的 Key Auth 插件：
+
+```bash
+curl http://127.0.0.1:8001/services/<service-name>/plugins
+```
+
+更新插件：
+
+```bash
+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"
+```
+
+确认返回配置中：
+
+```json
+{
+  "hide_credentials": true,
+  "key_in_header": true,
+  "key_in_query": false,
+  "key_in_body": false
+}
+```
+
+## 2. HTTP Log
+
+推荐挂载到开放接口对应的 Route。若一个 Service 只有开放接口，也可挂载到 Service。
+
+```bash
+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、请求体、发票号或图片内容。