gambn/dsh-dual-proxy ↗★ 0

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.

Package
dsh-dual-proxy
Compatibility
Unverified
Version
0.7.1
License
MIT
Last updated
Nov 3, 2026

Install

$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:gambn/dsh-dual-proxy

dsh-dual-proxy

中文 · English

CI npm

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-host127.0.0.1监听地址
--listen-port7898监听端口
--upstream-host127.0.0.1第一个候选网关
--upstream-port7897第一个候选网关的端口
--upstream-url—第一个候选的完整 URL,可含 user:pass;非空时覆盖 host/port
--gateway—额外候选网关,可重复
--health-url空通道验证地址
--health-interval-ms60000健康检查间隔,0 关闭
--fast-fail-ms2000已知路径的建连超时
--cooldown-ms30000失败网关的冷却时长
--timeout-ms5000每次尝试/探测超时
--response-timeout-ms60000普通 HTTP 等响应头的上限
--pref-ttl-ms60000每 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