dsh-proxy-bridge

@painclown/dsh-proxy-bridge

轻量级 DSH 反向代理桥，专为 nginx 等 TLS 终结反代后面的 WebSocket 转发设计。

理念参考 @riceawa/dsh-lan-gateway，感谢 riceawa 的启发。

解决什么问题

DSH Web GUI 的 WebSocket 连接在通过 nginx → 网关 → DSH 链路时会因 Origin/Host 不匹配返回 403。本插件跳过 same-site 检查，信任上游终结器（nginx）做访问控制，直接转发 HTTP + WebSocket 到 DSH。

架构

浏览器 ──HTTPS──> nginx (TLS 终结) ──HTTP──> Bridge (0.0.0.0:3083) ──HTTP──> DSH (127.0.0.1:3080)
                                              │
                                              ├── 密码门 (可选)
                                              ├── DSH Cookie 自动注入
                                              ├── WebSocket 透传 (raw TCP splice)
                                              └── 速率限制 / 会话撤销

• HTTP: 转发时重写 Host/Origin 到 127.0.0.1:3080
• WebSocket: socket 直接 splice 到上游，无 same-site 检查
• 密码门: 可选的第二层认证（在 nginx 之上）
• DSH Cookie 注入: 自动为请求注入 DSH 认证 Cookie，无需手动处理 DSH 登录

安装

# 通过 DSH 插件命令安装
dsh plugin --profile web add @painclown/dsh-proxy-bridge

# 或手动安装
cd ~/.dsh/profiles/web
npm install @painclown/dsh-proxy-bridge

快速开始

# 1. 启用桥（默认 3083 → 3080）
proxy_bridge enable

# 2. 设置密码
proxy_bridge config password=dsh2026

# 3. 配置 DSH Secret（从 ~/.dsh/.credentials.yaml 读取）
proxy_bridge config dshSecret=<your-secret>

# 4. 检查状态
proxy_bridge status

命令

命令 · 说明 proxy_bridge status · 查看桥状态 proxy_bridge enable · 启动桥 proxy_bridge disable · 停止桥 proxy_bridge restart · 重启桥 proxy_bridge config · 更新配置

配置示例

# 设置密码（至少 8 位）
proxy_bridge config password=dsh2026

# 配置 DSH Secret（自动注入 DSH 认证 Cookie）
proxy_bridge config dshSecret=vGIxivMEJblP1teRqVymk6sefy7wHMzxds9T0Unv6rE

# 启用自签名 TLS
proxy_bridge config tlsEnabled=true tlsHosts=["dsh.poxx.top","192.168.123.254"]

# 允许 LAN 免登录
proxy_bridge config lanPasswordless=true lanCidrs=["192.168.123.0/24"]

# 清除密码
proxy_bridge config password=

配置字段

字段 · 类型 · 默认值 · 说明 enabled · boolean · false · 是否启动监听 port · number · 3083 · 监听端口 (0.0.0.0) dshPort · number · 3080 · DSH 上游端口 password · string · '' · 密码门（空 = 无密码） cookieName · string · dsh_bridge_auth · 会话 Cookie 名 cookieMaxAgeDays · number · 30 · Cookie 有效期（天） dshSecret · string · '' · DSH browser-session secret secureCookies · boolean · false · Cookie 加 Secure 标志 tlsEnabled · boolean · false · 启用自签名 TLS (HTTPS) tlsDays · number · 365 · 自签名证书有效期（天） tlsHosts · string[] · [] · 证书 SAN 主机列表 lanCidrs · string[] · [] · 信任的 LAN CIDR lanPasswordless · boolean · false · LAN/loopback 源免登录

安全特性

密码门

• 设置密码后，所有请求必须携带有效会话 Cookie
• 登录页：/__bridge_login（GET 显示表单，POST 验证密码）
• 登出：/__bridge_logout（POST 撤销当前会话）
• 速率限制：每 IP 每 60 秒最多 5 次登录尝试
• 密码使用 scrypt 哈希存储，明文不保存

会话管理

• 每个会话有唯一 ID（16 字节随机数）
• 会话 Cookie 使用 HMAC-SHA256 签名
• 登出只撤销当前会话，不影响其他
• 修改密码递增 epoch，撤销所有会话
• 状态持久化到 ~/.dsh/proxy-bridge/state.json（0600 权限）

DSH Cookie 注入

当客户端请求不携带 dsh-auth-* Cookie 时，Bridge 使用配置的 secret 自动生成并注入，使 DSH 认证透明化。

文件结构

~/.dsh/proxy-bridge/
├── state.json          # 持久化状态（Cookie secret、密码哈希、会话 epoch、已撤销会话）
└── tls/
    ├── selfsigned.crt  # 自签名证书（tlsEnabled=true 时生成）
    └── selfsigned.key  # 私钥

nginx 配置示例

server {
    listen 11007 ssl;
    server_name dsh.poxx.top;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3083;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 86400;
    }
}

开发

# 构建
npx tsdown

# 部署到 DSH profile
rm -rf ~/.dsh/profiles/web/node_modules/@riceawa/dsh-proxy-bridge/lib/
cp -r lib/ ~/.dsh/profiles/web/node_modules/@riceawa/dsh-proxy-bridge/lib/

源码结构

src/
├── index.ts            # 插件入口，工具注册，生命周期管理
├── proxy.ts            # 核心代理逻辑（HTTP 转发 + WS 透传 + 认证）
├── auth.ts             # 源分类、会话签名、速率限制
├── state.ts            # 持久化状态（scrypt 密码、Cookie secret、会话管理）
├── tls.ts              # 自签名证书生成和加载
├── login.ts            # 登录页渲染、登出路径、速率限制处理
├── config-fields.ts    # 配置 schema
└── client/
    ├── index.ts        # 客户端入口
    └── bridge-card.tsx # React 配置卡片

与 dsh-lan-gateway 的区别

特性 · dsh-lan-gateway · dsh-proxy-bridge Same-site 检查 · 严格（Origin/Host 必须匹配） · 跳过（信任 nginx） 适用场景 · 直接暴露到 LAN · 放在 nginx 后面 WS 403 问题 · 需要配置 Origin 白名单 · 自动解决 DSH Cookie 注入 · 无 · 有 复杂度 · 较高（request policy、upstream session） · 较低

License

MIT