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