dsh-mesh-access 1.0.4 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 更新日志
 
+## 1.2.0 — 面板里就能填服务器信息
+
+1.1.0 仍然要求你先去跑脚本写 `frpc.toml`，面板只是个看板。现在不用了：
+
+- 「公网隧道」卡新增**改配置 / 填服务器信息**：服务器地址、`bindPort`、`remotePort`、本地端口、域名、token 直接在面板里填，保存后自动启动；
+- token 留空表示沿用 `frpc.toml` 里已有的那个（不用每次重填，也不会把密钥显示在页面上）；
+- 填了域名，复制的地址就是 **`https://域名/?token=…`**（域名记在同目录的 `dsh-mesh-access.json` 侧车里，`frpc.toml` 保持标准 frp 格式）；
+- 输入校验：地址只认 IP/域名、端口必须 1–65535、域名格式检查，错误直接在面板上说明；
+- 面板写出来的 `frpc.toml` 和 `tools/frpc-setup.sh` 生成的是同一种文件，先跑脚本后来用面板改也不会打架。
+
+仍然要**手动做一次**的事（脚本和面板都替你做不了）：DNS 里给域名加 A 记录指向服务器、云安全组放行端口、
+在服务器上跑一次 `tools/frps-setup.sh`（它会顺带把证书和 Basic 认证配好）。
+
+## 1.1.1 — 面板把「外部进程」说清楚
+
+1.1.0 里如果 frpc 是你自己的 systemd 单元在跑，面板会同时显示「frpc 未运行」和「公网可达」，看着自相矛盾。改成：
+
+- 第一颗状态改成三态：`frpc 运行中（本插件）` / `frpc 运行中（外部进程）` / `frpc 未运行`；
+- 「停止」按钮在外部进程时禁用并给出提示，告诉你用 `systemctl --user stop dsh-frpc` 停；
+- 说明文字写清为什么不让重复启动（两个 frpc 抢同一个 `remotePort`）。
+
+功能没有变化。
+
+## 1.1.0 — 把「自己的 VPS 隧道」做进面板
+
+组网这条路在某些网络下注定要中继（校园网只能一台设备在线、手机蜂窝 CGNAT），TCP 中继 RTT 800–990 ms，长连接撑不住。所以面板多了一张「公网隧道」卡片，用你自己的服务器 + frp 走第二条路：
+
+- 新增 `GET/POST /api/dsh-mesh-access/tunnel`：读 `~/.config/frp/frpc.toml`（`serverAddr` / `serverPort` / `localPort` / `remotePort`），面板显示公网地址与连通性；
+- 「启动隧道」在本进程内 `spawn frpc -c frpc.toml`，等到 `start proxy success` 才算成功（8 秒超时，失败把 frpc 的日志贴到面板上）；
+- 「公网可达」是**真连一次**面板域名/端口再判断，不是看进程在不在；
+- 新增配置 `frpcBin` / `frpcConfig` / `tunnelDomain`（有域名就走 `https://域名/`，没有就退回 `http://IP:remotePort/`）；
+- 新增 `tools/frps-setup.sh`：在你**自己的**服务器上一把装好 frps（systemd、随机 token、防火墙、可选 nginx + Let's Encrypt + Basic 认证），结尾打印本机要用的命令；
+- 新增 `tools/frpc-setup.sh`：在本机装 frpc、写 `frpc.toml`、写（不 enable）用户单元，缺参数时交互提问；
+- 新增 `docs/VPS.md`（给人看）与 `docs/AI-SETUP.md`（给 AI 执行：硬规则、运行顺序、四条验证、故障表）；
+- 面板文案改成「用你自己的服务器」，并在检测到公网可达但 frpc 不是本进程拉起时禁用启动按钮（避免两个 frpc 抢同一个 remotePort）。
+
+配套：`README` 增「用你自己的服务器（可选）」，`docker`/`systemd` 不是必需项。
+
 ## 1.0.4 — 把「性能与限制」写清楚
 
 功能不变。补了一节实测表格与判断方法，用来回答「卡是不是插件的问题」：

package/README.en.md

@@ -49,6 +49,7 @@ Restart the profile. A **组网访问 / Mesh access** entry appears in the left
 | 当前状态 | proxy state, DSH's own listen port, how many mesh interfaces were found |
 | 动作 | open the mesh port / close it / refresh |
 | 手机地址 | the URL to open on the phone, with a copy button |
+| Public tunnel (optional) | use **your own** server as a public entry point: start/stop frpc, show the public URL, probe it for real |
 | 第一次用星空组网？ | the referral sign-up link and the member-account rule |
 
 ## HTTP surface
@@ -142,6 +143,30 @@ mesh works — a phone or tablet, another Windows/macOS/Linux laptop, a NAS with
 Requirements are only: same mesh, a route to the mesh IP, and a browser. **Nothing** has to be
 installed on the other device, and no SSH is involved.
 
