@dsh-remote/relay 0.0.0-stage → 3.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 providcc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @dsh-remote/relay
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH Remote Control 的**零知识 WebSocket 中继**：在宿主插件与已配对的手机之间转发**密封记录**，
+只认帧名 / 会话 id / 能力协商，**从不解析载荷**——密文对它就是一个 base64 字符串。
+
+生产形态是**单文件产物** `dist/bundle/main.js`（`ws` / `zod` / 协议层全部内联，运行时零依赖）；
+部署只有两种：拷这个单文件 + 起进程（systemd / docker / nginx 配方见下），或从源码构建。
+
+## 自托管
+
+完整配方（环境变量表、systemd / docker / nginx、排错、升级与回滚）见
+[`docs/SELF-HOSTING.md`](docs/SELF-HOSTING.md)。最速验证：
+
+```sh
+DRC_HOST_TOKEN=<与主机插件一致> node dist/bundle/main.js
+curl -s http://127.0.0.1:8787/healthz
+```
+
+### 常用配置
+
+| 变量                          | 必填 | 默认        | 说明                                                                                             |
+| ----------------------------- | ---- | ----------- | ------------------------------------------------------------------------------------------------ |
+| `DRC_HOST_TOKEN`              | ✅   | —           | 主机出站认证凭据。`openssl rand -hex 32` 生成。**与主机插件那份必须逐字一致**                    |
+| `DRC_PORT`                    |      | `8787`      | 监听端口。`0` = 让系统分配（测试与容器用）                                                       |
+| `DRC_BIND`                    |      | `127.0.0.1` | 绑定地址。默认只绑回环：TLS 由反代终止。**只有自己就是边缘（容器直接发布端口）时才设 `0.0.0.0`** |
+| `DRC_PUBLIC_URL`              |      | 空          | `/api/info` 返回的对外地址。公网填 `wss://你的域名`                                              |
+| `DRC_LOG_LEVEL`               |      | `info`      | `debug` / `info` / `warn` / `error` / `silent`。**区分大小写**                                   |
+| `DRC_PAIR_TTL_MS`             |      | `120000`    | 配对码的**服务端权威**寿命（毫秒）                                                               |
+| `DRC_STATE_FILE`              |      | 空（关闭）  | 会话表落盘路径。默认关闭 = 纯内存；配上后启动先读它、会话表有增删时写回                          |
+| `DRC_STATE_SAVE_MS`           |      | `60000`     | 周期补写状态文件的间隔（只为刷新 `lastActivityAt`）                                              |
+| `DRC_MAX_BUFFERED_BYTES`      |      | `1048576`   | 慢消费者阈值：发送缓冲区**连续**超限达**本角色窗口**才 1008 断开                                 |
+| `DRC_SLOW_CONSUMER_HOST_MS`   |      | `10000`     | **主机**侧慢消费者窗口（毫秒）。主机卡住就是所有人卡住，所以窗口短                               |
+| `DRC_SLOW_CONSUMER_CLIENT_MS` |      | `45000`     | **客户端**侧慢消费者窗口（毫秒）。**必须大于手机自己的重连周期**（≈42.5 秒）                     |
+
+### 端点
+
+| 路径                   | 说明                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `GET /healthz`         | 运维契约（**二十三个字段**）：`ok` / `version` / `uptimeSec` / `hosts` / `clients` / `conversations` / `pendingPairs` / `droppedFrames` / `slowConsumers` / `rejectedPairs` / `shutdownForced` / `persistence` / `stateRestored` / `stateSavedAtSec` / `stateWrites` / `stateWriteFailures` / `lastPingAgo` / `shuttingDown` / `protocolSelf` / `protocolMin` / `peerProtocolMin` / `peerProtocolMax` / `peersNoProtocol` |
+| `GET /api/info`        | `{"publicUrl","protocol"}`                                                                                                                                                                                                                                                                                                                                                                                                |
+| `GET /api/pair-status` | **默认 404**。无需认证地回答"配对码 N 是否有效"等于给 6 位码空间装了扫描 oracle；确需调试时 `DRC_PAIR_STATUS=1`，用完关掉                                                                                                                                                                                                                                                                                                 |
+| WebSocket              | 路径不设限，任意路径都能升级                                                                                                                                                                                                                                                                                                                                                                                              |
+
+落盘五字段（`persistence` / `stateRestored` / `stateSavedAtSec` / `stateWrites` /
+`stateWriteFailures`）是"还在落盘"的唯一读数——换机器先看 `stateWriteFailures`，不是 0 就是没在写。
+
+## 开发
+
+```sh
+pnpm install
+pnpm build        # tsc + 单文件打包
+pnpm test         # tsc + 打包 + node --test（含产物级判据）
+```
+
+## 红线
+
+- **不 import 载荷**：依赖图里只有协议层的 `frames` / `ids` / `negotiate` / `outbound`；
+  构建产物里不许出现任何密码学实现——`tests/bundle.test.mjs` 直接读产物断言。
+- 路由表是**内存的**：重启即全部作废（客户端会看到 `unknown_session`），这是设计不是缺陷。
+- 日志永不落载荷、落完整配对码、落 hostToken（有判据锁住）。
+- **本包不发 npm**：`private: true`，发布流程里不许出现发包步骤与 id-token（有判据）。
+
+## 许可
+
+MIT

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security Policy
+
+## 报告漏洞
+
+用本仓 GitHub 的私密渠道：**Security → Report a vulnerability**（`/security/advisories/new`）。
+不要在公开 issue 里贴可利用细节。
+
+## 本仓的范围
+
+- 负责：WebSocket 路由与鉴权（`hostToken`）、配对码表（TTL / 一次性 / 限流）、
+  帧分级与体积闸（`ws.maxPayload`）、慢消费者处置、日志的凭据卫生。
+- 不负责：载荷内容——**结构上看不见**；密码学在中继的依赖图上不可达（有产物级判据）。
+
+## 零知识（可核对的说法）
+
+- 构建产物 `dist/bundle/main.js` 里**没有**任何密码学实现：`tests/bundle.test.mjs`
+  直接读产物，对 `xsalsa20` / `secretbox` / `tweetnacl` 等标记逐条断言。
+- 日志约定：只记 id / 计数 / reason；配对码与 `hostToken` 永不整值落日志（有判据）。
+- 部署加固（TLS 由反代终止、绑定与防火墙、状态/凭据文件权限）见 `docs/SELF-HOSTING.md`。

