408 lines
9.8 KiB
Markdown
408 lines
9.8 KiB
Markdown
# OmniSocketGo 视频链路启动与单中转切换指南
|
||
|
||
本文档记录两种运行方式：
|
||
|
||
1. 当前已经验证通过的机器人网线直连主机模式。
|
||
2. 后续计划使用的一台公网 KCP Hub 单中转模式。
|
||
|
||
当前直连模式的主机地址为 `192.168.41.144`，KCP 使用 UDP `10909`。后续公网模式中的 `<D_PUBLIC_IP>` 需要替换为实际中转服务器公网 IP。
|
||
|
||
## 1. 两种模式的区别
|
||
|
||
| 项目 | 网线直连 | 单公网中转 |
|
||
| --- | --- | --- |
|
||
| KCP Hub 位置 | 当前控制主机 | 公网服务器 D |
|
||
| 两端连接地址 | `192.168.41.144:10909` | `<D_PUBLIC_IP>:10909` |
|
||
| 主机 `relay_via` | 空 | 空 |
|
||
| 机器人 `relay_via` | 空 | 空 |
|
||
| 主机是否启动本地 Hub | 是 | 否 |
|
||
| 公网服务器是否启动 Hub | 否 | 是 |
|
||
| 视频路径 | 机器人 → 当前主机 | 机器人 → D → 当前主机 |
|
||
|
||
单中转模式仍然有 `机器人 ↔ D` 和 `D ↔ 当前主机` 两条 KCP 会话，但只经过一台第三方服务器。
|
||
|
||
## 2. 当前网线直连模式
|
||
|
||
### 2.1 网络拓扑
|
||
|
||
```text
|
||
机器人网口，例如 192.168.41.145/24
|
||
│
|
||
│ UDP 10909
|
||
▼
|
||
当前控制主机 192.168.41.144
|
||
│
|
||
└── 本地 KCP Hub
|
||
```
|
||
|
||
机器人与当前主机必须在同一网段。先在机器人上确认：
|
||
|
||
```bash
|
||
ping -c 3 192.168.41.144
|
||
```
|
||
|
||
### 2.2 直连配置检查
|
||
|
||
当前控制主机配置文件：
|
||
|
||
```text
|
||
/home/ps/Desktop/OmniSocketGo_add_camera/scripts/dev/robot-remote.env.local
|
||
```
|
||
|
||
关键配置应为：
|
||
|
||
```bash
|
||
CONTROL_SIDE_OMNISOCKET_SERVER_ADDR="192.168.41.144:10909"
|
||
CONTROL_SIDE_OMNISOCKET_RELAY_VIA=""
|
||
LOCAL_HUB_LISTEN_ADDR="0.0.0.0:10909"
|
||
```
|
||
|
||
准备移植到机器人的项目配置文件：
|
||
|
||
```text
|
||
OmniSocketGo_robot/scripts/dev/robot-remote.env.local
|
||
```
|
||
|
||
关键配置应为：
|
||
|
||
```bash
|
||
ROBOT_SIDE_OMNISOCKET_SERVER_ADDR="192.168.41.144:10909"
|
||
ROBOT_SIDE_OMNISOCKET_RELAY_VIA=""
|
||
|
||
ROBOT_RECEIVER_SERVER_ADDR="192.168.41.144:10909"
|
||
ROBOT_RECEIVER_RELAY_VIA=""
|
||
|
||
OMNI_VIDEO_SERVER_ADDR="192.168.41.144:10909"
|
||
OMNI_VIDEO_RELAY_VIA=""
|
||
|
||
OMNI_CONTROL_SERVER_ADDR="192.168.41.144:10909"
|
||
OMNI_CONTROL_RELAY_VIA=""
|
||
```
|
||
|
||
### 2.3 当前主机启动命令
|
||
|
||
以下命令分别在三个终端中运行，顺序为：本地 Hub、后端、前端。
|
||
|
||
#### 终端 1：启动本地 KCP Hub
|
||
|
||
```bash
|
||
cd /home/ps/Desktop/OmniSocketGo_add_camera
|
||
|
||
# 第一次运行或可执行文件不存在时构建
|
||
make bin/kcpserver
|
||
|
||
# 确认 10909/UDP 没有被另一个 Hub 占用
|
||
ss -lunp | grep ':10909' || true
|
||
|
||
bash scripts/dev/start-local-hub.sh
|
||
```
|
||
|
||
正常启动会看到类似输出：
|
||
|
||
```text
|
||
[start-local-hub] listen=0.0.0.0:10909 relay=disabled
|
||
kcp hub listening on 0.0.0.0:10909
|
||
```
|
||
|
||
如果已经有正确的 `kcpserver` 在监听 UDP 10909，不要重复启动。
|
||
|
||
#### 终端 2：启动 robot-command-center 后端
|
||
|
||
```bash
|
||
cd /home/ps/Desktop/OmniSocketGo_add_camera
|
||
|
||
# 先确认 8001/TCP 是否已经存在后端服务
|
||
ss -ltnp | grep ':8001' || true
|
||
|
||
bash scripts/dev/start-backend.sh
|
||
```
|
||
|
||
如果出现：
|
||
|
||
```text
|
||
address already in use
|
||
```
|
||
|
||
说明 8001 已有服务。先执行：
|
||
|
||
```bash
|
||
sudo lsof -nP -iTCP:8001 -sTCP:LISTEN
|
||
```
|
||
|
||
如果它是已经启动成功的当前后端，直接复用，不要再启动第二份；如果确认是过期进程，再对查到的具体 PID 执行普通 `kill <PID>` 后重新启动。
|
||
|
||
#### 终端 3：启动前端
|
||
|
||
```bash
|
||
cd /home/ps/Desktop/OmniSocketGo_add_camera
|
||
bash scripts/dev/start-frontend.sh
|
||
```
|
||
|
||
浏览器访问：
|
||
|
||
```text
|
||
http://127.0.0.1:5173
|
||
```
|
||
|
||
### 2.4 机器人端启动命令
|
||
|
||
把 `OmniSocketGo_robot` 项目复制到机器人后，在机器人终端执行：
|
||
|
||
```bash
|
||
cd /path/to/OmniSocketGo_robot
|
||
|
||
# 检查网络、两台相机、FFmpeg 依赖和直连配置
|
||
./check-robot-lan.sh
|
||
|
||
# 如果机器人原有开机服务正在占用相机，先停掉对应旧服务
|
||
sudo systemctl stop blitz-watchdog.service blitz-b-side-omnid.service
|
||
|
||
# 自动构建并启动机器人视频/控制 daemon
|
||
./start-robot-lan.sh
|
||
```
|
||
|
||
如果机器人上没有安装上述 systemd 服务，`systemctl stop` 报“unit not found”可以忽略，继续执行 `./start-robot-lan.sh`。
|
||
|
||
双相机正常打开时会看到：
|
||
|
||
```text
|
||
[video_pipeline] camera head ready on ...
|
||
[video_pipeline] camera waist ready on ...
|
||
```
|
||
|
||
随后周期日志应满足：
|
||
|
||
```text
|
||
video registered=1
|
||
frames 持续增加
|
||
```
|
||
|
||
### 2.5 直连模式验证
|
||
|
||
在当前控制主机执行：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8001/api/video/status/ | python3 -m json.tool
|
||
```
|
||
|
||
重点检查：
|
||
|
||
```text
|
||
connected: true
|
||
registered: true
|
||
has_recent_frame: true
|
||
server_addr: 192.168.41.144:10909
|
||
relay_via: 空
|
||
frames_received: 持续增加
|
||
```
|
||
|
||
机器人端也可以查看运行状态：
|
||
|
||
```bash
|
||
cd /path/to/OmniSocketGo_robot
|
||
python3 -m json.tool logs/runtime/b-side-omnid.status.json
|
||
```
|
||
|
||
## 3. 后续切换为单公网 KCP Hub 中转
|
||
|
||
### 3.1 目标拓扑
|
||
|
||
```text
|
||
机器人 B ── KCP/UDP ──▶ 公网服务器 D ◀── KCP/UDP ── 当前主机 A
|
||
KCP Hub
|
||
```
|
||
|
||
视频方向是：
|
||
|
||
```text
|
||
机器人 B → 公网服务器 D → 当前主机 A
|
||
```
|
||
|
||
两端都主动连接 D，因此机器人和当前主机即使都位于 NAT 后面，也不需要在本地暴露 UDP 端口。
|
||
|
||
### 3.2 公网服务器准备计划
|
||
|
||
在公网服务器 D 上部署与两端相同版本的 OmniSocketGo。首次验证建议以前台方式启动，便于直接观察日志：
|
||
|
||
```bash
|
||
cd /path/to/OmniSocketGo
|
||
make bin/kcpserver
|
||
mkdir -p logs
|
||
|
||
./bin/kcpserver \
|
||
-listen 0.0.0.0:10909 \
|
||
-telemetry-peer peer-a-telemetry \
|
||
-telemetry-interval 1000ms \
|
||
-kcp-session-stats-log logs/d-kcp-stats.jsonl \
|
||
-kcp-session-stats-interval 1000ms
|
||
```
|
||
|
||
公网服务器同时需要：
|
||
|
||
1. 云安全组允许入站 UDP `10909`。
|
||
2. 操作系统防火墙允许入站 UDP `10909`。
|
||
3. 公网 IP 固定，或者使用解析稳定的域名。
|
||
4. 出站 UDP 不被限制。
|
||
|
||
检查监听状态：
|
||
|
||
```bash
|
||
ss -lunp | grep ':10909'
|
||
```
|
||
|
||
必须启动默认的 KCP Hub 模式，不能使用：
|
||
|
||
```text
|
||
-mode=relay
|
||
```
|
||
|
||
`-mode=relay` 只是原始 UDP 转发器，不能代替按 Peer ID 路由消息的 KCP Hub。
|
||
|
||
### 3.3 当前主机计划修改
|
||
|
||
修改：
|
||
|
||
```text
|
||
/home/ps/Desktop/OmniSocketGo_add_camera/scripts/dev/robot-remote.env.local
|
||
```
|
||
|
||
计划改为：
|
||
|
||
```bash
|
||
CONTROL_SIDE_OMNISOCKET_SERVER_ADDR="<D_PUBLIC_IP>:10909"
|
||
CONTROL_SIDE_OMNISOCKET_RELAY_VIA=""
|
||
```
|
||
|
||
切换后当前主机不再启动：
|
||
|
||
```bash
|
||
bash scripts/dev/start-local-hub.sh
|
||
```
|
||
|
||
只启动后端和前端：
|
||
|
||
```bash
|
||
cd /home/ps/Desktop/OmniSocketGo_add_camera
|
||
bash scripts/dev/start-backend.sh
|
||
```
|
||
|
||
另开终端：
|
||
|
||
```bash
|
||
cd /home/ps/Desktop/OmniSocketGo_add_camera
|
||
bash scripts/dev/start-frontend.sh
|
||
```
|
||
|
||
前端仍然访问本机后端，前端代码和 `VITE_API_BASE_URL` 不需要因为 KCP 中转而修改。
|
||
|
||
### 3.4 机器人端计划修改
|
||
|
||
修改机器人项目中的：
|
||
|
||
```text
|
||
scripts/dev/robot-remote.env.local
|
||
```
|
||
|
||
所有网络目标统一改成同一个公网 D，所有 `relay_via` 保持为空：
|
||
|
||
```bash
|
||
ROBOT_SIDE_OMNISOCKET_SERVER_ADDR="<D_PUBLIC_IP>:10909"
|
||
ROBOT_SIDE_OMNISOCKET_RELAY_VIA=""
|
||
|
||
ROBOT_RECEIVER_SERVER_ADDR="<D_PUBLIC_IP>:10909"
|
||
ROBOT_RECEIVER_RELAY_VIA=""
|
||
|
||
OMNI_VIDEO_SERVER_ADDR="<D_PUBLIC_IP>:10909"
|
||
OMNI_VIDEO_RELAY_VIA=""
|
||
OMNI_VIDEO_PEER_ID="peer-b-video"
|
||
OMNI_VIDEO_TARGET_PEER="peer-a-video"
|
||
|
||
OMNI_CONTROL_SERVER_ADDR="<D_PUBLIC_IP>:10909"
|
||
OMNI_CONTROL_RELAY_VIA=""
|
||
OMNI_CONTROL_PEER_ID="peer-b-ctrl"
|
||
OMNI_CONTROL_EXPECTED_SENDER="peer-a-ctrl"
|
||
```
|
||
|
||
Peer ID 不要修改。D 根据 `peer-b-video → peer-a-video` 路由视频，根据控制 Peer ID 路由控制指令和相机切换确认。
|
||
|
||
如果机器人通过 5G 访问 D，还需要让系统明确从 5G 接口访问 D：
|
||
|
||
```bash
|
||
BLITZ_5G_ROUTE_TARGETS="<D_PUBLIC_IP>"
|
||
OMNI_5G_LINK_LOG_ENABLED="1"
|
||
```
|
||
|
||
具体路由需要在机器人上用以下命令确认：
|
||
|
||
```bash
|
||
ip route get <D_PUBLIC_IP>
|
||
```
|
||
|
||
结果应显示预期的 5G 网卡和源地址。
|
||
|
||
### 3.5 单中转启动顺序
|
||
|
||
1. 在公网服务器 D 启动 `kcpserver` Hub。
|
||
2. 在当前主机启动 `start-backend.sh`，让 `peer-a-video`、控制 ACK 和 telemetry Peer 先注册。
|
||
3. 在机器人启动 `start-robot-lan.sh` 或 `start-b-side-omnid.sh`。
|
||
4. 在当前主机启动前端。
|
||
5. 验证视频帧、相机切换、控制命令和 ACK。
|
||
|
||
### 3.6 单中转验证
|
||
|
||
当前主机执行：
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8001/api/video/status/ | python3 -m json.tool
|
||
```
|
||
|
||
预期关键字段：
|
||
|
||
```text
|
||
connected: true
|
||
registered: true
|
||
has_recent_frame: true
|
||
server_addr: <D_PUBLIC_IP>:10909
|
||
relay_via: 空
|
||
frames_received: 持续增加
|
||
```
|
||
|
||
机器人周期日志应显示：
|
||
|
||
```text
|
||
video registered=1
|
||
control registered=1
|
||
frames 持续增加
|
||
```
|
||
|
||
公网 D 应能看到来自机器人和当前主机的 KCP 会话。若两端都显示 `registered=false`，优先检查 UDP 10909 安全组、防火墙和机器人公网路由。
|
||
|
||
## 4. 与原始双服务器模式的关系
|
||
|
||
原项目曾使用两台第三方服务器：
|
||
|
||
```text
|
||
机器人 B → KCP Hub D → UDP Relay C → 当前主机 A
|
||
```
|
||
|
||
其中主机侧配置类似：
|
||
|
||
```bash
|
||
CONTROL_SIDE_OMNISOCKET_SERVER_ADDR="<D地址>:10909"
|
||
CONTROL_SIDE_OMNISOCKET_RELAY_VIA="<C地址>:10909"
|
||
```
|
||
|
||
机器人侧直接连接 D。`relay_via` 非空时，它会成为实际 UDP 发送目标。本文计划的一次中转不需要 C，所以主机和机器人两侧的 `relay_via` 都必须为空。
|
||
|
||
## 5. 回退到网线直连
|
||
|
||
如果公网链路尚未调通，回退不需要修改代码：
|
||
|
||
1. 把当前主机 `CONTROL_SIDE_OMNISOCKET_SERVER_ADDR` 恢复为 `192.168.41.144:10909`。
|
||
2. 把机器人所有 Server 地址恢复为 `192.168.41.144:10909`。
|
||
3. 确认两端所有 `relay_via` 为空。
|
||
4. 当前主机重新启动 `start-local-hub.sh`。
|
||
5. 重启当前主机后端和机器人 `b_side_omnid`。
|
||
|
||
网络模式切换只涉及环境配置和 Hub 所在位置，不需要修改视频编码、双相机切换、robot-command-center 前端或 Peer ID。
|