dsh-mobile 0.6.18 → 0.7.0

package/docs/SELF_HOSTED_ORIGIN.md

@@ -54,6 +54,31 @@ CIDR 限制针对 TCP 连接的**直接来源地址**，不是手机 IP，也不
 
 若代理在另一台机器上，还需由管理员保证网络可达，并将主机防火墙入站范围限制到代理的实际私网来源；此功能不自动改防火墙。
 
+### 已经自己运行 cloudflared 时
+
+如果你已经在用官方方式配置了命名隧道（`cloudflared tunnel`，可能是 systemd、launchd 或 Windows 服务），**不需要让插件再装一份 cloudflared，也不需要在插件里保存隧道 Token**。用上面的自备代理模式，把你已有的隧道指向插件的 HTTP 后端即可：
+
+1. 在电脑端 **移动访问 → 远程 → 自建连接 → 自有反向代理** 里填写：公网 HTTPS 地址填你隧道的公开主机名（例如 `https://dsh.example.com`），私有监听 IP 填 `127.0.0.1`，后端端口填一个未占用的值（默认 `3444`），允许来源填 `127.0.0.0/8`。
+2. 点击 **保存并启动后端**，复制面板给出的 HTTP 后端地址。
+3. 本地管理的隧道只需修改对应 `ingress` 的 `service`，保留已有隧道身份、凭据及其他路由。以下仅为片段，不要覆盖整份配置：
+
+   ```yaml
+   tunnel: <你的隧道 ID>
+   ingress:
+     - hostname: dsh.example.com
+       service: http://127.0.0.1:3444
+     - service: http_status:404
+   ```
+
+4. 按现有部署方式应用变更，必要时重启服务。通过 Cloudflare 控制台管理的隧道，应在那里修改公开主机名对应的服务地址，不必新建本地配置文件。**插件不会启动、停止、重载或删除这个服务**，也不会读取它的配置或 Token。
+
+这样分工是清楚的：**隧道、DNS 和公网证书由你管理，设备配对与 DSH 认证由插件管理**。插件的后端仍然执行完整的设备配对、Host/Origin 校验和 CSRF 检查，所以隧道指向它并不会把裸 DSH 暴露到公网。
+
+需要注意的两点：
+
+- **端口别冲突。** 插件自己的 cloudflared 组件也默认用 `3444`。同一时刻只应有一个远程提供方在运行；改用自备代理前先停掉插件托管的那份，或者在这里换一个端口。
+- **以面板实际展示的 HTTP 后端地址为准。** DSH 原始网页端口可能不是 `3080`，它也不是这里受保护的后端；局域网 HTTPS 入口（常见为 `3443`）有独立的信任和配对，也不是本模式的 HTTP 后端。不要假定面板会拒绝所有错误的外部隧道目标。
+
 ### Nginx 与 IPv6
 
 手机到 Nginx 的公网 IPv6 连接，与 Nginx 到 DSH Mobile 的 HTTP 后端连接是两段独立连接。**公网入口使用 IPv6，不要求后端也使用 IPv6**。同机 Nginx 可以通过 IPv6 接收手机请求，再代理到 `http://127.0.0.1:3444`；这时来源 CIDR 仍是 IPv4 回环。若后端明确监听 `::1`，Nginx 目标改为 `http://[::1]:3444`，来源改为 `::1/128`。

package/docs/SKIN_COMPATIBILITY.en.md

@@ -18,6 +18,8 @@ If saving reports a dependency conflict, retain the required module or also dese
 - First compare the normal computer layout. Developers can also open `/?frontend=stock` on the authenticated mobile Origin to diagnose boot and layout behavior. Gateway authentication and HTTPS checks remain; this entry skips dedicated mobile boot rewriting and module selection, but installed client adaptation and authenticated customizations may still apply. It is not a plugin-free control; some API operations may be rejected, so it does not replace normal mobile access.
 - When stock has a background but mobile does not, inspect the skin's mounting container and fallback for other layouts. WebSocket approval, APK reinstallation or making every container transparent cannot guarantee a fix.
 - A see-through sidebar, unreadable text shadows and an empty trace need separate diagnosis, not a single missing-background explanation. For an empty trace, inspect the first client exception, actual layout dimensions and whether its module loaded. A static screenshot does not distinguish rendering failure, occlusion and connection failure.
