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