前言¶
DeepSeek Harness（DSH）允许在本地运行智能体工作台。通常我们通过局域网内的浏览器访问其 Web GUI。若要在外网访问，没有公网 IP 或开放端口映射很不方便。
下面介绍的 dsh-remote-frp 插件通过 frp 反向隧道方案解决这一问题：利用你自己的云服务器作为中转，Mac 本机只需监听 127.0.0.1，无需公网 IP，也无需开放入站端口。
插件介绍¶
插件名：dsh-remote-frp
维护者：baigei0710
许可证：MIT
它负责 Mac 本机这一侧的配置管理。核心功能包括：
* 生成 frpc 配置与令牌文件（位于 $DSH_HOME/remote-frp/，权限 0600）。
* 写入 macOS LaunchAgent，实现登录自启与掉线自拉。
* 提供 GET /api/dsh-remote-frp/status 接口（仅限本机访问）查看状态与日志。
* 可选安装 caffeinate 常驻，避免 Mac 空闲睡眠断开隧道。
* 可选将域名写入受管块的 trustedHosts。
安装与配置¶
1. 安装本机插件¶
在 DSH 设置页执行：
dsh plugin --profile web add dsh-remote-frp
2. 配置服务器¶
服务器端需要安装 frps 和 Web 服务器（支持 Caddy 或 Nginx）。
将服务器安装脚本上传到服务器并执行：
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。
* 签发 Let’s Encrypt 证书。
* 配置 TLS 反向代理至 127.0.0.1:13080。
* 打印 frp 令牌。
3. 填写配置¶
回到 DSH 设置页，根据脚本输出填写以下字段：
| 字段 | 说明 | 默认值 |
|---|---|---|
server |
服务器地址（IP 或域名） | - |
serverPort |
frps 控制端口 | 7000 |
remotePort |
服务器侧转发端口（仅绑回环） | 13080 |
localPort |
本机 DSH Web 端口 | 0（自动取当前） |
token |
frp 令牌（明文存储，权限 0600） | - |
trustedHosts |
信任域名列表（JSON 数组） | - |
autoStart |
是否安装 LaunchAgent | 开 |
keepAwake |
是否安装 caffeinate 避免睡眠 | 关 |
使用与排查¶
检查状态¶
仅限本机访问，用于检查隧道状态：
curl -s http://127.0.0.1:3080/api/dsh-remote-frp/status
查看日志¶
查看 frpc 隧道日志：
tail -f ~/.dsh/remote-frp/frpc.log
查看 LaunchAgent 状态：
launchctl print gui/$(id -u)/com.local.dsh-remote-frp
端到端体检¶
服务器端提供校验脚本，用于检查域名、frp、TLS 及安全组配置：
bash scripts/verify.sh --domain dsh.example.com --ssh root@<你的服务器>
注意事项¶
- 职责范围：本插件仅管理 Mac 本机一侧。服务器那一侧需运行仓库中的安装脚本。
- 受管块与 API：若不将域名写入
trustedHosts，非回环来源的/api请求会返回 403，界面能打开但无法获取数据。 - 安全模型：
frp令牌和配置文件权限为0600，服务器/etc/frp/token权限为0600。- TLS 入口仅绑回环（
127.0.0.1），公网即使扫描到也无法直接访问。 - 建议在服务器端入口增加
auth_basic或其他鉴权层。
- 卸载：
- 停止并移除 LaunchAgent。
- 删除
~/.dsh/remote-frp目录。 - 服务器端停止
frps和 Web 服务，删除/etc/frp目录。
