前言¶
在 DeepSeek Harness（DSH）裏跑前端 dev server、臨時 Web 服務或需要 HMR 的場景時，常見做法是手動改 Cloudflare 隧道配置、寫腳本登記端口，或把整臺機器暴露出去。步驟多、容易和 agent 工作流脫節，註銷不及時還會留下公網入口。
下面介紹社區插件 dsh-tunnel-preview（維護者 SOVLOOKUP，分類：聯網工具）。它複用已有 Cloudflare 命名隧道，把容器內正在監聽的端口登記爲 https://<端口>.<你的域名>，用完可註銷；不新增對外端口，也不依賴人工改隧道配置文件。
這是什麼¶
dsh-tunnel-preview 是 DSH 插件，當前版本 0.2.0，MIT 許可證，倉庫：SOVLOOKUP/dsh-tunnel-preview。SkillHub 目錄頁：dsh-tunnel-preview（社區目錄，與 DeepSeek / 幻方無官方從屬關係）。
一句話定位：給 agent 一把「開/關公網入口」的鑰匙——登記監聽端口即得公網鏈接，註銷後公網立刻不可達。
核心機制¶
插件做三件事，彼此配合：
- 反代：默認在
127.0.0.1:9999監聽（配置項listen可改），與隧道 config 的 catch-all 對齊；按 Host 中的端口號轉發到127.0.0.1:<端口>。HTTP 與 WebSocket（含 HMR）同路徑，公網鏈接上熱更新可用。 - 登記表：僅登記過的端口會被轉發；狀態落在
stateDir/previews.json，宿主重啓不丟。未登記返回 403，註銷後恢復 403。 - 閘門：公網 URL 需帶
?dp_token=<token>驗證一次，通過後寫入域級 Cookie，同域下各端口子域後續可免 token。容器內直連127.0.0.1不受此限。
預覽地址形如 https://<端口>.<domain>，只支持一級子域（例如 5173.example.com；二級子域需額外 SSL 方案，見 README「已知取捨」）。
Agent 工具與 REST¶
| 工具 | 作用 |
|---|---|
preview_register({ port, label? }) |
建 DNS（API 優先，否則 CLI）並寫入登記表，返回可打開鏈接 |
preview_unregister({ port }) |
移出登記表，公網立刻 403；已綁定 API token 時可刪 DNS |
preview_list() |
列出登記項：端口、公網地址、本地是否仍在監聽 |
登記前本地服務必須已在 LISTEN（插件讀 /proc/net/tcp{,6}）；否則鏈接會 502。順序應是：先起服務，再登記。
DSH Web 還擴展 REST：
GET /api/tunnel-preview/servicesPOST /api/tunnel-preview/register（body：{ port, label }）POST /api/tunnel-preview/unregister（body：{ port }）
右側欄「服務」標籤與會話頂欄「暴露的服務」入口提供卡片列表、監聽狀態、新標籤打開、側欄預覽、複製鏈接、註銷與快速暴露候選端口等操作（細節見 README GUI 一節）。
配置要點¶
配置定義在 cordis.patch.yml，均有默認值。常用項如下：
| 鍵 | 默認 | 說明 |
|---|---|---|
listen |
9999 |
反代監聽，須與隧道 catch-all 一致 |
domain |
example.com |
子域後綴；設置頁「公網域名」可改，保存立即生效 |
stateDir |
$HOME/devpreview |
token、previews.json 目錄 |
tunnelName |
dsh-dev |
cloudflared tunnel route dns 使用的隧道名 |
cloudflared |
$HOME/bin/cloudflared |
可執行文件路徑 |
tunnelConfig |
$HOME/.cloudflared/config.yml |
隧道配置 |
manageTunnel |
true |
是否託管 cloudflared 進程 |
manageDns |
true |
登記時是否自動建 CNAME |
cloudflareApiToken |
空 | 粘貼即綁定；綁定後可 API 建刪 DNS |
dnsOnUnregister |
delete |
註銷時刪或留 DNS（delete / keep） |
在 DSH 側欄 → 插件 → tunnel-preview 填寫「公網域名」（不帶 https:// 與端口），保存即可。若 profile 的 cordis.patch.yml 中對 tunnel-preview 寫了整段 config，會以 profile 爲初始覆蓋，之後仍以設置頁保存爲準。
綁定 Cloudflare API Token 時，設置頁提供「直達 Cloudflare 生成 Token」鏈接（預填 Zone DNS Edit 與 Zone Read）。保存後熱更新，不重掛插件；preview_list() 頂部會顯示綁定狀態或失敗原因。未綁定 token 時建記錄可走 cloudflared tunnel route dns，但註銷時默認刪不掉 DNS 記錄（公網是否通仍由登記表決定）。
安裝與啓用¶
資料中的 SkillHub 目錄標識插件爲 SOVLOOKUP/dsh-tunnel-preview。請在 DSH 插件管理或目錄頁給出的方式安裝，安裝前閱讀倉庫源碼與 MIT 許可證；插件以當前 DSH 進程權限運行，涉及公網入口與 Cloudflare 憑據，安裝前應自行評估風險。
若曾使用舊版 /workspace/devpreview/ 手寫腳本，裝插件前先停舊棧，避免 9999 端口衝突：
/workspace/devpreview/start.sh stop
之後反代與 cloudflared 由插件託管；舊 .token 可繼續複用，已發出的鏈接在遷移說明下仍可沿用。
典型用法¶
- 在容器內啓動 dev server（例如監聽
3000）。 - 讓 agent 調用
preview_register({ port: 3000, label: "web" })，或經 REST / GUI 登記。 - 用返回鏈接訪問；首次在瀏覽器帶
?dp_token=<token>（token 位於stateDir）。 - 結束後
preview_unregister({ port: 3000 })，公網入口關閉。
倉庫自測命令：
node --check index.js && node --test test/
適用場景與注意¶
適合：已有 Cloudflare 命名隧道、需要在 DSH/agent 工作流裏臨時暴露本地 HTTP/WebSocket 服務並可控註銷的開發者。
務必知曉：
- 這是真實公網 HTTPS 入口；插件 token 主要防「猜鏈接」，若要限制陌生人訪問，應在 Cloudflare Access 等層面加固（README「已知取捨」）。
- 容器內若啓用
HTTPS_PROXY且代理攔截api.cloudflare.com，插件會對 Cloudflare API 嘗試直連重試；DNS 建刪失敗不會阻塞登記表更新，但 GUI/工具輸出會說明記錄是否未刪掉。 - 禁止登記的端口見配置
deny（含 VNC/調試端口等）。
結尾¶
dsh-tunnel-preview 把「登記端口 → 公網 HTTPS → 註銷」收成插件與 agent 工具，並附帶 DSH Web 服務側欄，適合在 Harness 裏做可審計的臨時預覽。進一步瞭解配置與 Cloudflare 綁定步驟，見 GitHub README；安裝入口見 SkillHub 目錄頁。
