@dsh-remote/relay 0.0.0-stage → 3.1.0

package/deploy/docker/compose.yaml

@@ -0,0 +1,116 @@
+# 中继的容器编排（Compose v2，生产用的就是这一份）。
+#
+#   docker compose -f deploy/docker/compose.yaml up -d --build
+#   docker compose -f deploy/docker/compose.yaml ps        # 看健康状态
+#   docker compose -f deploy/docker/compose.yaml logs -f relay
+#   docker compose -f deploy/docker/compose.yaml down
+#
+# ## 变量从哪来
+#
+# Compose 自动读**本文件所在目录**的 .env。所以 token 写在那儿，而不是命令行上
+# （命令行会进 shell history，也会进 ps 的 argv）。.env 已被 .gitignore 忽略。
+# 下面每一条 都是"不配就与裸机 systemd 单元同义"——
+# 容器不该偷偷改变程序的默认行为，它只改变"怎么被托管"。
+#
+# ## 与裸机部署的关系：nginx 一行都不用改
+#
+# 端口只发布到**宿主机回环**（127.0.0.1:8787:8787），所以宿主机上的
+# /etc/nginx/conf.d/drc.conf（proxy_pass http://127.0.0.1:8787）原样继续工作，
+# TLS 仍然由 nginx 终止。切容器化不动证书、不动反代，只换进程托管方式。
+name: dsh-remote-relay
+
+# 具名卷：docker compose up 开箱即用，且属主由镜像里的 /data 决定（uid 10001）。
+# 要用宿主机路径（生产那样做，落在 /var/lib 下）就把 DRC_DATA_DIR 指过去并 chown。
+volumes:
+  relay-data:
+
+services:
+  relay:
+    build:
+      context: ../..
+      dockerfile: deploy/docker/Dockerfile
+      args:
+        # 标签里的版本/提交号。CI 与发布脚本会传；本地构建不传就是 0.0.0/unknown，
+        # 而真正认版本的地方是 /healthz（产物内注入），两者由构建阶段的断言绑定。
+        DRC_VERSION: ${DRC_VERSION:-0.0.0}
+        VCS_REF: ${VCS_REF:-unknown}
+    # 标签与 /healthz 的 version 分工：标签给 docker inspect 与部署脚本，
+    # /healthz 给运维"线上跑的是哪一版"。
+    image: ${DRC_IMAGE:-dsh-remote-relay}:${DRC_IMAGE_TAG:-local}
+
+    # 崩溃即拉起，与 systemd 的 Restart=always 同义。
+    # 刻意**不是** always：中继优雅停机时会 exit 0，always 会在 docker compose down
+    # 之后又把它拉起来（"停机之后进程自己回来了"是最难查的一类故障）。
+    restart: unless-stopped
+
+    ports:
+      # 只绑回环。公网走 443（宿主机 nginx），8787 不对公网。
+      - '127.0.0.1:${DRC_PORT:-8787}:${DRC_PORT:-8787}'
+
+    environment:
+      # 唯一必填项。写错/漏写时 compose 在**启动前**就报出来，而不是让容器起来
+      # 再自己拒绝启动（那时报错在 logs 里，人不一定看）。
+      DRC_HOST_TOKEN: ${DRC_HOST_TOKEN:?在 deploy/docker/.env 里设 DRC_HOST_TOKEN（openssl rand -hex 32）}
+      DRC_PORT: ${DRC_PORT:-8787}
+      DRC_BIND: '0.0.0.0'
+      DRC_PUBLIC_URL: ${DRC_PUBLIC_URL:-}
+      DRC_LOG_LEVEL: ${DRC_LOG_LEVEL:-info}
+      DRC_PAIR_TTL_MS: ${DRC_PAIR_TTL_MS:-120000}
+      # 落盘：与卷是一对，所以写在这里与下面的 volumes 并排。
+      # 默认用**具名卷**：Docker 会用镜像里 /data 的属主（uid 10001）初始化它，所以
+      # `docker compose up` 开箱即用。改成宿主机路径（bind mount）时，属主必须也是
+      # 10001，否则状态写不进去 —— 属主不对时 2.x 启动就会记一条 error；1.x 时代只能等
+      # 每 60 秒一条的 state file write failed，而配对表面完全正常（HANDOFF 0.1）。
+      DRC_STATE_FILE: ${DRC_STATE_FILE:-/data/state.json}
+      DRC_STATE_SAVE_MS: ${DRC_STATE_SAVE_MS:-60000}
+      DRC_MAX_CONNS: ${DRC_MAX_CONNS:-200}
+      DRC_CONV_IDLE_TTL_MS: ${DRC_CONV_IDLE_TTL_MS:-604800000}
+      DRC_HOST_GRACE_MS: ${DRC_HOST_GRACE_MS:-120000}
+
+    volumes:
+      - ${DRC_DATA_DIR:-relay-data}:/data
+
+    # 与 systemd 单元同款的加固，容器里没有理由更松：
+    #  - read_only + tmpfs /tmp：中继只写 /data（卷），其余一律只读；
+    #  - cap_drop ALL + no-new-privileges：它不需要任何 capability，也不需要提权；
+    #  - mem_limit 与单元里的 MemoryMax=512M 取同一个数，两套形态口径一致。
+    read_only: true
+    tmpfs:
+      - /tmp
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+    mem_limit: 512m
+    # 每条 WebSocket 占用一个文件描述符，默认上限对 maxConnections 来说偏紧。
+    ulimits:
+      nofile:
+        soft: 4096
+        hard: 4096
+
+    # 停机窗口要大于程序内部的 5 秒兜底（main.ts 的 shutdown guard），
+    # 否则 compose 先 SIGKILL，状态文件的最后一次补写就被砍掉了。
+    stop_grace_period: 15s
+    stop_signal: SIGTERM
+
+    # 日志轮转：生产上 relay 的日志是有界的（每个字符串值截断到 256 字符，
+    # tests/log.test.mjs 有判据），但**行数**无界。不设上限的话 json-file 会一直长，
+    # 把磁盘吃满——而这正是中继所在那台机器上唯一真正稀缺的东西。
+    logging:
+      driver: json-file
+      options:
+        max-size: '10m'
+        max-file: '5'
+
+    healthcheck:
+      test:
+        [
+          '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))",
+        ]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s

