前言¶
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目錄。
