把武汉理工的 "DeepSeek云服务版"包装成标准协议接口，让 pi、Claude Code、Codex CLI、Cline、Cherry Studio 或任何 OpenAI SDK 都能直接用上学校的模型。

这套 OpenWebUI 本来就提供 OpenAI 格式的接口（POST /api/chat/completions），所以不需要逆向网页、不需要浏览器自动化。 真正麻烦的只有两个：

1. 个人 API Key 被管理员关了（enable_api_key: false）→ 只能用浏览器登录后那份 JWT；
2. 这份 JWT 7 天过期，而且是一大串 eyJhbGciOi...——直接塞进各个 AI 工具，每 7 天要改一遍配置，还没法统一做参数修正。

于是有了这层本地代理：把「凭证」和「协议修正」从每个客户端里收出来，集中在一处处理。

三个入口共用同一个 provider，所以限速、熔断、重试、用量统计、分发 key 全都一致。

动画图中间的四个模块：

实测（2026-11）：学校的 POST /api/v1/auths/signin 只校验学号是否存在，password 字段只要非空即可通过。 所以本项目只需要学号，从不保存也不需要你的密码。

共同前提：必须能访问校园网（校内 / 学校 VPN）。校外直连会超时。 若本机开着 Clash / Surge 等代理，请把 whut.edu.cn 加进直连规则——学校会拒绝代理节点的出口 IP。

懒人方案：把下面这段话直接发给你自己的 AI agent（pi / Claude Code / Cline 都行），让它替你装：

帮我在本机安装并部署 https://github.com/Song-xuan-xuan/wut-deepseek2api 这个项目：
1. git clone 到当前目录，用 python3 -m venv .venv 建虚拟环境，安装 requirements.txt
2. 复制 config.example.json 为 config.json
3. 后台启动 .venv/bin/python -m app（macOS/Linux），或 .venv\Scripts\python -m app（Windows）
4. 确认 http://127.0.0.1:8787/health 返回 200，并把面板地址 http://127.0.0.1:8787/dashboard 告诉我
5. 提醒我在面板「认证」页填学号完成认证（不需要密码）
6. 如果端口 8787 被占用、依赖装不上、或代理导致连不上学校，请自行排查并汇报原因
注意：必须先能访问校园网；token 和数据库都保存在项目内的 data/ 目录。

适合：想改代码、调面板，或机器上不方便跑 Docker。

① 准备环境

② 拉代码并启动

git clone https://github.com/Song-xuan-xuan/wut-deepseek2api.git
cd wut-deepseek2api

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt          # Windows: .venv\Scripts\pip install -r requirements.txt
cp config.example.json config.json                 # Windows: copy config.example.json config.json
.venv/bin/python -m app                            # Windows: .venv\Scripts\python -m app

③ 一键认证

打开 http://127.0.0.1:8787/dashboard → 左侧「认证」→ 输入学号 → 点「认证」。

看到"认证成功，token 剩 7.0 天"就好了：学号写回 config.json，token 写到 data/token， 之后每 60 分钟检查、剩余不足 2 天自动续期——再也不用管 token。

不装 Python，只要 docker + docker compose：

git clone https://github.com/Song-xuan-xuan/wut-deepseek2api.git
cd wut-deepseek2api

cp .env.example .env        # 填 WHUT_EMAIL=你的学号（也可以先本地认证一次，凭证落在 ./data/token）
docker compose up -d --build
docker compose logs -f      # 看到 "token 7.0 天后过期" 就成功了

验证：curl --noproxy '*' -s 127.0.0.1:8787/health，然后打开 http://127.0.0.1:8787/dashboard。

数据都在 ./data（token + usage.db），删容器不丢。

容器流量会跟着宿主机的系统代理走，而学校会拒绝代理节点的出口 IP。 症状很好认：宿主机 curl 返回 200，容器里 TLS 握手却被重置 / /health 报 ConnectError。

解决办法：在代理规则里让学校域名直连。以 FlClash 为例，四步：

1. 打开 FlClash → 左侧 配置（Profiles） → 找到你在用的那份 → 点右侧 编辑（Edit / 编辑文件）

2. 找到 rules: 这一段，把下面两行加到最前面（缩进与 rules: 同级，两个空格起头）：

   rules:
     - DOMAIN-SUFFIX,whut.edu.cn,DIRECT
     - IP-CIDR,218.197.110.99/32,DIRECT,no-resolve
     # ↓ 以下是原本就有的规则，保持不动
     - DOMAIN-SUFFIX,google.com,Proxy
     ...

3. 保存（⌘S / 右下角保存），FlClash 会自动重载配置；没重载就点一下该配置重新应用

4. 验证——这条命令输出 200 就通了：

   docker compose exec whut-2api python -c \
     "import urllib.request;print(urllib.request.urlopen('https://chatcloud.whut.edu.cn/api/config',timeout=10).status)"

   如果还是超时/报错，再补一条（有些订阅会把 IP 直连写死）：

   - AND,((DOMAIN-SUFFIX,whut.edu.cn),(NETWORK,tcp)),DIRECT
   