package/deploy/nginx/drc.conf

@@ -0,0 +1,69 @@
+# nginx vhost for the dsh-remote-control relay.
+#
+# Install to /etc/nginx/conf.d/drc.conf (conf.d is included inside the http
+# block, so the http-level directives below are valid here too).
+#
+#   drc.provid.cc  --wss-->  nginx (TLS)  --ws-->  127.0.0.1:8787
+#
+# Certificates are issued/renewed by acme.sh with the Aliyun DNS-01 hook
+# (see deploy/README.md). Nothing needs port 80 at renewal time.
+
+# ── http-level directives ────────────────────────────────────────────
+map $http_upgrade $connection_upgrade {
+    default upgrade;
+    ''      close;
+}
+
+# Per-IP throttle. The relay only has global + per-connection budgets because
+# it cannot see the real client IP; this is where per-IP limiting belongs.
+limit_req_zone $binary_remote_addr zone=drc:10m rate=20r/s;
+limit_conn_zone $binary_remote_addr zone=drc_conn:10m;
+
+# ── port 80: redirect only ───────────────────────────────────────────
+server {
+    listen      80;
+    listen      [::]:80;
+    server_name drc.provid.cc;
+    return 301 https://$host$request_uri;
+}
+
+# ── port 443: TLS + WebSocket reverse proxy ──────────────────────────
+server {
+    listen      443 ssl;
+    listen      [::]:443 ssl;
+    http2       on;
+    server_name drc.provid.cc;
+
+    ssl_certificate     /etc/nginx/ssl/drc.provid.cc.crt;
+    ssl_certificate_key /etc/nginx/ssl/drc.provid.cc.key;
+    ssl_protocols       TLSv1.2 TLSv1.3;
+    ssl_prefer_server_ciphers off;
+    ssl_session_cache   shared:SSL:10m;
+    ssl_session_timeout 1d;
+
+    add_header Strict-Transport-Security "max-age=31536000" always;
+    add_header X-Content-Type-Options nosniff always;
+
+    access_log /var/log/nginx/drc.access.log main;
+    error_log  /var/log/nginx/drc.error.log warn;
+
+    # WebSocket upgrade + long-lived connection
+    location / {
+        limit_req  zone=drc burst=40 nodelay;
+        limit_conn drc_conn 8;
+
+        proxy_pass         http://127.0.0.1:8787;
+        proxy_http_version 1.1;
+        proxy_set_header   Upgrade           $http_upgrade;
+        proxy_set_header   Connection        $connection_upgrade;
+        proxy_set_header   Host              $host;
+        proxy_set_header   X-Real-IP         $remote_addr;
+        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
+        proxy_set_header   X-Forwarded-Proto $scheme;
+
+        # the relay is a long-lived socket: never time it out mid-session
+        proxy_read_timeout  3600s;
+        proxy_send_timeout  3600s;
+        proxy_buffering     off;
+    }
+}

package/deploy/systemd/dsh-remote-control.service