package/deploy/README.md

@@ -0,0 +1,125 @@
+# 部署记录与复用步骤
+
+本目录是**实际生产部署**的配置，不是示例。
+
+## 当前部署
+
+| 形态 | **Docker**（`deploy/docker/compose.yaml`；2026-10-07 从 systemd 切过来，nginx 不动） |
+
+| 项       | 值                                                                                                                                            |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| 公网入口 | `wss://drc.provid.cc`                                                                                                                         |
+| 中继     | 镜像 `dsh-remote-relay`（里面是**一个自包含单文件**），compose 服务 `relay`。systemd 单元 `dsh-remote-control.service` 仍保留可用，**二选一** |
+| 反向代理 | nginx，`/etc/nginx/conf.d/drc.conf`                                                                                                           |
+| 证书     | Let's Encrypt（acme.sh + 阿里云 DNS-01），ECC，自动续期                                                                                       |
+| 绑定     | 中继只监听 `127.0.0.1:8787`，公网只暴露 80/443                                                                                                |
+| 密钥     | `/etc/dsh-remote-control.env`（600），同一份 token 也写在主机插件的 profile 配置里                                                            |
+
+中继现在部署的是 `pnpm build` 打出来的 `dist/bundle/main.js`
+（`ws` 与协议层都内联进去了，`bufferutil`/`utf-8-validate` 是可选原生加速、缺了照常跑）。
+于是生产只有"拷一个文件 + 一个 env 文件"，没有 `npm install`，也就没有
+"服务器上的依赖树和 CI 不一样"这一类故障。
+
+> 完整的环境变量表、日志契约、重启语义、升级回滚见 [`../docs/SELF-HOSTING.md`](../docs/SELF-HOSTING.md)。
+
+## 从零复现
+
+### 1. 服务器准备
+
+```sh
+dnf install -y nodejs nginx           # Alibaba Cloud Linux 4 自带 node 22
+mkdir -p /opt/dsh-remote-control/server /etc/nginx/ssl
+```
+
+### 2. 部署中继（Docker）
+
+> 生产现在跑的是容器，完整步骤在 [`docker/README.md`](docker/README.md)（含镜像源拉不到时的三条路）。 下面这份是**裸机 systemd** 那条路，仍然可用，但两条**别同时开**——同一个端口只能有一个进程在听。
+
+#### 2b. 裸机 systemd
+
+```sh
+# 本地先构建产物
+pnpm install && pnpm build
+
+scp dist/bundle/main.js            root@HOST:/opt/dsh-remote-control/server/relay.mjs
+scp deploy/systemd/*.service       root@HOST:/etc/systemd/system/
+
+# token：与主机插件那份必须逐字一致
+cat > /etc/dsh-remote-control.env <<'EOF'
+DRC_HOST_TOKEN=<openssl rand -hex 32 的输出>
+DRC_PORT=8787
+DRC_PUBLIC_URL=wss://drc.provid.cc
+DRC_PAIR_TTL_MS=90000
+DRC_LOG_LEVEL=info
+# 会话表落盘（默认关闭 = 纯内存模式，重启丢配对；配上之后会话表重启恢复，见 CHANGELOG 1.0.6）
+# 标准生产值（相对路径按 systemd WorkingDirectory 解析）：
+# DRC_STATE_FILE=/var/lib/dsh-remote-control/state.json
+EOF
+chmod 600 /etc/dsh-remote-control.env
+
+systemctl daemon-reload && systemctl enable --now dsh-remote-control
+curl -s http://127.0.0.1:8787/healthz      # version 必须是包的 version，不是 0.0.0
+```
+
+### 3. DNS 证书（DNS-01，不需要占用 80 端口）
+
+acme.sh 已保存阿里云 DNS 凭证，所以换域名只需一条命令：
+
+```sh
+acme.sh --issue --dns dns_ali -d drc.provid.cc --server letsencrypt
+acme.sh --install-cert -d drc.provid.cc \
+  --key-file       /etc/nginx/ssl/drc.provid.cc.key \
+  --fullchain-file /etc/nginx/ssl/drc.provid.cc.crt \
+  --reloadcmd      "systemctl reload nginx"
+```
+
+### 4. nginx
+
+```sh
+scp deploy/nginx/drc.conf root@HOST:/etc/nginx/conf.d/drc.conf
+ssh root@HOST 'nginx -t && systemctl enable --now nginx'
+```
+
+`drc.conf` 里包含**按 IP 限流**（`limit_req` 20r/s、`limit_conn` 8）——中继本身
+只有全局和单连接配额，看不到真实客户端 IP，所以这一层必须由反代来做。
+
+### 5. 验证
+
+```sh
+curl -s https://drc.provid.cc/healthz
+```
+
+`/healthz` 的 `version` 必须等于包版本。真要端到端验一遍，得在这台机器之外跑一次真配对
+（出码 → 手机扫码 → 发指令拿到流式回复），见 `../docs/SELF-HOSTING.md` §10.4。
+
+## 运维
+
+```sh
+systemctl status dsh-remote-control
+journalctl -u dsh-remote-control -f                                  # 一行一个 JSON
+journalctl -u dsh-remote-control -o cat | grep '"level":"warn"'      # 按 JSON 里的 level 过滤
+curl -s https://drc.provid.cc/healthz
+tail -f /var/log/nginx/drc.access.log
+```
+
+> 别用 `journalctl -p warning`：中继写到 stdout 的 JSON 不带 syslog 级别前缀，这些行进
+> journal 时优先级一律是 `info`，按优先级过滤很可能一条都出不来。按 JSON 里的 `level` 过滤。
+
+改中继代码后：
+
+```sh
+pnpm build
+scp dist/bundle/main.js root@HOST:/opt/dsh-remote-control/server/relay.mjs
+ssh root@HOST 'systemctl restart dsh-remote-control'
+```
+
+中继默认是纯内存的，未配 `DRC_STATE_FILE` 落盘时重启会丢掉配对关系：客户端拿旧 convId 发帧会撞上
+`error{unknown_session}`，手机上就是中文的"会话已失效，请重新配对"。
+
+## 安全组
+
+```
+TCP  22, 80, 443   0.0.0.0/0   Accept
+```
+
+8787 **不要**对公网开放 —— 中继只绑 `127.0.0.1`，nginx 在同一台机器上转发。