+## Use your own server (optional)
+
+The mesh path is fine on a LAN or a P2P link, but it can fall back to a public relay: measured RTT 800-990 ms (worst
+3.7 s), and long-lived connections get dropped by heartbeat timeouts — on a phone that looks like a page stuck on
+"reconnecting". If you have your own server with a public IP, point the tunnel at it: usually 30-60 ms.
+
+**We do not provide a server, and you do not use somebody else's.** It is your box, your credentials. Two scripts ship
+in this repo:
+
+```bash
+# 1) on your server (root): install frps
+sudo ./tools/frps-setup.sh --port 7000 --http-port 21081
+#    with HTTPS: add --domain dsh.example.com --email you@example.com
+
+# 2) on the machine running DSH: install frpc and point it at that server
+./tools/frpc-setup.sh --server <server-ip> --token <token printed in step 1> --remote-port 21081
+```
+
+Then open "组网访问" → "公网隧道" → start. Step 1 prints the token and the exact step-2 command for you.
+The cloud security group must allow **7000/tcp** and **21081/tcp** — only you can do that.
+
+Full guide (prerequisites, domain/TLS/Basic auth, troubleshooting, uninstall): **[docs/VPS.md](docs/VPS.md)**.
+To let an AI do the setup, hand it **[docs/AI-SETUP.md](docs/AI-SETUP.md)**.
+
 ## Companion
 
 The shell-script edition (Linux/macOS/Windows launchers that start a *second* dsh instance bound

package/README.md

@@ -50,8 +50,31 @@ dsh plugin --profile web add link:/绝对路径/dsh-mesh-access
 | 当前状态 | 反代是否在跑、DSH 自己的监听端口、找到几张组网网卡 |
 | 动作 | 在组网地址上开端口 / 关闭 / 刷新 |
 | 访问地址 | 给组网内任何设备打开的地址（带 token，可直接复制） |
+| 公网隧道（可选） | 用**你自己的**服务器做公网入口：启停 frpc、显示公网地址、真实探测是否可达 |
 | 第一次用星空组网？ | 邀请注册链接 + 成员账号规则 |
 
+## 用你自己的服务器（可选）
+
+组网那条路对局域网/P2P 很够用，但它要过公网中继：实测 RTT 800–990 ms（最坏 3.7 s），长连接会被心跳判死，
+手机上就表现为一直「重新连接中」。如果你自己有一台带公网 IP 的服务器，可以把它当公网入口，延迟通常 30–60 ms。
+
+**插件不提供服务器，也不用别人的服务器** —— 这一步完全是你自己的机器。两个脚本，都在这个仓库里：
+
+```bash
+# 1) 在你自己的服务器上（root）：装 frps
+sudo ./tools/frps-setup.sh --port 7000 --http-port 21081
+#    想直接上 HTTPS：加 --domain dsh.example.com --email you@example.com
+
+# 2) 在跑 DSH 的这台电脑上：装 frpc，指向上面那台服务器
+./tools/frpc-setup.sh --server <服务器IP> --token <第 1 步打印的 token> --remote-port 21081
+```
+
+然后回到左侧「组网访问」→「公网隧道」→ 启动隧道。第 1 步会打印 token 和给你复制的第 2 步命令；
+安全组要放行 **7000/tcp** 与 **21081/tcp**（这一步只能在云控制台做）。
+
+完整说明（前置条件、域名/TLS/Basic 认证、故障表、卸载）见 **[docs/VPS.md](docs/VPS.md)**。
+想让 AI 帮你配：把 **[docs/AI-SETUP.md](docs/AI-SETUP.md)** 整份丢给它，它就知道该跑什么、怎么验证。
+
 ## HTTP 接口
 
 面板只是两个接口的外壳，故意做得极小：

package/docs/AI-SETUP.md

@@ -0,0 +1,112 @@
+# AI-SETUP — give this file to an AI agent
+
+You are helping a human expose **their own** DeepSeek Harness instance on **their own** server, so they can open it
+from a phone or another computer over the public internet. Read all of it before running anything.
+
+This is not a hosted service. You never get a server from us. The human provides one (any Linux VPS with a public IP,
+or a home box with port forwarding). If they have none, stop and tell them the mesh-only path already works inside
+their StarVPN/Tailscale/WireGuard network — a public entry point is optional.
+
+## 0. Hard rules
+
+1. **Never invent credentials.** The frp token and the Basic-auth password are generated by the scripts on the
+   human's machine. Do not type your own, do not reuse one from a doc example.
+2. **Only touch the human's own machines.** The server must be theirs. Do not point `frpc` at a server you cannot
+   justify, and do not run these scripts on a host they have not named.
+3. **Do not open more public ports than necessary.** Two TCP ports, nothing else: `bindPort` (default 7000) and the
+   web entry (`remotePort`, default 21081). If they go the domain route, 80 is needed once for the ACME challenge.
+4. **Do not disable TLS verification, do not run `curl -k` in a verification step** and call it success. Use the real
+   certificate or accept that the check failed and say so.
+5. **Do not edit the plugin's `lib/*.js`.** Configuration lives in three keys (`frpcBin`, `frpcConfig`,
+   `tunnelDomain`). If the human wants different behaviour, that is a feature request, not a patch.
+6. **Never enable the frpc unit.** `dsh-frpc.service` is written but intentionally not enabled; either the panel
+   starts `frpc`, or the human starts the unit by hand. Two frpc processes fight over the same `remotePort`.
+7. **Verify before you claim success** (§4). "The script finished" is not verification.
+
+## 1. What the pieces are
+
+```
+phone ──https──> their server: frps ──frp tunnel──> their computer: frpc ──> 192.168.188.1:3081 ──> DSH 127.0.0.1:3080
+```
+
+- `tools/frps-setup.sh` — runs on the **server** (root). Installs `frps`, writes `/etc/frp/frps.toml`, systemd unit,
+  firewall rule; with `--domain` also writes the nginx reverse proxy + Let's Encrypt cert + Basic auth.
+- `tools/frpc-setup.sh` — runs on the **computer** (normal user). Installs `frpc` if missing, writes
+  `~/.config/frp/frpc.toml`, writes the systemd **user** unit.
+- The plugin reads `~/.config/frp/frpc.toml` and shows a "public tunnel" card: start / stop / live status / public URL.
+
+The port the tunnel points at is **not** DSH's own port. It is the mesh address the *plugin* opened, e.g.
+`192.168.188.1:3081`. The human must press "在组网地址上开端口" (open a port on the mesh address) once; otherwise
+the tunnel comes up and every request 502s.
+
+## 2. Run order
+
+```bash
+# A) on the server, as root — ask the human for: nothing but consent and the optional domain
+sudo ./tools/frps-setup.sh --port 7000 --http-port 21081
+#    with a domain (recommended, gives https + browser login prompt):
+sudo ./tools/frps-setup.sh --port 7000 --http-port 21081 --domain dsh.example.com --email them@example.com
+
+# B) copy from the output of A: server address, token, ports. Then on the computer:
+./tools/frpc-setup.sh --server <IP or domain> --port 7000 --token <token> \
+  --remote-port 21081 [--domain dsh.example.com]
+```
+
+Both scripts are idempotent. Re-running A keeps the existing token unless `--token` is passed; re-running B rewrites
+the config file.
+
+## 3. The one manual step you must also do
+
+Tell the human to open **Cloud console → Security group / firewall** and allow the two TCP ports. A script cannot do
+this, and no amount of debugging on the box will fix a blocked port.
+
+## 4. Verification (all four, in order)
+
+```bash
+# 1. server: frps is up and listening
+systemctl is-active frps && ss -Hltn | grep -E ':(7000|21081)\b'
+
+# 2. server: frpc actually connected (look for a client, not just the listener)
+tail -20 /var/log/frp/frps.log
+
+# 3. computer: frpc logged in and proxy started
+tail -20 ~/.config/frp/frpc.log        # expect: "login to server success" + "[dsh-mesh] start proxy success"
+
+# 4. end to end from outside — plain HTTP entry:
+curl -s -o /dev/null -w '%{http_code}\n' "http://<server>:21081/"          # 401 (DSH wants a token) is correct
+#    with the domain + Basic auth:
+curl -s -o /dev/null -w '%{http_code}\n' -u dsh:<password> "https://<domain>/"   # 401 again, still correct
+
+# 5. WebSocket path must answer 101, not 403/404 (this is what "keeps reconnecting" looks like when broken):
+curl -si --http1.1 -u dsh:<password> \
+  -H 'Connection: Upgrade' -H 'Upgrade: websocket' \
+  -H 'Sec-WebSocket-Version: 13' -H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
+  -H "Origin: https://<domain>" "https://<domain>/api/remote.mux" | head -1
+```
+
+`101 Switching Protocols` = good. `403` = the proxy rewrote `Host` but not `Origin` (plugin < 1.0.1, or your own
+nginx overriding headers). `404` = you are on HTTP/2; browsers open WS over 1.1, but a `--http1.1` flag is needed
+when you test with curl.
+
+Then have the human open the URL on the phone, and confirm their **whole session list** appears and a message typed on
+the computer shows up on the phone within a second.
+
+## 5. Failure table
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `curl http://server:21081/` times out | security group blocks 21081 | console → allow TCP 21081 (and 7000) |
+| `connection refused` on 21081 | frpc never connected | `journalctl -u frps -n 50`, check token equality |
+| 502 from nginx | nothing listening on the local port | open the port in the DSH panel; `ss -Hltn \| grep 3081` |
+| 500 from nginx | `.dsh_htpasswd` unreadable by the worker | `chown root:<nginx group>` + `chmod 640` |
+| page loads, then "reconnecting" | WebSocket not forwarded | `proxy_http_version 1.1` + `Upgrade`/`Connection` headers |
+| `start error: port already used` | two frpc on one `remotePort` | stop the systemd unit **or** the panel tunnel, keep one |
+| certbot fails | 80 blocked, or DNS not pointing here yet | check A record, open 80, rerun with `--domain` |
+| works on Wi-Fi, fails on cellular | frpc points at a LAN address | `--server` must be the public IP or domain |
+
+## 6. Report back with
+
+- which machine is the server (distro), which is the computer
+- `bindPort`, `remotePort`, whether a domain/TLS was used
+- the four verification outputs from §4, pasted as-is
+- anything that failed, including the exact error line

package/docs/VPS.md

