Skip to content

relay-deployment.md

Latest commit

 

History

History
177 lines (128 loc) · 10.7 KB

relay-deployment.md

File metadata and controls

177 lines (128 loc) · 10.7 KB
Raw

自托管 Relay Hub — 部署运维速查

这是面向运维者的精简 runbook。完整图文指南（架构、TLS/反向代理、systemd、备份、故障排查）见文档站点 自托管 Relay Hub（英文版 /guide/relay-self-hosting）。 模块内部实现见 relay-module.md / relay-web-module.md。

安装

  • hub：npm i -g @ganglion/xacpx-relay —— 提供 xacpx-relay 二进制；看板（@ganglion/xacpx-relay-web，private）已内嵌在该包内，随包出厂，无需单独安装/构建。
  • 连接器（实例机）：xacpx plugin add @ganglion/xacpx-channel-relay —— 自动拉取 @ganglion/xacpx-relay-protocol；实例核心需 xacpx ≥ 0.17.0-beta.6（首个支持 model-set deadline 的版本）。
  • 从源码运行见文档站自托管 Relay Hub 的「从源码运行」details；发布流程见 relay-release.md。

快速上手（零参数）

所有参数都有合理默认值，最简流程不需要任何 flag：

# 1. 安装 hub（看板已内嵌在包里，无需单独构建）
npm i -g @ganglion/xacpx-relay

# 2. 生成访问令牌 — DB 自动建在 ~/.xacpx-relay/relay.db
xacpx-relay add token
# 输出示例：
#   access token: bBS9nN2W2MwdrdksoLTLrQeMLMah9M5flTOyEcBbIHc
#   (store it now — not shown again)
#   hint: use this token for web login AND: xacpx channel add relay --url wss://<host> --token <token>
# 把该令牌交给用户：Web 登录页「Access token」字段粘贴登录；同时用来配对连接器。

# 3. 起服务 — 自动使用同一个默认 DB，自动检测内嵌看板
xacpx-relay start
# 输出示例：
#   xacpx-relay listening: http :8787, instance gateway: merged on http :8787 (path / or /gateway), db ~/.xacpx-relay/relay.db, dashboard: /usr/lib/node_modules/@ganglion/xacpx-relay/dist/relay-web

# 4. 实例侧接入（同一个 access token 直接用于配对，--url 指向与看板相同的域名/主机——裸域名即 wss 根路径连入合并网关）
xacpx channel add relay --url wss://relay.example.com --token <上面的访问令牌> --name home-pc
xacpx restart

默认值说明：

  • --db → ~/.xacpx-relay/relay.db（绝对路径，父目录自动创建）
  • --web-root → 自动检测 hub 包内嵌入的 dist/relay-web；几乎不需要传
  • 其他：--host 0.0.0.0、--http-port 8787
  • --ws-port → 可选：省略（默认）= 实例网关合并到 HTTP 端口（连接器从根路径连入）；只有当你想把网关单独放在自己的端口上（便于单独防火墙，旧的双端口布局）时才传。

只有在需要自定义 DB 路径、绑定地址、端口或反向代理时才需要传 flag。

端到端（自定义路径示例）

# 自定义 DB 路径（生产环境推荐用绝对路径）
xacpx-relay add token --db /var/lib/xacpx-relay/relay.db

# 带全量参数启动（反向代理场景；--web-root 一般无需传，看板已内嵌）
# 默认单端口：实例网关合并在 HTTP 端口 8787 上，无需 --ws-port。
xacpx-relay start \
  --db /var/lib/xacpx-relay/relay.db \
  --host 0.0.0.0 --http-port 8787 \
  --history-retention-days 30 --request-timeout-ms 120000 --trust-proxy

关键事实

  • 单端口（默认）：只暴露一个端口 8787 = HTTP API + 看板 + 看板 /ws + 实例网关（实例网关合并为 HTTP 端口上的 WebSocket upgrade，实例/连接器从根路径 / 注册）。运维只需开放一个端口、一个域名，反代单条 reverse_proxy 127.0.0.1:8787 即可。生产经反代终结 TLS，实例用 wss://。仅当你想把实例网关单独放到自己的端口上分别防火墙时，才传 --ws-port <n>（恢复旧的双端口布局）。
  • xacpx-relay CLI 子命令：start / add token / ls / rm token <value-or-id> / update [--check]。没有 stop/status——用 Ctrl-C/SIGTERM（建议 systemd/pm2/Docker 托管）。
  • xacpx-relay update：自更新 hub 包（npm i -g @ganglion/xacpx-relay@latest；PACKAGE_MANAGER=bun 时改用 bun add -g）。--check 只比对当前与 npm 最新版本、打印结果而不安装。当前运行版本与「有可用更新」提示也会显示在看板设置页（见 relay-module.md 的 GET /api/version）。更新后需自行重启 hub 进程（systemd/pm2/Docker 重启即可）。
  • 持久化：全部在单个 SQLite 文件（--db）。默认 ~/.xacpx-relay/relay.db（固定绝对路径，父目录自动创建）。备份即停机/静默期 cp 该文件。
  • 凭证：访问令牌（access token）一令两用——既用于 Web 登录，也用于连接器首连（无需单独铸造配对令牌）。首连后实例换取长期凭证，写入 <xacpx-home>/relay/credential.json（0600），不进 config.json。
  • 自动 GC：每小时清理超 --history-retention-days（默认 30，另每会话硬上限 2000 条）的缓存消息，以及过期的 web 会话和配对令牌。
  • RPC 超时：--request-timeout-ms（默认 120000）限定网关 RPC 请求超时；agent 冷启动慢 / 长 prompt 时可调大。
  • 多租户：账号只见自己的实例/会话；服务端盖戳身份；登录令牌和凭证一律哈希存储。
  • 看板可安装为 PWA：看板是 PWA，可「添加到主屏 / 安装为独立窗口」并预缓存应用壳加速二次加载（实时数据仍走 /ws，不做离线数据）。前提是安全上下文：必须经反代终结 TLS 用 https:// 访问；纯 http://（局域网 IP 直连）下浏览器不会注册 Service Worker、也不显示安装入口。模块细节见 relay-web-module.md 的「PWA」段。