package/deploy/docker/Dockerfile

@@ -0,0 +1,150 @@
+# dsh-remote-relay —— 中继的容器形态。
+#
+# ## 这份 Dockerfile 刻意很短，因为它要成立的前提是上游已经打过包
+#
+# 中继的分发形态是**一个自包含单文件**（pnpm build 产出的 dist/bundle/main.js：ws / zod /
+# 协议层全内联，运行时依赖为空，tests/bundle.test.mjs 有产物级断言）。于是镜像只有两个阶段：
+#
+#   build   —— 装依赖、打包，**只为了产出那一个文件**；
+#   runtime —— 只 COPY 那一个文件，没有 node_modules、没有 npm install。
+#
+# 这条"运行时零依赖"不是省事，是**故障类别的消除**：镜像里不可能出现"服务器上的依赖树和
+# CI 不一样"，也不可能出现某个传递依赖换个 Node 小版本就变行为这一类只在生产才显形的问题。
+# 可选原生加速（bufferutil / utf-8-validate）在 bundle 里是 external、且 ws 对它们是
+# try/catch，缺了照常跑纯 JS —— 与裸机部署同形。
+#
+# ## 版本号在镜像里有三份，且互为对账
+#
+#   1. 产物内（esbuild define 注入）→ /healthz 的 version 字段，**运维唯一认的**；
+#   2. OCI 标签 org.opencontainers.image.version → docker inspect / SBOM 看得到；
+#   3. 镜像标签 dsh-remote-relay:<version> → 部署脚本与人看的。
+#
+# 构建阶段末尾那条断言（产物里必须找得到包版本）让 1 与 2 不会各说各话：版本号打错时
+# **构建就失败**，而不是等上线后靠 /healthz 才发现。
+#
+# ## 两条 FROM 为什么写死而不是用 ARG
+#
+# 早期版本写成 ARG NODE_IMAGE=… + FROM ${NODE_IMAGE}，那份在 BuildKit（Docker 23+ 默认）下
+# 没问题，但在**只有 legacy builder** 的机器上直接构建失败（NotFound: content digest）。
+# 换镜像源这件事有更标准的做法，见下面「拉不到 Docker Hub 怎么办」，所以这里不为了一个
+# 方便性参数牺牲可构建性。tests/docker.test.mjs 会钉住两条 FROM 指向同一个镜像。
+#
+# ## 拉不到 Docker Hub 怎么办（生产那台机器就是拉不到的）
+#
+# 与其把某个第三方镜像站硬写进 FROM（那是把供应链交给一个别人随时可能下线或被投毒的域名），
+# 不如让 FROM 保持标准写法，可达性交給环境去解决：
+#
+#   1) 配 daemon 级镜像加速（/etc/docker/daemon.json 的 registry-mirrors），**推荐**；
+#   2) 或从可达的镜像站拉一份再本地打标签：docker pull <mirror>/library/node:22-alpine
+#      后 docker tag 成 node:22-alpine —— docker build 在本地有这个名字时不会再解析远端；
+#   3) 或在能上网的机器上 build，再 docker save | docker load 搬过去
+#      （deploy/docker/README.md 有完整的离线步骤；生产那次就是这么发的）。
+#
+# Node 22 与 CI、与 HANDOFF 的工具链口径一致（pnpm 11 要求 >= 22.13）。
+FROM node:22-alpine AS build
+WORKDIR /src
+
+# 先只拷锁文件再装：pnpm 的安装缓存按 lockfile 命中，改 src 不必重装依赖树。
+# --frozen-lockfile 是刻意的——镜像里装的必须与提交的 lockfile 逐位一致，
+# "构建时顺手升了某个传递依赖"这类漂移正是要消掉的。
+#
+# ## v3 单仓：这里的 COPY 必须带 packages/ 前缀（2026-10-08 修）
+#
+# v2 时这个仓是**独立仓**，build 上下文（compose 的 `context: ../..`）就是本仓根，
+# 所以 `COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./` 拷的是"本包 + 本包锁"。
+# v3 变成 monorepo 后，同一行拷的是 **monorepo 根**的三个文件——而根 package.json 里
+# 没有 relay 的依赖，于是 pnpm 报的错是「lockfile 里有 ^22.9.0、manifest 要 ^26.6.3」
+# 这类**看起来毫不相关**的 mismatch（真实原因：那份 package.json 不是这个包的）。
+#
+# 症状与判据：`docker compose build` 失败，而 `pnpm install` 在本机完全正常。
+# 所以下面显式列出三个路径，让"上下文是单仓根"这件事变成 Dockerfile 自己保证的。
+# ⚠️ 下面几行的行尾**不许带注释** —— Dockerfile 会把 `#` 之后的内容也当成拷贝路径
+# （报错形态：`"/需要它要解": not found`，看起来像文件不存在，其��是把注释当路径了）。
+# 要说明就写在上一行。
+COPY pnpm-workspace.yaml ./
+COPY pnpm-lock.yaml ./
+# monorepo 根清单：pnpm 需要它来解 workspace（里面没有 relay 的依赖，只负责解析结构）
+COPY package.json ./
+#
+# ⚠️ **pnpm-workspace.yaml 声明的每一个包都要有 package.json 在场**，少一个都不行。
+# 缺的那几个不会报"文件不存在"，而是报 `specifiers in the lockfile don't match`，
+# 并把**缺的包的依赖名**列出来（第一次栽在这里：漏了 plugin/client/e2e，于是报错说
+# 「lockfile 有 ^22.9.0、manifest 要 ^26.6.3」——那是 plugin 的 @types/node，
+# 与 relay 一点关系都没有 ⇒ 看起来像 lockfile 坏了，其��是清单没拷全）。
+# 镜像只需要 relay + protocol 的源码，但**清单必须全在场**，否则 pnpm 在 install 阶段就退出了。
+COPY packages/relay/package.json ./packages/relay/
+COPY packages/protocol/package.json ./packages/protocol/
+#
+# ⚠️ **不需要**把 workspace 里其他包（plugin / client / e2e）的 package.json 也拷进来。
+# 我一度以为"声明的包必须清单齐备"，为此加了三条 COPY —— 那三条**无效**：
+# 删掉之后 `pnpm install --frozen-lockfile` 照样通过（2026-10-08 在服务器上实测过：
+# 只放 protocol + relay 两份清单，frozen 检查顺利过，只在下一步因缺 protocol 的
+# tsconfig 而失败）。pnpm 只校验**它要解析的那些 importer**。
+#
+# 那次「lockfile 有 ^22.9.0、manifest 要 ^26.6.3」的 mismatch 真相不是"清单没拷全"，
+# 而是**根 package.json 被污染**：上传源码时用 `tar xzf`，relay 的 package.json
+# 覆盖到了仓库根，于是 pnpm 拿 relay 的依赖去比根的 lock ⇒ 报出 relay 的依赖名。
+# ⇒ **报错指错地方时，先怀疑"文件被覆盖"，别急着加 COPY。**
+#
+# protocol 的 src + tsconfig 必须在 install **之前**进来：
+# 它的 `prepare: tsc -p tsconfig.json` 是 install 生命周期的一环，
+# 顺序写反的报错是 `TS5058: path does not exist`，出现在 install 阶段。
+COPY packages/protocol/tsconfig.json ./packages/protocol/
+COPY packages/protocol/src ./packages/protocol/src
+RUN corepack enable && pnpm install --frozen-lockfile
+
+COPY packages/relay/tsconfig.json ./packages/relay/
+COPY packages/relay/src ./packages/relay/src
+COPY packages/relay/scripts ./packages/relay/scripts
+# protocol 必须**先构建**：它是 workspace 依赖，`pnpm install` 只软链它的 package.json，
+# 而 bundle 脚本按 node_modules 解析 ⇒ 拿到的必须是 `dist/src/**`（main 字段指向那里）。
+# 少这一步的报错形态是 esbuild 找不到 `@dsh-remote/protocol/dist/src/index.js`。
+RUN pnpm --filter @dsh-remote/protocol build
+# 在 relay 包目录里构建：它的 tsconfig 与 bundle 脚本都以包根为基准
+WORKDIR /src/packages/relay
+RUN pnpm build
+
+# 产物级断言。两条取自 tests/bundle.test.mjs 的同款断言，写在这里是因为
+# **镜像构建不该依赖 CI 跑过了**：本机或临时机器上 docker build 时 CI 并不在场。
+#   - shebang 在第一行：chmod +x 之后能直接 ./relay.mjs 起；
+#   - 包版本真的进了产物：否则 /healthz 的 version 会是 0.0.0，而运维正是靠它
+#     判断线上跑的是哪一版（那就成了"看起来正常、其实根本判不出来"）。
+RUN set -e; head -1 dist/bundle/main.js | grep -q '^#!/usr/bin/env node'; node -e 'const {readFileSync}=require("node:fs");const v=JSON.parse(readFileSync("package.json","utf8")).version;const b=readFileSync("dist/bundle/main.js","utf8");if(!b.includes(JSON.stringify(v)))throw new Error("产物里没有包版本 "+v);console.log("[docker] bundle ok, version "+v)'
+
+# ── 阶段 2：运行 ──────────────────────────────────────────────────────────────
+FROM node:22-alpine AS runtime
+
+ARG DRC_VERSION=0.0.0
+ARG VCS_REF=unknown
+LABEL org.opencontainers.image.title="dsh-remote-relay" org.opencontainers.image.description="Zero-knowledge WebSocket relay for DSH Remote Control" org.opencontainers.image.source="https://github.com/providcc/dsh-remote-server" org.opencontainers.image.licenses="MIT" org.opencontainers.image.version="${DRC_VERSION}" org.opencontainers.image.revision="${VCS_REF}"
+
+WORKDIR /app
+COPY --from=build /src/packages/relay/dist/bundle/main.js /app/relay.mjs
+
+# 只有这两个。**故意不设 DRC_STATE_FILE**：镜像里的默认值要与裸机（systemd 单元）一致——
+# 不配就是纯内存、配了才落盘。落盘路径属于"部署形态"而不是"程序形态"，它与卷是一对，
+# 所以由 compose 显式配在一起（compose.yaml 里 env 与 volume 并排）。这样
+# "docker run 一个裸镜像"与"systemd 跑同一个文件"语义相同，也避免了"忘了挂卷 →
+# 状态写进容器可写层 → 重建即丢"这条静默失败。
+#
+# DRC_BIND=0.0.0.0 不能省：代码默认只绑 127.0.0.1，容器里那样绑等于"-p 发布了没人监听"。
+# 公网面仍然是宿主机 nginx 的 443，因为 compose 只把端口发布到**回环**。
+ENV DRC_PORT=8787 DRC_BIND=0.0.0.0
+
+# 非 root。uid/gid 写死成 10001，于是状态目录的属主在容器与裸机两套部署形态之间是同一组
+# 数字，切换时只需要一次 chown（deploy/docker/README.md 第 3 节）。
+RUN addgroup -g 10001 -S drc && adduser -u 10001 -S -G drc -h /app drc && mkdir -p /data && chown 10001:10001 /data
+USER 10001:10001
+
+EXPOSE 8787
+STOPSIGNAL SIGTERM
+
+# 健康检查用 node 自己发请求，不装 curl/wget——运行阶段本来就只有 node，为一个探针多装一个
+# 二进制不值得，而且它会是这个镜像里唯一一个外部依赖。
+# 判 j.ok === true 而不是只看 HTTP 200：停机过程中 /healthz 明确回 ok:false 且状态码 503，
+# 那一刻容器应当立刻变成 unhealthy，而不是继续被当成健康的。
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD node -e 'fetch("http://127.0.0.1:"+(process.env.DRC_PORT||8787)+"/healthz").then(r=>r.json()).then(j=>process.exit(j.ok===true?0:1)).catch(()=>process.exit(1))'
+
+# ENTRYPOINT 固定、参数透传：docker run … dsh-remote-relay --version 就能问出镜像里是哪一版，
+# 不必为此起一个会监听端口的进程。
+ENTRYPOINT ["node", "/app/relay.mjs"]