所有客户端都是同一组值（面板「仪表盘」页可一键复制，或「分发 / Key」页下载现成模板）：

{
  "whut": {
    "baseUrl": "http://127.0.0.1:8787/v1",
    "api": "openai-completions",
    "apiKey": "sk-whut-local",
    "models": [
      {
        "id": "deepseek-v4-flash",
        "name": "WHUT DeepSeek V4 Flash",
        "contextWindow": 700000,
        "maxTokens": 120000,
        "input": ["text", "image"],
        "reasoning": false,
        "compat": {
          "supportsStore": false,
          "supportsDeveloperRole": false,
          "supportsReasoningEffort": false,
          "maxTokensField": "max_tokens",
          "supportsStrictMode": false
        }
      }
    ]
  }
}

pi --model whut/deepseek-v4-flash

# 方式一：临时覆盖，不影响已有的 ~/.claude/settings.json
export ANTHROPIC_BASE_URL="http://127.0.0.1:8787"
export ANTHROPIC_AUTH_TOKEN="sk-whut-local"
export ANTHROPIC_MODEL="deepseek-v4-flash"
export ANTHROPIC_SMALL_FAST_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=700000
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

claude -p "只回复两个字：成功"

model = "deepseek-v4-flash"
model_provider = "whut"

[model_providers.whut]
name = "WHUT OpenWebUI"
base_url = "http://127.0.0.1:8787/v1"
env_key = "WHUT_API_KEY"
wire_api = "responses"
request_max_retries = 2
stream_max_retries = 1

export WHUT_API_KEY=sk-whut-local
codex

{
  "models": [
    {
      "title": "WHUT DeepSeek",
      "provider": "openai",
      "model": "deepseek-v4-flash",
      "apiBase": "http://127.0.0.1:8787/v1",
      "apiKey": "sk-whut-local"
    }
  ]
}

# OpenAI 协议
curl --noproxy '*' -s 127.0.0.1:8787/v1/chat/completions \
  -H "Authorization: Bearer sk-whut-local" -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"你好"}],"max_tokens":512}'

# Anthropic 协议
curl --noproxy '*' -s 127.0.0.1:8787/v1/messages \
  -H "x-api-key: sk-whut-local" -H "anthropic-version: 2023-06-01" \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-flash","max_tokens":256,"messages":[{"role":"user","content":"你好"}]}'

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8787/v1", api_key="sk-whut-local")
resp = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=[{"role": "user", "content": "你好"}],
    max_tokens=512,
)
print(resp.choices[0].message.content)

统计写在 data/usage.db（SQLite）。如果这个文件被写坏，代理会自动把它改名留档 （usage.db.corrupt-<时间戳>）并重建空库，同时 /health 的 warnings 和面板「系统信息」 都会显示提示 —— 不会再出现「面板一直是 0 却毫无提示」的情况。

常见成因都是「同一时刻有多个进程写同一个库」：

• 本地源码和 Docker 容器同时在跑（docker compose ps 和 lsof -ti:8787 都查一下，只留一个）
• 容器 --force-recreate / down 时正好有请求在写
• 直接在宿主机用别的工具打开 data/usage.db 又强行中断

处理：

docker compose stop
mv data/usage.db.corrupt-* /tmp/         # 想留证据就备份到别处
docker compose up -d                      # 会新建一个干净的库

学校这套 OpenWebUI 的失败模式比较杂，代理层统一兜住，客户端不需要自己重试：

重试只发生在「拿到响应头之前」，对流式请求同样安全；每次重试都会在日志里留一行：

[19:58:02] chat 重试 1/3（400 'Open WebUI: Server Connection Error'）
[19:58:02] chat 重试 2/3（400 'Open WebUI: Server Connection Error'）

实测：上游连续两次 400 抖动 → 客户端拿到正常结果；一直 403 → 1 + 3 次尝试后（约 2.4 s） 返回带续期提示的 403，不会无限重试。

所有请求都会落库到 data/usage.db（SQLite），重启不清零，面板可按区间/模型/Key 查看，也能导出 CSV。

学校三个模型的真实表现（2026-10-26 实测，真实打到上游，不是抄官方参数）：

更详细的测评请看 👉 docs/model-capabilities.md

这是本项目**最容易误解、也最容易误判成「代理有 bug」**的地方，所以单独讲清楚。

模型能读 74 万 token，但学校 nginx 只允许一次请求 1 MiB 字节。 这两件事用不同的单位度量，1 MiB 折合多少 token 取决于你的内容类型 —— 所以「模型窗口 1M tokens」和「传输上限 1 MB」完全不是同一件事，只是数字看起来像。

