Qoder2API-Hub — 国际版、国内版多账号网关中枢

本项目为 Qoder2API-Hub，将阿里 qoder.com.cn (国内版) 与 qoder.com (国际版) 的原生服务封装为标准 OpenAI 兼容接口，支持 Chat Completions 与 Responses API。具备多账号负载轮询、稳定物理设备指纹隔离、OAuth 设备授权一键免客户端登录、每日签到与实时额度查询、Pro 福利包自动领取、后台常驻定时调度器、Web 监控看板等全套能力 —— 与 WorkBuddy2API-Hub 同构的完整功能矩阵。

• 开箱即用：双击批处理脚本即启；亦支持 Docker 容器化部署，零外部 pip 依赖。
• 本机已登录凭证一键入池（双区）：只读探测桌面 App（auth.v1.dat，os_crypt/DPAPI 解密）与 Qoder CLI（~/.qoder*/.auth/user，AES-128-CBC）两类官方存储，看板两步确认导入，永不静默采用。
• 模型清单完全跟官方走（双区不同、以官方此刻为准）：三源优先级 —— 动态 /algo/api/v2/model/list（COSY 签名，GET 需携带与签名一致的 {} body，否则 403）> 本机官方客户端模型目录缓存（~/.qoder*/.models/<uid>/catalog-v6，QMC/HKDF+AES-256-GCM 解密）> 双区官方快照文件（qoder_catalog_intl.json/qoder_catalog_cn.json，python _refresh_catalog.py 一键随客户端更新）；清单以动态源返回的集合为准（官方桌面版此刻显示什么这里就显示什么，如国际版动态 15 条就不多塞静态独有的 smodel/cmodel）。逐字段忠实保留：id = 官方模型名（如 Qwen3.8-Max，客户端唯一需要填的值；upstream_key/aliases 同时给出 key、key (Name) 与人类别名等全部可填形式）、官方桌面版介绍文案（description，取自客户端 dynamic-text）、本地化名（name_local，如 Ultimate→极致）、context_config 多窗口（200K 默认/400K/1M）、thinking_config 思考档位（low/medium/high/xhigh/max + 默认标注 + 可关闭）、峰谷价（price_factor_peak 促销前倍率 → price_factor_valley 谷时倍率 + off_peak 时段窗口 22:00-08:00 与官方错峰文案）、is_free/is_new；官方 enable=false 条目不过滤，附官方原文禁用原因（disabled_reason = "需要升级或购买千问官方套餐开放"，并透传上游 disabled_message_key）。最大输出：官方 catalog 与动态接口原始响应均无此字段，故不再输出/展示任何编造值。
• 双区域独立路由：支持 🌐 国际版 (qoder.com / api1.qoder.sh，备用 api2/api3 自动故障切换) 与 🇨🇳 国内版 (qoder.com.cn / gateway.qoder.com.cn) 独立配置与管理，区域独占模型（如国内 q37fmodel/glm-5.2、国际 smodel/ultimate）自动路由到归属出口并拦截错配 Key，看板一键切换且状态落盘持久化。
• COSY 签名推理链路：RSA 包裹 AES 会话密钥 + MD5 请求签名 + 自定义 Base64 请求体编码，纯标准库实现（含 AES-128/256、RSA-PKCS1v15、GCM、DPAPI、QMC 纯 Python 实现，Docker alpine 下同样零依赖），逆向对齐官方桌面/CLI 客户端协议。
• 稳定物理设备指纹隔离 (derive_id)：以账号自身 UID 稳定哈希派生专属 cosy-machineid / cosy-machinetoken / 会话标识，同一账号长期固定在同一台虚拟物理设备，天然防多号关联风控。
• OAuth 设备授权一键免客户端登录：PKCE (S256) 设备流（双区 URL 参数按官方差异构造：国内带 redirect_uri+client_id+machine_id，国际带 client_id+machine_id），点击看板链接在浏览器完成授权即可自动入池；亦支持 PAT (pt-) 导入，jobToken 自动交换与轮换。
• 每日签到与额度体系（双区域 · 真实领取）：「每日领取 100 Credits」等活动由网关直接领取——用桌面端请求头（Cosy-ClientType: 10 + 机器头，缺了服务端会返回空列表）列出活动 → 对 CLAIMABLE 的 Credits 活动 POST /sash/api/v1/me/campaigns/{id}/claim（官方幂等：已领返回 replayed，不会重复发放）；旧 sash 签到接口仅在仍开放时兜底（能力运行时探测，404 记「本区域无此接口」6 小时后自动重探）；Pro 升级包资格检查与领取、quota/usage 额度与套餐快照实时刷新。
• 后台常驻定时调度器：每日整点排程（09:00 / 21:00 签到 · 22:00 Token 集中保活），drt- / jrt- 按前缀路由刷新，PAT 最终兜底。
• 双协议全功能支持：同时支持标准 OpenAI Chat Completions 协议与 Responses API (Codex / Claude Code)，含 custom freeform 工具（apply_patch）双向转译、DSML 工具调用回退解析，以及泄漏文本回读（模型把历史工具调用序列化复述成正文时，流式/非流式/Responses 三链路都还原为结构化 tool_calls；若回声被截断无法还原，则按严格判据吞掉、绝不把内部标记透给用户，而普通回复一律 fail-open 不吞正文）。
• 现代化 Web 看板：弹性指标卡片、签到与福利中心、模型能力清单、性能指标与用量透视、实时请求流水与运行日志。