@@ -0,0 +1,66 @@
+# systemd unit for the dsh-remote-control relay.
+#
+#   /etc/systemd/system/dsh-remote-control.service
+#   /etc/dsh-remote-control.env      (chmod 600, DRC_HOST_TOKEN=...)
+#
+# The relay binds 127.0.0.1 by default — nginx terminates TLS and proxies wss
+# to it. (Override with DRC_BIND in the env file if it must be the edge.)
+#
+# What actually runs is ONE self-contained file. `pnpm build`
+# emits dist/bundle/main.js with `ws` and the protocol layer (dsh-remote-wire) inlined,
+# so the deployment is "copy that file" — no node_modules, no `npm install --omit=dev`,
+# and therefore no way for the server's dependency tree to drift from CI's.
+# The old unit ran `src/main.mjs`; that entry point is gone, and `dist/src/main.js`
+# (the unbuilt-tree form) needs devDependencies to resolve dsh-remote-wire —
+# the bundle is the only supported production entry.
+
+[Unit]
+Description=DSH Remote Control relay (zero-knowledge WebSocket relay)
+Documentation=file:///opt/dsh-remote-control/README.md
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/opt/dsh-remote-control/server
+EnvironmentFile=/etc/dsh-remote-control.env
+ExecStart=/usr/bin/node /opt/dsh-remote-control/server/relay.mjs
+Restart=always
+RestartSec=3
+
+# The relay already handles SIGTERM gracefully (drain sockets, exit 0);
+# give it room, then be firm.
+TimeoutStopSec=15
+KillSignal=SIGTERM
+
+# 会话表落盘（DRC_STATE_FILE）用的目录。
+#
+# 这条是 `ProtectSystem=strict` 的直接后果，不是顺手加的：strict 把整个文件系统
+# 挂成只读（除 ReadWritePaths），所以 2026-10-06 第一次上 1.0.6 时，
+# 状态文件写到 /var/lib/... 每 5 秒失败一次（EROFS），配对表面还在、其实**永远不落盘**。
+# StateDirectory= 让 systemd 建目录、按 User/Group 修属主，并在 strict 下把这一个
+# 路径放回可写——**不需要**为它放松 ProtectSystem。
+# 别改成 ReadWritePaths=/var/lib：那是把整个 /var/lib 放开，范围大得多。
+StateDirectory=dsh-remote-control
+UMask=0077
+
+# --- hardening ---
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/opt/dsh-remote-control
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+MemoryMax=512M
+
+# --- logging ---
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=dsh-remote-control
+
+[Install]
+WantedBy=multi-user.target

package/deploy/windows/drc-relay-install.cmd