package/deploy/docker/README.md

@@ -0,0 +1,192 @@
+# 容器部署（Docker / Compose）
+
+生产实例现在跑的就是这一份。形态与裸机（systemd）**同形**：同一个单文件产物、同一套
+`DRC_*` 环境变量、同一个 `/healthz`。变的只有"谁负责把它拉起来"。
+
+```sh
+# 1. 配置（Compose 自动读本目录的 .env）
+cat > deploy/docker/.env <<EOF
+DRC_HOST_TOKEN=$(openssl rand -hex 32)     # 与主机插件那份逐字一致
+DRC_PUBLIC_URL=wss://drc.provid.cc
+DRC_DATA_DIR=/var/lib/dsh-remote-control
+DRC_IMAGE_TAG=2.0.15
+EOF
+chmod 600 deploy/docker/.env
+
+# 2. 状态目录：属主必须是镜像里的非 root 用户 uid 10001
+mkdir -p /var/lib/dsh-remote-control && chown 10001:10001 /var/lib/dsh-remote-control
+
+# 3. 起
+docker compose -f deploy/docker/compose.yaml up -d --build
+```
+
+## 为什么「nginx 一行都不用改」
+
+端口只发布到**宿主机回环**（`127.0.0.1:8787:8787`），所以宿主机上的
+`/etc/nginx/conf.d/drc.conf`（`proxy_pass http://127.0.0.1:8787`）原样继续工作，TLS 仍由
+nginx 终止。切容器化不动证书、不动反代，只换进程托管方式。
+
+三个必须自己记住的点：
+
+| 项           | 值                                         | 不这么做会怎样                                                                                                                           |
+| ------------ | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `DRC_BIND`   | 镜像里已经是 `0.0.0.0`，compose 里显式写死 | 容器内绑 `127.0.0.1` → `-p` 发布成功但**外面连不上**                                                                                     |
+| 端口发布     | `127.0.0.1:8787:8787`                      | 绑 `0.0.0.0:8787:8787` → 8787 直接暴露公网，绕过 nginx 的按 IP 限流                                                                      |
+| `/data` 属主 | `10001:10001`                              | 状态写不进去。2.x 起启动时会直接记一条 `state file is not writable` 的 **error**；1.x 时代只能等第一条 `state file write failed` 的 warn |
+
+## 运维
+
+```sh
+docker compose -f deploy/docker/compose.yaml ps         # STATUS 列会显示 healthy
+docker compose -f deploy/docker/compose.yaml logs -f relay
+docker compose -f deploy/docker/compose.yaml restart    # 优雅停机 → 最多 15s
+curl -s http://127.0.0.1:8787/healthz                   # version 必须是包的 version
+```
+
+日志是 **docker logs** 而不是 journald，过滤方式因此变了一点：
+
+```sh
+docker compose … logs relay | grep '"level":"warn"'     # 按 JSON 里的 level 过滤
+docker compose … logs relay | jq 'select(.msg=="counters")'
+```
+
+> 别用 `docker logs … | grep ERROR`：中继写到 stdout 的 JSON 不带级别前缀，
+> 按 "ERROR" 过滤很可能一条都出不来。按 JSON 里的 `level` 过滤。
+
+`docker logs` 有**条数上限**（每个容器默认保留若干 MB），所以 compose 里配了
+json-file 轮转（`max-size: 10m` / `max-file: 5`）。要长期留存就装一个日志驱动转发出去，
+别依赖 `docker logs`。
+
+## 升级与回滚
+
+```sh
+# 升级：构建 → 重启 → 看版本号变了没有
+docker compose -f deploy/docker/compose.yaml up -d --build
+curl -s http://127.0.0.1:8787/healthz | grep -o '"version":"[^"]*"'
+
+# 回滚：把标签切回去再 up（镜像还在本地）
+docker tag dsh-remote-relay:2.0.14 dsh-remote-relay:2.0.15
+docker compose -f deploy/docker/compose.yaml up -d
+```
+
+**回滚必须成对**（中继产物 + 主机插件产物）：两代握手帧名不兼容，只回滚一边会
+"永远配不上对"或"静默不上线"。见 `../SELF-HOSTING.md` §10.2 的对照表。
+
+## 拉不到 Docker Hub 怎么办
+
+生产那台机器 `registry-1.docker.io` 超时（而 npm registry 通）。三条路，按推荐顺序：
+
+1. **配 daemon 级镜像加速**（一劳永逸，`FROM` 不用改）—— **生产走的就是这条**：
+
+   ```json
+   // /etc/docker/daemon.json
+   { "registry-mirrors": ["https://6faa0280329c285d57dd15ba1333bdeb.d.1ms.run"] }
+   ```
+
+   ```sh
+   systemctl daemon-reload && systemctl restart docker
+   ```
+
+   > ⚠️ **`daemon.json` 要合并，不能覆盖。** 那台机器上原本已经有三条现网配置
+   > （`log-driver` + `log-opts`、`live-restore: true`、`default-address-pools`）。
+   > 写坏它会让 **docker 起不来**，而它是那台机器上所有容器的地基。
+   > 判据：`tests/docker.test.mjs` 里有「compose 不许覆盖 daemon 级设置」那条。
+   >
+   > 配完**必须核对 digest**，不能只看「拉下来了」：加速站是第三方，
+   > 拉到的内容是不是官方的，靠 `RepoDigests` 说话。
+   >
+   > ```sh
+   > docker image inspect node:22-alpine --format '{{index .RepoDigests 0}}'
+   > # node@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402
+   > ```
+   >
+   > 与直连 Docker Hub 拉到的是**同一个 digest**，才是可信的（2026-10-07 实测）。
+   >
+   > **加速地址会变**：它是按账号发的，换账号/换机器就是另一个串。
+   > 上面那个是 2026-10-07 生产实测可用的那一个；失效时按本文另一条路走。
+
+   ```
+
+   ```
+
+2. **本地打标签**：从可达的镜像站拉一份再改名，docker build 就不解析远端了。
+
+   ```sh
+   docker pull <mirror>/library/node:22-alpine
+   docker tag <mirror>/library/node:22-alpine node:22-alpine
+   ```
+
+3. **离线搬运**（生产那次就是这么发的）：在能上网的机器上构建并导出，拷过去导入。
+
+   ```sh
+   docker build -f deploy/docker/Dockerfile -t dsh-remote-relay:2.0.15 .
+   docker save dsh-remote-relay:2.0.15 | gzip > relay-2.0.15.tar.gz
+   scp relay-2.0.15.tar.gz root@HOST:/opt/dsh-remote-control/
+   ssh root@HOST 'gunzip -c /opt/dsh-remote-control/relay-2.0.15.tar.gz | docker load'
+   ssh root@HOST 'cd /opt/dsh-remote-control/dsh-remote-server && docker compose -f deploy/docker/compose.yaml up -d'
+   ```
+
+   > 目标机架构要和构建机一致（或构建时加 `--platform`）。arm64 机器上构建出来的
+   > 镜像在 x86_64 上起不来，而这类错误在 `docker compose up` 之前不会报。
+
+## 镜像里没有什么
+
+- **没有 node_modules、没有 npm install**：运行阶段只有 node 与那一个产物文件。
+- **没有 curl/wget**：健康检查用 node 自己发请求。
+- **没有 bash**：基础镜像是 alpine（用的是 busybox 的 `/bin/sh`，HEALTHCHECK 的 shell
+  形式用它）。
+- **没有状态文件**：`/data` 是挂进来的卷，且镜像**故意不设 `DRC_STATE_FILE`**——
+  落盘路径属于部署形态，与卷由 compose 并排配在一起。
+
+## 与 systemd 并存
+
+`deploy/systemd/dsh-remote-control.service` 仍然保留并可用，两条路共用同一个产物。
+**别同时开**（同一个端口只能有一个进程在听）。切回 systemd：
+
+```sh
+docker compose -f deploy/docker/compose.yaml down
+chown -R root:root /var/lib/dsh-remote-control   # 单元以 root 跑
+systemctl enable --now dsh-remote-control
+```
+
+### ⚠️ 从 systemd 切过来时，属主要在**停服务之后**改
+
+2026-10-07 第一次切容器时踩了，这个坑值得单独写一节，因为它**静默丢数据**。
+
+`daemon.json` / compose 都不管属主，容器以 uid 10001 跑，于是切换那一步要
+`chown -R 10001:10001 /var/lib/dsh-remote-control`。**但那必须放在 `systemctl stop` 之后**：
+
+单元里有 `StateDirectory=dsh-remote-control`，而 systemd 会在**每次停止/启动时**
+按单元的 `User=` 把那个目录的属主**改回去**。顺序反了就是：
+
+```
+chown 10001  →  systemctl stop（把属主改回 root）
+             →  起容器（uid 10001 读一个 root 拥有的 600 文件）
+             →  EACCES → state file unreadable, starting empty
+             →  30 秒后第一次落盘，把空状态写回去
+```
+
+最后那步是**不可逆**的：原来的配对记录被空状态覆盖，`conversations: 0`，
+用户必须重新扫码。实测这次就是这样丢了一条会话。
+
+正确顺序：
+
+```sh
+systemctl stop dsh-remote-control        # 先停，StateDirectory 就不再改属主
+chown -R 10001:10001 /var/lib/dsh-remote-control
+chmod 700 /var/lib/dsh-remote-control
+docker compose -f deploy/docker/compose.yaml up -d
+```
+
+**判据**：切完必看这三样，`stateRestored` 那个最要紧 ——
+`stateRestored:0` 而 `conversations:0` 就是"读不到旧状态、被当成空启动"，
+此时 `/healthz` 仍然是 `ok:true`，配对表面也正常，只有一处能看出来。
+
+```sh
+curl -s 127.0.0.1:8787/healthz | grep -o '"stateRestored":[0-9]*'
+docker logs dsh-remote-relay-relay-1 2>&1 | grep -i unreadable   # 必须没有
+```
+
+> `read_only: true` + `cap_drop: ALL` 下，容器**写不进** `/data` 时只会在
+> `/healthz` 的 `stateWriteFailures` 上体现，而配对表面完全正常 ——
+> 与 §0.1 记的那个老坑是同一族，容器只是给它多了一个成因（忘了挂卷 / 属主不对）。