DSH bundle · MIT · zero runtime dependencies DSH 插件 · MIT · 零运行时依赖

Your DSH Web GUI,
on your own domain.
把本机的 DSH Web GUI,
放到你自己的域名上。

dsh-frp runs an frpc tunnel to the frps you already own and puts a login gateway in front of it. DSH's signed cookie never reaches the browser — visitors only ever hold the gateway's own session. dsh-frp 在你自己的 frps 上开一条 frpc 隧道,并在前面加一道登录网关。DSH 的签名 cookie 永远不会到浏览器,访客手里只有网关自己签发的会话。

dsh plugin --profile <profile> add github:trymesoft/dsh-frp
Set it up开始配置 Read the docs阅读文档
◆ DSH 0.2.2-rc.5 ◆ Node ≥ 20 ◆ frps 0.64–0.80 ◆ MIT
A server reaches this machine's DSH Web GUI through an frp tunnel and an authenticated gateway
The problem问题所在

A tunnel alone is not an entrance. 光有隧道,算不上一个入口。

Point a bare frpc at the DSH Web GUI and three things break, in order. 把一个裸 frpc 直接对着 DSH Web GUI,会依次断在三件事上。

01

DSH refuses the requestDSH 会拒掉这个请求

The GUI keeps its own fence: a loopback host and a matching origin. A plain tunnel rewrites Host, so the page 404s — and if you bend it until DSH accepts, everything downstream inherits the bend. GUI 有一道自己的围栏:只认 loopback 的 Host 和同源 Origin。裸隧道会把 Host 改写掉,于是 404;就算你把它掰到 DSH 能接受,下游也全都继承了这个弯。

02

The cookie is the machinecookie 就是这台机器

DSH hands the browser a long-lived signed cookie. Publish that cookie to the internet and you have published full control of this machine's agent — including the panel that manages the tunnel. DSH 发给浏览器的是一枚长期签名 cookie。把它放到公网上,等于把这台机器上 agent 的完整控制权放上去,包括管理隧道的那块面板本身。

03

Access has to be revocable权限必须能撤销

The gateway signs its own sessions. Changing the public password bumps an epoch in the credential store, and every signed-in device is out on its next request. Kill the gateway and frpc dies with it. 网关自己签发会话。改一次密码就抬高 credential store 里的 epoch,所有已登录设备在下一个请求就失效。网关被杀掉,frpc 跟着一起死。

Under the hood实际跑起来

Four moves, one of them invisible. 四步,其中一步你看不见。

1

A loopback gateway starts先起来一个 loopback 网关

On an OS-assigned port, bound to 127.0.0.1. It exchanges DSH's launch token for a signed cookie and keeps that cookie in Host process memory — never in a file, never in a header to the browser. 端口由系统分配,只绑 127.0.0.1。它用 DSH 的 launch token 换一枚签名 cookie,这枚 cookie 只放在 Host 进程内存里 —— 不落盘,也不进浏览器的任何头。

2

The plugin writes frpc.toml and supervises frpc插件生成 frpc.toml 并看护 frpc

Random proxy name per start, random admin credentials on loopback, mode 0600. Proxy state comes from frpc's admin API, not from parsing stdout. Restarts back off instead of hammering. 每次启动用随机代理名,admin API 用随机凭据、只听 loopback,文件权限 0600。代理状态从 frpc 的 admin API 读,不靠解析 stdout。重启是退避的,不会疯狂重试。

3

A visitor arrives访客进来

nginx → frps → frpc → gateway. The gateway asks for its own login first, then normalizes Host, Cookie and Origin into the shape the DSH fence accepts. WebSocket upgrades go through the same check. nginx → frps → frpc → 网关。网关先要它自己的登录,然后把 Host、Cookie、Origin 规整成 DSH 围栏接受的样子。WebSocket 升级走同一道检查。

4

The way back is scrubbed回程要擦干净

Set-Cookie is stripped, Location is rewritten to the public origin, hop-by-hop headers are dropped. If the gateway errors or stops, frpc is killed at once — a live tunnel must never outlive its authentication layer. Set-Cookie 一律剥掉,Location 改写成公网 origin,逐跳头丢弃。网关一出错或停止就立刻杀掉 frpc —— 一条活着的隧道不能活得比它的认证层更久。

Security安全模型

What the gateway buys you. 这道网关具体买到了什么。