@@ -0,0 +1,113 @@
+@echo off
+rem ============================================================================
+rem  drc-relay-install.cmd — 把中继装成 Windows 服务（V3-PLAN D1 / §6.3）
+rem
+rem  为什么需要这个：v2 只有 Linux（systemd）与容器两条路，Windows 上没有配方。
+rem 而"服务停止"在 Windows 上是**硬杀**——Node 收不到 SIGTERM，
+rem 于是排空（close）与兜底落盘（forceShutdown）一次都不跑（见 §A3 / lifecycle.ts）。
+rem 装成服务之后至少有了「停止 = 走一遍优雅停机」这条��。
+rem
+rem  用法（管理员 PowerShell 或 cmd）：
+rem   1) 先构建（Linux/macOS 同理）：pnpm -C packages/relay build
+rem   2) 设好环境变量（见下）
+rem   3) drc-relay-install.cmd install
+rem
+rem  依赖：NSSM（把任意 exe 变成 Windows 服务）。这是**外部**依赖，不进本仓——
+rem  它是 Windows 上没有内置 service wrapper 的事实所迫（systemd 是 Linux 自带的）。
+rem  下载：https://nssm.cc/ （解压后把 nssm.exe 放到 PATH，或用 NSSM 环境变量指到它）
+rem ============================================================================
+setlocal enabledelayedexpansion
+
+set "APP_DIR=%~dp0..\server"
+set "SERVICE_NAME=dsh-remote-relay"
+set "DISPLAY_NAME=DSH Remote Control Relay (zero-knowledge)"
+set "DESCRIPTION=DSH Remote Control 的零知识中继。只做路由，不碰载荷明文。"
+set "NSSM=%NSSM%"
+
+if "%NSSM%"=="" set "NSSM=nssm.exe"
+
+if not exist "%APP_DIR%\relay.mjs" (
+  echo [x] 找不到 %APP_DIR%\relay.mjs
+  echo     先构建并拷贝产物：pnpm -C packages/relay build
+  echo     然后把 dist\bundle\main.js 放到 %APP_DIR%\relay.mjs
+  exit /b 1
+)
+
+rem ── 环境变量：凭据不进命令行历史，也不进服务描述 ───────────────────────────
+rem ⚠️ 中继**没有** hostToken 就在启动时拒绝（这是协议层纪律）。
+rem    所以下面两行必须配好，否则服务起来又立刻退出，日志里只有 "fatal"。
+if "%DRC_HOST_TOKEN%"=="" (
+  echo [!] 未设 DRC_HOST_TOKEN。中继缺它会**拒绝启动**——先设好再装。
+  echo     临时设：set DRC_HOST_TOKEN=...  ^(openssl rand -hex 32 生成^)
+  exit /b 1
+)
+
+if /i "%~1"=="install" goto :install
+if /i "%~1"=="uninstall" goto :uninstall
+if /i "%~1"=="status" goto :status
+goto :usage
+
+:install
+echo [1/4] 注册服务 %SERVICE_NAME% ...
+"%NSSM%" install "%SERVICE_NAME%" "%APP_DIR%\relay.mjs"
+if errorlevel 1 goto :nssm_failed
+
+echo [2/4] 设置 AppDirectory ...
+"%NSSM%" set "%SERVICE_NAME%" AppDirectory "%APP_DIR%"
+
+echo [3/4] 设置环境变量（凭据 / 端口 / 绑定）...
+rem  nssm set 会把值写进服务配置，落在注册表里 —— 所以这台机器的凭据由它的 ACL 守着。
+rem  **不要**把 hostToken 写进 deploy 文件或文档示例里。
+"%NSSM%" set "%SERVICE_NAME%" AppEnvironmentExtra "DRC_HOST_TOKEN=%DRC_HOST_TOKEN%" "DRC_PORT=%DRC_PORT%" "DRC_BIND=127.0.0.1" "DRC_LOG_LEVEL=info"
+if "%DRC_STATE_FILE%"=="" (
+  echo     提示：未设 DRC_STATE_FILE = 重启丢失全部配对（纯内存）。生产请设。
+) else (
+  "%NSSM%" set "%SERVICE_NAME%" AppEnvironmentExtra "DRC_STATE_FILE=%DRC_STATE_FILE%"
+)
+
+echo [4/4] 配置日志与重启策略 ...
+rem  默认级别 info：debug 会把**完整配对码**打进日志（server.ts）。
+"%NSSM%" set "%SERVICE_NAME%" AppStdout "%APP_DIR%\logs\relay.out.log"
+"%NSSM%" set "%SERVICE_NAME%" AppStderr "%APP_DIR%\logs\relay.err.log"
+"%NSSM%" set "%SERVICE_NAME%" AppRotateFiles 1
+"%NSSM%" set "%SERVICE_NAME%" AppRotateBytes 10485760
+rem  服务被停止时先发 Ctrl+C（= SIGINT）而不是 TerminateProcess：
+rem 那 5 秒里排空与兜底落盘才跑得起来（lifecycle.ts 的 registerSignalHandlers）。
+"%NSSM%" set "%SERVICE_NAME%" AppStopMethodConsole 15000
+
+if not exist "%APP_DIR%\logs" mkdir "%APP_DIR%\logs"
+
+echo.
+echo ✅ 已安装为服务。常用命令：
+echo    %NSSM% start   %SERVICE_NAME%     启动
+echo    %NSSM% stop    %SERVICE_NAME%     停止（走优雅停机）
+echo    %NSSM% status  %SERVICE_NAME%     看状态
+echo.
+echo ⚠️ 反代与防火墙（这一步**不能省**）：
+echo    - TLS 由反代终止（IIS / nginx / Caddy）。中继只绑 127.0.0.1。
+echo    - 反代必须转发 WebSocket 升级头（Upgrade / Connection / Host）。
+echo    - 防火墙：**不要**把 8787 暴露到公网（那样就绕过了反代的按 IP 限流）。
+exit /b 0
+
+:uninstall
+"%NSSM%" stop "%SERVICE_NAME%" >nul 2>&1
+"%NSSM%" remove "%SERVICE_NAME%" confirm
+echo ✅ 已卸载服务（%APP_DIR% 下的文件与日志保留）。
+exit /b 0
+
+:status
+"%NSSM%" status "%SERVICE_NAME%"
+exit /b 0
+
+:nssm_failed
+echo [x] NSSM 调用失败。检查 "%NSSM%" 是否可用（set NSSM=D:\path\to\nssm.exe）。
+exit /b 1
+
+:usage
+echo 用法：
+echo   %~nx0 install      装成 Windows 服务（需要管理员）
+echo   %~nx0 status       看服务状态
+echo   %~nx0 uninstall    卸载服务
+echo.
+echo 前置：pnpm -C packages/relay build，并把 dist\bundle\main.js 放到 %APP_DIR%\relay.mjs
+exit /b 1