dsh-mobile 0.5.5 → 0.6.0

package/docs/CADDY_MANAGED.en.md

@@ -0,0 +1,39 @@
+# Managed Caddy
+
+[中文](CADDY_MANAGED.md)
+
+> Managed mode and its isolated tests are integrated, but no pinned component has been published. Installation and connection remain disabled. Existing external HTTPS proxy mode is unaffected.
+
+## Requirements
+
+Managed Caddy manages an HTTPS proxy and certificates; it is not a NAT traversal service. You need a domain with Tencent Cloud DNSPod DNS, a reachable public inbound port, and router forwarding to the DSH computer. DNS-01 cannot bypass CGNAT, campus isolation, or an unavailable inbound route. Use Cloudflare Tunnel, cpolar, or FRP on an existing VPS for those networks.
+
+```text
+Android App / browser → public HTTPS hostname (Caddy terminates TLS)
+                      → dedicated HTTP Gateway on 127.0.0.1
+                      → current DSH WebServer
+```
+
+## Relationship to an external proxy
+
+These are upstream modes of the same own-proxy provider. External mode remains the default: you manage Lucky, Nginx, or Caddy, and the plugin provides the HTTP backend. Managed mode owns a separate Caddy child and loopback Gateway, stopping the previous mode before starting the next. External proxy settings and paired-device records are retained, never overwritten by managed settings.
+
+Configure the public HTTPS origin, DNS-01 credentials and local HTTPS port separately. The public URL can use port 443 while the router forwards to local port 8443; the local port is what Caddy actually binds. This mode reserves 3080, 3443 and 3444, so they cannot be selected; check that any other selected port is unused. Use a least-privilege DNS credential restricted to the required zone, not an account-wide cloud master key.
+
+## Installation, startup, and readiness
+
+Once pinned assets are published, installation requires explicit download confirmation. The plugin verifies exact length, SHA-256, Caddy core version, and DNS module version; unavailable or invalid assets are not executed. Installed is not ready: after parsing the local configuration, the proxy starts, and readiness requires verified public HTTPS and discovery identifying the current DSH instance.
+
+Initial DNS-01 issuance waits for DNS propagation and certificate issuance. Keep the computer online and avoid repeated restarts that can trigger issuer limits. Managed mode creates no system service, PATH entry, startup item, or system trust-store certificate. Caddy's admin API and configuration autosave are disabled.
+
+## Privacy and cleanup
+
+Settings and DNS credentials are atomically stored in the plugin's private directory. The Caddyfile contains environment placeholders, never the credentials. The child receives only necessary DNS credentials and runtime environment, not unrelated API secrets, proxy overrides, or admin-address overrides. Raw DNS module logs are not retained. Certificates, private keys, configuration caches, and runtime files also stay in the private directory.
+
+Stopping access or changing provider waits for Caddy and Gateway termination, retaining settings. Confirming removal deletes the managed binary, DNS credentials, certificate keys, logs, and caches without deleting other providers, LAN settings, or paired-device data. Existing manually installed proxies are not owned or uninstalled by the plugin.
+
+## Maintainer build and validation
+
+`scripts/build-caddy-component.mjs` fixes Go 1.26.6, xcaddy v0.4.7, Caddy v2.11.6, and the Tencent Cloud DNS module v0.4.3. It generates the executable, exact size and SHA-256, version/module records, and licenses for embedded dependencies. `caddy-component.yml` produces review artifacts only: no Release creation, production pin changes, or automatic publication.
+
+The public custom-download endpoint returned v2.11.7 when v2.11.6 was requested; a dynamic latest endpoint cannot serve as a fixed-version artifact. Before enabling production installation, publish reviewed builds at immutable versioned URLs and populate the production verification table. All platforms remain disabled until then. Isolated tests use ephemeral loopback listeners and a test CA that is not installed in the system trust store to verify TLS, pairing authentication, raw API bytes, and WebSockets. They do not establish real DNS-01 issuance or public-route readiness.

package/docs/CADDY_MANAGED.md

@@ -0,0 +1,39 @@
+# 托管 Caddy
+
+[English](CADDY_MANAGED.en.md)
+
+> 托管模式的代码和隔离测试已接入；固定组件尚未正式分发，当前安装和连接按钮保持禁用。已有的自备 HTTPS 反向代理模式不受影响。
+
+## 适用条件
+
+托管 Caddy 为自建连接管理 HTTPS 代理和证书，不提供内网穿透。你需要自己的域名、由腾讯云 DNSPod 管理的 DNS，以及可从公网访问的入站端口；路由器需把公网端口映射到运行 DSH 的电脑。CGNAT、校园网隔离或没有入站权限的网络不能仅靠 DNS-01 绕过限制，可以使用 Cloudflare Tunnel、cpolar，或已有 VPS 上的 FRP。
+
+```text
+Android App / 浏览器 → 公网 HTTPS 域名（Caddy 终止 TLS）
+                  → 127.0.0.1 上的独立 HTTP Gateway
+                  → 当前 DSH WebServer
+```
+
+## 与自备反向代理的关系
+
+两者属于「自备反向代理」提供方的不同上游模式。默认仍为自备代理：你维护 Lucky、Nginx 或 Caddy，插件只提供 HTTP 后端。切换为托管模式后，插件拥有一个独立的 Caddy 子进程和回环 Gateway，先停止旧模式再启动新模式；原有代理配置和已配对设备记录保留，不会被托管配置覆盖。
+
+公网入口、DNS-01 凭据与本机 HTTPS 端口需单独配置。公网 URL 可以使用 443，而路由器转发到本机 8443；「本机 HTTPS 端口」是 Caddy 实际绑定的端口。3080、3443、3444 在此模式中保留，不可选择；其他端口仍需确认未被占用。DNS-01 凭据应使用仅能管理目标 DNS 区域的最小权限账号，不要提供云账号的主密钥。
+
+## 安装、启动与就绪
+
+固定组件正式分发后，安装需要你明确确认下载。插件检查完整大小、SHA-256、Caddy 核心版本和 DNS 模块版本；来源不可用或验证失败时不执行文件。组件已安装不等于连接就绪：本地配置完成解析后启动代理，只有公网 HTTPS 证书通过验证，并确认 discovery 属于当前 DSH 实例，才显示已就绪。
+
+首次 DNS-01 签发需要等待 DNS 生效和证书签发。期间电脑保持在线，避免反复重启触发签发限流。托管模式不安装系统服务、不修改 PATH、不设置开机启动、不导入系统证书；Caddy 的管理 API 和自动配置落盘均关闭。
+
+## 隐私与清理
+
+设置与 DNS 凭据原子保存在插件私有目录，Caddyfile 只包含环境变量占位符。子进程只获得必要的 DNS 凭据和运行环境，不继承其他 API 密钥或代理、管理口配置；原始 DNS 模块日志不保存。证书、私钥、配置缓存和运行文件也保存在该私有目录。
+
+停止访问或切换提供方会等待 Caddy 与 Gateway 退出，但保留设置。确认「移除托管 Caddy 与配置」后删除受管二进制、DNS 凭据、证书私钥、日志与缓存，不删除其他提供方、局域网或设备配对数据。已有手动安装的代理不归插件所有，也不会被插件卸载。
+
+## 维护者构建与验证
+
+`scripts/build-caddy-component.mjs` 使用 Go 1.26.6、xcaddy v0.4.7、Caddy v2.11.6 和腾讯云 DNS 模块 v0.4.3，生成二进制、完整大小与 SHA-256、版本/模块记录和嵌入依赖许可证清单。`caddy-component.yml` 仅产生 CI 审查产物，不创建 Release、不修改生产组件表、不自动发布。
+
+公开定制下载端点曾在请求 v2.11.6 时返回 v2.11.7，所以不能将动态「最新版」端点当作固定版本资产。正式开放前必须将审核通过的构建放到不可变版本化分发地址，并补齐生产校验数据；目前所有平台都保持禁用。隔离测试使用回环随机端口和不导入系统信任库的测试 CA，验证 TLS、配对认证、API 原始数据与 WebSocket，不等同于真实 DNS-01 或公网路由验收。