客户端每轮的请求体（全部历史 + system + 工具 schema，每轮全量重发，不是增量）
    │
    ├─ ① nginx  client_max_body_size 1m  →  1,048,576 字节   硬上限，超了立刻 413
    │                                       （请求根本没到模型）
    ├─ ② OpenWebUI  RAG_FILE_MAX_SIZE    →  2 MB             上传文件时才检查
    │                                       （永远轮不到它生效）
    └─ ③ 模型窗口                         →  ≥ 745,080 tokens 只有前两道没超才受它约束

生效顺序永远是「最紧的那道先拦」：① > ② > ③，所以实际可用上下文 = min(① ÷ 每token字节数, ③)。

补充两点常被忽略的：

• 只算 body，HTTP 头不算；Content-Length 与 Transfer-Encoding: chunked 都按总量计。
• 是「每次请求」而不是「整个会话」：agent 每轮都把历史重发一遍，所以会话越长越接近这条线。

同一个 1 MiB，装多少 token 完全看内容（全部为本项目实测）：

换句话说：中文内容到 17 万 token 就撞墙了，而随机串能装 80 万 —— 差 4 倍以上，但都发生在同一个 1 MiB 上。

用不存在的 model 名探测，让上游几毫秒内回 400，这样每次只测 nginx 那一层：

用真实模型复验同一位置：

body = 1,048,576 B  → 200 ✅  21.6 s  prompt_tokens = 349,578
body = 1,048,577 B  → 413 ❌   33 ms  Server: nginx/1.27.4

拿本项目自身的历史会话（1,624 条消息 / 7.24 MB，其中 toolResult 占 63.4%）模拟：

常见误判：「我上下文才 300 多 K，怎么就 413 了？」 因为那 300 多 K 是 token，不是 KB —— 300,000 × 4 ≈ 1.2 MB，早就超过 1 MiB 了。

自查公式（对代码/中英混排内容误差很小）：

报错里的字节数 ÷ 4 ≈ 实际 token 数
1,048,576 ÷ 4 ≈ 262,000 tokens   ← 这条链路能装的上限

因为那次用的是最省字节的文本：随机 ASCII 每个字符基本等于一个 token，1 字节换 1 token，所以 974,025 字符只占 0.95 MiB。

它证明的是「模型窗口至少 745,080 tokens」（验证码放最开头、问题放最后，模型准确答出）， 不代表日常能塞 74 万 token —— 同样 74 万 token 换成代码内容约需 2.9 MiB，早就 413 了。

网页端提示「文件大小不应超过 2 MB」（来自 OpenWebUI 的 RAG_FILE_MAX_SIZE），但实测：

所以界面承诺的 2 MB 永远达不到，实际能传约 1.00 MB（1,048,576 减去 multipart 头几百字节）。 这是一处配置不一致：应用层说 2 MB、传输层只给 1 MB。

网页版对话同理 —— 浏览器把完整历史打包进 POST /api/chat/completions 的 body，聊得足够久也会 413，只是人打字慢，很难撞到。

首次启动自动生成；用面板认证过的不用改。

环境变量覆盖：WHUT_BASE_URL、WHUT_TOKEN、WHUT_TOKEN_FILE、WHUT_EMAIL、WHUT_PORT、WHUT_HOST、WHUT_CLIENT_KEY、WHUT_MAX_TOKENS_CAP、WHUT_DATA_DIR。

wut-deepseek2api/
├── app/                      后端（FastAPI）
│   ├── core/                 配置 · SQLite · 路径 · 日志
│   ├── providers/            上游抽象 + OpenWebUI 实现
│   ├── modules/
│   │   ├── proxy/            /v1/chat/completions · 参数修正 · SSE 透传
│   │   ├── anthropic/        /v1/messages（Claude Code）
│   │   ├── responses/        /v1/responses（Codex CLI）
│   │   ├── auth/             学号登录 · 自动续期 · 事件历史
│   │   ├── usage/            用量聚合 · CSV
│   │   ├── access/           多 key · 配额 · 限速 · 模板
│   │   └── system/           健康检查 · 静态资源
│   └── main.py               组装 + 挂模块
├── web/                      面板（Vue 3 + Vite）
│   ├── src/                  源码
│   ├── public/               架构动画图 · 截图
│   └── dist/                 构建产物（已提交，运行不需要 Node）
├── scripts/modeltest/        模型实测（bench · suites · report）+ results/
├── docs/                     说明文档（Docker 部署手册、模型与协议实测报告）
├── data/                     运行时数据（token、用量库，已忽略）
├── Dockerfile · docker-compose.yml · .env.example
├── requirements.txt · config.example.json
└── LICENSE

• 这是一个个人学习项目，用于学习 HTTP 代理、流式传输与协议转换。
• 与武汉理工大学官方无关，不代表学校立场，也未获得学校授权。
• 使用时请遵守学校的网络与信息系统管理规定，仅限个人本地使用，不要对外提供服务。

MIT License · 详见 LICENSE