dsh-dual-proxy
Agent gateway manager: picks a working gateway among proxies and direct, verifies the model channel, and switches online; DSH plugin plus standalone CLI.
Install
npx -p @deepseek-ai/dsh dsh plugin --profile web add github:gambn/dsh-dual-proxyREADME
Read the full README ↗dsh-dual-proxy
Agent 的网关管理插件:在多个网关之间在线自动切换,让模型请求不再被一条不稳的路卡死。
它把「agent 到模型端点的网络路径」当成可管理的资源:在配置的上游、额外指定的代理、启动环境里的代理和直连之间自动选一条能通的;运行中用真实请求持续验证,失败立刻切到下一条——不需要重启宿主,也不需要改客户端配置。
快速开始
# DSH 插件(npm)
dsh plugin --profile web add dsh-dual-proxy
# 独立 CLI
npm install -g dsh-dual-proxy
要求 Node.js ≥ 22.19.0;DSH 插件还要求 dsh ≥ 0.1.7。插件安装后确认 dsh.profile.bundles 含 dsh-dual-proxy,再重启 dsh web;细节见下文。
从源码安装(可选):
git clone https://github.com/gambn/dsh-dual-proxy.git
cd dsh-dual-proxy
npm install
dsh plugin --profile web add "$PWD"
两种形态,同一份核心:
- DSH 插件(推荐):随 DSH 启停,配置在「设置 → 插件」里改,可把宿主自身的模型请求接进来;
- 独立进程:手动跑 CLI,或挂 systemd 用户服务,非 DSH 宿主的 agent 与脚本也能直接用。
它解决什么
上游代理并不稳定:同一个代理可能对 A 站通、对 B 站不通,也可能整段时间全挂;本机同时装着两个代理时,哪个能用还会变。只认一条路的客户端在这种时候会成片失败,而在死路上重试只是拖延。
这一层把候选路都握在手里,按 host 选:
客户端 → 127.0.0.1:7898
├── 网关 A(TLS 探测通过)→ 上游代理
├── 网关 B(TLS 探测通过)→ 上游代理
└── 都探测失败 → 直连
健康检查用一个真实请求把同一组候选走一遍,谁先给出 /dev/null
## 作为独立进程
```bash
node bin/dsh-dual-proxy.js --listen-port 7898 --upstream-port 7897 \
--gateway 127.0.0.1:12334 --health-url https://api.deepseek.com
| 参数 | 默认 | 说明 |
|---|---|---|
--listen-host | 127.0.0.1 | 监听地址 |
--listen-port | 7898 | 监听端口 |
--upstream-host | 127.0.0.1 | 第一个候选网关 |
--upstream-port | 7897 | 第一个候选网关的端口 |
--upstream-url | — | 第一个候选的完整 URL,可含 user:pass;非空时覆盖 host/port |
--gateway | — | 额外候选网关,可重复 |
--health-url | 空 | 通道验证地址 |
--health-interval-ms | 60000 | 健康检查间隔,0 关闭 |
--fast-fail-ms | 2000 | 已知路径的建连超时 |
--cooldown-ms | 30000 | 失败网关的冷却时长 |
--timeout-ms | 5000 | 每次尝试/探测超时 |
--response-timeout-ms | 60000 | 普通 HTTP 等响应头的上限 |
--pref-ttl-ms | 60000 | 每 host 偏好缓存 TTL |
--no-verify-tls | 关 | 跳过 443 的 TLS 探测 |
--retry-non-idempotent-after-send | 关 | 连接建立后失败时也重放 POST/PATCH |
--retry-non-idempotent-with-idempotency-key | 关 | 带 Idempotency-Key 时允许发送后重放 |
环境变量同名(LISTEN_HOST、LISTEN_PORT、UPSTREAM_HOST、UPSTREAM_PORT、UPSTREAM_URL、GATEWAY、HEALTH_URL、HEALTH_INTERVAL_MS、FAST_FAIL_MS、COOLDOWN_MS、ATTEMPT_TIMEOUT_MS、RESPONSE_TIMEOUT_MS、PREF_TTL_MS、VERIFY_TLS=0、RETRY_NON_IDEMPOTENT_AFTER_SEND=1、RETRY_NON_IDEMPOTENT_WITH_IDEMPOTENCY_KEY=1)。
systemd 用户服务模板在 contrib/。
配合 Claude Code
Claude Code 是原生二进制,不能像 DSH 那样把 fetch 引到进程内;适配方式是用启动器包一层:代理在启动器进程里监听,再把代理环境变量指向它并启动 claude。
# 默认监听 7896;`--` 之后原样交给 claude
claude-dual-proxy --listen-port 7896 --gateway 127.0.0.1:12334 -- --resume
启动器会:按与独立进程相同的方式解析候选网关;给子进程设置 HTTP_PROXY/HTTPS_PROXY(大小写各一份)和 ALL_PROXY,并替换掉启动环境里 socks 的 ALL_PROXY;把回环地址并入 NO_PROXY;claude 退出时关闭代理。子进程的 ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN 等变量保持不变。
宿主适配层与核心的边界:包入口(src/index.js)仍是 DSH 插件,实现在 src/adapters/dsh.js;宿主无关的核心通过 dsh-dual-proxy/core 导出(createDispatcher、resolveUpstream、collectGateways 等),其他宿主可以只依赖这一层。
测试
npm test
测试面向仓库或源码快照;首次先在源码目录 npm install,再 npm test。npm 包不含 test/,安装后不能直接跑这套用例。
用例覆盖:HTTP 直连回退、经假代理转发、多个网关时跳过不通的、两条都不通返回 502、黑洞网关按超时换路、请求与响应两个方向的逐跳标头过滤、上游中途断开不带崩进程、CONNECT 直连隧道与经假代理隧道、CONNECT 200 同包早期数据、IPv6 字面量、缓存网关卡住时快失败换路、失败网关冷却后不再先撞、关闭时强制断开在途隧道、网关解析与去重(含自身端口排除与自环防护)、健康检查的选择与失败、健康循环记住首选、失败踢一次健康检查、健康检查重入锁、偏好缓存上限、CLI 参数校验与退出码、插件生命周期(启动/重启/双 context)、自签证书的 TLS 探测、非幂等重放策略(send 前后边界、方法分类、开关、日志与冷却)、上游代理认证(CONNECT/HTTP/健康检查、407)、带幂等键的发送后重放(开关/键存在性/日志)、以及 fetch 路由的安装/替换/回滚与回环绕过。
边界
- 只处理 HTTP/1.1 的
CONNECT与普通 HTTP;不做透明代理、不接管 UDP。 - 普通 HTTP 请求在网关连上后要等满
responseTimeoutMs(默认 60 秒)才判定响应头超时;0.7.0 不缩短这个等待,幂等键只改变超时后的重放决策。 - CONNECT 隧道建立后代理只转发字节,TLS 端到端;隧道内失败无法换路,要覆盖只能做 MITM 解密,和本项目“不拦截”的定位冲突。
- 不校验证书,不缓存内容,不做鉴权。默认只绑回环;把
listenHost改成非回环地址会在启动时告警——那等于开放一个无鉴权代理,风险自负。 - 上游代理认证只支持
http://的 Basic;不支持https://上游代理(TLS-to-proxy)。Basic 只适合回环或受信任网络,远程代理的凭证保护不在本项目范围内。 - 只负责「到不到得了」,不负责「信不信得过」——证书校验仍是客户端的责任。
- 健康检查只发一个无凭证
GET,判据是「有没有 。请勿在 Issue 里粘贴 token、密钥或完整请求内容;安全问题见 SECURITY.md。
License
MIT