# Reachy Relay Server

独立部署包，版本 **1.0.0**。无需桌面应用源码、Node、Rust 或容器平台。
维护服务器上的 coturn、TURN 临时凭据服务、固定 Central 加密出口和受限 SSH 通道。
目前按**一台机器人、一组已登记客户端密钥**设计；不提供多租户账号管理。

机器人保持现有 Hugging Face 认证。Central 出口只帮助已有有效认证的机器人上线，
不提供首次登录、令牌刷新或任意网站代理。腾讯、新加坡或其他云厂商均不写死在部署包内。
新服务器能否稳定访问官方 Central，必须通过健康检查确认。

## 环境

- Ubuntu 22.04 / 24.04 或 Debian 12，systemd 正常运行，Python 3.10+，root 权限。
- 服务器具有公网 IPv4；配置 `bind_ipv4` 为实际网卡 IPv4，`public_ipv4` 为外部地址。
- 允许 SSH TCP、TURN TCP/UDP 3478、媒体 UDP 49160–49200（端口可配置）。
- 18443、18444、22022 只监听回环，不开放到公网；不开放机器人 daemon 或 Netdata。
- 云防火墙、NAT 映射和域名 DNS 由运营者管理，部署程序不会修改整机防火墙。
- 应使用专用中继或明确允许接管现有 coturn 配置的服务器。安装会管理 `/etc/turnserver.conf`
  和专用 `reachy-*` 服务/SSH 账号，不能与其他业务共用同一个 coturn 实例。

已在本机和现有 Ubuntu 24.04 腾讯节点通过 15 项测试；腾讯节点另通过只读健康、SSH 配置与 systemd 服务校验。
尚未在全新服务器执行完整安装或迁移；其他支持版本也未做真实新机安装验收。

## 一键安装 / 升级

先将解压后的完整发布包、配置和登记材料通过管理 SSH 上传到目标服务器。
不要执行来源不明的在线 `curl | sh` 脚本。

1. 复制 `config.example.json` 为服务器配置，填写公网地址、网卡地址和 SSH 地址。
2. 在权限为 0700 的登记目录放入这三个文件：
   - `robot-tunnel.pub`：机器人现有中继 SSH 公钥。
   - `mac-diagnostics.pub`：桌面现有诊断 SSH 公钥。
   - `device-digests`：已有设备凭据的 SHA-256 登记值，每行一个。
     通过旧服务器导出，不要粘贴或上传原始 HF token。
3. 执行：

```sh
./relayctl verify
sudo ./relayctl install --config /root/relay.json --enrollment /root/relay-enrollment --install-deps
```

同一条命令用于升级。第一次 `--install-deps` 安装 coturn、OpenSSH 与 curl；依赖已齐全时可省略。
安装保留原有 TURN 密钥，新服务器才生成新的随机密钥。不会生成或替换客户端私钥。
无配置变化时不重启正在运行的服务；停止的受管服务会启动。
有变更的升级与回滚会短暂重启中继，应在没有通话的维护时段执行。

安装会先备份受管文件和服务启用/运行状态，校验 SSH 配置后加载服务，再检查运行状态、
匿名凭据请求是否被拒绝、Central 出口是否可达。失败时自动恢复文件和原有服务状态。
部署输出只有状态与回滚编号，不输出凭据或配置中的中继密钥。

预览不安装依赖、不生成密钥、不修改系统：

```sh
./relayctl render --config relay.json --output ./preview
```

预览 coturn 文件使用不可部署的占位密钥，不能直接拿去启动服务。

## 日常维护

```sh
sudo ./relayctl health
sudo ./relayctl rollback 20260910T120000Z-abcdef
```

回滚编号来自对应安装的输出，也可在 `/var/lib/reachy-relay/backups/` 查看。
该目录含旧配置和中继密钥，仅 root 可读。回滚不卸载系统软件包或删除账号；
新建账号仍受专用 SSH 约束，不会授予管理 shell。

服务器健康检查只证明本机服务与 Central 出口可用，不等于客户端认证、媒体质量或全链路验收。
程序不会自动重启机器人、刷新其登录、触发电机动作或开启通话。

## 迁移到另一台服务器

保留旧节点，先部署新节点，再切换客户端。无需复制旧 TURN 密钥：临时凭据会由新节点重新签发。
旧服务器的管理 SSH 主机私钥也不应复制到新服务器。

在旧节点导出登记信息：

```sh
sudo ./relayctl export-enrollment --output /root/relay-enrollment.tar.gz
```

归档权限为 0600，只有客户端公钥和设备摘要，没有原始 HF token、客户端私钥或 TURN 密钥。
仍应通过受信管理通道传输，不加入源码或公开下载。
在新节点将其解压到 0700 私有目录，按上面的安装命令部署新配置。

生成客户端切换模板：

```sh
./relayctl clients --config relay.json --output ./clients
```

输出：

- `reachy-relay-link.service`：机器人常驻 SSH 通道。
- `remote-relay.example.json`：桌面应用的原生中继配置模板。
- `desktop-ssh.conf`：手动外层 SSH 转发的备选模板。
- `firewall.txt`：本次配置所需的开放端口。

切换前必须核对新服务器主机指纹：在服务器控制台读取
`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`，与通过管理通道取得的主机公钥核对，
再更新机器人专用 known_hosts 和桌面 known_hosts。
部署包不会自动信任 `ssh-keyscan` 结果，不关闭 StrictHostKeyChecking。

机器人模板默认使用 `/home/pollen/.ssh/reachy-relay` 与 `reachy-relay-known-hosts`。
迁移已有机器人时，把这两项调整为它**现有私钥路径**和已核对的新主机密钥文件，
保留原账号、daemon、网络模块和认证；安装模板为原 `reachy-relay-link.service` 后，
运行 `systemctl daemon-reload` 与 `systemctl restart reachy-relay-link`。
已经部署的独立 Central 网络模块仍通过本机 18444 访问，不需要修改官方 daemon。

桌面优先使用原生 `remote-relay.json`，填入真实绝对密钥路径，放到应用数据目录；
现有用户应仅更新自己的现有配置，并保留副本。
手动 SSH 转发是备选方式，不要与原生转发同时占用本机 22022。
在应用中选择 `127.0.0.1:22022` 作为该机器人的私有线路时，内层 SSH 仍校验机器人的密钥。
如果继续使用局域网 SSH，监控线路可以暂时不切换。

迁移验收：

1. 桌面退出、旧桌面代理不可用时，机器人仍能在 Central 上线。
2. 重启机器人中继通道后自动恢复（不要求重启 daemon）。
3. 桌面自动连接控制；监控和诊断数据新鲜。
4. 手动开启通话时验证 TURN 中继；只做服务健康检查不算媒体验收。
5. 确认完成后再停用旧节点；失败时恢复旧主机地址、已保存的主机密钥和客户端配置。

## 发布与源码

```sh
python3 -m unittest discover -s tests
python3 build-release.py --output ./dist
```

发布包只收录工具、示例、说明、测试和运行时；不收录本机配置、登记材料、备份、私钥或 token。
包内 `SHA256SUMS` 和包外 `.sha256` 用于检测损坏，**不是发布者签名**；发布来源仍需可信。
`runtime/` 是服务代码唯一来源，旧 `scripts/remote` 入口通过兼容链接引用，不要求部署桌面应用。

当前包包含服务器部署和已有机器人迁移模板；全新机器人初始化不在此包范围。