Concrete behaviours, not adjectives. Each one is enforced in code and covered by the test suite. 具体行为,不是形容词。每一条都在代码里强制,并有测试覆盖。

  • One door. Every request and WebSocket upgrade needs a gateway session; unknown Host headers get 404 before authentication, so the loopback port is not a second entrance. 只有一个门。每个请求和 WebSocket 升级都要过网关会话;未知 Host 在认证之前就 404,loopback 端口不是第二个入口。
  • No cookie leakage. Set-Cookie and Set-Cookie2 are stripped from every proxied response. The browser never sees a DSH cookie. cookie 不外泄。所有被代理的响应都剥掉 Set-Cookie 和 Set-Cookie2,浏览器永远看不到 DSH 的 cookie。
  • Sessions you can burn. HMAC over {exp, epoch}; HttpOnly, SameSite=Strict, host-only, and Secure + __Host- when the entrance is HTTPS. 会话可以一次性烧掉。对 {exp, epoch} 做 HMAC;HttpOnly、SameSite=Strict、host-only,HTTPS 下带 Secure 和 __Host- 前缀。
  • Login throttling that works here. Constant-time comparison plus a global 1s→30s failure delay. Deliberately not per-IP: in this topology the gateway's TCP peer is always 127.0.0.1. 适合这个拓扑的登录限速。常量时间比较,加一个 1s→30s 的全局失败延迟。故意不做按 IP:这个拓扑上网关的 TCP 对端永远是 127.0.0.1。
  • Verified binaries. The managed download checks the archive against SHA-256 pinned in the source. A version without a pinned hash needs an explicit consent prompt. 二进制经过校验。托管下载会按源码里钉死的 SHA-256 校验压缩包;没有钉死哈希的版本必须显式确认才能下载。
  • Header hygiene. Hop-by-hop headers dropped; a message carrying both Transfer-Encoding and Content-Length is rejected; the visitor IP comes from the trusted XFF chain. 头部卫生。丢弃逐跳头;同时带 Transfer-Encoding 和 Content-Length 的消息直接拒绝;访客 IP 从可信的 XFF 链里取。
  • Nothing sideways. No agent tools registered, no telemetry, no session data touched. Peers: your frps, the local GUI, and — only when you ask for a download — the frp release URL. 不横着长。不注册 agent 工具、不做遥测、不碰会话数据。对端只有:你的 frps、本地 GUI,以及你主动点下载时的 frp 发布地址。
  • Secrets stay out of config. The frps token, the public password, the signing secret and the epoch live in the DSH credential store — never in cordis.patch.yml or the status payload. 密钥不进配置文件。frps token、公网密码、签名密钥和 epoch 都存在 DSH 的 credential store —— 不进 cordis.patch.yml,也不进状态响应。
A working tunnel is remote control. The public entrance has the same authority as the DSH agent on this machine — including this plugin's panel, which can start, stop and reconfigure the tunnel. Treat the password like an SSH key, and remember this is a single-user view: no per-user isolation. 一条能用的隧道就是远程控制。公网入口的权限等于这台机器上的 DSH agent —— 也包括这个插件的面板,它能启停和重配隧道。请把密码当 SSH 私钥对待,同时记住这是单用户视图,没有按用户的隔离。
Honest edges边界说清楚

Where it stops. 它不管的那部分。

If one of these is a requirement, this is the wrong tool — better to know now. 下面哪条是你的硬需求,那就是选错了工具 —— 现在知道比装完再知道好。

—No TLS termination. The gateway speaks plain HTTP on loopback; HTTPS is your nginx's job, and the plugin cannot verify that it happened.不做 TLS 终止。网关在 loopback 上说纯 HTTP;HTTPS 是你 nginx 的事,插件也无法验证它真的做了。
—One target: this DSH GUI. No multi-proxy, multi-domain, or per-device management.只有一个目标:这台 DSH GUI。不做多代理、多域名、按设备管理。
—No multi-user accounts, no per-user DSH sessions, no audit log, no MFA.没有多账号、没有按用户的 DSH 会话、没有审计日志,也没有 MFA。
—Automatic binary download handles tar.gz only; Windows users bring their own frpc.exe.自动下载只处理 tar.gz;Windows 用户自己放一个 frpc.exe。
Setup上手

Up in three moves. 三步就能跑起来。

01Turn on token auth in frps在 frps 上打开 token 认证

The plugin routes by customDomains, so subdomainHost is unnecessary. Keep vhostHTTPPort reachable only from nginx. 插件按 customDomains 路由,所以不用配 subdomainHost。vhostHTTPPort 只对 nginx 和本机开放。

bindPort = 17000
vhostHTTPPort = 17002

auth.method = "token"
auth.token = "<a long random token>"

02Put TLS in front of the vhost port在 vhost 端口前面做 TLS

The defaults 404 and drop WebSockets: without an explicit Host, nginx rewrites it to $proxy_host, and frps routes by Host. 默认配置会 404 且丢 WebSocket:不显式设 Host,nginx 会把它改写成 $proxy_host,而 frps 正是按 Host 路由的。

location / {
  proxy_pass http://127.0.0.1:17002;
  proxy_http_version 1.1;
  # required: frps routes by Host
  proxy_set_header Host $host;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection $connection_upgrade;
  # keep idle WebSockets alive
  proxy_read_timeout 3600s;
}

03Fill the panel and start the tunnel在面板里填好并启动隧道

Open Plugins → frp tunnel: server, port, domain, public URL, then the auth token. Get a binary — download it (SHA-256 checked) or point at your own. Set a 12+ character password and press Start tunnel. Failures name their cause instead of sitting on “Starting”. 打开 插件 → frp tunnel:填服务器、端口、域名、公网地址,再保存 auth token。取一个二进制 —— 自动下载(已校验 SHA-256)或指向你自己的。设一个 12 位以上的密码,点 启动隧道。失败会直接说原因,不会卡在“正在启动”。

# install into an existing DSH profile
dsh plugin --profile <profile> add github:trymesoft/dsh-frp