⚡ 本项目架构与交互对齐 WorkBuddy2API-Hub，上游协议替换为 Qoder COSY 签名体系。

🖼️ 看板预览 (Dashboard Preview)

网关总览 —— 双区出口状态、调度器、账号池与请求流水一屏尽览：

模型清单 —— 与官方桌面版同源：官方模型名、峰谷价、上下文多窗口、思考档位、能力徽标：

数据指标看板 —— Token 消耗透视、TTFT 首字延迟、生成速度与缓存命中率：

签到与福利中心 —— 每日签到领积分、Pro 福利包一键领取、限时活动真实状态（双区域）：

一、快速启动

1. 本机单机使用

双击运行 start-qoder-proxy.bat，保持窗口运行：

• API 接口地址：http://127.0.0.1:8790/v1
• Web 监控看板：http://127.0.0.1:8790/

⚠️ "客户端一直显示工作中、一个字都不吐，网关日志也毫无变化" → 九成是网关没在跑：请求根本没到达，所以日志自然一动不动。一条命令确诊：

python _diag_gateway.py --chat   # 端口 → /health → /v1/models → 真实流式，逐项报出断在哪
python _diag_campaign.py         # 签到/活动链路体检（含本机虚拟化状态，中文输出）

• 生命周期就是那个 cmd 窗口（刻意的设计）：窗口开着网关就活着，关掉窗口网关即停，不会有后台残留进程；下次要用重新双击 start-qoder-proxy.bat 即可。
• 判别口诀：日志时间戳停在某一刻、此后再无 POST /v1/chat/completions = 网关已停；重新双击启动脚本即可恢复。

ℹ️ 默认端口 8790（8788 被 mimo-api-proxy.mjs 占用，8789 为 wb-proxy 默认）。改端口：start-qoder-proxy.bat 8791。

首次启动若无账号，直接打开看板点击 「+ 添加账号 (OAuth)」，在浏览器完成设备授权即可自动加入；或点 「🔑 导入 PAT」 粘贴个人访问令牌。

2. 面板访问密码

打开看板需要先输入面板访问密码，默认是 admin。它与 API Key 相互独立：

• 面板密码只用于打开网页看板，可在看板「设置」页修改（也可启动时 --panel-password 指定）；
• 密码以 PBKDF2-SHA256 摘要形式保存在 accounts/settings.json，不存明文；
• 登录状态存放在浏览器会话中，关闭浏览器或重启网关后需要重新输入。

首次登录后请立即到「设置」修改默认密码。

3. 局域网共享模式

双击运行 start-qoder-proxy-lan.bat，允许局域网内其他设备访问：

• Base URL：http://<本机局域网IP>:8790/v1
• 密钥随机生成并持久化：LAN 模式首次启动生成高强度随机 API Key（qd- 前缀），保存到 accounts/settings.json 并在终端打印，重启复用。
• 自定义 Key：start-qoder-proxy-lan.bat 8790 我的Key
• 支持带密钥直达面板：http://<IP>:8790/?key=生成的Key。
• 其他设备连不上时，管理员运行一次 allow-firewall.bat 放行防火墙。

