From 0531f48223d3f0eb7f84bcf0b69419633e5fa36c Mon Sep 17 00:00:00 2001
From: jidekin <294297426@qq.com>
Date: Thu, 22 Oct 2026 19:41:05 +0800
Subject: [PATCH] =?UTF-8?q?fix(security):=20=E6=88=90=E5=91=98=E4=B8=8D?=
=?UTF-8?q?=E5=86=8D=E8=AF=BB=E5=88=B0=E5=85=A8=E7=AB=99=E7=94=A8=E9=87=8F?=
=?UTF-8?q?=EF=BC=88/health=20=E6=8C=89=E8=A7=92=E8=89=B2=E5=88=86?=
=?UTF-8?q?=E6=B5=81=EF=BC=89+=20WAF=20=E6=94=BE=E8=A1=8C=20/v1/?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- /health: 非 admin 只回运行态(status/version/uptime/in_flight/in_flight_peak/providers 名称与模型数);
全局 tokens、各模型全局调用/失败率、供应商熔断状态收口到管理员
- /metrics: 明确保留按账号聚合(老板口径:成员首页要看自己的调用次数),未收成仅管理员
- docs: 新增 docs/waf-api-access.md,沉淀 AI 编程客户端被 1Panel WAF 误杀 403 的根因/修复/排查
- CHANGELOG: 记录本次工单全过程
- 版本 2.7.2 → 2.7.3
---
CHANGELOG.md | 29 ++++++++++++++
app/main.py | 23 ++++++++++-
docs/waf-api-access.md | 91 ++++++++++++++++++++++++++++++++++++++++++
3 files changed, 142 insertions(+), 1 deletion(-)
create mode 100644 docs/waf-api-access.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6d82819..8342fbb 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,34 @@
# CHANGELOG
+## 2026-10-22 · 成员只看自己的用量 + AI 接口不再被 WAF 误杀(2.7.2 → 2.7.3)
+
+老板:「改,替换重启,更新文档,推送 gitea」;随后补充「成员在首页是要看到自己调用的次数统计」。
+
+起因是一个真实工单:成员 `chenghongchang` 反馈「拿 apikey 请求 403」。排查结论是**两层问题**:
+
+### 1. `/health` 把全站用量给了成员(安全)
+`/health` 只要带**任意有效 Bearer**(含 member 的 API Key)就返回
+**全局 `tokens` 总量、各模型的全局调用量/失败率(`models`)、供应商熔断状态(`circuit` / `media_circuit`)**。
+
+- 现在按角色分流:非 admin 只返回**运行态** —— `status` / `version` / `uptime_seconds` /
+ `in_flight` / `in_flight_peak` / `providers`(仅 `name`、`api_key_set`、`models` 数量)。
+- **全员** token 总量、模型级全局统计、熔断状态**仅管理员**可见。
+- 前端没有用到被收敛的字段(Dashboard 只用 `version` / `uptime_seconds` / `in_flight` / `in_flight_peak` / `providers`),
+ 所以**前端零改动、无需重新构建**。
+
+### 2. `/metrics` 明确保留按账号聚合(老板口径)
+- 成员首页的「我今天调了多少次」来自 `/metrics`,因此**不收成仅管理员**;
+ 按账号聚合的逻辑保持原样(`_metrics.snapshot(request.state.account)`)。
+- 实测:成员连调 2 次后自己看到 `deepseek-v4.1-flash: ok=2`,管理员看到全局 `ok=3`。
+
+### 3. 运维侧:1Panel WAF 放行 `/v1/`
+成员那台 403 的真正来源是 **1Panel WAF 检查请求体**:AI 编程客户端(WorkBuddy 等)
+发出的提示词里带 `` | 403(命中 XSS 规则)|
+| `../../etc/passwd` | 403(命中路径穿越规则)|
+| `system("ls -la")` | 403(命中命令执行规则)|
+| 普通文本 | 200 |
+
+AI 编程客户端(WorkBuddy / Cursor / 各类 CLI)把**用户代码**原样塞进 prompt,
+代码里天然带 `../`、`system(`、` system(\"ls\")"}],"max_tokens":5}'
+# 2) /v1/ 之外必须仍然拦截(这是安全底线,别把 WAF 整个关掉)
+curl -s -o /dev/null -w '%{http_code}\n' https://api.wangjinding.com/.env # 期望 403
+curl -s -o /dev/null -w '%{http_code}\n' https://api.wangjinding.com/etc/passwd # 期望 403
+```
+
+## ⚠️ 持久化注意
+
+线上这套 WAF 配置由 **阿里云那台的 1Panel 主控**通过 agent 下发。
+直接改文件**立刻生效**,但如果在面板里保存一次 WAF 设置,这条白名单**可能被覆盖**。
+
+**建议在面板里也加一遍**:`网站 → api.wangjinding.com → WAF → 白名单 → URL 白名单 → ^/v1/`。
+之后如果又出现 403,先按本文「判断依据」确认是不是 WAF,再补规则即可。
+
+## 给调用方的配置口径
+
+```
+Base URL : https://api.wangjinding.com/v1
+API Key : wjd-...(成员自己的 Key)
+Model : deepseek-v4.1-flash ← 注意不要写 opencode/deepseek-v4.1-flash(会 400 未知模型)
+ 或 wjd ← 虚拟 id,由管理员在网关里映射到具体模型
+```