@@ -0,0 +1,104 @@
+# 用自己的服务器做公网入口（可选）
+
+插件默认只把 DSH 挂到**组网网卡**上——手机、平板、另一台电脑在同一个星空组网里就能打开。
+这条路的代价是流量要过组网中继：实测 RTT 800–990 ms（最坏 3.7 s），长连接会被心跳判死，表现为手机页面
+一直「重新连接中」。
+
+如果你**自己有一台带公网 IP 的服务器**（阿里云轻量、腾讯云、搬瓦工、家里的固定 IP 都行），可以让它当公网入口，
+延迟通常 30–60 ms，稳定得多。插件不是要你用别人的服务器——这一步完全是你自己的机器，你自己掌握账号密码。
+
+```
+手机 / 平板 / 公司电脑
+        │  https://你的域名  （可选，走 nginx + 证书）
+        ▼
+你自己的服务器   frps  ←── 公网，只开一个 7000
+        │  隧道（frp，token 认证 + 加密）
+        ▼
+你的电脑        frpc  →  192.168.188.1:3081（插件在组网地址上开出来的那个口）
+        │
+        ▼
+            DSH 本体 127.0.0.1:3080
+```
+
+## 一句话版本
+
+```bash
+# 1) 在你自己的服务器上（root）
+sudo ./tools/frps-setup.sh --port 7000 --http-port 21081
+#    想直接上 HTTPS：加 --domain dsh.example.com --email you@example.com
+
+# 2) 在你跑 DSH 的电脑上
+./tools/frpc-setup.sh --server <服务器IP> --port 7000 \
+  --token <第 1 步打印的 token> --remote-port 21081 [--domain dsh.example.com]
+
+# 3) 回到 DSH 左侧「组网访问」面板 → 公网隧道卡片 → 启动隧道
+```
+
+第 1 步结束会打印 token、端口和给你复制粘贴的第 2 步命令。两个脚本都可以重复跑（幂等）。
+
+## 前置条件
+
+| 项 | 要求 |
+|---|---|
+| 服务器 | Linux（systemd），1 核 512 MB 够用，公网 IP |
+| 端口 | 云控制台安全组放行 **7000/tcp**（frp 控制）和 **21081/tcp**（网页入口） |
+| 域名 | 可选。要用 https 才需要，且要先把 A 记录指到服务器 |
+| 本机 | 已经能在面板上「在组网地址上开端口」；`~/.local/bin` 在 PATH 上 |
+
+## 两个脚本各自做什么
+
+`tools/frps-setup.sh`（服务器上，root）：
+
+1. 装 frp v0.72.0 的 `frps` 到 `/usr/local/bin/frps`（GitHub 不通时自动走 `gh-proxy.com`）
+2. 写 `/etc/frp/frps.toml`：`bindPort`、`auth.token`（没给就随机生成 24 位）、日志、本机管理面板 `127.0.0.1:7500`
+3. 建 `frps.service` 并 enable + start，核对 `:7000` 真的在听
+4. firewalld / ufw 有就放行 7000
+5. 给了 `--domain` 且有 nginx：写 ACME 探针、申请 Let's Encrypt 证书、写 443 反代、加 Basic 认证（随机密码）
+
+`tools/frpc-setup.sh`（你的电脑上，普通用户）：
+
+1. 没 `frpc` 就装到 `~/.local/bin/frpc`
+2. 写 `~/.config/frp/frpc.toml`（600）：`serverAddr`、`serverPort`、token、`[[proxies]]` 映射
+   `192.168.188.1:3081 → 服务器:21081`，开 `transport.useEncryption`
+3. 检查组网端口是否已经在听（不对就去面板点「在组网地址上开端口」）
+4. 写 `~/.config/systemd/user/dsh-frpc.service`（**不 enable**，按需启动；插件自己也能拉起 frpc）
+
+## 认证是两层
+
+1. **DSH 自己的 token**：面板里「访问地址」那一行就是带 `?token=` 的完整地址，换完 cookie 30 天有效。
+2. **你加的入口认证**（推荐）：`frps-setup.sh --domain` 会顺手配好 nginx Basic 认证，浏览器打开先弹账号密码框。
+   不用 Basic 也可以只暴露 IP:端口——但那样等于把 DSH 登录页直接挂在公网，靠 token 一层兜底。
+
+想更硬一点：把 nginx 换成 mTLS（客户端证书）或者只允许公司 IP 访问（`allow`/`deny`），这些都在 nginx 那一层做，
+插件不用改。
+
+## 常见问题
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 面板显示「frpc 未运行」但公网能打开 | 你自己的 systemd 单元在跑 frpc | 正常。面板会显示「外部进程已在跑」，不让重复启动 |
+| 面板「公网不可达」 | 安全组没放行、frps 没起、`remotePort` 冲突 | 服务器上 `ss -Hltn \| grep 21081`、`journalctl -u frps -n 50` |
+| 隧道起来了，打开是 502 | 本机 `192.168.188.1:3081` 没监听 | 回面板点「在组网地址上开端口」；`ss -Hltn \| grep 3081` |
+| https 打开 500 | `/etc/nginx/.dsh_htpasswd` 权限不对 | `chown root:<nginx组>` + `chmod 640`（600 会让 worker 读不到） |
+| 页面能开但一直「重新连接中」 | WebSocket 没被转发 | nginx 里必须有 `Upgrade`/`Connection "upgrade"`，且 `proxy_http_version 1.1` |
+| `frpc` 报 `start error: port already used` | 同一 `remotePort` 被占 | 换 `--remote-port`，或在 frps 上 `allowPorts` 收窄 |
+
+## 只想临时用一下
+
+```bash
+# 本机前台跑，Ctrl+C 就停
+~/.local/bin/frpc -c ~/.config/frp/frpc.toml
+```
+
+## 卸载
+
+```bash
+# 本机
+systemctl --user disable --now dsh-frpc 2>/dev/null
+rm -f ~/.config/systemd/user/dsh-frpc.service ~/.config/frp/frpc.toml ~/.local/bin/frpc
+
+# 服务器
+systemctl disable --now frps
+rm -f /etc/systemd/system/frps.service /etc/frp/frps.toml /usr/local/bin/frps
+rm -f /etc/nginx/conf.d/dsh-https.conf /etc/nginx/conf.d/dsh-acme.conf
+```

package/lib/client.js