4. 多 API Key 管理与出口绑定

网关支持多 API Key 并行管理，并可为每个 Key 指定独立出口：

• 添加与在线生成：看板「设置」页，输入名称 + 一键生成随机 Key；
• 出口自由绑定：
  • 🌐 国际版出口：该 Key 流量强制走 api1.qoder.sh（连不上自动切 api2/api3）
  • 🇨🇳 国内版出口：该 Key 流量强制走 gateway.qoder.com.cn
  • 跟随面板切换：未绑定出口的 Key 实时跟随看板顶部全局出口
• 状态管理：单独启停、一键删除，删除即刻失效；配置持久化到 accounts/settings.json；
• 安全防冲突：面板配置过 Key 后，启动脚本里的旧 --api-key 自动失效；
• 模型区域自检：Key 出口与模型区域不匹配时返回通俗 400，杜绝上游晦涩拒流报错。

5. Docker 容器化部署

方式一：官方预构建镜像（推荐）。每个版本会自动构建并推送多架构（amd64 / arm64）镜像到 GHCR，升级只要 pull：

# 1. 拉取并启动
docker compose pull
docker compose up -d

# 2. 查看网关日志
docker compose logs -f

方式二：从源码自行构建。把 docker-compose.yml 里的 image: 注释掉、改用 build: .：

docker compose up -d --build

或直接 docker run：

docker run -d --name qoder-proxy --restart unless-stopped \
  -p 8790:8790 -v $(pwd)/accounts:/app/accounts -v $(pwd)/usage:/app/usage \
  -e API_KEY=your_secret_key ghcr.io/shuishuipingan/qoder2api-hub:latest

• 持久化目录：./accounts（账号凭证及出口设置）与 ./usage（请求流水与指标快照）；
• 配置参数：环境变量 API_KEY、PORT（监听端口，默认 8790）、HOST（监听地址，默认 127.0.0.1；容器内如需对外暴露设为 0.0.0.0）。

设备身份稳定性（issue #18 实测 + v1.2.13 起根治）：容器里的机器身份是**「容器级」的——默认 bridge 网络下重启即换**（含 docker compose restart 与宿主机重启后自动拉起），任何网络模式下重建即换。若你依赖「每台设备每日限领」这类按设备去重的规则，只要 accounts/ 是挂载卷，v1.2.13 起默认就已根治（见下 ①）。注意：推理 / API 链路不受影响，它用的是按账号 UID 派生的身份。

① 机器身份落盘缓存（v1.2.13 起默认启用 —— 根治「重建 / 升级必换」） 网关会把官方组件首次输出的身份缓存到 accounts/machine_identity.json，之后优先复用：重建、升级、重启容器后设备身份保持不变。

• 前提：accounts/ 必须是挂载卷（不挂卷时缓存写在容器内部、随容器消亡，等于没缓存）；
• 缓存的是官方组件自己的输出，不是伪造；
• ⚠️ 更正（v1.2.16，据 issue #18 的实测）：组件会落状态文件 —— 它在 $HOME/.config/.locale_cfg（350 B）里存一个随机种子，身份由「该种子 + 机器证据 + 容器证据」共同决定。「想换身份」本质上就是换这个种子（我们之前「组件不落状态文件」的说法是错的）；
• 机制（三输入模型）：identity = f(种子[, $HOME/.config/.locale_cfg], 机器证据[DMI / CPU / …], 容器证据[/proc/mounts 的 overlay 行、网卡 MAC]) —— 这解释了两件事：同一容器内身份恒定（种子不变，实测 69 分钟 24 次采样无变化），而重建容器会换（overlay 行变，compose 层盖不住）；
• 想主动换身份：删除 accounts/machine_identity.json（或启动时设 QD_MACHINE_IDENTITY_RESET=1 跑一次）；
• 不想启用：QD_MACHINE_IDENTITY_CACHE=off（回到旧行为）；
• 想定期轮换：QD_MACHINE_IDENTITY_CACHE_TTL=<秒>（默认 0＝不过期）。到期后会清掉组件种子并取一个新身份（真的换，不是重读一遍同一个值），重建后身份也随之改变；
• 三条会自动「换身份」的路径：① 服务端不认当前身份时的自愈（campaigns() 判 showCampaign=false）；② QD_MACHINE_IDENTITY_RESET=1（或直接删缓存文件）；③ TTL 到期。其余路径一律不碰种子 —— 否则「重建不换」会被自己削弱；
• 若服务端某天不再接受该身份，既有自愈会在活动列表被判「未认可」时刷新并更新缓存（日志有 WARN 提示）；
• ⚠️ 该文件代表物理机器的身份，不要跨机器共享 accounts/；顺带一提，组件不可用时（如 alpine 缺兼容层）现在也能继续用真身份，而不是退化成派生假身份。

