Files
xiaoyin-gateway/docs/waf-api-access.md
T
jidekin 0531f48223 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
2026-10-22 19:41:05 +08:00

92 lines
3.4 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# WAF 与 API 访问:为什么 AI 编程客户端会被 403
> 2026-10-22 由真实工单沉淀(成员 `chenghongchang` 反馈「拿 apikey 请求 403」)。
## 现象
```
POST https://api.wangjinding.com/v1/chat/completions
Authorization: Bearer wjd-...
User-Agent: WorkBuddy/5.8.3 → HTTP 403
```
同一把 Key 用 `curl`(`content: "hi"`)请求**完全正常 200**,模型、网关、渠道都没问题。
## 根因
`api.wangjinding.com` 前面挂着 **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/api.wangjinding.com/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://api.wangjinding.com/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://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,由管理员在网关里映射到具体模型
```