# 自部署 Server [English](README.md) · **中文** 单账号 Remote Server,支持 WebRTC(LAN / P2P / TURN)与端到端加密 Relay,环境变量配置账号密码,Web 提供首页、登录和设备状态页。Server 不包含在 Host 插件 bundle 中,需要单独部署。 当前版本定位为继续维护的最小自部署 Server。完整 Server Web 的产品形态仍在调整,暂不承诺在本仓库开源当前或未来的完整站点。 ## 自部署页面 首页地址是 `/`,点击“开始使用”进入登录页;登录成功后进入 `/app/remote` 设备列表。Host 和客户端都填写同一个 Server 地址,并使用相同的账号密码登录。设备凭据由 Server 保存,Web 登录会话使用 HttpOnly Cookie。 ## 刷新响应丢失恢复 刷新成功但响应丢失时,重试旧 refresh token 会返回同一组后继凭据,Server 重启后也可恢复。恢复持续到后继再次轮换、撤销或过期,不延长任何 token 的生命周期。若恢复的 access token 已过期,可用恢复的 refresh token 再次轮换。更早的旧 token 会被拒绝,但不撤销当前有效凭据。 已有设备数据保持兼容。升级前已经消耗的 token 没有恢复元数据,无法恢复;已撤销或过期的凭据仍需重新登录。仅更新 Plugin 不会增加此 Server 行为。恢复元数据不保存明文 bearer token,详见 [刷新协议](../../docs/protocol.md#82-refresh)。 ## Docker 部署 使用官方最新版镜像(`latest`): ```text ghcr.io/liguobao/ds-harness-remote/server:latest ``` ```bash cd apps/server cp .env.example .env # 编辑 .env,设置账号、密码和访问地址 docker compose pull server docker compose up -d --no-build server ``` 打开 。设备凭据保存在 `server-data` 卷;停止使用 `docker compose down`。 更新到最新发布的镜像,在同一目录执行(保留 `.env` 和现有数据卷): ```bash docker compose pull server docker compose up -d --no-build server ``` `latest` 指向最近一次 Tag 工作流发布的镜像,不跟随 main 分支。若要从当前源码自行构建,执行 `docker compose up -d --build server`。 若旧镜像启动时无法解析 `@dsh-remote/protocol`,更新源码后执行 `docker compose build --no-cache server && docker compose up -d server`。镜像显式包含 protocol 编译产物,并在构建阶段校验 Server 的模块加载;重建会保留数据卷。 GitHub Tag 工作流发布包含 `linux/amd64` 和 `linux/arm64` 的多架构生产镜像,拉取时 Docker 自动选择匹配的架构。生产环境应使用 HTTPS 反向代理,不要直接把 Node 监听端口暴露到公网。 ### 页面白屏或静态资源返回 403 `DSH_SERVER_PUBLIC_URL` 必须与浏览器实际访问的 origin 一致,包括 `http` / `https`、域名和非默认端口;不要填写容器内部地址或页面路径。例如通过 `https://remote.example.com` 访问时,在 `.env` 设置: ```dotenv DSH_SERVER_PUBLIC_URL=https://remote.example.com ``` 修改后执行 `docker compose up -d --force-recreate server`;仅 `docker compose restart` 不会更新环境变量。使用预构建镜像时可加 `--no-build`。保留现有数据卷,不要执行 `down -v`。 如果 JS/CSS 返回 403,且响应 JSON 中为 `AUTH_INVALID`,优先核对上述配置与请求的 `Origin`。Server 在静态资源处理前执行 origin 校验;因此首页可能打开,JS/CSS 却被拒绝,浏览器随后报告 MIME 为 `application/json` 并白屏。不要通过修改 MIME 或删除 origin 校验来绕过。若响应来自反向代理,则检查代理访问规则;代理应保留浏览器原始 `Origin`。 源码 Docker 构建报 protocol 入口无法解析时,也检查文件权限(`ls -ld packages/protocol packages/protocol/package.json`)。镜像会规范化发布文件的读取/目录遍历权限,并在最终 `node` 用户下校验模块加载。 ## 本地启动 需要 Node.js 22、pnpm 9.15.4。在仓库根目录执行: ```bash pnpm install pnpm --filter @dsh-remote/protocol build pnpm --filter @dsh-remote/server build cp apps/server/.env.example apps/server/.env ``` 编辑 `apps/server/.env`,设置账号和至少 12 字符的密码,然后启动: ```bash cd apps/server node --env-file=.env dist/main.js ``` 打开 。Host 和客户端填写同一 Server 地址,使用同一账号密码登录。建议账号使用邮箱格式,以兼容现有客户端。 | 环境变量 | 用途 / 默认值 | | --- | --- | | `DSH_SERVER_ACCOUNT` | 必填,登录账号 | | `DSH_SERVER_PASSWORD` | 必填,至少 12 字符 | | `DSH_SERVER_PUBLIC_URL` | 浏览器访问地址,默认 `http://localhost:8080` | | `DSH_SERVER_HOST` | 监听/端口映射地址,默认 `127.0.0.1`;局域网设为 `0.0.0.0` | | `DSH_SERVER_PORT` | 默认 `8080` | | `DSH_SERVER_DATA_FILE` | 默认 `data/state.json`,相对启动目录 | | `DSH_SERVER_TRUSTED_PROXY_IPS` | 受信任反向代理 peer IP 列表,逗号分隔;留空(默认)时忽略转发 IP | | `DSH_SERVER_STUN_URLS` | 下发给 Host/Client 的 STUN URL,逗号分隔;留空(默认)时只使用 host candidate | | `DSH_SERVER_TURN_URLS` | TURN URL,逗号分隔;必须同时配置 `DSH_SERVER_TURN_SECRET` 或 `DSH_SERVER_TURN_USERNAME` + `DSH_SERVER_TURN_PASSWORD` | | `DSH_SERVER_TURN_SECRET` | coturn REST API 共享密钥;不会下发给客户端 | | `DSH_SERVER_TURN_USERNAME` | 无法使用共享密钥的部署的静态 TURN 用户名;与 `DSH_SERVER_TURN_SECRET` 互斥 | | `DSH_SERVER_TURN_PASSWORD` | 静态 TURN 密码;必须与 `DSH_SERVER_TURN_USERNAME` 同时配置 | | `DSH_SERVER_TURN_TTL_SECONDS` | TURN credential 有效期秒数,60–3600,默认 `300`(仅对短期凭据生效) | 公网使用 HTTPS 反向代理,并将 `DSH_SERVER_PUBLIC_URL` 设为实际域名;代理需支持 `/ws/v1/connect` 的 WebSocket Upgrade,空闲超时大于 75 秒。 ## WebRTC 与 TURN Server 协调与托管 Server 相同的四条路径:`LAN -> P2P -> TURN -> Relay`。 - 在已授权连接的两台设备之间转发 WebRTC `signal.offer` / `signal.answer` / `signal.ice`,并转发发起方的 `transport.selected`(包含对旧 Host 的 `lan -> p2p` 兼容降级)。 - 仅向正在建立的连接的两台设备签发短期 STUN/TURN 配置:`GET /api/v1/turn/credentials`。TURN credential 采用 coturn REST API:`username=<过期秒级时间戳>:`,`credential=base64(HMAC-SHA1(secret, username))`。 - Server 不读取也不解密业务流量:WebRTC 直接承载 Noise 密文,TURN 只转发 WebRTC 数据包,Relay 通过 WebSocket 转发密文。 - WebRTC/TURN 不可用时客户端会自动回退到加密 Relay;`DSH_SERVER_STUN_URLS` / `DSH_SERVER_TURN_URLS` 留空即保持原来的 Relay-only 行为。 需要单独部署 coturn,配置 `use-auth-secret` 且 `static-auth-secret` 与 `DSH_SERVER_TURN_SECRET` 一致,开放 TURN 端口(通常为 3478/UDP、TCP 以及 relay 端口段),并让 STUN/TURN URL 指向 Host 与 Client 都能访问的地址。HTTPS 反向代理只需承载控制 WebSocket 与 REST API,WebRTC/TURN 流量不经过它。 无法使用共享密钥的 TURN 部署可改设 `DSH_SERVER_TURN_USERNAME` + `DSH_SERVER_TURN_PASSWORD`(与 `DSH_SERVER_TURN_SECRET` 互斥,二者不可同时配置);Server 会把静态凭据下发给连接参与方。优先使用 REST API 短期凭据——静态凭据在轮换前被所有连接共用。 ### 反向代理下的限流 默认按 socket peer IP 限流并忽略 `X-Forwarded-For`。使用反向代理时所有连接都来自代理,全部客户端会共用 240/min 的 API 限额和 20/min 的登录限额。将 `DSH_SERVER_TRUSTED_PROXY_IPS` 设为受信任代理 peer IP 的逗号分隔列表,即可按真实客户端 IP 分别限流: ```dotenv DSH_SERVER_TRUSTED_PROXY_IPS=172.18.0.2,2001:db8::2 ``` 只接受纯 IPv4 / IPv6 字面量;端口(`10.0.0.1:8080`)、CIDR 网段(`10.0.0.0/8`)和域名会在启动时报错,也不会默认信任任何私网网段。IPv4-mapped IPv6(`::ffff:127.0.0.1`)会规范化为 `127.0.0.1`,两种写法匹配同一条配置。 来自受信任 peer 的请求必须带且仅带一个 `X-Forwarded-For` 头,且值为单个 IP 字面量。缺失、重复、逗号分隔多 IP、`IP:port` 或域名都会返回 HTTP 400 `INVALID_MESSAGE`。其他 peer 的请求一律按 socket IP 处理,客户端无法自行伪造该头来冒充别的地址。 受信任代理必须**覆盖** `X-Forwarded-For` 为真实客户端 IP(不要追加或透传客户端自带的值),并且 Server 端口不能直接暴露到公网,否则信任边界会被绕过。在 Docker 中应填写代理**在 Server 容器内看到的地址**(可用 `docker network inspect <网络名>` 查看),不是 `127.0.0.1`:容器内该地址是 Server 自身。WebSocket 连接和共享同一公网 NAT IP 的客户端仍按同一 IP 共享限额。 修改后执行 `docker compose up -d --force-recreate server`;`docker compose restart` 不会重新加载环境变量。 ## 功能 - 支持设备注册、凭据刷新、设备发现、Control、WebRTC LAN/P2P/TURN 协调与端到端加密 Relay。 - 单进程运行;持久化保存 `data` 目录。重启后设备凭据保留,Web 需重新登录;修改密码后设备需重新授权。 验证:`pnpm --filter @dsh-remote/server test`。真实跨机与长期连接仍待回归。UI 复用来源见 [web/UPSTREAM.md](web/UPSTREAM.md)。 ## 常见问题 ### 会开源当前的完整 Server Web 吗? 暂不考虑。Server Web 的产品形态我还在调整,后续会按实际思路继续演进;当前仓库只承诺维护上面介绍的最小自部署版本。 ### 为什么没有多账号、完整 membership 和 Remote Web? 这些能力本身实现门槛不高,但不同用户会有不同的场景和取舍,建议按自己的需求修改。Remote Web 稳定后,未来也可能加入当前 Server;目前没有固定时间表。 ## 发布 Tag 检查 发布 Tag 必须与根 `package.json` 和 `packages/plugin/package.json` 的版本一致,例如 `v0.4.15`。Tag 工作流会执行 workspace check、测试、构建、插件 npm 打包、Browser 扩展打包和 SHA256 校验;Server Docker 镜像也从同一个 Tag 构建。 本地可先运行: ```bash pnpm --filter './packages/**' -r build pnpm -r check pnpm -r test NODE_ENV=production pnpm --workspace-concurrency=1 -r build node scripts/verify-dsh-plugin.mjs pnpm --dir packages/plugin pack --pack-destination /tmp/dsh-release-assets ```