package/docs/CLIENT_MODULES.en.md

@@ -0,0 +1,33 @@
+# Mobile page modules
+
+[中文](CLIENT_MODULES.md) · [Back to README](../README.en.md#060-update)
+
+> DSH Mobile 0.6.0 provides module management in General settings. Update the plugin and app together.
+
+Choose which client components the dedicated mobile page loads. This does not uninstall computer plugins, stop their services, or restrict device permissions. A paired device remains a trusted DSH operator.
+
+## Computer defaults and this device
+
+- On the **computer: Settings → General → Mobile page modules → Manage**, set defaults for this computer's mobile access. Enable a LAN or remote access entry first so the current DSH module catalog can be read.
+- On the **phone: Settings → General → Mobile page modules → Manage**, override only the currently authenticated paired device. This cannot change another phone or the computer default.
+
+Selection precedence is: device override → computer default → the profile's `excludedClientModules` configuration. Without custom selections, no modules are excluded. LAN and remote entries share the computer default. Device overrides belong to pairing identities; independent LAN and remote pairings on the same phone do not automatically share an override.
+
+**Restore defaults** on a phone removes its override and uses the computer default. On the computer, it removes the computer override and uses plugin configuration. Other device overrides are retained.
+
+## Choose and apply
+
+1. Wait for the catalog to load. A failed read leaves saving disabled; close and reopen to retry.
+2. Checked means loaded; unchecked means omitted next time. Required boot modules cannot be unchecked, and other rows show declared dependencies.
+3. Select **Save for next open**. Saving rejects a retained module that depends on an excluded module and identifies the conflict: keep the dependency, or also exclude its dependent if it is not needed. Unknown module IDs are rejected too.
+4. After a successful save, the current page, conversation, and draft are not reloaded automatically. Manually reopen or refresh the DSH page to apply the selection; saving through this control does not require a DSH restart.
+
+Computer pages and `?frontend=stock` pages are unaffected. DSH or community-plugin updates can change the catalog and dependencies. When a saved selection prevents the mobile page from starting, the page offers “Load all modules for this device and retry”; it changes this device’s selection only when you click, without changing computer defaults, other devices or pairing authorization. Settings APIs still reject invalid selections and enforce required-module and dependency checks. Module sizes depend on the installation, so no fixed traffic reduction is promised.
+
+## Data and authorization
+
+Selections are atomically stored in the computer's private DSH Mobile data directory, without copying conversation drafts. The catalog returns only module IDs, required markers, dependencies, and selections—not upstream download URLs, host file paths, or pairing credentials. A phone reads its own selection through the authenticated Gateway; changes also require same-origin and CSRF checks.
+
+Revoking a pairing removes that identity's module override. To stop a phone from operating the computer, revoke the device on the computer rather than disabling one client component.
+
+Direct edits to the profile's advanced configuration still require a DSH restart. See [Third-party plugin compatibility](../README.en.md#third-party-plugin-compatibility) for examples and limits.

package/docs/CLIENT_MODULES.md

@@ -0,0 +1,33 @@
+# 移动页面模块
+
+[English](CLIENT_MODULES.en.md) · [返回 README](../README.md#060-更新)
+
+> DSH Mobile 0.6.0 在通用设置中提供模块管理入口；请同步更新插件与 App。
+
+用“移动页面模块”选择专用移动页面要加载的客户端组件。它不卸载电脑上的插件，不停止插件服务，也不是设备权限隔离；已配对设备仍是受信任的 DSH 操作者。
+
+## 电脑默认与本设备选择
+
+- **电脑端：设置 → 通用设置 → 移动页面模块 → 管理**，修改此电脑的移动访问默认加载项。先开启一个局域网或远程访问入口，才能读取当前 DSH 的模块目录。
+- **手机端：设置 → 通用设置 → 移动页面模块 → 管理**，只修改当前已认证配对设备的覆盖选择，不能修改其他手机或电脑默认。
+
+有效选择依次为：本设备覆盖 → 电脑默认 → profile 中的 `excludedClientModules` 配置。没有这些自定义设置时不排除模块。电脑默认由局域网与远程入口共用；设备覆盖按配对身份保存，同一手机的独立局域网和远程配对不会自动共用一个覆盖。
+
+手机的“恢复默认”删除自己的覆盖，重新使用电脑默认；电脑的“恢复默认”删除电脑覆盖，重新使用插件配置。其他设备的覆盖保持不变。
+
+## 选择与生效
+
+1. 等待目录读取完成；无法读取时不能保存，关闭后重新打开可重试。
+2. 勾选表示加载，取消勾选表示下次不加载。启动必需模块不能取消；其余条目显示已声明的依赖。
+3. 点击“保存，下次打开生效”。若保留模块仍依赖已排除模块，保存会拒绝并说明冲突：保留依赖，或同时排除不再需要的依赖方。不存在的模块也不能保存。
+4. 保存成功后，当前页面、会话和草稿不会被自动刷新。下次手动重新打开或刷新 DSH 页面时应用选择，无需为设置入口的保存重启 DSH。
+
+电脑页面与 `?frontend=stock` 页面不受模块选择影响。DSH 或社区插件更新可能改变模块目录和依赖；已保存的选择阻止移动页面启动时，页面提供“为本设备加载全部模块并重试”，由你点击后恢复本设备的加载选择，不改变电脑默认、其他设备或配对授权。设置接口仍拒绝无效选择，不绕过启动必需或依赖检查。模块大小因安装环境而异，不承诺固定的加载流量节省比例。
+
+## 数据与授权
+
+选择原子保存在电脑的 DSH Mobile 私有数据目录，不复制会话草稿。目录接口只返回模块 ID、必需标记、依赖和选择，不返回上游下载 URL、本机文件路径或配对凭据。手机只能通过已认证的 Gateway 读取自己的选择；修改还需同源和 CSRF 校验。
+
+撤销配对授权会移除该授权的模块覆盖。要停止某台手机操作电脑，请在电脑端撤销设备，而不是只关闭一个客户端模块。
+
+直接修改 profile 中的高级配置仍需重启 DSH；配置示例与限制见 [第三方插件适配](../README.md#第三方插件适配)。

package/docs/CLOUDFLARE_TUNNEL.en.md

@@ -12,24 +12,30 @@ The built-in cloudflared provider runs in one of two modes, chosen in the panel
 | Availability | Officially for testing: rate-limited, no uptime guarantee | Carried by your own Cloudflare account |
 | Settings | None | Connector token, public hostname, local forward port |
 
-Cloudflare terminates DNS and TLS for the public hostname. The plugin only runs `cloudflared` locally and hands traffic to its authenticated private gateway, so **the phone still pairs through the app's Remote access flow** — a tunnel does not change how devices pair.
+Cloudflare provides the public hostname and TLS. The plugin runs `cloudflared` locally and forwards requests to its paired-device gateway. Select **Remote access** in the Android app; a mobile browser can also use the public HTTPS pairing link. The tunnel does not replace DSH Mobile pairing.
+
+## Quick tunnel feature limits
+
+[Cloudflare's official limits](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations) include no uptime guarantee, up to 200 in-flight requests and no SSE. DSH Mobile uses SSE for extension changes, task completion and online revocation events. Quick-tunnel extension updates fall back to periodic checks; completion notifications and immediate revocation notices may not arrive, and missed completion events are not replayed. Server-side revocation still blocks access. For regular use, choose a named tunnel or another channel.
 
 ## Prerequisites
 
 1. A domain already on Cloudflare. Its nameservers must point at the pair Cloudflare assigned, changed at your registrar; that usually takes minutes and up to 24 hours.
-2. Cloudflare Zero Trust (a team domain) enabled, because the tunnel console lives inside it.
+2. A Cloudflare account permitted to manage that domain and Tunnel.
 3. The cloudflared component installed in the panel. Named and quick tunnels share the same official client.
 
 The component supports Windows x64, Linux x64/arm64 and macOS x64/arm64. Official downloads are verified before installation; macOS also verifies the extracted executable. Components remain inside DSH Mobile's private directory.
 
 ## Create the tunnel in the Cloudflare dashboard
 
-1. Open **Zero Trust → Networks → Tunnels** and choose **Create a tunnel** → **Cloudflared**.
-2. Name it, for example `dsh-mobile`, and save; the dashboard then shows a connector install command.
-3. On the **Public Hostname** tab add one entry:
+1. In the Cloudflare dashboard, open **Networking → Tunnels** and create a tunnel named, for example, `dsh-mobile`.
+2. Obtain its Tunnel token from the connector instructions. **Do not run the service-install command**: DSH Mobile manages the verified cloudflared process.
+3. Open **Routes → Add route → Published application** and add a public hostname:
    - Subdomain `dsh`, and pick your domain, giving `dsh.example.com`
    - Service: **HTTP** → `127.0.0.1:3444`
-4. On the **Overview** tab copy the connector token — the long string starting with `eyJ`. It already contains the account, tunnel id and tunnel secret, so **it is a credential**.
+4. Save the route and enter the connector token in the DSH Mobile panel below. It is a credential: never put it in an issue, screenshot or log.
+
+These labels follow [Cloudflare's current official guide](https://developers.cloudflare.com/tunnel/get-started/); older dashboards may call the published route Public Hostname. This setup uses an HTTP loopback Service and does not require disabling TLS verification.
 
 > `127.0.0.1:3444` is the panel's "Local forward port". Cloudflare routes the public hostname to exactly that port, so it must match what you enter in the panel and must not change afterwards.
 
@@ -72,7 +78,7 @@ The old address may show **Address may have changed** or temporarily unreachable
 | Local forward port unavailable | `cloudflared_tunnel_port_unavailable` | The configured port is taken. A named tunnel cannot move to another port, because Cloudflare routes to that exact one: free the port, or pick another and update the Service in Cloudflare to match. |
 | Invalid public hostname | `cloudflared_tunnel_hostname_invalid` | Must be a real hostname under a domain on this account. IP literals, wildcards, `.trycloudflare.com` and `.cfargotunnel.com` are refused. |
 | Invalid forward port | `cloudflared_tunnel_port_invalid` | The port must be between 1024 and 65535. |
-| Reserved forward port | `cloudflared_tunnel_port_reserved` | **3443** cannot be used: it is the DSH Mobile LAN gateway's HTTPS port, held for as long as DSH runs. It is not a transient conflict, so pick 3444 or 3445. |
+| Reserved forward port | `cloudflared_tunnel_port_reserved` | **3443** is the reserved default LAN HTTPS port and is rejected in this mode. Select 3444, 3445 or another allowed, unused port. Reservation does not mean the LAN listener is always active. |
 | Invalid token | `cloudflared_tunnel_token_invalid` | Copy the whole token from the dashboard, with no spaces or newlines. |
 | Settings rejected | `cloudflared_tunnel_settings_invalid` | The request carried a field that does not belong to the mode, such as a port in quick mode. |
 | Token, hostname and port are all required | `cloudflared_tunnel_config_missing` | First-time named-tunnel setup needs all three. |
@@ -95,7 +101,7 @@ The old address may show **Address may have changed** or temporarily unreachable
 ## Troubleshooting
 
 - **Stuck on "connecting"**: the named tunnel becomes ready only after the connector registers with Cloudflare. Check cloudflared output in the DSH log and test DNS, UDP/QUIC and TCP reachability from the computer to a Cloudflare edge.
-- **Public access returns 1033**: Cloudflare believes no connector is healthy for that hostname. Check the tunnel shows Healthy in Zero Trust, and that its ingress port matches the panel.
+- **Public access returns 1033**: Cloudflare sees no healthy connector for the hostname. Confirm the dashboard reports Healthy and the route's Service port matches the panel.
 - **`cloudflared` reports `Unauthorized`, or the tunnel id does not exist**: the token belongs to a different tunnel, for example one that was deleted and recreated. Copy the token again.
 - **The phone stalls on "Loading plugins" or the remote page is slow while a TUN or transparent proxy is active**: check whether a catch-all rule sends `cloudflared` connections to `*.argotunnel.com` through a proxy node. This routing has caused slow boot-resource transfers before; it does not by itself indicate a pairing failure. This Clash-rule example is for Windows; on Linux, adapt the process name and syntax to your proxy client, and put direct-route rules before catch-all rules:
 

package/docs/CLOUDFLARE_TUNNEL.md

@@ -12,24 +12,30 @@
 | 可用性 | 官方定位为测试用途：有限流、无可用性保证 | 由你的 Cloudflare 账号承载 |
 | 配置项 | 无 | 连接器令牌、公网域名、本机转发端口 |
 
-命名隧道的公网域名由 Cloudflare 负责解析与 TLS，插件只负责在本机运行 `cloudflared` 并把流量交给已认证的私有网关；**手机端仍然要走 App 的远程访问扫码流程**，隧道不改变配对方式。
+Cloudflare 提供公网域名与 TLS，插件在本机运行 `cloudflared`，把请求交给有设备配对认证的私有网关。在 Android App 中请选择 **远程访问**；手机浏览器也可打开公开 HTTPS 配对链接。隧道不能替代 DSH Mobile 配对。
+
+## 快速隧道的功能限制
+
+[Cloudflare 官方限制](https://developers.cloudflare.com/tunnel/get-started/quick-tunnels/#limitations)包括无可用性保证、最多 200 个并发进行中的请求，以及不支持 SSE。插件通过 SSE 传递扩展变更、任务完成和在线设备撤销事件：快速隧道中扩展更新会退回定期检测，完成提醒与在线撤销提示可能无法及时送达，没有离线完成事件补发。服务端撤销认证仍然有效；长期使用请选择命名隧道或其他通道。
 
 ## 前置条件
 
 1. 一个已接入 Cloudflare 的域名（该域名的 NS 必须指向 Cloudflare 分配的名称服务器，在域名注册商处修改；改完通常几分钟到 24 小时生效）。
-2. Cloudflare Zero Trust（团队域名）已启用——隧道控制台位于其中。
+2. 可以管理该域名和 Tunnel 的 Cloudflare 账号。
 3. 面板中 cloudflared 组件已安装（命名隧道和快速隧道使用同一个官方客户端）。
 
 组件支持 Windows x64、Linux x64/arm64 与 macOS x64/arm64。所有平台都在安装前校验官方发布文件；macOS 另校验解压后的可执行文件，组件仅保存在 DSH Mobile 私有目录。
 
 ## 在 Cloudflare 控制台创建隧道
 
-1. 打开 **Zero Trust → Networks → Tunnels**，选择 **Create a tunnel**，类型选 **Cloudflared**。
-2. 命名（例如 `dsh-mobile`），保存后会显示 connector 安装命令。
-3. 在 **Public Hostname** 页签添加一条：
+1. 在 Cloudflare 控制台打开 **Networking → Tunnels**，创建隧道并命名，例如 `dsh-mobile`。
+2. 在连接器安装说明中取得 Tunnel token。**不要执行系统服务安装命令**：本插件会管理已校验的 cloudflared 进程。
+3. 打开 **Routes → Add route → Published application**，添加公网主机名：
    - Subdomain：`dsh`，Domain：选你的域名（得到 `dsh.example.com`）
    - Service：**HTTP** → `127.0.0.1:3444`
-4. 回到 **Overview** 页签复制连接器令牌（一长串以 `eyJ` 开头的字符串）。令牌里已经包含账号、隧道 ID 和隧道密钥，**等同于密码**。
+4. 保存路由，再把连接器令牌填写到下节的 DSH Mobile 面板。令牌是凭据，不要发到 issue、截图或日志中。
+
+步骤按 [Cloudflare 当前官方指南](https://developers.cloudflare.com/tunnel/get-started/)核对；旧控制台可能仍将公开路由称为 Public Hostname。此处的 Service 使用 HTTP 回环后端，不需要关闭 TLS 验证。
 
 > `127.0.0.1:3444` 就是面板里的「本机转发端口」。Cloudflare 把公网主机名固定转发到这个端口，所以它必须与面板中填写的端口一致，并且长期不变。
 
@@ -72,7 +78,7 @@
 | 本机转发端口不可用 | `cloudflared_tunnel_port_unavailable` | 配置的端口已被占用。命名隧道不能改用其他端口（Cloudflare 固定转发到该端口），请释放端口或换一个端口并同步修改 Cloudflare 的 Service。 |
 | 公网域名无效 | `cloudflared_tunnel_hostname_invalid` | 必须是本账号下域名的真实主机名；不接受 IP、通配符、`.trycloudflare.com` 与 `.cfargotunnel.com`。 |
 | 转发端口无效 | `cloudflared_tunnel_port_invalid` | 端口需在 1024–65535 之间。 |
-| 转发端口被保留 | `cloudflared_tunnel_port_reserved` | 不能填 **3443**：那是 DSH Mobile 局域网网关的 HTTPS 端口，只要 DSH 在运行就一直被占用，不是"临时被别的程序占了"。请换 3444 或 3445。 |
+| 转发端口被保留 | `cloudflared_tunnel_port_reserved` | **3443** 是保留的默认 LAN HTTPS 端口，此模式不接受它；选择 3444、3445 或其他允许且未占用的端口。保留规则不表示 LAN 始终在监听。 |
 | 令牌无效 | `cloudflared_tunnel_token_invalid` | 令牌需从控制台完整复制，不能有空格或换行。 |
 | 设置未通过校验 | `cloudflared_tunnel_settings_invalid` | 请求里带了不该有的字段（例如快速隧道模式下携带端口）。 |
 | 需要同时填写令牌、域名和端口 | `cloudflared_tunnel_config_missing` | 首次配置命名隧道时三项都必填。 |
@@ -95,7 +101,7 @@
 ## 排错
 
 - **连接一直停在「正在连接」**：命名隧道只有在 connector 向 Cloudflare 注册后才显示就绪。检查 DSH 日志中的 cloudflared 输出，以及本机到 Cloudflare 边缘的 DNS、UDP/QUIC 和 TCP 连通性。
-- **公网访问返回 1033**：Cloudflare 认为该主机名没有健康的 connector。确认隧道在 Zero Trust 里显示 Healthy，且 ingress 指向的端口与面板一致。
+- **公网访问返回 1033**：Cloudflare 认为该主机名没有健康的 connector。确认隧道在控制台显示 Healthy，且路由的 Service 端口与面板一致。
 - **`cloudflared` 报 `Unauthorized` 或隧道 ID 不存在**：令牌与控制台里的隧道不匹配（例如隧道被删除后重建）。重新复制令牌。
 - **手机卡在「正在加载插件」或远程页面明显慢，而本机开着 TUN/透明代理**：先检查 `cloudflared` 到 `*.argotunnel.com` 的连接是否被兜底规则送进代理节点。曾有这种路由导致启动资源传输很慢；它不等于配对失败。以下是 Windows 上 Clash 客户端的规则示例；Linux 的进程名与具体规则语法应按所用客户端调整，并让直连规则排在兜底规则前：
 

package/docs/README.md

@@ -1,29 +1,41 @@
-# DSH Mobile 文档 / Documentation
+# 使用指南 / Documentation
 
-本目录收录需要展开说明的指南。内置的远程通道（Tailscale Funnel、cpolar、cloudflared）为零配置或按需安装，说明见根目录 [README](../README.md#连接教程)，不单独成文；cloudflared 的命名隧道需要在 Cloudflare 控制台建隧道、配公开主机名并取令牌，步骤较多，单独成文。
+第一次使用请先看[快速开始](../README.md#快速开始)和[局域网／远程连接教程](../README.md#连接教程)。这里收录需要进一步配置或排障的专题；不必为了完成首次配对读完所有页面。
 
-## 面向用户 / User guides
+## 已发布功能 / Released features
 
-| 中文 | English | 内容 |
+| 你想做什么 | 中文 | English |
 | --- | --- | --- |
-| [Cloudflare 命名隧道](CLOUDFLARE_TUNNEL.md) | [Cloudflare named tunnel](CLOUDFLARE_TUNNEL.en.md) | 用 Cloudflare 账号令牌把 cloudflared 从随机快速隧道换成固定公网域名 |
-| [自建 FRP 使用指南](SELF_HOSTED_FRP.md) | [Self-hosted FRP guide](SELF_HOSTED_FRP.en.md) | 已有 VPS 时用 frps + Caddy 自建远程通道，避开公共隧道带宽限制 |
-| [接入你既有的 frps](ATTACH_EXISTING_FRPS.md) | [Attach to an existing frps](ATTACH_EXISTING_FRPS.en.md) | 复用 VPS 上已运行的 frps，不自动修改服务器；可选公开 CA + Caddy 或自签 CA + TCP 透传，须核对监听与证书有效期。 |
-| [自有 HTTPS 反向代理](SELF_HOSTED_ORIGIN.md) | [Own HTTPS reverse proxy](SELF_HOSTED_ORIGIN.en.md) | 复用已有的 Lucky / Nginx / Caddy 公网 HTTPS 入口，无需隧道组件 |
-| [慢链路与反复重连](SLOW_CONNECTIONS.md) | [Slow links and repeated reconnection](SLOW_CONNECTIONS.en.md) | 区分 HTTP 与实时连接故障，按需配置 DSH 等待时间或启用 WebSocket 压缩 |
+| 使用 Android App、了解返回键、权限与升级 | [App 手册](../apps/mobile/README.zh-CN.md) | [Android app](../apps/mobile/README.md) |
+| 使用固定 Cloudflare 域名，而非临时随机地址 | [命名隧道](CLOUDFLARE_TUNNEL.md) | [Named tunnel](CLOUDFLARE_TUNNEL.en.md) |
+| 在已有 VPS 上新部署 FRP 与 HTTPS 入口 | [自建 FRP](SELF_HOSTED_FRP.md) | [Self-hosted FRP](SELF_HOSTED_FRP.en.md) |
+| 复用已经运行的 frps，不自动修改服务器 | [接入既有 frps](ATTACH_EXISTING_FRPS.md) | [Existing frps](ATTACH_EXISTING_FRPS.en.md) |
+| 复用 Lucky、Nginx 或 Caddy 的公开 HTTPS 入口 | [自有反向代理](SELF_HOSTED_ORIGIN.md) | [Own reverse proxy](SELF_HOSTED_ORIGIN.en.md) |
+| 页面加载慢、实时连接反复重连或长操作超时 | [慢链路与重连](SLOW_CONNECTIONS.md) | [Slow links and reconnection](SLOW_CONNECTIONS.en.md) |
 
-> 命名隧道与两个自建提供方都要求手机端走 App 的**远程访问**扫码流程；`SELF_HOSTED_ORIGIN.en.md` 是精简版，字段表与排错清单以中文版为准。
+在 Android App 中连接公开隧道或自建入口时请选择 **远程访问**。公开受信任证书也可用手机浏览器配对；既有 frps 的自签入口需要 **0.4.6 或更高版本 App** 固定远程 CA。各通道仍要求 DSH Mobile 配对，不能直接暴露普通 DSH 或私有 HTTP 后端。
 
-> 既有 frps 接入从 0.4.6 起提供；其中自签入口需要 0.4.6 Android App，旧版不能配对。
+## 0.6.0 新增功能 / New features
 
-## 验证记录 / Verification records
+以下指南介绍 0.6.0 的模块管理与局域网高级设置，以及尚未开放安装的托管 Caddy 模式。
 
-| 文档 | 内容 |
-| --- | --- |
-| [DSH 0.1.5 局域网验证记录](DSH_0.1.5_LAN.md) | DSH Mobile 0.3.15 的历史局域网实测；当前版本组合请看[兼容性表](../README.md#兼容性) |
+| 功能 | 中文 | English | 使用状态 |
+| --- | --- | --- | --- |
+| 为移动页面选择加载模块 | [模块设置](CLIENT_MODULES.md) | [Module settings](CLIENT_MODULES.en.md) | 电脑默认与设备覆盖分别保存，不自动刷新会话 |
+| 允许受控路由网络访问 LAN Gateway | [额外可信网段](TRUSTED_NETWORKS.md) | [Trusted networks](TRUSTED_NETWORKS.en.md) | 不建立 VPN，不自动扩大防火墙规则 |
+| 由插件管理 Caddy HTTPS 上游 | [托管 Caddy](CADDY_MANAGED.md) | [Managed Caddy](CADDY_MANAGED.en.md) | 尚无可信固定二进制分发，安装与连接仍禁用 |
+
+## 开发与安全 / Development and security
 
-## 面向维护者 / Maintainer notes
+- [贡献指南](../CONTRIBUTING.md)：本地检查、浏览器与 Android 验证、发布要求。
+- [安全说明](../SECURITY.md)：配对授权、TLS、组件清理与私密漏洞反馈。
+- [贡献记录](../CONTRIBUTORS.md)与[更新记录](../CHANGELOG.md)：分别查看社区参与和版本变化。
 
-维护者文档面向改代码的人，**不随 npm 包发布**，只在仓库中阅读：
+## 历史验证 / Historical records
 
-- [自建 FRP 维护记录](HANDOFF_SELF_HOSTED_FRP.md) —— 0.4.6 开发时的代码地图、安全检查点与历史真机验证；当前使用步骤以本页上方的用户指南为准。
+以下记录保留原来的版本和测试范围，不能当作当前版本或你的网络环境已验证的证明。
+
+| 记录 | 范围 |
+| --- | --- |
+| [DSH 0.1.5 局域网验证](DSH_0.1.5_LAN.md) | 0.3.15 的历史实测；当前组合见[兼容性](../README.md#兼容性) |
+| [FRP 维护交接](HANDOFF_SELF_HOSTED_FRP.md) | 0.4.6 开发时的代码地图与历史证据，仅在仓库阅读，不随 npm 包发布 |

package/docs/SELF_HOSTED_FRP.en.md

@@ -2,7 +2,7 @@
 
 [中文指南](SELF_HOSTED_FRP.md)
 
-This page covers managed deployment, in which the plugin installs frps and Caddy. If your VPS already runs frps, version 0.4.6 can attach to it directly; see the [attachment guide](ATTACH_EXISTING_FRPS.en.md).
+This page covers a new FRP entry, deployed manually or managed by the plugin over SSH. If your VPS already runs frps, plugin 0.4.6 or later can attach to it without deployment; see the [attachment guide](ATTACH_EXISTING_FRPS.en.md).
 
 Self-hosted FRP is for users who already operate a VPS and want to avoid the bandwidth limits of public tunnels. The phone reaches Caddy on the VPS over HTTPS, crosses the encrypted FRP tunnel, and then reaches DSH on the computer. FRP only transports the request; DSH pairing is still required.
 
@@ -18,16 +18,16 @@ Android app
 ## Two entry modes
 
 - **Domain mode**: use your own public domain; Caddy obtains and renews the certificate automatically.
-- **Public IPv4 mode**: use the VPS public IPv4 address directly. The plugin uses Certbot to request a roughly six-day Let's Encrypt IP certificate and installs a daily renewal timer. Documentation ranges such as `203.0.113.10`, private addresses, and other reserved addresses are rejected; enter a real routable public IP.
+- **Public IPv4 mode**: use the VPS public IPv4 directly. The current template uses Certbot for a roughly six-day Let's Encrypt IP certificate. Automatic deployment installs a daily renewal timer; manual deployment requires operator-managed renewal, certificate copying and Caddy reload. Documentation ranges such as `203.0.113.10`, private addresses and reserved addresses are rejected; enter a real routable public IP.
 
 The publicly trusted entry in this guide requires Android app 0.3.3 or later for custom remote origins. The separate self-signed TCP passthrough in the [existing-frps attachment guide](ATTACH_EXISTING_FRPS.en.md) is attach-only and requires the 0.4.6 or later app with remote CA pinning; older apps cannot use that entry and continue to work with LAN, cpolar, and Tailscale.
 
 ## Manual deployment vs automatic deployment
 
-- **Manual deployment**: copy the restricted template from the panel. Save the frps section as `/etc/dsh-mobile/frps.toml`, save the Caddy snippet as `/etc/caddy/dsh-mobile-dsh.caddy`, and add exactly this line to the main Caddyfile: `import /etc/caddy/dsh-mobile-dsh.caddy`. If the Caddyfile does not exist, create one containing only that line. Copying the template changes nothing by itself. Public IPv4 mode also requires the Certbot steps in the template because Caddy cannot issue an IP certificate; domain mode is automatic.
+- **Manual deployment**: install frps and Caddy and configure services and firewalls yourself, then copy the panel's restricted template. Save its frps section as `/etc/dsh-mobile/frps.toml` and Caddy snippet as `/etc/caddy/dsh-mobile-dsh.caddy`. Add `import /etc/caddy/dsh-mobile-dsh.caddy` once to the main Caddyfile without overwriting other sites. Copying or saving a template does not install or start services. This project's public-IPv4 template uses Certbot and requires operator-managed renewal and certificate reload; Caddy manages domain certificates.
 - **Automatic deployment**: enter an SSH user, port, and local private-key path (leave the path empty to use ssh-agent or SSH configuration), then select the one-click deployment action. The VPS must run Ubuntu or Debian with systemd. Only key-based login is accepted; passwords are not supported.
 
-Before deployment, the panel lists every VPS change. It installs Caddy from its official APT source; public IPv4 mode additionally installs a Python virtual environment, Certbot, and the renewal timer. It creates or reuses the `dsh-mobile` system user, the frps service and configuration, the Caddy snippet and one import line, and—when UFW is active—allows the FRP control port plus 80/tcp and 443/tcp. **Your existing Caddy content is never merged or overwritten**: an existing DSH Mobile import is only normalized to one line; another non-empty configuration stops the deployment and asks you to add the import manually.
+Before deployment, the panel lists every VPS change. It installs Caddy from its official APT source; public IPv4 mode additionally installs a Python virtual environment, Certbot and the renewal timer. It creates the frps service/configuration, Caddy snippet and one import line, and allows the FRP control port plus 80/tcp and 443/tcp when UFW is active. An existing `dsh-mobile` system user is reused and retained during cleanup; a user created by this deployment is removed during cleanup. **Your existing Caddy content is never merged or overwritten**: an existing DSH Mobile import is only normalized to one line; another non-empty configuration stops deployment and asks you to add the import manually.
 
 ## Verify the host keys every time
 
@@ -63,12 +63,12 @@ Only public IPv4 mode installs `dsh-mobile-cert-renew.timer`; in that mode, also
 
 On the computer, start with the plugin log at `$DSH_HOME/mobile-access/logs/dsh-mobile.log` (JSONL, 5 MB rotation, tokens and keys redacted) and the panel diagnostic report. Windows antivirus software can quarantine frpc; if it does, create the smallest possible exception for the verified component directory only.
 
-When several computers share one frps, remember that proxy names are unique across the **whole server** and entry ports are first-come, first-served. The plugin registers an installation-derived name (`dsh-mobile-<first 12 characters of the installation identity>`), so two computers no longer compete for the same name. "A proxy with this installation name is already in use" means that name belongs to another computer, or to this computer's previous session before the frps heartbeat expired it; "the entry port is already occupied" means another proxy holds that port, so give this computer a different one. In both cases frpc stays alive without ever publishing the entry port, which is why the panel previously reported only "the public endpoint did not become ready".
+When several computers share one frps, proxy names are unique across the server and entry ports cannot overlap. The plugin uses `dsh-mobile-<first 12 characters of the installation identity>` as its name. A name conflict requires checking another computer or an unexpired old connection; a port conflict requires a different entry port. A running frpc process does not mean the public entry was published: verify the public route.
 
 ## Limits
 
 - An unregistered domain on a mainland-China VPS may be intercepted by the cloud provider; use public IPv4 mode in that case.
-- An IPv4 certificate is short-lived; keep its renewal timer and Caddy service running.
+- An IPv4 certificate is short-lived; keep the automatic deployment's timer or your manual renewal/copy/reload procedure operational.
 - SSH form values are browser-profile state. Changing browsers or clearing site data requires entering them again; private keys and passwords are never stored.
 - VPS SSH targets currently cannot use IPv6.
 - The frps plaintext vhost must bind to `127.0.0.1`. The plugin rejects a publicly reachable plaintext port and reports readiness only after public discovery identifies the current computer.

package/docs/SELF_HOSTED_FRP.md

@@ -2,7 +2,7 @@
 
 [English guide](SELF_HOSTED_FRP.en.md)
 
-本页介绍托管部署（插件安装 frps 与 Caddy）。
+本页介绍新建 FRP 远程入口，可手动部署，也可让插件通过 SSH 托管部署 frps 与 Caddy。
 
 > **已经有一台跑着 frps 的 VPS？** 从 0.4.6 起可直接接入，见 [接入你既有的 frps](ATTACH_EXISTING_FRPS.md)：
 > 插件不装不改你的 frps、**零 SSH**；还提供**完全不用公开证书**的自签穿透档（frps 只做 TCP 透传，
@@ -22,16 +22,16 @@
 ## 两种入口
 
 - **域名模式**：公开地址是自己的域名，Caddy 自动申请并续期证书。
-- **公网 IPv4 模式**：公开地址直接是 VPS 公网 IPv4（例如你自己的 VPS 地址），插件用 Certbot 申请约 6 天有效的 Let's Encrypt IP 证书，并安装每日自动续期定时器。注意：文档示例地址（如 `203.0.113.10`）和内网、保留地址会被拒绝，必须填写真实可路由的公网 IP。
+- **公网 IPv4 模式**：公开地址直接是 VPS 公网 IPv4，当前模板用 Certbot 申请约 6 天有效的 Let's Encrypt IP 证书。自动部署会安装每日续期定时器；手动部署须自行安排续期、证书复制和 Caddy 重载。示例地址（如 `203.0.113.10`）、内网和保留地址会被拒绝，必须填写真实可路由的公网 IP。
 
 本页的公开证书入口需要 Android App 0.3.3 或更高版本（远程自定义入口）。另见[接入既有 frps](ATTACH_EXISTING_FRPS.md)中的自签 TCP 穿透档：它仅适用于接入模式，需要 0.4.6 或更新的 Android App 固定远程 CA；旧版 App 不支持该档，仍可使用局域网、cpolar 和 Tailscale。
 
 ## 手动部署 vs 自动部署
 
-- **手动部署**：在面板复制受限模板，把 frps 部分存为 `/etc/dsh-mobile/frps.toml`，把 Caddy 片段存为 `/etc/caddy/dsh-mobile-dsh.caddy`，并确保主 Caddyfile 里有且仅需这一行：`import /etc/caddy/dsh-mobile-dsh.caddy`（没有 Caddyfile 就新建一个只写这一行）。复制操作本身不改变任何东西。公网 IPv4 还需要按模板里的注释步骤用 Certbot 申请一次 IP 证书（Caddy 自己签发不了 IP 证书）；域名模式 Caddy 全自动。
+- **手动部署**：先自行安装 frps、Caddy，配置服务和防火墙，再复制面板的受限模板。frps 部分存为 `/etc/dsh-mobile/frps.toml`，Caddy 片段存为 `/etc/caddy/dsh-mobile-dsh.caddy`；主 Caddyfile 只需添加一次 `import /etc/caddy/dsh-mobile-dsh.caddy`，不要覆盖其他站点。复制或保存模板不会自动安装、启动服务。公网 IPv4 按本项目模板使用 Certbot，并需自行维护续期和证书重载；域名证书由 Caddy 管理。
 - **自动部署**：填写 SSH 用户、端口和本机私钥路径（留空则用 ssh-agent 或 SSH 配置），点击一键部署。要求 Ubuntu/Debian + systemd，只接受密钥登录，不接受密码。
 
-点部署按钮前，面板会列出自动部署将在 VPS 上做的全部改动：从官方 APT 源安装 Caddy；仅在公网 IPv4 模式安装 Python venv、Certbot 和证书续期定时器；创建 `dsh-mobile` 系统用户（已存在则复用，卸载时保留）、frps 配置与服务、Caddy 片段和主文件里的一行 import；如果 UFW 已启用，则放行 FRP 控制端口与 80/443。**主 Caddyfile 里你自己的内容永远不会被改写或合并**：没有 Caddyfile、空文件或官方默认文件时才写入这一行 import；已有 DSH Mobile import 时只整理为一行，其他非空配置会停止部署并告诉你手动加这一行。
+点部署按钮前，面板会列出自动部署将在 VPS 上做的全部改动：从官方 APT 源安装 Caddy；仅在公网 IPv4 模式安装 Python venv、Certbot 和证书续期定时器；创建 `dsh-mobile` 系统用户、frps 配置与服务、Caddy 片段和主文件里的一行 import；如果 UFW 已启用，则放行 FRP 控制端口与 80/443。已存在的系统用户会复用并在清理时保留，本次部署创建的用户则会在清理时删除。**主 Caddyfile 里你自己的内容不会被改写或合并**：没有 Caddyfile、空文件或官方默认文件时才写入这一行 import；已有 DSH Mobile import 时只整理为一行，其他非空配置会停止部署并告诉你手动加这一行。
 
 ## 主机指纹核对（每次必做）
 
@@ -67,12 +67,12 @@ curl -v https://PUBLIC_HOST/mobile-access/discovery
 
 本机优先看插件日志（`$DSH_HOME/mobile-access/logs/dsh-mobile.log`，JSONL，超 5 MB 轮转，自动脱敏 Token 与密钥）与面板诊断报告。Windows 杀毒软件可能隔离 frpc；如确有拦截，只为已校验的组件目录设置最小范围例外。
 
-一台 frps 被多台电脑共用时：代理名在**整台服务器**内唯一，公网入口端口同样先到先得。插件按本机安装标识注册代理名（`dsh-mobile-<安装标识前 12 位>`），不同电脑之间不会再抢同一个名字；若报「已有本机安装名对应的 FRP 代理在使用中」，说明该名字被另一台电脑占用，或本机上一次连接尚未等到 frps 心跳超时，处理后再重连；若报「入口端口已被占用」，为这台电脑换一个入口端口即可。frpc 遇到这两种冲突时并不会退出，只是入口端口从未发布，修复前面板只会显示「公网端点未能就绪」。
+一台 frps 被多台电脑共用时，代理名在整台服务器内唯一，公网入口端口也不能重复。插件使用 `dsh-mobile-<安装标识前 12 位>` 作为代理名。报代理名已使用时，检查另一台电脑或尚未过期的旧连接；报入口端口已占用时，为本机选择另一个入口端口。frpc 仍在运行并不表示入口已发布，应以公网验证结果为准。
 
 ## 限制
 
 - 中国大陆 VPS 上的未备案域名可能被云厂商拦截，此时改用公网 IPv4 模式。
-- IPv4 证书是短期证书，必须保持续期定时器与 Caddy 正常运行。
+- IPv4 证书是短期证书，必须保持自动部署的续期定时器，或手动配置的续期／复制／重载流程正常运行。
 - SSH 表单按浏览器配置文件保存，换浏览器或清理站点数据后需重填（私钥与密码从不保存）。
 - VPS 的 SSH 目前不支持 IPv6 地址。
 - frps 明文 vhost 必须只监听 `127.0.0.1`；插件会拒绝公网可达的明文端口，并在公开发现接口确认是当前电脑后才显示“已就绪”。

package/docs/SELF_HOSTED_ORIGIN.en.md

@@ -2,33 +2,83 @@
 
 [中文指南](SELF_HOSTED_ORIGIN.md)
 
-> This provider ships with the package from **0.4.2** on.
+> This provider ships from **0.4.2** onward.
 
-This provider appears under **Mobile Access → Remote → Self-hosted connection → Own reverse proxy**. It adds a separate authenticated private HTTP origin for an HTTPS reverse proxy you already own; it does not install a tunnel or manage your proxy, DNS, certificate, firewall, or router.
+## When to use it
 
-## Setup
+Use an existing Lucky, Nginx or Caddy HTTPS proxy rather than a tunnel. Under **Mobile Access → Remote → Self-hosted connection → Own reverse proxy**, DSH Mobile creates a separate private HTTP backend with device authentication:
 
-- Public origin: `https://phone.example.com:8815` (HTTPS only, optional custom port, no path/query/fragment/credentials).
-- Same computer: listen on `127.0.0.1:3444`, allow `127.0.0.0/8`.
-- Separate LAN proxy: listen on the DSH computer's private IPv4, e.g. `192.168.50.10:3444`, and allow the proxy's actual direct source, e.g. `192.168.50.1/32`.
-- Only explicit loopback/RFC1918 IPv4 binds are supported. Wildcard, public and IPv6 binds are rejected. The port must be 1024–65535 and may not be 3443 (the LAN gateway) or 3080 (DSH's own WebServer); note that 3444 is also the cloudflared named tunnel's default forward port. Source CIDRs must be canonical private/loopback networks, at most 16; prefer a single-host /32. Forwarded headers do not determine source authorization.
+```text
+phone → https://phone.example.com:8815 (your proxy terminates TLS)
+      → http://192.168.50.10:3444 (private Mobile backend)
+      → current DSH WebServer
+```
 
-Select **Save and start backend**, then point the proxy at the displayed HTTP backend. **Never expose/port-forward that HTTP listener publicly**, and never bypass it by proxying to DSH's WebServer (default port 3080) or the LAN 3443 gateway. HTTP between separate devices is suitable only for a trusted private network. Pairing, authentication, normalized-exact Host/Origin enforcement, CSRF, Secure cookies and WebSocket path policy remain active. Do not open the plain HTTP backend in a browser to verify it: it only accepts requests proxied from the configured public HTTPS origin; direct access has the wrong Host, and its cookie/CSRF flow may fail.
+Only the public HTTPS proxy may face the Internet. **Never port-forward the HTTP backend**, proxy directly to ordinary DSH (default 3080), or reuse the LAN HTTPS gateway (default 3443). HTTP between separate machines is suitable only for a trusted private network.
 
-## Proxy contract
+The backend still enforces device pairing, exact normalized Host/Origin, CSRF, Secure Cookies and WebSocket path policy. Do not test it by opening the private HTTP address in a browser: that has the wrong Host and may break authentication. The operator owns public TLS, renewal, DNS, routing and firewall rules; the plugin does not configure or probe the public route.
 
-Terminate public TLS with a trusted certificate on your proxy. Preserve the external **Host including the port** (`phone.example.com:8815`), Origin, cookies and authentication/CSRF headers; do not rewrite cookie security attributes or cache authentication responses. Forward WebSocket upgrades and bidirectional traffic.
+## Four settings
 
-[Lucky's Web module](https://lucky666.cn/docs/modules/web) supports WebSocket by default. Use **“使用请求Host” (request Host)** rather than **“使用目标地址Host” (target-address Host)**, and verify the external custom port survives. Certificates remain Lucky's responsibility. If the proxy is on another machine, configure routing and a source-restricted private firewall rule yourself; the plugin does not change either.
+Replace these examples with your own addresses:
 
-## Readiness, pairing and persistence
+| Field | Proxy on the DSH computer | Proxy on another private-network host |
+| --- | --- | --- |
+| Public HTTPS origin | `https://phone.example.com:8815` | `https://phone.example.com:8815` |
+| Private listen IPv4 | `127.0.0.1` | DSH computer's address, e.g. `192.168.50.10` |
+| HTTP backend port | `3444` | `3444` |
+| Allowed proxy source CIDR | `127.0.0.0/8` | Actual proxy source, e.g. `192.168.50.1/32` |
 
-**Backend listening is not public readiness.** The provider and diagnostics make no public probe: check your domain, certificate, public port, pairing and WebSocket from the phone's intended external network. Use the existing Android **Remote access** QR flow on app **0.4.0 or later** for user-owned domains and custom HTTPS ports. App 0.3.16 rejects these pairings; no APK change is required for this provider. Local real-socket HTTPS/HTTP/WebSocket tests are not a substitute for testing your own proxy and phone.
+The public origin must be HTTPS and may include a custom port, but no path, credentials, query or fragment. Private/reserved public addresses, local names and IPv6 literals are rejected by this provider.
 
-Stopping retains settings and paired devices. **Clear proxy settings** stops only this listener and deletes only its configuration, after confirmation. The separate existing **reset remote devices** action removes shared remote pairings, but keeps proxy settings and LAN devices. Switching providers stops the previous remote provider without affecting LAN.
+Bind to an explicit loopback or RFC1918 IPv4 already assigned to the DSH computer, not `0.0.0.0`, a hostname, public IP or IPv6. Choose an unused integer port from 1024–65535, excluding reserved 3080 and 3443. Default 3444 is also the named-cloudflared forward port: only one remote provider runs at a time, but verify the port is released during a switch.
 
-Under the default `$DSH_HOME/mobile-access/` root, settings live at `remote/origin/config/settings.json`, enabled state at `remote/origin/control.json`, and pairings continue to use `remote/devices.json`. Only the selected, enabled provider resumes on DSH restart. All addresses shown here are examples; supply your own configuration.
+CIDRs match the proxy's **direct TCP peer**, not the phone or `X-Forwarded-For` / `X-Real-IP` / `Forwarded`. Docker or NAT may change that peer. Prefer the actual single-host /32, not an entire subnet. Up to 16 canonical private/loopback CIDRs are accepted, separated by spaces or commas; explicit private proxy sources are required for a LAN bind.
 
-## More detail
+Select **Save and start backend**. An active backend reloads its settings. The panel separates the public HTTPS origin from the actual listening HTTP backend; saved settings remain visible after stopping.
 
-The [Chinese guide](SELF_HOSTED_ORIGIN.md) carries the full field-by-field table, the Lucky checklist and a troubleshooting list; this English page is the condensed version.
+## Proxy requirements, including Lucky
+
+1. Terminate public TLS with a trusted certificate. Never ask the phone to ignore a public certificate error.
+2. Point the proxy at the displayed private HTTP backend, not the phone's public HTTPS address.
+3. Preserve the external **Host including non-default port**: the example requires `phone.example.com:8815`, not the private target or a hostname without its port.
+4. Preserve Origin, Cookie, Set-Cookie and authentication/CSRF headers. Do not rewrite Cookie domain/security attributes or cache authentication responses.
+5. Forward HTTP/1.1 WebSocket upgrades and bidirectional data. Approve any required third-party WebSocket paths separately in diagnostics.
+
+[Lucky's official Web documentation](https://www.lucky666.cn/docs/modules/web/) describes WebSocket support. UI labels vary by version, but this backend requires the incoming external Host. Do not enable target-address Host; if a version offers custom Host, provide the full public hostname and port. Certificates belong on Lucky, not this HTTP backend.
+
+For a separate proxy host, configure routing and a firewall rule limited to its actual private source yourself. This provider does not change the firewall.
+
+## State and phone verification
+
+**Backend listening proves the local listener only, not public HTTPS, certificates or WebSocket connectivity.** This provider's diagnostics do not probe the public origin.
+
+Generate a remote pairing QR code and use **Remote access** in Android app **0.4.0 or later**, not Local network. A publicly trusted origin also supports mobile-browser pairing. Verify from the intended external network:
+
+- The hostname, public port and trusted certificate are correct.
+- Pairing and DSH login succeed.
+- A live conversation or other real-time operation keeps WebSockets working.
+- Stopping the backend disables this remote entry without affecting LAN access.
+
+Local real-socket HTTPS/HTTP/WebSocket tests do not replace your own proxy and phone acceptance.
+
+## Stop, remove settings or reset devices
+
+| Action | Result |
+| --- | --- |
+| Disable remote access | Stops the backend; keeps settings and paired devices |
+| Clear proxy settings, after confirmation | Stops this backend and deletes its settings; keeps remote pairings, LAN and other provider settings |
+| Reset remote devices, after confirmation | Clears shared remote authorizations; remote devices must pair again, while proxy settings and LAN devices remain |
+| Switch provider | Stops the previous remote provider; LAN is unaffected |
+
+Under the default `$DSH_HOME/mobile-access/` root, settings are in `remote/origin/config/settings.json`, enabled state in `remote/origin/control.json`, and remote devices in shared `remote/devices.json`. Normal shutdown retains settings; only the selected, enabled provider resumes after DSH restarts.
+
+## Troubleshooting
+
+| Symptom | First check |
+| --- | --- |
+| Port occupied | Choose an unused backend port and update the proxy target |
+| Listen address unavailable | Use a private IPv4 assigned to the DSH computer, not the proxy host |
+| Refused / HTTP 403 | Verify direct source CIDR, full external Host and HTTPS Origin; forwarded headers cannot bypass them |
+| Page works but real-time operations fail | Check WebSocket forwarding, timeout and approved paths without disabling trust checks |
+| Only Backend listening | Expected local state; verify public DNS, HTTPS routing, certificate and actual phone access |

package/docs/SELF_HOSTED_ORIGIN.md

@@ -46,7 +46,7 @@ CIDR 限制针对 TCP 连接的**直接来源地址**，不是手机 IP，也不
 4. 透传浏览器的 Origin、Cookie、Set-Cookie，以及认证/CSRF 相关头，不要改写 Cookie 的域或安全属性；不要缓存配对或认证响应。
 5. 透传 WebSocket 升级（HTTP/1.1、Upgrade、Connection）以及双向数据。已有的 WebSocket 路径白名单继续生效；第三方插件需要时仍在现有面板中单独允许其路径。
 
-根据 [Lucky 官方 Web 模块文档](https://lucky666.cn/docs/modules/web)，WebSocket 默认支持，不必寻找单独的开启开关。Host 自定义模式应使用 **“使用请求Host”**，不要选 **“使用目标地址Host”**，并核对非默认端口没有丢失。TLS/证书仍配置在 Lucky，不在这个 HTTP 后端上配置。
+[Lucky 官方 Web 文档](https://www.lucky666.cn/docs/modules/web/)说明其支持 WebSocket。配置界面随版本变化，但本插件要求不变：保留外部请求 Host，不要启用“使用目标地址Host”；若版本提供自定义 Host，请填写完整公网主机名及端口。TLS/证书配置在 Lucky，不在这个 HTTP 后端上配置。
 
 若代理在另一台机器上，还需由管理员保证网络可达，并将主机防火墙入站范围限制到代理的实际私网来源；此功能不自动改防火墙。