前言¶
DeepSeek Harness 的 Web 界面默認只在本機或局域網可訪問。若要在手機或外網繼續對話、改配置，常見做法是單獨開 SakuraFrp 官方啓動器（SakuraLauncher），再手動對齊 frpc、隧道本地端口與 DSH 監聽端口。端口不一致時，隧道顯示已連接但訪問返回 502，排查成本高。
dsh-sakurafrp 由社區維護者 MentholTea 發佈，分類爲聯網工具，在 DSH 設置頁與側邊欄集中完成 SakuraFrp 隧道管理、frpc 生命週期與公網訪問前的密碼門，定位是替代 SakuraLauncher、與 DSH 同進程協作。倉庫 MentholTea/dsh-sakurafrp 當前 npm 版本爲 2.3.0，MIT 許可證；README 註明代碼與文檔在與 DeepSeek Harness 會話中迭代生成，作者實測環境爲 Windows + WSL2，使用前建議自行審閱源碼。
這是什麼¶
一句話：DeepSeek Harness 內建的內網穿透面板——託管 SakuraFrp 的 frpc，在界面裏選隧道、對齊端口、看流量，並在公網入口加一層密碼門後再反代到 DSH WebServer。
入口有兩處：設置 → 內網穿透 (SakuraFrp)；左側邊欄 內網穿透，帶三色狀態點（已連接 / 未連接 / 故障）與啓停開關，摺疊爲圖標欄時狀態點仍在圖標右上角。
核心功能¶
下列能力均來自項目 README 與 package.json 說明，可按倉庫內 npm test（23 個套件、643 項離線斷言）自行復核網關鑑權等邏輯。
frpc 與隧道
- DSH 啓動時拉起 frpc、退出時停止；崩潰後指數退避重連（1s 起，封頂 60s）。
- 訪問密鑰經
NATFRP_TOKEN環境變量傳遞，不寫入 argv，降低進程列表泄漏風險。 - 通過 SakuraFrp API v4 拉隧道列表（含節點名），下拉切換；選隧道後本機端口可自動跟隨隧道配置。
- 本地無隧道時可「新建」：固定 TCP，表單端口同時作爲本機端口，遠程端口由官方分配；節點列表展示負載（空閒 / 一般 / 擁擠 / 滿載），滿載節點不可選。
autoAlign/adoptTunnelPort：改本機端口前先檢測綁定，成功則同步更新 SakuraFrp 面板上該隧道的local_port，減少「隧道連上但端口不對」的 502。- 30 秒內斷線不少於 6 次時提示疑似互踢（例如其它機器或 SakuraLauncher 佔用同一條隧道）。
流量與界面
- 展示本日已用流量、剩餘流量及基於
data_plans總量的剩餘百分比（綠 / 橙 / 紅三檔）。 - frpc 日誌默認展開，約每 2 秒刷新。
公網安全與反代
- 未設置公網密碼時外網請求一律拒絕；README 建議 20 位以上隨機密碼。密碼門使用 HMAC 簽名 cookie、常量時間比較，按 IP 失敗 5 次鎖定 60 秒。
- 網關做 Host 圍欄反代，改寫 Host / Origin / Referer 等，透傳 WebSocket，並注入非安全上下文所需的 polyfill；首次 HTML 導航可自動補 DSH 的 launch token（
ctx.connection.authenticatedUrl()）。 - 管理路由
/natfrp/*需密碼門 cookie；本機設置頁走 DSH webServer 同名路由，不經過網關，本機操作無需公網密碼。
架構概覽
Web 設備 → xxx.nyat.app:端口 → SakuraFrp 節點 → frpc(本插件託管)
→ 127.0.0.1:<gatePort> 網關
├─ /natfrp/* 管理路由（需密碼門 cookie）
├─ 密碼門（HMAC cookie / ?gate=）
└─ Host 圍欄反代 + WS 透傳
→ 127.0.0.1:<dshPort> DSH WebServer
安裝與啓用¶
插件以當前 DSH 進程權限運行；安裝前請閱讀源碼與 MIT「按原樣」聲明。frpc 二進制不包含在 npm 包內，裝完插件後通常還需在設置頁「一鍵安裝」frpc。
方式 A：從 npm 安裝（推薦）
dsh plugin --profile desktop add dsh-sakurafrp -w
# web / CLI 場景把 --profile 換成你的 profile 名，例如 --profile web
裝完後確認 dsh.profile.bundles 中包含 dsh-sakurafrp，然後重啓 DSH。
方式 A2：從 Release tarball 安裝
dsh plugin --profile desktop add https://github.com/MentholTea/dsh-sakurafrp/releases/latest/download/dsh-sakurafrp.tgz -w
任一條失敗可換另一條。重啓後若提示未安裝 frpc，在設置頁點「一鍵安裝」；默認路徑爲 ~/.dsh/dsh-sakurafrp/frpc-standalone(.exe)，frpc -V 輸出應含 sakura。
典型用法：四步逐步解鎖¶
第一次使用可按界面順序完成，上一步未完成則下一步不出現。
- 訪問密鑰：在 SakuraFrp 面板 → 用戶信息 → 查看訪問密鑰，粘貼到設置頁 ① 訪問密鑰 並保存。
- 隧道：出現 ② 隧道 後下拉選擇已有隧道，或點「新建」選節點與端口。
- 本機端口：出現 ③ 本機端口 後填寫（新裝爲空，需自行填寫並檢測可用性）；選已有隧道時會自動填入。
- 訪問密碼：端口可用後出現 ④ 訪問密碼；保存後打開頂部開關，從外網訪問隧道公網地址並輸入密碼進入完整 DSH 界面。
插件默認 關閉（enabled 默認爲 false），本機端口默認未填，避免安裝後無意把 DSH 暴露到公網。README 強調：儘量綁定子域名走 HTTPS；直接用默認 xxx.nyat.app 可能遇到證書警告，部分瀏覽器繼續訪問後白屏，綁定方法見倉庫 README「證書警告與白屏問題」一節。
常用配置項（cordis.patch.yml → config）包括：
| 鍵 | 默認 | 說明 |
|---|---|---|
enabled |
false |
是否啓用插件 |
frpcPath |
~/.dsh/dsh-sakurafrp/frpc-standalone(.exe) |
frpc 路徑 |
gatePort |
— | 網關端口，與隧道本地端口對齊；留空則網關不監聽 |
gatePassword |
— | 公網密碼（也可經設置頁寫入獨立文件，不寫入 state.json） |
autoAlign |
true |
啓動前自動把隧道本地端口改成 gatePort |
適用場景與注意¶
適合誰
- 已使用或打算使用 SakuraFrp，希望少開一個 SakuraLauncher，在 DSH 內完成 frpc、隧道與端口同步的用戶。
- 需要在外網訪問 DSH Web 界面，並願意在公網入口設置強密碼與 HTTPS 子域名的場景。
注意
- 插件與 DSH 同進程；網關若監聽
0.0.0.0會在局域網繞過密碼門，默認應使用127.0.0.1（見gateHost說明）。 - frpc 版本更新在面板內手動「檢查更新」，不會在後臺自動拉取清單。
- 社區插件目錄 skillhub.cn 上的 dsh-sakurafrp 頁 與 GitHub 倉庫相互引用，與 DeepSeek / 幻方無官方從屬關係；生態上 DSH 主張「一切皆插件」，目錄站爲獨立社區站點。
結尾¶
dsh-sakurafrp 把 SakuraFrp 的 frpc 託管、隧道與端口對齊、流量展示和公網密碼門收進 DSH 設置頁與側邊欄，減少啓動器與 DSH 端口不一致帶來的運維摩擦。安裝命令以 README 爲準，細節與 API 列表見 GitHub：MentholTea/dsh-sakurafrp，插件索引見 SkillHub 目錄頁。