+- **The mobile chrome does not depend on the skin**: the drawer, the right detail panel and the panel return bar composite `--dsw-alias-bg-layer-1` (the return bar uses `--dsw-alias-bg-base`) over the opaque CSS `Canvas` system color. A skin that makes those tokens translucent, or leaves them unresolvable, no longer shows conversation text behind the sidebar labels; a still see-through surface then comes from the skin's own decoration layer, not the chrome base.
+- **Page-level styles injected by a skin travel with the page**: wallpapers and whole-page palettes are injected into the HTML by the plugin on the host, so deselecting that skin's client module does not remove them (module selection covers client modules only). Disable the whole plugin to stop loading them.
 
 For example, the published `maid-atelier` 0.1.7 package mounts its background in the stock `centerCol` container. Its repository's fallback for other layouts does not establish that an installed package contains the same correction. DSH Mobile does not imitate that class or move the skin's nodes. A skin supporting mobile can locate its decoration with the existing `[data-pane="conversation"]` and `[data-pane="sidebar"]` markers, or use DSH public theme variables. The skin must still own sizing, stacking, cleanup and light/dark behavior without obscuring text or hit targets. This guide does not establish full skin acceptance. See [#202](https://github.com/saya-ch/dsh-mobile/issues/202).
 

package/docs/SKIN_COMPATIBILITY.md

@@ -18,6 +18,8 @@ DSH Mobile 在已认证的移动页面中使用专用根布局，继续渲染 DS
 - 先与电脑上的原生布局对照。开发者还可在已认证移动 Origin 打开 `/?frontend=stock` 作启动与布局诊断；它保留 Gateway 认证与 HTTPS 检查，跳过专用移动启动改写和模块选择，但仍可能加载客户端移动适配及已认证定制，并非不含插件的对照页。部分 API 操作可能被拒绝，不能代替正常移动入口。
 - 若原生布局有背景而移动布局没有，检查皮肤背景的挂载容器及其对非原生布局的回退逻辑；单纯放行 WebSocket、重装 APK 或把全部容器设为透明不能保证修复。
 - 侧栏透底、文字阴影难读和轨迹空白应分别排查，不能都归为“少了一张背景图”。轨迹空白时还需检查首个客户端异常、实际布局尺寸和是否加载了相应模块；仅从静态截图不能判断是渲染异常、遮挡还是连接问题。
+- **移动外壳的底板不依赖皮肤**：抽屉、右侧详情和面板返回栏把 `--dsw-alias-bg-layer-1`（返回栏用 `--dsw-alias-bg-base`）叠在不透明的 CSS `Canvas` 系统色上。皮肤把这些 token 设成半透明，或让它们解析不到，会话内容都不会再透到侧栏文字后面；若此时仍透底，来源是皮肤自己的装饰层，而不是外壳底板。
+- **皮肤注入的整页样式会跟着页面走**：壁纸与整页配色由插件在服务端注入 HTML，取消该皮肤的客户端模块不会移除它们（模块选择只覆盖客户端模块）。要彻底不加载，请在插件层禁用。
 
 例如 `maid-atelier` 0.1.7 发布包的背景依赖原生 `centerCol` 容器；皮肤仓库源码中的非原生布局回退不代表已安装包包含相同修正。DSH Mobile 不伪造这个类名或移动皮肤节点。支持移动布局的皮肤可以利用现有 `[data-pane="conversation"]`、`[data-pane="sidebar"]` 标记定位自己的装饰，或使用 DSH 公共主题变量；皮肤仍需自行处理尺寸、层叠、关闭清理和明暗主题，装饰不得遮挡文字或点击区域。本指南不表示整套皮肤已完成兼容验收。参见 [#202](https://github.com/saya-ch/dsh-mobile/issues/202)。
 

package/docs/SLOW_CONNECTIONS.en.md

@@ -108,6 +108,14 @@ These optional fields sit alongside `paths`; their defaults normally suffice:
 
 Restart DSH and reopen the phone page after a change. Developer tools can show whether the WebSocket handshake negotiated `permessage-deflate`; a client that does not negotiate it can still connect without compression. Compare actual channel transfer volume and CPU use for the same Session, rather than judging savings from the decompressed message lengths shown in developer tools. Set `paths` back to `[]` to disable it. Compression does not raise provider quotas or replace connection troubleshooting.
 
+### When it is worth enabling
+
+Compression is most useful when large, compressible live messages cross a bandwidth-limited link. In an isolated Gateway/`ws` test with synthetic repetitive text, an 8 KiB message used 8,196 bytes without compression and 249 bytes with it; a 64 KiB sample used 65,546 and 692 bytes. These are WebSocket frame bytes, not TLS/TCP overhead or measurements of a real Session. Savings depend strongly on the content.
+
+With the default 1 KiB threshold and no-context-takeover negotiation, the tested 1,023-byte message stayed uncompressed. Incompressible 64 KiB data grew by 22 bytes and added about 1.1 ms to the local round trip. A local bandwidth-shaped test showed lower delivery latency for repetitive messages, but does not predict any particular cellular, relay or LAN result; sustained-load memory and physical-device behavior were not measured.
+
+Compare the same workload with and without compression before drawing a conclusion. HTTP history responses and `/api/remote.mux` frames are separate paths: a faster Session switch after several simultaneous upgrades cannot be attributed to WebSocket compression alone. Compression remains opt-in.
+
 ## Static-resource caching and repeated downloads
 
 Owned static resources (`/mobile-access/compat.js`, `mobile-layout.js` and custom CSS/JS) use quoted content ETags and `Cache-Control: private, no-cache`. A browser may store the body but must revalidate before reuse. The gateway checks device authorization and the current resource before processing conditional GET/HEAD requests: unchanged content receives `304`, while a file edit returns the new body. Actual cache reuse still depends on browser behavior.

package/docs/SLOW_CONNECTIONS.md

@@ -108,6 +108,14 @@ websocketCompression:
 
 修改后重启 DSH 并重新打开手机页面。可在开发者工具中查看 WebSocket 握手是否协商了 `permessage-deflate`；客户端没有协商时仍可无压缩连接。对比同一会话的实际通道传输量与 CPU 使用，不能仅以开发者工具显示的解压后消息长度判断节省比例。需要关闭时把 `paths` 改回 `[]`；压缩不能提高服务商限额，也不能替代连接故障排查。
 
+### 什么时候值得开启
+
+可压缩的大消息经过受限带宽时，压缩通常更有价值。在隔离 Gateway／`ws` 测试中，合成的重复文本样本从 8 KiB 对应的 8,196 字节降到 249 字节，从 64 KiB 对应的 65,546 字节降到 692 字节。这是 WebSocket 帧字节，不含 TLS／TCP 开销，也不是实际会话的测量；压缩率取决于具体内容。
+
+使用默认 1 KiB 阈值并协商禁用上下文复用时，测试中的 1,023 字节消息没有压缩。不可压缩的 64 KiB 数据反而增加 22 字节，本地往返增加约 1.1 ms。局部限速测试中，重复文本的传递延迟有所下降，但不能据此预测具体蜂窝、转发或局域网体验；本轮未测量持续负载内存和真机行为。
+
+请对相同工作负载分别开关压缩再比较。HTTP 历史响应与 `/api/remote.mux` 消息是不同路径，不能将同时升级多个组件后的会话切换改善全部归因于 WebSocket 压缩。该功能仍默认关闭、按需开启。
+
 ## 静态资源缓存与重复下载
 
 网关自有静态资源（`/mobile-access/compat.js`、`mobile-layout.js`、自定义 CSS/JS）使用带引号的内容 ETag 和 `Cache-Control: private, no-cache`。浏览器可保存正文，但每次复用前必须重新校验；网关先检查设备授权和当前资源，再处理 GET/HEAD 条件请求，内容未变时返回 `304`，文件改动后返回新正文。实际缓存复用仍取决于浏览器行为。