前言¶
在 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 目录页。