@@ -41,6 +41,16 @@ window.__ModuleLoader__.load({
       dot: (on) => ({ width: 7, height: 7, borderRadius: 999, background: on ? '#3fb950' : '#8b949e' }),
       err: { color: '#f85149', fontSize: 13, marginTop: 8 },
       hint: { fontSize: 12, opacity: 0.6, marginTop: 10, lineHeight: 1.6 },
+      input: {
+        padding: '6px 10px',
+        borderRadius: 8,
+        border: '1px solid rgba(127,127,127,.35)',
+        background: 'transparent',
+        color: 'inherit',
+        fontSize: 13,
+        width: 200,
+      },
+      label: { fontSize: 12, opacity: 0.7, marginBottom: 4, display: 'block' },
     }
 
     /** 带硬超时的 fetch：超时就 abort，绝不让调用方永远挂着。
@@ -56,6 +66,13 @@ window.__ModuleLoader__.load({
 
     const api = {
       status: () => fetchJson('/api/dsh-mesh-access/status', {}, 6000),
+      tunnel: () => fetchJson('/api/dsh-mesh-access/tunnel', {}, 8000),
+      tunnelAction: (action) =>
+        fetchJson('/api/dsh-mesh-access/tunnel', {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify(typeof action === 'string' ? { action } : action),
+        }, 20000),
       action: (action, port) =>
         fetchJson('/api/dsh-mesh-access/proxy', {
           method: 'POST',
@@ -79,9 +96,14 @@ window.__ModuleLoader__.load({
 
     function Panel() {
       const [state, setState] = react.useState(null)
+      const [tunnel, setTunnel] = react.useState(null)
       const [busy, setBusy] = react.useState(false)
+      const [tunnelBusy, setTunnelBusy] = react.useState(false)
       const [err, setErr] = react.useState(null)
+      const [tunnelErr, setTunnelErr] = react.useState(null)
       const [copied, setCopied] = react.useState(false)
+      const [formOpen, setFormOpen] = react.useState(false)
+      const [form, setForm] = react.useState({})
 
       const refresh = react.useCallback(() => {
         api
@@ -91,6 +113,10 @@ window.__ModuleLoader__.load({
             setErr(s && s.ok === false ? s.error ?? '未知错误' : null)
           })
           .catch((e) => setErr(String(e && e.message ? e.message : e)))
+        api
+          .tunnel()
+          .then((t) => setTunnel(t))
+          .catch(() => {})
       }, [])
 
       react.useEffect(() => {
@@ -99,6 +125,64 @@ window.__ModuleLoader__.load({
         return () => clearInterval(t)
       }, [refresh])
 
+      const runTunnel = (action) => {
+        setTunnelBusy(true)
+        setTunnelErr(null)
+        api
+          .tunnelAction(action)
+          .then((t) => {
+            if (t && t.ok === false) setTunnelErr(t.error ?? '操作失败')
+            else setTunnelErr(t && t.error ? t.error : null)
+            setTunnel(t && t.tunnel ? t.tunnel : t)
+            refresh()
+          })
+          .catch((e) => setTunnelErr(String(e && e.message ? e.message : e)))
+          .finally(() => setTunnelBusy(false))
+      }
+
+      const runConfig = () => {
+        const payload = Object.assign({ action: 'config' }, form)
+        setTunnelBusy(true)
+        setTunnelErr(null)
+        api
+          .tunnelAction(payload)
+          .then((t) => {
+            if (t && t.ok === false) {
+              setTunnelErr(t.error ?? '保存失败')
+              return null
+            }
+            setFormOpen(false)
+            setForm({})
+            refresh()
+            // 存完顺手起隧道；起不来也只报错，不静默
+            return api.tunnelAction('start')
+          })
+          .then((t) => {
+            if (!t) return
+            if (t && t.ok === false) setTunnelErr(t.error ?? '隧道没起来')
+            else if (t && t.error) setTunnelErr(t.error)
+            refresh()
+          })
+          .catch((e) => setTunnelErr(String(e && e.message ? e.message : e)))
+          .finally(() => setTunnelBusy(false))
+      }
+
+      const openForm = () => {
+        const tn0 = tunnel || (state && state.tunnel) || {}
+        setForm({
+          serverAddr: tn0.serverAddr || '',
+          serverPort: String(tn0.serverPort || 7000),
+          remotePort: String(tn0.remotePort || 21081),
+          localPort: String(tn0.localPort || (state && state.proxy && state.proxy.port) || 3081),
+          localIP: tn0.localIP || (state && state.mesh && state.mesh[0] && state.mesh[0].address) || '127.0.0.1',
+          domain: tn0.domain || '',
+          token: '',
+        })
+        setFormOpen(true)
+      }
+
+      const setField = (k) => (e) => setForm(Object.assign({}, form, { [k]: e.target.value }))
+
       const run = (action) => {
         setBusy(true)
         setErr(null)
@@ -135,6 +219,7 @@ window.__ModuleLoader__.load({
       const host = (state && state.host) || {}
       const url = proxy.url
       const referral = (state && state.referral) || 'https://starvpn.cn/register.html?referralCode=Kurali'
+      const tn = tunnel || (state && state.tunnel) || {}
 
       return h(
         'div',
@@ -182,6 +267,83 @@ window.__ModuleLoader__.load({
             )
           : null,
 
+        h(
+          Card, { title: '公网隧道（自己的 VPS，可选的第二条路）' },
+          h('div', { style: S.row },
+            h('span', { style: S.pill(Boolean(tn.running || tn.external)) }, h('span', { style: S.dot(Boolean(tn.running || tn.external)) }),
+              tn.running ? 'frpc 运行中（本插件）' : tn.external ? 'frpc 运行中（外部进程）' : 'frpc 未运行'),
+            h('span', { style: S.pill(Boolean(tn.reachable)) }, h('span', { style: S.dot(Boolean(tn.reachable)) }), tn.reachable ? '公网可达' : '公网不可达'),
+            h('span', { style: S.pill(Boolean(tn.url)) }, h('span', { style: S.dot(Boolean(tn.url)) }), tn.domain ? '域名 ' + tn.domain : tn.remotePort ? '端口 ' + tn.remotePort : '未配置'),
+          ),
+          h('div', { style: S.row, marginTop: 12 },
+            h('button', {
+              style: S.btnPrimary,
+              disabled: tunnelBusy || Boolean(tn.running) || Boolean(tn.external) || !tn.configFound,
+              onClick: () => runTunnel('start'),
+            }, tunnelBusy ? '处理中…' : tn.external ? '外部进程已在跑' : '启动隧道'),
+            h('button', {
+              style: S.btn,
+              disabled: tunnelBusy || !tn.running,
+              title: tn.external && !tn.running ? '这个 frpc 是外部进程（systemd 单元），请用 systemctl --user stop dsh-frpc' : '',
+              onClick: () => runTunnel('stop'),
+            }, '停止'),
+            h('button', { style: S.btn, disabled: tunnelBusy, onClick: refresh }, '刷新'),
+            h('button', { style: S.btn, disabled: tunnelBusy, onClick: formOpen ? () => setFormOpen(false) : openForm }, formOpen ? '收起' : tn.configFound ? '改配置' : '填服务器信息'),
+          ),
+          formOpen
+            ? h('div', { style: { marginTop: 12, padding: 12, borderRadius: 8, border: '1px dashed rgba(127,127,127,.35)' } },
+                h('div', { style: S.hint, marginTop: 0, opacity: 0.8 },
+                  '填的是你自己的服务器。不知道填什么就问给你配服务器的那个人，或者把 docs/AI-SETUP.md 丢给你的 AI。'),
+                h('div', { style: S.row, marginTop: 10, gap: 10 },
+                  h('div', null, h('label', { style: S.label }, '服务器地址（IP 或域名）'),
+                    h('input', { style: S.input, value: form.serverAddr || '', placeholder: '1.2.3.4', onChange: setField('serverAddr') })),
+                  h('div', null, h('label', { style: S.label }, '绑定端口 bindPort'),
+                    h('input', { style: S.input, value: form.serverPort || '', placeholder: '7000', onChange: setField('serverPort') })),
+                  h('div', null, h('label', { style: S.label }, '公网端口 remotePort'),
+                    h('input', { style: S.input, value: form.remotePort || '', placeholder: '21081', onChange: setField('remotePort') })),
+                ),
+                h('div', { style: S.row, marginTop: 10, gap: 10 },
+                  h('div', null, h('label', { style: S.label }, '域名（可选，填了就用 https）'),
+                    h('input', { style: S.input, value: form.domain || '', placeholder: 'dsh.example.com', onChange: setField('domain') })),
+                  h('div', null, h('label', { style: S.label }, '本地端口（组网 IP 上那个）'),
+                    h('input', { style: S.input, value: form.localPort || '', placeholder: '3081', onChange: setField('localPort') })),
+                  h('div', null, h('label', { style: S.label }, 'token' + (tn.tokenSet ? '（已存，留空不变）' : '')),
+                    h('input', {
+                      style: S.input,
+                      type: 'password',
+                      value: form.token || '',
+                      placeholder: tn.tokenSet ? '••••••••（保持不变）' : '服务端 /etc/frp/frps.toml 里的 auth.token',
+                      onChange: setField('token'),
+                    })),
+                ),
+                h('div', { style: S.row, marginTop: 12 },
+                  h('button', { style: S.btnPrimary, disabled: tunnelBusy, onClick: runConfig }, tunnelBusy ? '保存中…' : '保存并启动'),
+                  h('button', { style: S.btn, disabled: tunnelBusy, onClick: () => setFormOpen(false) }, '取消'),
+                ),
+                h('div', { style: S.hint }, '保存会写 ~/.config/frp/frpc.toml（600）和同目录的 dsh-mesh-access.json（只存域名）。'),
+              )
+            : null,
+          tunnelErr ? h('div', { style: S.err }, tunnelErr) : null,
+          tn.urlSigned
+            ? h('div', { style: S.row, marginTop: 12 },
+                h('code', { style: { ...S.mono, wordBreak: 'break-all' } }, tn.urlSigned),
+                h('button', { style: S.btn, onClick: () => copy(tn.urlSigned) }, copied ? '已复制' : '复制'),
+              )
+            : null,
+          h('div', { style: S.hint },
+            tn.configFound
+              ? 'frpc 配置：' + tn.configPath + (tn.serverAddr ? '（' + tn.serverAddr + '，本地 ' + tn.localPort + ' → 远端 ' + tn.remotePort + '）' : '')
+              : '没找到 frpc 配置 ' + (tn.configPath || '') + '。这条是可选的：用你自己的服务器做公网入口，就不受组网中继心跳超时的影响。装法见 docs/VPS.md，或者把 docs/AI-SETUP.md 丢给你的 AI 让它跑 tools/frps-setup.sh + tools/frpc-setup.sh。',
+            tn.external && !tn.running
+              ? ' 现在这个隧道是你自己的外部进程在跑（多半是 systemd 单元 dsh-frpc），所以这里显示为「外部进程」并且不让重复启动，免得抢同一个 remotePort。想停：systemctl --user stop dsh-frpc。'
+              : '',
+            ' 组网走中继时 RTT 800–990 ms（最坏 3.7 s），长连接会被心跳判死；你自己的服务器通常 30–60 ms。',
+          ),
+          tn.log && tn.log.length
+            ? h('div', { style: { ...S.hint, ...S.mono, marginTop: 8, whiteSpace: 'pre-wrap', opacity: 0.5 } }, tn.log.slice(-4).join('\n'))
+            : null,
+        ),
+
         h(
           Card, { title: '第一次用星空组网？' },
           h('div', { style: S.hint }, '三步走，不用记 IP，也不用改任何配置。'),

package/lib/index.js

@@ -9,10 +9,18 @@
  *   1. 找出组网网卡（StarVPN / utun* / tap* / tun* / wg* / gpd* / ppp*）上的 IPv4
  *   2. GET /api/dsh-mesh-access/status   看状态
  *   3. POST /api/dsh-mesh-access/proxy   启停反代（{action:'start'|'stop', port?}）
+ *   4. GET/POST /api/dsh-mesh-access/tunnel  公网隧道（frpc）状态与启停
+ *
+ * 组网只适合「两端都能连上同一个虚拟网」的场景；校园网/蜂窝网络下走中继，
+ * 心跳撑不住长连接。所以额外支持「自己的 VPS + frp」：这里只管 spawn/停止 frpc，
+ * 公网地址与证书交给 VPS 上已有的 nginx。
  */
 import os from 'node:os'
+import fs from 'node:fs'
 import http from 'node:http'
 import net from 'node:net'
+import path from 'node:path'
+import { spawn } from 'node:child_process'
 
 export const name = 'dsh-mesh-access'
 export const inject = ['webServer', 'connection']
@@ -177,9 +185,25 @@ export function apply(ctx, config = {}) {
     addressPrefix: typeof config.addressPrefix === 'string' ? config.addressPrefix : '192.168.',
     proxyPort: asPort(config.proxyPort, 3081),
     upstream: asText(config.upstream, '127.0.0.1'),
+    // 公网隧道（frp）。默认路径与 frp 官网安装脚本一致，用户换位置就在配置里覆盖。
+    frpcBin: asText(config.frpcBin, `${os.homedir()}/.local/bin/frpc`),
+    frpcConfig: asText(config.frpcConfig, `${os.homedir()}/.config/frp/frpc.toml`),
+    frpcLog: asText(config.frpcLog, `${os.homedir()}/.config/frp/frpc.log`),
+    // 隧道对外暴露的域名（有 TLS 时写域名，没有就留空 —— 会自动退回 http://serverAddr:remotePort）
+    tunnelDomain: asText(config.tunnelDomain, ''),
   }
 
-  const state = { server: null, address: null, port: null, startedAt: null, error: null }
+  const state = {
+    server: null,
+    address: null,
+    port: null,
+    startedAt: null,
+    error: null,
+    frpc: null,
+    tunnelLog: [],
+    tunnelError: null,
+    tunnelStartedAt: null,
+  }
 
   const upstreamPort = () => ctx.webServer?.port ?? null
 
@@ -221,9 +245,288 @@ export function apply(ctx, config = {}) {
         error: state.error,
       },
       referral: REFERRAL,
+      tunnel: tunnelSnapshot(),
+    }
+  }
+
+  /* ---------------------------------------------------------------- 公网隧道 */
+  // frp 的配置是 TOML，但这里只读几个扁平键，手写一个极简取值器就够 ——
+  // 引入 TOML 解析库只为读 4 个字符串不划算（插件想保持零运行时依赖）。
+  const tomlValue = (text, key) => {
+    const m = text.match(new RegExp(`^\\s*${key}\\s*=\\s*(.+?)\\s*$`, 'm'))
+    if (!m) return null
+    const raw = m[1].split('#')[0].trim()
+    const quoted = raw.match(/^"(.*)"$/)
+    if (quoted) return quoted[1]
+    const num = Number(raw)
+    return Number.isFinite(num) ? num : raw
+  }
+
+  const sidecarPath = () => `${path.dirname(cfg.frpcConfig)}/dsh-mesh-access.json`
+
+  const readSidecar = () => {
+    try {
+      return JSON.parse(fs.readFileSync(sidecarPath(), 'utf8'))
+    } catch {
+      return {}
+    }
+  }
+
+  const writeSidecar = (data) => {
+    try {
+      fs.mkdirSync(path.dirname(sidecarPath()), { recursive: true })
+      fs.writeFileSync(sidecarPath(), JSON.stringify(data, null, 2) + '\n')
+    } catch {
+      /* 侧车只是记域名，写不进去就退回插件配置 */
+    }
+  }
+
+  /**
+   * 写 frpc.toml + 侧车（域名）。面板上的「设置」和 tools/frpc-setup.sh 产出的是同一种文件，
+   * 所以用户先跑脚本、后来改用面板改，两边不会打架。
+   */
+  const writeTunnelConfig = (input) => {
+    const str = (v) => (typeof v === 'string' ? v.trim() : '')
+    const serverAddr = str(input.serverAddr)
+    const domain = str(input.domain).replace(/^https?:\/\//, '').replace(/\/+$/, '')
+    const serverPort = Number(input.serverPort ?? 7000)
+    const remotePort = Number(input.remotePort ?? 21081)
+    const localPort = Number(input.localPort ?? cfg.proxyPort)
+    const localIP = str(input.localIP) || '127.0.0.1'
+    const token = str(input.token)
+
+    if (!/^[A-Za-z0-9._-]+$/.test(serverAddr)) throw new Error('服务器地址只能填 IP 或域名')
+    for (const [name, v] of [['绑定端口', serverPort], ['公网端口', remotePort], ['本地端口', localPort]]) {
+      if (!Number.isInteger(v) || v < 1 || v > 65535) throw new Error(`${name}要填 1–65535 之间的整数`)
+    }
+    if (domain && !/^[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/.test(domain)) throw new Error('域名格式不对，例如 dsh.example.com')
+
+    let oldToken = ''
+    try {
+      oldToken = String(tomlValue(fs.readFileSync(cfg.frpcConfig, 'utf8'), 'auth.token') || '')
+    } catch {
+      /* 没有旧配置就算了 */
+    }
+    const finalToken = token || oldToken
+    if (!finalToken) throw new Error('token 不能为空（服务端 /etc/frp/frps.toml 里的 auth.token）')
+
+    const text = `# 由 dsh-mesh-access 面板生成
+serverAddr = "${serverAddr}"
+serverPort = ${serverPort}
+
+auth.method = "token"
+auth.token = "${finalToken}"
+
+log.to = "${cfg.frpcLog}"
+log.level = "info"
+
+[[proxies]]
+name = "dsh-mesh"
+type = "tcp"
+localIP = "${localIP}"
+localPort = ${localPort}
+remotePort = ${remotePort}
+transport.useEncryption = true
+`
+    fs.mkdirSync(path.dirname(cfg.frpcConfig), { recursive: true })
+    fs.writeFileSync(cfg.frpcConfig, text, { mode: 0o600 })
+    try {
+      fs.chmodSync(cfg.frpcConfig, 0o600)
+    } catch {
+      /* ignore */
+    }
+    writeSidecar({ domain: domain || null, updatedAt: new Date().toISOString() })
+    return true
+  }
+
+  const tunnelCfg = () => {
+    let text = ''
+    try {
+      text = fs.readFileSync(cfg.frpcConfig, 'utf8')
+    } catch {
+      text = ''
+    }
+    const serverAddr = tomlValue(text, 'serverAddr')
+    const serverPort = Number(tomlValue(text, 'serverPort') ?? 7000)
+    const remotePort = Number(tomlValue(text, 'remotePort') ?? 0)
+    const localPort = Number(tomlValue(text, 'localPort') ?? cfg.proxyPort)
+    const localIP = String(tomlValue(text, 'localIP') || '127.0.0.1')
+    const domain = readSidecar().domain || cfg.tunnelDomain || ''
+    // 有域名就走 https://domain/（VPS 上 nginx 已经接管 TLS），否则直连 IP:remotePort
+    const base = domain ? `https://${domain}/` : remotePort && serverAddr ? `http://${serverAddr}:${remotePort}/` : null
+    return {
+      configFound: Boolean(text),
+      configPath: cfg.frpcConfig,
+      binary: cfg.frpcBin,
+      serverAddr,
+      serverPort,
+      remotePort,
+      localPort,
+      localIP,
+      tokenSet: Boolean(tomlValue(text, 'auth.token')),
+      domain: domain || null,
+      url: base,
+      urlSigned: signed(base),
+    }
+  }
+
+  /** 探测「公网入口是否真的连得上」——比看进程在不在更接近用户感受。 */
+  const probe = (host, port, ms = 1500) =>
+    new Promise((resolve) => {
+      if (!host || !port) return resolve(false)
+      const socket = net.connect({ host, port })
+      const done = (ok) => {
+        socket.destroy()
+        resolve(ok)
+      }
+      socket.setTimeout(ms)
+      socket.once('connect', () => done(true))
+      socket.once('timeout', () => done(false))
+      socket.once('error', () => done(false))
+    })
+
+  const tunnelSnapshot = () => {
+    const t = tunnelCfg()
+    const running = Boolean(state.frpc)
+    return {
+      ...t,
+      running,
+      startedAt: state.tunnelStartedAt,
+      error: state.tunnelError,
+      log: state.tunnelLog.slice(-12),
+      // 进程在跑 ≠ 公网通；反之进程没了但端口仍可连（外部 systemd 起的）也算可用。
+      // 这里只给「本插件在看什么」，真正的连通性由 GET /tunnel 现测。
+      mode: running ? 'plugin' : 'stopped',
     }
   }
 
+  let startingTunnel = null
+  // frpc 默认把日志写进配置里的 log.to，stdout 是空的 —— 所以既要抓管道，也要跟着日志文件读。
+  function logFileOffset(logPath) {
+    try {
+      return fs.statSync(logPath).size
+    } catch {
+      return 0
+    }
+  }
+
+  function startTunnel() {
+    if (state.frpc) return Promise.resolve({ ok: true, ...snapshot() })
+    if (startingTunnel) return startingTunnel
+    startingTunnel = new Promise((resolve) => {
+      const t = tunnelCfg()
+      if (!t.configFound) {
+        state.tunnelError = `没找到 frpc 配置：${cfg.frpcConfig}（先按 docs/VPS.md 装 frpc 并写好 frpc.toml）`
+        return resolve({ ok: false, error: state.tunnelError })
+      }
+      let text = ''
+      try {
+        text = fs.readFileSync(cfg.frpcConfig, 'utf8')
+      } catch {
+        /* 读不到就当没有 log.to */
+      }
+      const logPath = tomlValue(text, 'log.to') || ''
+      let child
+      try {
+        child = spawn(cfg.frpcBin, ['-c', cfg.frpcConfig], { stdio: ['ignore', 'pipe', 'pipe'] })
+      } catch (err) {
+        state.tunnelError = String(err?.message ?? err)
+        return resolve({ ok: false, error: state.tunnelError })
+      }
+      state.frpc = child
+      state.tunnelError = null
+      state.tunnelStartedAt = Date.now()
+      let settled = false
+      let offset = logPath ? logFileOffset(logPath) : 0
+      let stopTail = () => {}
+
+      const settle = (ok, error) => {
+        if (settled) return
+        settled = true
+        stopTail()
+        if (!ok) {
+          state.tunnelError = error ?? 'frpc 启动失败'
+          try {
+            child.kill('SIGTERM')
+          } catch {
+            /* ignore */
+          }
+          state.frpc = null
+          state.tunnelStartedAt = null
+        }
+        resolve(ok ? { ok: true, ...snapshot() } : { ok: false, error: state.tunnelError })
+      }
+
+      const push = (line) => {
+        if (!line.trim()) return
+        state.tunnelLog.push(line.slice(0, 300))
+        if (state.tunnelLog.length > 40) state.tunnelLog.splice(0, state.tunnelLog.length - 40)
+        if (/start proxy success/i.test(line)) settle(true)
+        else if (/start error|port already used|login to server failed/i.test(line)) settle(false, line.slice(0, 200))
+      }
+
+      const onLine = (buf) => {
+        for (const line of String(buf).split(/\r?\n/)) push(line)
+      }
+      child.stdout?.on('data', onLine)
+      child.stderr?.on('data', onLine)
+
+      const poll = () => {
+        if (!logPath || settled) return
+        let size = 0
+        try {
+          size = fs.statSync(logPath).size
+        } catch {
+          return
+        }
+        if (size <= offset) return
+        try {
+          const fd = fs.openSync(logPath, 'r')
+          const len = size - offset
+          const buf = Buffer.alloc(len)
+          fs.readSync(fd, buf, 0, len, offset)
+          fs.closeSync(fd)
+          offset = size
+          for (const line of buf.toString('utf8').split(/\r?\n/)) push(line)
+        } catch {
+          /* 文件被轮转之类，下一轮再说 */
+        }
+      }
+      const timer = setInterval(poll, 150)
+      stopTail = () => clearInterval(timer)
+
+      child.on('error', (err) => settle(false, String(err?.message ?? err)))
+      child.on('exit', (code, signal) => {
+        state.frpc = null
+        state.tunnelStartedAt = null
+        if (!settled) settle(false, `frpc 退出（code=${code} signal=${signal}）`)
+        else if (state.tunnelError === null) state.tunnelError = `frpc 已退出（code=${code} signal=${signal}）`
+      })
+      setTimeout(() => {
+        if (!settled) settle(false, '等了 8 秒没收到「start proxy success」，看下面日志')
+      }, 8000)
+    }).finally(() => {
+      startingTunnel = null
+    })
+    return startingTunnel
+  }
+
+  async function stopTunnel() {
+    const child = state.frpc
+    state.frpc = null
+    state.tunnelStartedAt = null
+    if (child) {
+      try {
+        child.kill('SIGTERM')
+      } catch {
+        /* ignore */
+      }
+      await new Promise((resolve) => setTimeout(resolve, 150))
+    }
+    state.tunnelError = null
+    return { ok: true, ...snapshot() }
+  }
+
   /** 关掉一个代理服务：先拒绝新连接，再强断旧连接，最多等 500ms，绝不挂死。 */
   async function closeServer(server) {
     if (!server) return
@@ -314,11 +617,46 @@ export function apply(ctx, config = {}) {
           return json(res, 400, { ok: false, error: "action 只能是 'start' 或 'stop'" })
         },
       },
+      {
+        kind: 'exact',
+        path: '/api/dsh-mesh-access/tunnel',
+        handler: async (req, res) => {
+          if (req.method === 'GET') {
+            const t = tunnelCfg()
+            const host = t.domain || t.serverAddr
+            const port = t.domain ? 443 : t.remotePort
+            const snap = tunnelSnapshot()
+            const reachable = await probe(host, port)
+            // external：公网已经通了，但 frpc 不是这个进程拉起来的（用户自己的 systemd 单元在跑）
+            return json(res, 200, { ok: true, ...snap, reachable, external: reachable && !snap.running })
+          }
+          if (req.method !== 'POST') return json(res, 405, { ok: false, error: 'GET or POST only' })
+          let body = {}
+          try {
+            body = JSON.parse((await readBody(req)) || '{}')
+          } catch {
+            return json(res, 400, { ok: false, error: 'body 不是合法 JSON' })
+          }
+          const action = String(body.action ?? '')
+          if (action === 'start') return json(res, 200, await startTunnel())
+          if (action === 'stop') return json(res, 200, await stopTunnel())
+          if (action === 'config') {
+            try {
+              writeTunnelConfig(body)
+            } catch (err) {
+              return json(res, 400, { ok: false, error: String(err?.message ?? err) })
+            }
+            return json(res, 200, { ok: true, ...tunnelSnapshot() })
+          }
+          return json(res, 400, { ok: false, error: "action 只能是 'start' 或 'stop'" })
+        },
+      },
     ]
     const disposers = routes.map((route) => ctx.webServer.register(route))
     return () => {
       for (const d of disposers) d()
       void stop()
+      void stopTunnel()
     }
-  }, 'dsh-mesh-access: routes + proxy')
+  }, 'dsh-mesh-access: routes + proxy + tunnel')
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mesh-access",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "Control your DSH from your phone: opens a port on the mesh/VPN interface from inside the running server process, so a phone browser gets the same instance and the same session list — no SSH, no second dsh. Also reachable from another PC, a GUI NAS, or a TV box.",
   "type": "module",
   "main": "lib/index.js",
