Files
AndroidDeviceStreaming/docs/cluster.md
T

75 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 控制中心、多中继与 P2P
## 当前部署
| 角色 | 主机 | 服务与入口 |
| --- | --- | --- |
| 控制中心 | 175.178.213.60 | ads-server,127.0.0.1:18081,`wss://ttstd.com/ads` |
| relay-1 | 175.178.213.60 | ads-relay,127.0.0.1:18082,Nginx `wss://ttstd.com/ads-relay-1` |
| relay-2 | 47.242.112.133 | ads-relay,443 TLS,`wss://ttstd.com`,origin 指定 47.242.112.133:443 |
| STUN | 两台公网主机 | 复用已有 coturn 的 UDP 3478;已验证公网 Binding 响应 |
| 设备端 | Windows 192.168.5.222 | ADS-Agent 计划任务;home-phone → 192.168.100.141:5555 |
两节点均使用 ttstd.com 的有效证书;origin 覆盖 TCP 地址,TLS SNI、主机名和证书校验保持开启。无需新增 DNS 才能使用当前配置。当前证书到期时间为 **2026-11-28 06:59:59 UTC**,续期后必须同步到 relay-2 的 `/etc/ads/tls/` 并重启其 ads-relay;第一台使用原 Nginx 证书。若改用不同子域名,需要分别配置 A 记录和匹配证书,再更新 cluster.json 的 URL;可去掉 connect_address 使用域名解析。
此处 IP 为部署信息,不包含登录密码或角色令牌。两端只需要控制中心地址和各自角色令牌,不需要知道中继共享密钥。
## 连接与回退
1. 设备端带 agent 角色注册,本地端带 client 角色取得独占租约。
2. 中心生成会话,将 SDP 与双方各自的中继票据发给对应端。
3. 默认通过 STUN 收集地址,以可靠有序的 WebRTC DataChannel 连接。默认也允许 LAN/VPN 候选地址;`--p2p-public-only` 仅公布公网候选用于诊断。
4. P2P 默认最多尝试 10 秒,失败后尝试中继:健康节点优先,同一健康状态按 priority(越小越优先),相同 priority 按负载排序。每个节点连接有超时,失败尝试下一节点。
5. 中心每 5 秒探测一次 `/healthz`。节点健康是中心视角;两端仍各自验证能否连接。
6. 租约或 agent 控制断线会关闭会话信令;两端停止数据通道,中心向各节点发送撤销。节点保留 2 分钟撤销记录,阻止旧票据重新连接。
P2P 需要两端能够互通 UDP。复杂 NAT、UDP 被阻止时会使用 WSS 中继;无需为桌面或远程电脑做路由器映射。已有 TCP 流不能在故障时无缝迁移:流断开后由 ADB 每 5 秒重试并重新选路。scrcpy 会话中断后可能需要重新打开控制窗口。
当前是单控制中心,状态在内存,无数据库、账号多租户或控制中心高可用。中心重启后两端重连;不是多控制中心一致性系统。v1 兼容客户端仍可能通过中心转发数据,v2 的 data_bytes=0 仅描述 v2 信令端点。
## 配置与服务
- `deploy/cluster.example.json`:节点 ID、WSS URL、可选 origin、priority、STUN URL 和 P2P 超时。
- `deploy/ads-control.service`:控制中心,读取 `/etc/ads/server.env`,需 ADS_AGENT_TOKEN、ADS_CLIENT_TOKEN、ADS_RELAY_SECRET;原先的 ads-server.service 仍作为单机模式示例。
- `deploy/ads-relay.service`:节点 1,读取 `/etc/ads/relay.env` 中 ADS_RELAY_SECRET。
- `deploy/ads-relay-tls.service`:节点 2,直接 TLS,使用 CAP_NET_BIND_SERVICE 绑定 443,进程以 ads 用户运行。
- `deploy/nginx-ads-relay-path.conf`:加入现有 HTTPS server,转发 relay-1 前缀;不缓存、不记录带票据的 URL。
- 全部节点的 ADS_RELAY_SECRET 与控制中心一致,至少 32 个随机字符;root 私有环境文件不打包进客户端。
- 节点可以选择 `--stun-listen IP:端口` 启用内置 Binding 服务(仅 Binding、无 TURN,固定全局速率预算);当前两台部署使用已有 coturn,因此不启用此选项。
新增节点:构建 ads-relay、配置同一中继密钥和有效 TLS,开放其 WSS 端口;把节点加到控制中心 cluster.json 后重启中心。配置目前静态加载,重启会短暂中断已有连接。更改优先级同样需要重启。节点容量默认 256,可用 --capacity 调整;当前两台配置 128 通道。节点健康、通道数和累计转发字节可从各自 healthz 读取。
## 协议与边界
保留 `/v1/agent?v=2` 与 `/v1/lease?v=2` 协商;两端支持且中心配置集群时租约回复 protocol=2。旧端和未配置集群的中心仍使用 v1。
- `/v2/nodes`(client 角色):节点配置及健康、v2 signaling_bytes,data_bytes 固定为 0,因为 v2 会话端点拒绝二进制数据。
- `/v2/connect?device=&lease=`(client):创建会话,接收含 STUN、超时和本端票据的 manifest。
- `/v2/signal?session=&key=`(agent):使用短期会话 key 绑定,接收设备端 manifest。
- 信令只允许 offer、answer、p2p-ready、relay、route-ready、route-error;二进制及未知消息关闭会话。单条上限 128 KiB。
- 节点 `/v2/tunnel`:Authorization Bearer 是中心签发的 HMAC-SHA256 票据,绑定 session、lease、node、side、到期时间;签发有效 60 秒,每侧只用一次。长期角色令牌不能连接节点。
- 节点 `/internal/revoke`:仅中继共享密钥允许撤销租约。
- P2P 使用 DTLS/SCTP 加密;WSS 节点终止双方 TLS,属于受信基础设施,尚未在中继之上增加端到端载荷加密。
数据通道按 16 KiB 分块,可靠有序,接收队列及发送积压有界;每个设备/本地守护程序最多 32 并发流。票据、密钥与 SDP 不写入桌面状态文件。
## 验证
```powershell
.\scripts\build.ps1
python tests/cluster_e2e.py
python tests/e2e.py
```
集群测试使用真实可执行文件与模拟手机 TCP,覆盖 2 MiB 完整性、P2P 时中继零数据、强制中继、活动节点故障后同一客户端租约重建通道、P2P 不可达回退和租约撤销。Go 的 `go test -race ./...` 覆盖票据篡改/过期/角色、重放、撤销、升级失败资源清理、STUN Binding 和中心拒绝数据载荷。
真机只读测试可加 `--transport relay` 或 `--p2p-public-only`:
```powershell
python tests/real_device.py --existing-device home-phone --relay-url wss://ttstd.com/ads --connect-address 175.178.213.60:443 --credentials-dir config/private --adb bin/tools/scrcpy/adb.exe --p2p-public-only
```
Windows 的双端与桌面、Linux amd64 的控制中心/节点已验证;macOS/Linux 桌面及 Rust 两端仍待对应平台验证。
2026-11-12 实机结果:公网候选限定的 P2P、relay-1 强制中继、停止 relay-1 后经 relay-2 的真机 ADB 识别与 shell 均通过;测试后 relay-1 恢复。桌面读取双节点健康、显示实际路线,并通过真实 scrcpy 视频、重连和释放租约验证。