10router-dev

10Router — Dev & Troubleshooting 开发排障

Gateway: local AI routing proxy. NAS 上是 Next.js standalone 编译产物（server/.next/），不是源码。改逻辑必须 build + 部署 + 重启才生效。

部署循环（改源码 → 构建 → 部署 → 重启）

cd ~/projects/10router
npm run build    # 2-4 分钟
S=.next/standalone
cp -r open-sse $S/ 2>/dev/null; cp -r src/mitm $S/src/ 2>/dev/null; cp -r node_modules/node-forge $S/node_modules/ 2>/dev/null
cat $S/.next/BUILD_ID
tar -czf /tmp/10router-standalone.tar.gz -C $S .; scp /tmp/10router-standalone.tar.gz [email protected]:/tmp/

NAS 上（走 fnOS 生命周期，不能手动 kill）：

SERVER=/vol4/@appcenter/10router/server
sudo mkdir -p /tmp/10router-new; sudo tar -xzf /tmp/*.tar.gz -C /tmp/10router-new
sudo cp -a $SERVER/.env /tmp/10router-new/.env      # 必须保留 .env
sudo cp -a $SERVER /vol4/@appcenter/10router/server.bak_vXXX   # 备份可回滚
sudo find $SERVER -mindepth 1 -delete; sudo cp -a /tmp/10router-new/. $SERVER/
sudo chown -R 10router:10router $SERVER
sudo appcenter-cli stop 10router; sudo appcenter-cli start 10router

验证：sudo cat $SERVER/.next/BUILD_ID 确认新 ID。重启会短暂断开当前 Hermes 会话（本会话经 10router 代理）——重启前告知用户。

第三方客户端兼容问题排查方法论（"XX 用不了"）

适用于：用户报某个第三方客户端（mirasim/dsh/codex/Claude Code 等）经 10router 调某模型报错，但同一模型其他客户端可能正常。先定位责任环节（客户端 / 网关 / 上游），再决定是否适配。

第一步：跨环境对比定位责任环节（最重要）

让用户在不同环境 + 客户端测同一个模型，做对照矩阵：

环境	结果 → 结论
NAS 直连客户端（独立安装，不经 mirasim）	正常 → 10router + 上游都正常
经 mirasim 的同一客户端	异常 → 嫌疑在 mirasim
经 mirasim 的另一个客户端（codex）	正常 → mirasim 本身没大问题
Claude Code → 10router	正常 → 10router translator 正确
同一客户端 + 官方 DeepSeek	报错更清晰 → 拿明确报错定位

多个"正常"锁定 10router 无责；一个"异常"锁定源头。

第二步：看网关日志确认请求到达 + 路由

sudo grep -nE "cbcn/deepseek|11133|ERROR" /vol4/@appdata/10router/10router.log | tail -20

请求行 POST <模型> → <provider/model> · FMT: <src>→<dst> · N MSG · N TOOL · ACC:<账号>：

• FMT 关键：openai→openai = 原样透传（客户端发什么 10router 转发什么）；claude→openai = 经 translator 转换（会重建 tool_calls）。
• N TOOL 是客户端特征（mirasim+dsh=25，Claude Code=53）。
• 确认请求真的到了（有时用户以为触发了但没到网关，日志空白）。