fix(security): 成员不再读到全站用量(/health 按角色分流)+ WAF 放行 /v1/

- /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
This commit is contained in:
jidekin committed 2026-10-22 19:41:05 +08:00
1 parent 1576162ecc
commit 19224f1993
3 files changed
+142 -1

No files matched your search

+29
View File
@@ -1,5 +1,34 @@
# CHANGELOG # 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 等)
发出的提示词里带 `<script>`、`../`、`system(` 就被当成攻击拦截(403 响应 16711/23682 字节的拦截页)。
- 给 `1pwaf` 的 `rules/urlWhite.json` 增加 `{"state":"on","name":"000901","rule":"^/v1/","type":"urlWhite"}`,
使网关的 AI 接口跳过内容检查;`/v1/` 之外仍照常拦截(实测 `/.env`、`/etc/passwd` 依旧 403)。
- 背景、证据与排查手册见 `docs/waf-api-access.md`。
## 2026-10-12 · 清除旧托管残留(远端 / 脚本 / 文档) ## 2026-10-12 · 清除旧托管残留(远端 / 脚本 / 文档)
老板:「旧托管的都删了,代码,文档相关的都去掉」。 老板:「旧托管的都删了,代码,文档相关的都去掉」。
+22 -1
View File
@@ -340,7 +340,7 @@ _docs_on = config.server.docs_enabled # 安全默认关(report: /docs、/ope
# 2026-09-30: 2.6.1 → 2.7.0(按老板要求整个删除「火山方舟 Coding Plan」供应商:配置/模型/代码/文档/前端下拉/环境变量全清)。 # 2026-09-30: 2.6.1 → 2.7.0(按老板要求整个删除「火山方舟 Coding Plan」供应商:配置/模型/代码/文档/前端下拉/环境变量全清)。
# 2026-09-30: 2.7.0 → 2.7.1(界面提示白话化:熔断器→供应商自动保护、引擎→运行环境、slug→标识;删 120 个未引用死键)。 # 2026-09-30: 2.7.0 → 2.7.1(界面提示白话化:熔断器→供应商自动保护、引擎→运行环境、slug→标识;删 120 个未引用死键)。
# ★ 版本号纪律:每次改动都要往上加,小改动加小版本号、大改动加大版本号(README 有专章)。 # ★ 版本号纪律:每次改动都要往上加,小改动加小版本号、大改动加大版本号(README 有专章)。
VERSION = "2.7.2" VERSION = "2.7.3"
app = FastAPI( app = FastAPI(
title="API Gateway", title="API Gateway",
@@ -2935,6 +2935,8 @@ async def metrics(request: Request, _auth=Depends(require_auth)):
if not _cfg().server.metrics_enabled: if not _cfg().server.metrics_enabled:
raise HTTPException(404, "metrics 已禁用") raise HTTPException(404, "metrics 已禁用")
# M5+: 普通账号只看自己名下调用产生的聚合,admin 看全局 + 熔断状态。 # M5+: 普通账号只看自己名下调用产生的聚合,admin 看全局 + 熔断状态。
# 2026-10-22(老板):成员首页要看自己调用的次数统计,所以**不**把本端点收成仅管理员;
# 按账号聚合的逻辑保持原样(全局字段的收敛在 /health 里做)。
if request.state.role == "admin": if request.state.role == "admin":
snap = _metrics.snapshot() snap = _metrics.snapshot()
snap["circuits"] = _circuits.statuses() # P2-16 熔断状态 snap["circuits"] = _circuits.statuses() # P2-16 熔断状态
@@ -3778,6 +3780,25 @@ async def health(request: Request, _auth=Depends(require_auth_or_open)):
return {"status": "ok"} return {"status": "ok"}
cfg = _cfg() cfg = _cfg()
snap = _metrics.snapshot() if cfg.server.metrics_enabled else {} snap = _metrics.snapshot() if cfg.server.metrics_enabled else {}
# 2026-10-22(老板):成员首页需要"运行时长 / 并发 / 供应商列表"这些运行态,
# 但**全局** token 总量、各模型的全局调用量与失败率、供应商熔断状态属运维数据,
# 只应收口给管理员(此前任何有效 Bearer 都能读到全站用量)。
if request.state.role != "admin":
return {
"status": "ok",
"version": VERSION,
"uptime_seconds": snap.get("uptime_seconds"),
"in_flight": snap.get("in_flight", 0),
"in_flight_peak": snap.get("in_flight_peak", 0),
"providers": {
pkey: {
"name": pconfig.name,
"api_key_set": bool(pconfig.auth.resolve_token()),
"models": len(pconfig.models),
}
for pkey, pconfig in cfg.providers.items()
},
}
calls = snap.get("calls", {}) calls = snap.get("calls", {})
# 每模型失败率 + 平均耗时 # 每模型失败率 + 平均耗时
model_health = {} model_health = {}
+91
View File
@@ -0,0 +1,91 @@
# WAF 与 API 访问:为什么 AI 编程客户端会被 403
> 2026-10-22 由真实工单沉淀(成员 `chenghongchang` 反馈「拿 apikey 请求 403」)。
## 现象
```
POST https://127.0.0.1:8808/v1/chat/completions
Authorization: Bearer wjd-...
User-Agent: WorkBuddy/5.8.3 → HTTP 403
```
同一把 Key 用 `curl`(`content: "hi"`)请求**完全正常 200**,模型、网关、渠道都没问题。
## 根因
`127.0.0.1:8808` 前面挂着 **1Panel 的 WAF(1pwaf)**,它会检查**请求体内容**:
| 请求体里出现 | 结果 |
|---|---|
| `<script>alert(1)</script>` | 403(命中 XSS 规则)|
| `../../etc/passwd` | 403(命中路径穿越规则)|
| `system("ls -la")` | 403(命中命令执行规则)|
| 普通文本 | 200 |
AI 编程客户端(WorkBuddy / Cursor / 各类 CLI)把**用户代码**原样塞进 prompt,
代码里天然带 `../`、`system(`、`<script>` —— 于是**被当成攻击拦掉**。
判断依据(WAF 访问日志):
```
/opt/1panel/www/sites/127.0.0.1:8808/log/access.log
117.85.65.211 - - [22/Oct/2026:17:40:26 +0800] "POST /v1/chat/completions HTTP/1.1" 403 16711
"-" "WorkBuddy/5.8.3" "116.228.205.72" ← 最后一列是真实客户端 IP(经 EO 回源后)
```
**403 响应体大小 16711 / 23682 字节 = WAF 拦截页**(网关自己的错误是 JSON,通常 < 1KB)。
遇到 403 先看这两个数字,就能区分「WAF 拦」还是「网关拒」。
## 处置
给 WAF 的 URL 白名单加一条,让 `/v1/` 下的 AI 接口跳过内容检查:
```json
// /opt/1panel/apps/openresty/openresty/1pwaf/data/rules/urlWhite.json
{
"rules": [
{ "state": "on", "name": "000901", "rule": "^/v1/", "type": "urlWhite" }
]
}
```
生效:
```bash
docker exec 1Panel-openresty-npAh nginx -t
docker exec 1Panel-openresty-npAh nginx -s reload
```
> `1pwaf/data` 是宿主目录挂进容器的:
> `/opt/1panel/apps/openresty/openresty/1pwaf/data -> /usr/local/openresty/1pwaf/data`
## 验证
```bash
K=wjd-... # 任一成员的 Key
# 1) 以前被拦的内容现在应 200
curl -s -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8808/v1/chat/completions \
-H "Authorization: Bearer $K" -H 'Content-Type: application/json' \
-d '{"model":"deepseek-v4.1-flash","messages":[{"role":"user","content":"<script>alert(1)</script> system(\"ls\")"}],"max_tokens":5}'
# 2) /v1/ 之外必须仍然拦截(这是安全底线,别把 WAF 整个关掉)
curl -s -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8808/.env # 期望 403
curl -s -o /dev/null -w '%{http_code}\n' https://127.0.0.1:8808/etc/passwd # 期望 403
```
## ⚠️ 持久化注意
线上这套 WAF 配置由 **阿里云那台的 1Panel 主控**通过 agent 下发。
直接改文件**立刻生效**,但如果在面板里保存一次 WAF 设置,这条白名单**可能被覆盖**。
**建议在面板里也加一遍**:`网站 → 127.0.0.1:8808 → WAF → 白名单 → URL 白名单 → ^/v1/`。
之后如果又出现 403,先按本文「判断依据」确认是不是 WAF,再补规则即可。
## 给调用方的配置口径
```
Base URL : https://127.0.0.1:8808/v1
API Key : wjd-...(成员自己的 Key)
Model : deepseek-v4.1-flash ← 注意不要写 opencode/deepseek-v4.1-flash(会 400 未知模型)
或 wjd ← 虚拟 id,由管理员在网关里映射到具体模型
```