@@ -25,7 +25,8 @@
     "LICENSE",
     "docs",
     "screenshots.json",
-    "assets"
+    "assets",
+    "tools"
   ],
   "engines": {
     "node": ">=22"

package/tools/frpc-setup.sh

@@ -0,0 +1,147 @@
+#!/usr/bin/env bash
+# frpc-setup.sh —— 在**你自己的电脑**（跑 DSH 的那台）上装 frpc，把面板开出来的
+# 组网端口（默认 192.168.188.1:3081）挂到你自己服务器的公网入口上。
+#
+# 用法：
+#   ./tools/frpc-setup.sh --server 1.2.3.4 --token <token> [--port 7000] [--remote-port 21081]
+#                         [--local 192.168.188.1:3081] [--domain dsh.example.com] [--no-service]
+#
+# 不带参数跑会进入问答模式。写完之后 DSH 面板的「公网隧道」卡片会自动认到这份配置。
+set -uo pipefail
+
+FRP_VERSION="${FRP_VERSION:-0.72.0}"
+SERVER=""
+BIND_PORT=7000
+REMOTE_PORT=21081
+TOKEN=""
+LOCAL="192.168.188.1:3081"
+DOMAIN=""
+SERVICE=1
+BIN_DIR="${HOME}/.local/bin"
+CONF="${HOME}/.config/frp/frpc.toml"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --server) SERVER="$2"; shift 2 ;;
+    --port) BIND_PORT="$2"; shift 2 ;;
+    --remote-port) REMOTE_PORT="$2"; shift 2 ;;
+    --token) TOKEN="$2"; shift 2 ;;
+    --local) LOCAL="$2"; shift 2 ;;
+    --domain) DOMAIN="$2"; shift 2 ;;
+    --no-service) SERVICE=0; shift ;;
+    -h|--help) sed -n '2,16p' "$0"; exit 0 ;;
+    *) echo "未知参数：$1（--help 看用法）" >&2; exit 2 ;;
+  esac
+done
+
+say() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+ok()  { printf '  \033[32m✔\033[0m %s\n' "$*"; }
+warn(){ printf '  \033[33m!\033[0m %s\n' "$*"; }
+die() { printf '  \033[31m✘\033[0m %s\n' "$*" >&2; exit 1; }
+
+ask() { # ask <变量名> <提示> [默认值]
+  local __var="$1" __prompt="$2" __def="${3:-}" __ans=""
+  if [ -t 0 ]; then
+    printf '%s%s: ' "$__prompt" "${__def:+（默认 $__def）}"
+    read -r __ans
+  fi
+  [ -n "$__ans" ] || __ans="$__def"
+  printf -v "$__var" '%s' "$__ans"
+}
+
+[ -n "$SERVER" ] || ask SERVER "服务器地址（IP 或域名）"
+[ -n "$TOKEN" ]  || ask TOKEN  "token（服务端 /etc/frp/frps.toml 里的 auth.token）"
+[ -n "$SERVER" ] || die "服务器地址不能为空"
+[ -n "$TOKEN" ]  || die "token 不能为空"
+
+LOCAL_IP="${LOCAL%%:*}"
+LOCAL_PORT="${LOCAL##*:}"
+
+say "[1/4] 装 frpc v${FRP_VERSION}"
+case "$(uname -m)" in
+  x86_64|amd64) FRP_ARCH=amd64 ;;
+  aarch64|arm64) FRP_ARCH=arm64 ;;
+  armv7l) FRP_ARCH=arm ;;
+  *) die "不认识的架构：$(uname -m)" ;;
+esac
+if command -v frpc >/dev/null; then
+  ok "已有 frpc：$(command -v frpc)（$(frpc --version 2>/dev/null || echo 版本未知)）"
+else
+  mkdir -p "$BIN_DIR"
+  TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+  NAME="frp_${FRP_VERSION}_linux_${FRP_ARCH}.tar.gz"
+  URL="https://github.com/fatedier/frp/releases/download/v${FRP_VERSION}/${NAME}"
+  fetch() {
+    if command -v curl >/dev/null; then curl -fL --retry 3 --connect-timeout 10 -o "$TMP/$NAME" "$1"
+    else wget -q -O "$TMP/$NAME" "$1"; fi
+  }
+  fetch "$URL" || { warn "直连 GitHub 失败，改用加速镜像"; fetch "https://gh-proxy.com/${URL}" || die "下载 frpc 失败"; }
+  tar -xzf "$TMP/$NAME" -C "$TMP" || die "解包失败，包可能不完整"
+  B="$(find "$TMP" -maxdepth 2 -type f -name frpc | head -1)"
+  [ -n "$B" ] || die "包里没有 frpc"
+  install -m 755 "$B" "$BIN_DIR/frpc"
+  ok "frpc → $BIN_DIR/frpc"
+fi
+
+say "[2/4] 写 $CONF"
+mkdir -p "$(dirname "$CONF")"
+umask 077
+cat > "$CONF" <<EOF
+# 由 frpc-setup.sh 生成
+serverAddr = "${SERVER}"
+serverPort = ${BIND_PORT}
+
+auth.method = "token"
+auth.token = "${TOKEN}"
+
+log.to = "${HOME}/.config/frp/frpc.log"
+log.level = "info"
+
+[[proxies]]
+name = "dsh-mesh"
+type = "tcp"
+localIP = "${LOCAL_IP}"
+localPort = ${LOCAL_PORT}
+remotePort = ${REMOTE_PORT}
+transport.useEncryption = true
+EOF
+chmod 600 "$CONF"
+ok "配置写入 $CONF（600）"
+
+say "[3/4] 校验组网端口在听"
+if ss -Hltn 2>/dev/null | grep -q "${LOCAL_IP}:${LOCAL_PORT}\b"; then
+  ok "${LOCAL_IP}:${LOCAL_PORT} 在监听"
+else
+  warn "${LOCAL_IP}:${LOCAL_PORT} 还没监听 —— 先去 DSH 面板点「在组网地址上开端口」，再回来启动 frpc"
+fi
+
+if [ "$SERVICE" = "1" ] && command -v systemctl >/dev/null; then
+  say "[4/4] systemd 用户单元（不 enable，只按需 start；插件自己也能拉起 frpc）"
+  mkdir -p "$HOME/.config/systemd/user"
+  cat > "$HOME/.config/systemd/user/dsh-frpc.service" <<EOF
+[Unit]
+Description=frpc for dsh-mesh-access
+
+[Service]
+Type=simple
+ExecStart=${BIN_DIR}/frpc -c ${CONF}
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+EOF
+  systemctl --user daemon-reload 2>/dev/null || true
+  ok "单元已写：dsh-frpc.service（systemctl --user start dsh-frpc）"
+else
+  say "[4/4] 跳过 systemd（--no-service 或没有 systemctl）"
+fi
+
+say "搞定"
+cat <<EOF
+  手动启动（前台看日志）: ${BIN_DIR}/frpc -c ${CONF}
+  或后台              : systemctl --user start dsh-frpc
+  公网地址            : ${DOMAIN:+https://${DOMAIN}/}${DOMAIN:-http://${SERVER}:${REMOTE_PORT}/}
+
+之后在 DSH 左侧「组网访问」面板看「公网隧道」卡片：状态应是 frpc 运行中 + 公网可达。
+EOF

package/tools/frps-setup.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# frps-setup.sh —— 在你**自己的**服务器上装 frps（公网入口），给 dsh-mesh-access 用。
+#
+# 用法（在服务器上、用 root 或能 sudo 的账号执行）：
+#   sudo ./frps-setup.sh --port 7000 --http-port 21081
+#   sudo ./frps-setup.sh --port 7000 --http-port 21081 --domain dsh.example.com --email you@example.com
+#
+# 它会：
+#   1. 装 frps（v0.72.0，从 GitHub 取；失败可加 --mirror 用 gh-proxy）
+#   2. 写 /etc/frp/frps.toml（随机 token，权限 600）
+#   3. 建 systemd 单元并启动（开机自启）
+#   4. 放行 firewalld / ufw 的 bindPort 与 http-port（有才放）
+#   5. 给了 --domain 且本机有 nginx：写反代 + 申请 Let's Encrypt 证书 + Basic 认证
+#
+# 结束时打印：token、bindPort、remotePort、以及本机要执行的 frpc-setup 命令。
+set -uo pipefail
+
+FRP_VERSION="${FRP_VERSION:-0.72.0}"
+BIND_PORT=7000
+HTTP_PORT=21081
+DOMAIN=""
+EMAIL=""
+TOKEN=""
+MIRROR=0
+BASIC_USER="dsh"
+BASIC_PASS=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --port) BIND_PORT="$2"; shift 2 ;;
+    --http-port) HTTP_PORT="$2"; shift 2 ;;
+    --domain) DOMAIN="$2"; shift 2 ;;
+    --email) EMAIL="$2"; shift 2 ;;
+    --token) TOKEN="$2"; shift 2 ;;
+    --mirror) MIRROR=1; shift ;;
+    -h|--help) sed -n '2,20p' "$0"; exit 0 ;;
+    *) echo "未知参数：$1（--help 看用法）" >&2; exit 2 ;;
+  esac
+done
+
+say() { printf '\n\033[1m%s\033[0m\n' "$*"; }
+ok()  { printf '  \033[32m✔\033[0m %s\n' "$*"; }
+warn(){ printf '  \033[33m!\033[0m %s\n' "$*"; }
+die() { printf '  \033[31m✘\033[0m %s\n' "$*" >&2; exit 1; }
+
+[ "$(id -u)" = "0" ] || die "要用 root 跑（sudo ./frps-setup.sh …）"
+command -v systemctl >/dev/null || die "没有 systemd，这个脚本不支持你的发行版"
+
+ARCH="$(uname -m)"
+case "$ARCH" in
+  x86_64|amd64) FRP_ARCH=amd64 ;;
+  aarch64|arm64) FRP_ARCH=arm64 ;;
+  armv7l) FRP_ARCH=arm ;;
+  *) die "不认识的架构：$ARCH" ;;
+esac
+
+say "[1/5] 装 frps v${FRP_VERSION} (${FRP_ARCH})"
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+NAME="frp_${FRP_VERSION}_linux_${FRP_ARCH}.tar.gz"
+URL="https://github.com/fatedier/frp/releases/download/v${FRP_VERSION}/${NAME}"
+fetch() {
+  local u="$1"
+  if command -v curl >/dev/null; then curl -fL --retry 3 --connect-timeout 10 -o "$TMP/$NAME" "$u"
+  else wget -q -O "$TMP/$NAME" "$u"; fi
+}
+if ! fetch "$URL"; then
+  warn "直连 GitHub 失败，改用加速镜像"
+  fetch "https://gh-proxy.com/${URL}" || die "下载 frp 失败：$URL"
+fi
+# 只认 tar 里真有两个二进制，避免拿到半截文件（GitHub 偶发截断）
+tar -xzf "$TMP/$NAME" -C "$TMP" || die "解包失败，包可能不完整"
+BIN="$(find "$TMP" -maxdepth 2 -type f -name frps | head -1)"
+[ -n "$BIN" ] || die "包里没有 frps"
+install -m 755 "$BIN" /usr/local/bin/frps
+ok "frps → /usr/local/bin/frps（$(/usr/local/bin/frps --version 2>/dev/null || echo '版本未知')）"
+
+say "[2/5] 写 /etc/frp/frps.toml"
+mkdir -p /etc/frp /var/log/frp
+[ -n "$TOKEN" ] || TOKEN="$(head -c 18 /dev/urandom | base64 | tr -d '/+=' | head -c 24)"
+umask 077
+cat > /etc/frp/frps.toml <<EOF
+# 由 frps-setup.sh 生成。token 是这台服务器的唯一凭据，别公开。
+bindPort = ${BIND_PORT}
+
+auth.method = "token"
+auth.token = "${TOKEN}"
+
+log.to = "/var/log/frp/frps.log"
+log.level = "info"
+log.maxDays = 7
+
+# 本机管理面板，只监听回环
+webServer.addr = "127.0.0.1"
+webServer.port = 7500
+webServer.user = "admin"
+webServer.password = "admin"
+EOF
+chmod 600 /etc/frp/frps.toml
+ok "配置写入 /etc/frp/frps.toml（600）"
+
+say "[3/5] systemd 单元"
+cat > /etc/systemd/system/frps.service <<'EOF'
+[Unit]
+Description=frp server (dsh-mesh-access public entry)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/frps -c /etc/frp/frps.toml
+Restart=always
+RestartSec=3
+LimitNOFILE=1048576
+
+[Install]
+WantedBy=multi-user.target
+EOF
+systemctl daemon-reload
+systemctl enable --now frps.service >/dev/null 2>&1 || warn "frps 启动失败，看 journalctl -u frps -n 50"
+sleep 1
+if systemctl is-active --quiet frps.service; then ok "frps 已运行"; else warn "frps 没起来，看 journalctl -u frps -n 50"; fi
+ss -Hltn 2>/dev/null | grep -q ":${BIND_PORT}\b" && ok "监听 :${BIND_PORT}" || warn "没看到 :${BIND_PORT} 在监听"
+
+say "[4/5] 防火墙"
+if command -v firewall-cmd >/dev/null && firewall-cmd --state >/dev/null 2>&1; then
+  firewall-cmd --permanent --add-port=${BIND_PORT}/tcp >/dev/null && firewall-cmd --reload >/dev/null && ok "firewalld 放行 ${BIND_PORT}/tcp"
+elif command -v ufw >/dev/null && ufw status 2>/dev/null | grep -q active; then
+  ufw allow ${BIND_PORT}/tcp >/dev/null && ok "ufw 放行 ${BIND_PORT}/tcp"
+else
+  warn "没有活动的 firewalld / ufw，跳过（云厂商安全组仍需自己放行）"
+fi
+warn "别忘了在云控制台「安全组 / 防火墙」放行 ${BIND_PORT}/tcp 和 ${HTTP_PORT}/tcp"
+
+if [ -n "$DOMAIN" ]; then
+  say "[5/5] nginx + TLS + Basic 认证（${DOMAIN}）"
+  if ! command -v nginx >/dev/null; then
+    warn "没装 nginx，跳过；先 dnf/apt install nginx 再重跑本脚本加 --domain"
+  else
+    mkdir -p /var/www/acme
+    cat > /etc/nginx/conf.d/dsh-acme.conf <<EOF
+server {
+    listen 80;
+    server_name ${DOMAIN};
+    location /.well-known/acme-challenge/ { root /var/www/acme; }
+    location / { return 301 https://\$host\$request_uri; }
+}
+EOF
+    nginx -t >/dev/null 2>&1 && systemctl reload nginx
+    if [ ! -f "/etc/letsencrypt/live/${DOMAIN}/fullchain.pem" ]; then
+      if command -v certbot >/dev/null; then
+        certbot certonly --webroot -w /var/www/acme -d "$DOMAIN" --non-interactive --agree-tos \
+          ${EMAIL:+--email "$EMAIL"} ${EMAIL:---register-unsafely-without-email} >/dev/null 2>&1 \
+          && ok "证书已签发" || warn "certbot 失败，看 /var/log/letsencrypt/letsencrypt.log"
+      else
+        warn "没有 certbot：dnf install certbot / apt install certbot 后重跑本脚本"
+      fi
+    else
+      ok "证书已存在，复用"
+    fi
+    BASIC_PASS="$(head -c 12 /dev/urandom | base64 | tr -d '/+=' | head -c 14)"
+    if command -v openssl >/dev/null; then
+      printf '%s:%s\n' "$BASIC_USER" "$(openssl passwd -6 "$BASIC_PASS")" > /etc/nginx/.dsh_htpasswd
+      # 属主必须是跑 nginx worker 的那个用户，否则 error log 报 Permission denied、页面 500
+      chown "root:$(id -gn nginx 2>/dev/null || echo nginx)" /etc/nginx/.dsh_htpasswd 2>/dev/null || true
+      chmod 640 /etc/nginx/.dsh_htpasswd
+    fi
+    cat > /etc/nginx/conf.d/dsh-https.conf <<EOF
+server {
+    listen 443 ssl;
+    http2 on;
+    server_name ${DOMAIN};
+
+    ssl_certificate     /etc/letsencrypt/live/${DOMAIN}/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/${DOMAIN}/privkey.pem;
+
+    # 浏览器弹窗式登录：挡掉所有没带账号密码的请求
+    auth_basic "DSH";
+    auth_basic_user_file /etc/nginx/.dsh_htpasswd;
+
+    client_max_body_size 64m;
+
+    location / {
+        proxy_pass http://127.0.0.1:${HTTP_PORT};
+        proxy_http_version 1.1;
+        # WebSocket（DSH 的实时通道）
+        proxy_set_header Upgrade \$http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host 127.0.0.1:${HTTP_PORT};
+        proxy_set_header X-Forwarded-Proto https;
+        proxy_buffering off;
+        proxy_request_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+}
+EOF
+    if nginx -t >/dev/null 2>&1; then systemctl reload nginx; ok "nginx 反代已生效"; else warn "nginx 配置校验失败：nginx -t"; fi
+  fi
+else
+  say "[5/5] 跳过域名/TLS（没给 --domain）"
+fi
+
+say "记下来（本机 frpc 要用）"
+printf '  服务器地址 : %s\n' "$(curl -fsS --max-time 5 https://api.ipify.org 2>/dev/null || echo '<你的公网IP>')"
+printf '  bindPort   : %s\n' "$BIND_PORT"
+printf '  remotePort : %s\n' "$HTTP_PORT"
+printf '  token      : %s\n' "$TOKEN"
+[ -n "$DOMAIN" ] && printf '  域名       : %s（https://%s/）\n' "$DOMAIN" "$DOMAIN"
+[ -n "$BASIC_PASS" ] && printf '  网页账号   : %s / %s\n' "$BASIC_USER" "$BASIC_PASS"
+
+say "下一步（在你自己的电脑上跑）"
+cat <<EOF
+  ./tools/frpc-setup.sh \\
+    --server <上面那个服务器地址> --port ${BIND_PORT} \\
+    --token ${TOKEN} --remote-port ${HTTP_PORT}${DOMAIN:+ --domain ${DOMAIN}}
+EOF
+echo "然后在 DSH 的「组网访问」面板点「启动隧道」。"