② 固定网卡 MAC（可选） —— 如果你不想启用落盘缓存、或希望组件调用本身也稳定：

① 固定网卡 MAC（推荐，代价最小） —— 留在默认 bridge 网络、保留 ports: 映射：

services:
  qoder-proxy:
    mac_address: "02:42:ac:11:00:77"
    ports: ["8790:8790"]

📌 v1.2.13 起本方案已非必需：只要 accounts/ 是挂载卷，落盘缓存就连「重建/升级」都覆盖了（见上面 ①）。保留这一条是给「不挂载 accounts/」或「希望组件调用本身也稳定」的场景。 ⚠️ 上面那串 MAC 只是示例，请换成你自己生成的，别照抄——macvlan 网络或同一宿主机跑多个实例时会撞 MAC：

printf '02:42:%02x:%02x:%02x:%02x\n' $((RANDOM%256)) $((RANDOM%256)) $((RANDOM%256)) $((RANDOM%256))

若你的 Docker 拒绝 service 级 mac_address（官方文档提到 Engine ≥ v25 可能拒绝；实测 Docker 29.6.1 与 29.7.2 均接受），改用 networks.<网络名>.mac_address。

② network_mode: host（备选） —— 彻底共享宿主网络栈，适合宿主机端口冲突、或确实需要容器直接占用宿主端口时；代价是不能用 ports: 映射，且切换前请确认目标端口在宿主机上空闲，否则容器会启动失败。

机制（两输入模型）：identity = f(每容器独有的量, 容器网卡 MAC) —— bridge 下容器停止会重建 veth、MAC 随之改变，而身份同时依赖这两者；固定 MAC 即可让 stop/start 后身份逐字节不变。两条路都只解决「重启」这一类：重建容器仍会换（由「每容器独有的量」决定，compose 层无法覆盖）。

以上已在 amd64 与 arm64、真实官方镜像 + 真实 compose 下验证（issue #18 的作者与我们的独立复现）。

二、核心特性详解

1. 请求链路（COSY 签名推理）

瞬时故障韧性（双层）：上游把自己的 provider 故障包装成 418/5xx + provider_error 抛回，或对 qoder.sh 出现 TLS/连接抖动（SSL: UNEXPECTED_EOF...）时：

• 连接层（urlopen 时刻的 HTTP/传输错误）：同账号快速重试 2 次（1s/2s 退避）；
• 流内信封层（关键形态：上游先 HTTP200 建流、再在 SSE 信封里投 statusCodeValue=418——表现为 access log 记 200 而业务错 418）：在尚未向客户端写出任何上游字节前重开上游重试 2 次（chat 流式/非流式 + Responses 全覆盖），流式客户端全程无感。

重试仍失败才短冷却（15s，单账号池实际 3s）换号——不因上游的锅罚账号 60 秒；短错误冷却期间（≤10s）后续请求改为「等待续上」而非报错，且 429 usage exceeds frequency limit 只在上游真频控时出现（账号错误冷却不再被误标为频控）。客户端参数错误（invalid_parameter_error 等）与上游内容安全审核拒绝（InternalError.Algo.DataInspectionFailed: Input text data may contain inappropriate content）绝不重试、快速失败——后者返回中文解释（content_policy_rejected：确定性拒绝、重试无效，请检查/缩短输入），由调用方修改输入而非等待。耗尽后其余瞬时错误客户端收到中文友好提示（upstream_transient_error）；错误详情经 qoder_detail 挂载保留 400 字节完整送达日志（含内层 details）。

HTTP 帧层与保活（治“一直重连/连不上”）：

• 流式响应使用 HTTP/1.1 Transfer-Encoding: chunked 并以 0\r\n\r\n 正确收尾，不再发 Connection: close：同一个 keep-alive 连接