远程访问隧道 baigei0710/dsh-remote-frp

dsh-remote-frp

用你自己的云服务器，给 DeepSeek Harness（DSH）的 Web GUI 开远程访问。

手机、平板、另一台电脑打开 https://你的域名 就能用同一份界面、同一份会话 —— 而你的 Mac 不需要公网 IP、不需要开放任何入站端口。

Remote access for the DSH Web GUI through your own cloud server. The Mac keeps listening on 127.0.0.1; a frpc LaunchAgent dials out to your server, where nginx/Caddy terminates TLS for your domain. No port forwarding, no public IP, no third-party relay.

手机/平板 ──https──> 云服务器 nginx/Caddy（你的域名 + Let's Encrypt） │ └──> 127.0.0.1:13080 ← frps 转发口，只绑回环，公网摸不到 ▲ 本机 dsh web <── frpc（本插件管理的 LaunchAgent，登录自启 / 掉线自拉）

为什么这样做

| | 局域网直连 | 第三方隧道（Cloudflare 快隧道等） | 本方案（自有服务器 + 自有域名） |
| Mac 是否需要公网 IP / 端口映射 | 否（但只能同网） | 否 | 否 |
| 地址是否固定 | — | 通常每次重启都变，要重新配对 | 固定，你的域名 |
| 流量经过谁 | — | 第三方边缘（作者运营） | 只有你自己的服务器 |
| 是否依赖境外网络 | — | 是（境内常不稳定） | 否（境内直连） |
| 备案 | — | 不需要 | 境内服务器 + 域名走 80/443 需要 |

本插件负责什么

本插件只做本机这一侧（服务器那一侧用仓库里的脚本一次装好）：

1. 生成 frpc 配置与令牌文件（$DSH_HOME/remote-frp/，令牌权限 0600），写入 macOS LaunchAgent 并加载 —— 登录自启、掉线自拉；
2. 可选：安装 caffeinate 常驻，避免 Mac 空闲睡眠把隧道睡断；
3. 可选：把域名写进信任域名受管块（connection + web-runtime 两行的 trustedHosts）—— 不写的话，非回环来源的 /api 一律 403，界面能开但拿不到数据；
4. 提供 GET /api/dsh-remote-frp/status（仅限本机）查看运行状态与日志尾部。

安装

1) 本机插件
dsh plugin --profile web add dsh-remote-frp
或者从源码装：dsh plugin --profile web add link:/path/to/dsh-remote-frp

2) 服务器那一侧（在服务器上跑，幂等） scp scripts/setup-server.sh root@<你的服务器>:/tmp/ ssh root@<你的服务器> 'bash /tmp/setup-server.sh --domain dsh.example.com --email you@example.com'

服务器脚本会：装 frps（下载并校验官方 sha256）+ Caddy/nginx（取不到 Caddy 源时自动回退 nginx）、签发 Let's Encrypt 证书、把 TLS 入口反代到 127.0.0.1:13080，并且把 frps 的转发口固定在回环上（proxyBindAddr = "127.0.0.1"，allowPorts 只放行这一个端口）。

装完脚本会打印 frp 令牌（也存在服务器 /etc/frp/token）。回到设置页填进插件：

| 字段 | 说明 |
| server | 你的服务器地址（IP 或域名） |
| serverPort | frps 控制端口，默认 7000 |
| remotePort | 服务器侧转发端口，默认 13080（必须只绑回环） |
| localPort | 本机 dsh web 端口，0 = 自动取当前端口 |
| token | 上面那串令牌（按密文存储；与服务器 /etc/frp/token 一致） |
| trustedHosts | 形如 ['dsh.example.com']：写入信任域名受管块（写前会备份 profile 配置） |
| autoStart | 装 LaunchAgent（默认开） |
| keepAwake | 装 caffeinate 常驻（默认关） |

设置页由官方设置界面按 schema 自动渲染，本插件不带客户端半边。

状态与排查

仅限本机访问；从外面访问会被 403
curl -s http://127.0.0.1:3080/api/dsh-remote-frp/status | python3 -m json.tool

完整链路体检（会把域名、frp、TLS、控制面围栏都查一遍） bash scripts/verify.sh --domain dsh.example.com --ssh root@<你的服务器>

日志：

tail -f ~/.dsh/remote-frp/frpc.log # 隧道日志（看到 start proxy success 即为通） launchctl print gui/$(id -u)/com.local.dsh-remote-frp

常见问题

| 现象 | 原因 / 处理 |
| 公网打开是 502 Bad Gateway | Mac 没在服务（睡眠 / 已关机 / frpc 没跑）。看 frpc.log 与 launchctl print；keepAwake 打开 |
| 界面能开但没有数据、会话列表空 | 域名没进信任名单。配 trustedHosts 后重启一次 dsh web（部分插件在启动时采样白名单） |
| POST /api/session/create 返回 405 | 你打开的是旧版缓存的页面（旧代码把请求改写到已不存在的接口）。彻底关掉该标签页，或删掉该站点的网站数据（含 service worker）再打开 |
| 某个插件面板 403 | 同上，属于信任名单问题；trustedHosts + 重启 dsh web 后恢复 |
| 证书签发失败 | A 记录没生效 / 安全组没放行 80 / 域名未备案。可改用 --tls manual 走自有证书 |
| 突然连不上，日志没变 | 你的出口 IP 漂了（安全组按 IP 白名单时）→ 用云控制台的 VNC 进去改安全组 |
| 从本机 ssh 连不上服务器 | 本机代理（Clash TUN / fake-IP）会掐断 SSH 与任意 TCP：给服务器 IP 加直连规则，或临时关代理 |

安全模型

- frp 令牌：frps 只认令牌；转发口只绑回环，公网即使扫到也进不来。
- 只有 TLS 入口对外开放：80（证书验证 + 跳转）、443。7000 建议在安全组里限制来源 IP。
- 配对/密码是可选的额外一层：本插件不提供鉴权层。如果你把 DSH 暴露到公网，强烈建议至少加一层入口鉴权（nginx auth_basic 或自建登录页 + limit_req 限速）。
- 能进到界面 = 完全控制权：DSH 的界面等同于你 Mac 上的 shell。别把访问凭据发给别人。
- $DSH_HOME/remote-frp/ 内的令牌是明文（权限 0600）；服务器上的 /etc/frp/token 同样是明文（权限 600）。

卸载 / 回滚

launchctl bootout gui/$(id -u)/com.local.dsh-remote-frp
rm -f ~/Library/LaunchAgents/com.local.dsh-remote-frp.plist
rm -rf ~/.dsh/remote-frp
keepAwake 同理：把 Label 换成 com.local.dsh-remote-frp-awake trustedHosts：把插件配置里的 trustedHosts 清空，受管块会被自动移除（有 .bak-remote-frp 备份）服务器：systemctl disable --now frps caddy（或 nginx），删 /etc/frp 与站点配置

开发

node test/smoke.mjs # 冒烟测试：schema 默认值 / volatile 解包 / toml / plist / 受管块（只用临时目录）

目录：

lib/index.js 宿主半边（唯一的运行时代码） cordis.patch.yml bundle patch（插入插件行） scripts/setup-server.sh 服务器一键安装（frps + TLS 入口 + 证书） scripts/setup-mac.sh 不用插件时的手动安装（等价的 CLI 版本） scripts/setup-awake.sh 保持 Mac 不睡（可独立使用） scripts/verify.sh 端到端体检 test/smoke.mjs 冒烟测试

License

MIT