访问令牌管理

访问令牌（access token）是唯一的凭证形式——既用于 Web 登录，也直接用于连接器注册（无需单独的配对令牌）。

# 生成一个新访问令牌（令牌只打印一次）
xacpx-relay add token --db /var/lib/xacpx-relay/relay.db

# 生成时加上备注标签（--label 可选）
xacpx-relay add token --label laptop --db /var/lib/xacpx-relay/relay.db

# 列出所有令牌（显示短 id、标签、创建时间、实例数）
xacpx-relay ls --db /var/lib/xacpx-relay/relay.db

# 删除令牌及其关联账号（级联删除所有实例和历史）
# 可传令牌原值、完整 id 或 id 前缀（前缀唯一时才接受）
xacpx-relay rm token <value-or-id> --db /var/lib/xacpx-relay/relay.db

删除令牌后，该令牌派生的所有 web 会话同步失效（下次请求返回 401）。注意：已建立的 /ws 长连接不会被立即强制断开——需等到客户端重连时才感知；若需硬切，重启 hub 即可。

反向代理与限流（--trust-proxy）

限流按客户端 IP 统计。当 hub 位于 nginx/Caddy 等反向代理后方时，直接连到 hub 的 socket 地址是代理 IP，所有用户的失败计数会共用同一个桶。此时须传 --trust-proxy，hub 将读取 X-Forwarded-For 首部的真实客户端 IP：

xacpx-relay start --db /var/lib/xacpx-relay/relay.db --trust-proxy ...

不经反代直接暴露时不要传该标志，否则客户端可伪造 X-Forwarded-For 绕过限流。

Caddy 反向代理（最简配置）

hub 默认单端口（HTTP API + 看板 + 看板 /ws + 实例网关全部合并在 8787），所以 Caddy 只需一条 reverse_proxy 就能覆盖全部流量。Caddy v2 自动签发并续期 TLS 证书，并透明转发 WebSocket（实例网关的 wss:// 与看板 /ws 都无需额外配置）。

/etc/caddy/Caddyfile：

relay.example.com {
	reverse_proxy 127.0.0.1:8787
}
caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy   # 用 Caddy 服务托管时

配套要点：

  • hub 在反代后方，启动须带 --trust-proxy，限流才按真实客户端 IP 统计。Caddy 默认会写 X-Forwarded-For，无需额外指令。
  • 实例侧 --url 指向同一域名的 wss:// 根路径：xacpx channel add relay --url wss://relay.example.com --token <token> --name <name>。
  • Caddy 走 https:// 即满足 PWA 的安全上下文要求，看板可「安装到主屏」。纯 http:// 不会注册 Service Worker。
  • Caddy reverse_proxy 默认无请求体大小限制、对 WebSocket 长连接也不主动超时，看板的图片上传与长连接开箱可用；如需限制再按需加 request_body max_size。

进程托管（pm2）

xacpx-relay 没有 stop/status 子命令（用 Ctrl-C/SIGTERM 退出），适合交给 pm2 托管常驻、开机自启、崩溃重拉。

# 启动并命名为 xacpx-relay（-- 之后是传给 xacpx-relay 的参数）
pm2 start xacpx-relay --name xacpx-relay -- start

# 固化当前进程列表 + 生成开机自启脚本（按提示执行它打印的 sudo 命令）
pm2 save
pm2 startup

# 常用运维
pm2 logs xacpx-relay        # 看日志
pm2 restart xacpx-relay     # 改完配置 / xacpx-relay update 之后重启
pm2 stop xacpx-relay        # 停止

hub 的结构化日志直接写 stdout/stderr（error 级写 stderr，info/debug 写 stdout），不落文件，交给 pm2/systemd/Docker 的日志托管即可，pm2 logs xacpx-relay 能看到启动、登录被拒、实例上下线等事件。日志级别通过 RELAY_LOG_LEVEL=error|info|debug 环境变量控制，默认 info（debug 会额外打印看板 WebSocket 连接/断开等细粒度事件）。

pm2 会从 PATH 解析 xacpx-relay 并把绝对路径存进 dump，重启后也能恢复；万一 pm2 找不到（非标准安装），改传 command -v xacpx-relay 的绝对路径即可。

也可以用 ecosystem 文件固定参数，pm2 start ecosystem.config.js：

// ecosystem.config.js
module.exports = {
  apps: [{
    name: "xacpx-relay",
    script: "xacpx-relay",
    args: "start",
    autorestart: true,
  }],
};

升级流程：xacpx-relay update（或 xacpx-relay update --check 先比对版本）→ pm2 restart xacpx-relay 让新版本生效。

进阶（默认即可用，不必加）：默认 DB（~/.xacpx-relay/relay.db）和默认绑定（0.0.0.0:8787）开箱即用。仅在需要时才往 start 后追加参数：--db <path> 自定义 DB 路径（见「端到端（自定义路径示例）」）、--host 127.0.0.1 仅绑定本地、--trust-proxy 让限速按反代转发的真实客户端 IP 统计（见「反向代理与限流」）。

强制全员重登录

停止 hub，在 DB 中清空 web 会话，然后重启：

sqlite3 /var/lib/xacpx-relay/relay.db "DELETE FROM web_sessions;"
# 再重启 hub

所有用户的会话 cookie 失效，需重新粘贴登录令牌登录。