docs: add cross-device migration runbook

2026-08-10 17:29:01 +08:00
parent 67c9b65768
commit 89a8c3418f
2 changed files with 747 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -14,7 +14,9 @@
 - `tg3_data_collection/`：部署在本机；通过本地 SSH/rsync 拉取已完整收尾并校验的
  episode，原子保存到 `Data_Get/`；持久化验真凭据后自动回收机器人上的对应副本。
 - `Data_Get/`：最终数采目录。实际 MCAP、清单和同步状态默认不提交 Git。
- `docs/`：可提交的跨机器人迁移步骤。含实测帧和现场拓扑的汇报/证据文档只保留在
+- `docs/`：跨设备迁移先看
  [`天工3.0同构臂遥操与数采跨设备迁移手册.md`](docs/天工3.0同构臂遥操与数采跨设备迁移手册.md)，
  更底层的公网/本地 Hub 与 ZMQ 细节见原迁移部署指南。含实测帧和现场拓扑的汇报/证据文档只保留在
  当前本地工作副本，不同步到匿名可读的远端仓库。
 ## 外部依赖（不随仓库提交）
--- a/docs/天工3.0同构臂遥操与数采跨设备迁移手册.md
+++ b/docs/天工3.0同构臂遥操与数采跨设备迁移手册.md
@@ -0,0 +1,744 @@
 # 天工 3.0 同构臂遥操与数采跨设备迁移手册
 适用范围：天工 3.0、HBWALK、TS1P 同构臂、BrainCo Revo2 双手、EAI 本地
 OmniSocket Hub，以及 PS 主机保存数采数据的当前方案。
 本文按“换机器人、换 EAI 工控机、换 PS 主机、全部更换”分别说明。更底层的公网 Hub、
 纯 ZMQ 备选和协议证据见
 [`天工3.0本地同构臂遥操迁移部署指南.md`](天工3.0本地同构臂遥操迁移部署指南.md)。
 ## 1. 当前系统基线
 迁移前先记录实际提交，不要只记录文件夹名称：
 ```bash
 cd ~/Desktop/TG3_TS1P_OmniSocket_Teleop
 git rev-parse HEAD
 git status --short
 ```
 本文编写时的功能基线为：
 ```text
 TG3 项目：67c9b657688680c686f55b3f868bbc310edbfd41
 OmniSocketGo：de3f5c96779dbe1571c10feb22fc7f2331b6b222
 TG3 仓库：https://gitea.public.snrc.site/meiqi/TG3.git
 OmniSocketGo：https://gitea.public.snrc.site/limingjie/OmniSocketGo.git
 ```
 迁移时应优先使用 `main` 上更新且已经过现场验收的提交，并把最终提交号写入设备档案。
 ### 1.1 当前链路
 ```text
 EAI 工控机
  xTELE tcp://127.0.0.1:5003（原始双臂、按钮、摇杆、扳机）
       + tcp://127.0.0.1:5001（处理后的手势目标）
  -> tg3-omnisocket-sender.service
  -> 本机 tg3-omnisocket-hub.service，UDP 0.0.0.0:14049
  -> 局域网 192.168.5.14:14049
 机器人 Nvidia
  tg3-local-teleop.service
  -> 双臂、BrainCo 双手、/hric/robot/cmd_vel
  -> tg3-data-recorder.service 临时录制 MCAP
 PS 主机
  tg3-data-get-sync.service
  -> SSH/rsync 从 Nvidia 拉取 READY episode
  -> SHA-256 + fsync + VERIFIED
  -> Data_Get/<episode>/
  -> 验真后精确删除 Nvidia 对应临时副本
 ```
 EAI 不保存数采数据。Nvidia 在录制和等待 PS 同步期间必须临时落盘；最终持久副本只保留在
 PS 主机。PS 离线时，机器人会保留尚未验真的 `ready/`，恢复连接后再同步和回收。
 ### 1.2 当前地址与标识
 | 用途 | 当前值 | 变化时修改位置 |
 |---|---|---|
 | EAI 运维 SSH | SSH 别名 `eai` | PS 的 SSH 配置和运维命令 |
 | EAI 控制局域网 IP | `192.168.5.14` | 机器人 `config.toml` 的 `omnisocket_server`；ZMQ 回退时还改 `iarm_endpoint` |
 | 机器人控制局域网 IP | `192.168.5.15` | 通常只影响 EAI 防火墙规则 |
 | 机器人 Nvidia SSH | `nvidia@192.168.41.2` | PS 同步 unit 的 `--remote` 和运维命令 |
 | 机器人 Ubuntu SSH | `ubuntu@192.168.41.1` | 仅厂家运维；本项目不部署到 Ubuntu |
 | 本地 Hub | EAI UDP `14049` | EAI Hub、EAI sender、机器人 `omnisocket_server` 和防火墙同时修改 |
 | EAI Peer | `tg3-009027fa8190-iarm` | EAI `--peer-id` 与机器人 `omnisocket_expected_sender` 同时修改 |
 | 机器人 Peer | `tg3-009027fa8190-robot` | EAI `--target-peer` 与机器人 `omnisocket_peer_id` 同时修改 |
 | TS1P ID | `IArm009027FA8190` | 更换同构臂时修改机器人 `expected_iarm_id` |
 | 本机数据目录 | `~/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get` | PS 同步 unit 的 `WorkingDirectory`、脚本和 `--destination` |
 不要把机器人内部厂家链路 `192.168.41.1/192.168.41.2` 与 EAI—机器人控制局域网
 `192.168.5.0/24` 混为一谈，也不要把 EAI 本机的 `127.0.0.1:5001/5003` 改成网卡地址。
 ## 2. 三台设备分别需要哪些文件
 ### 2.1 PS 主机
 必须保留：
 ```text
 TG3_TS1P_OmniSocket_Teleop/
  tg3_omnisocket_transport/   # 用于部署 EAI
  tg3_local_teleop/           # 用于部署机器人
  tg3_data_collection/        # PS 同步程序
  Data_Get/                   # 唯一持久数采目录，不进入 Git
  docs/
  verify.sh
 ~/.config/systemd/user/tg3-data-get-sync.service
 ~/.ssh/known_hosts
 ~/.ssh/config                  # 如果使用 eai 等别名
 ```
 `Data_Get` 必须单独迁移，Git clone 不会带回 MCAP。SSH 私钥也不应提交到仓库，应在新主机
 重新生成并使用 `ssh-copy-id` 登记。
 ### 2.2 EAI 工控机
 必须具备：
 ```text
 原厂 xTELE 与 TS1P 标定配置             # 不在本仓库
 /home/eai/OmniSocketGo/                 # 固定提交，目标机原生编译
 /home/eai/tg3_omnisocket_transport/
 ~/.config/systemd/user/tg3-omnisocket-hub.service
 ~/.config/systemd/user/tg3-omnisocket-sender.service
 ```
 不要从旧 EAI 复制 Python 扩展 `.so` 到不同架构或不同 Python ABI 的新机器。不要把旧串口
 路径、CAN 配置和关节偏置盲目用于另一套 TS1P。
 ### 2.3 机器人 Nvidia
 必须具备：
 ```text
 /home/nvidia/OmniSocketGo/              # 固定提交，aarch64 原生编译
 /home/nvidia/tg3_local_teleop/          # 整个目录
 ~/.config/systemd/user/tg3-local-teleop.service
 ~/.config/systemd/user/tg3-data-recorder.service
 /home/nvidia/tg3_data_collection/       # 运行时临时目录，由程序创建
 ```
 不要把旧机器人的 `status.json`、`__pycache__`、ROS `build/install/log` 或编译好的
 OmniSocket `.so` 当成部署文件。`ros2_py` 必须在新机器人重新构建。
 ### 2.4 机器人 Ubuntu
 本项目不向 Ubuntu 安装文件，不修改厂家 `record_bag_node`、`proc_manager`、FSM 或
 HBWALK 服务。迁移后仍由操作者按厂家流程切换到 HBWALK；本项目不发布 `gotoHBWALK`。
 ## 3. 迁移前的统一停机与备份
 1. 松开所有按键和摇杆，长按 Z+C 3 秒退出遥操；
 2. 等待 Home 流程结束，确认机器人 `armed=false`；
 3. 若正在数采，等待本机出现完整 episode；
 4. 确认同步状态为 `idle` 且 `pending_remote_cleanup=0`；
 5. 停止旧 PS 的同步服务，防止两台 PS 同时拉取和回收同一个 episode；
 6. 记录当前配置、提交号、设备 ID 和服务文件。
 检查命令：
 ```bash
 ssh nvidia@192.168.41.2 \
  'python3 -m json.tool /home/nvidia/tg3_local_teleop/status.json | head -80'
 python3 -m json.tool \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get/sync_status.json
 systemctl --user stop tg3-data-get-sync.service
 ```
 至少备份以下内容：
 ```bash
 mkdir -p ~/tg3_migration_backup
 scp nvidia@192.168.41.2:/home/nvidia/tg3_local_teleop/config.toml \
  ~/tg3_migration_backup/robot-config.toml
 scp eai:/home/eai/.config/systemd/user/tg3-omnisocket-sender.service \
  ~/tg3_migration_backup/eai-sender.service
 scp eai:/home/eai/.config/systemd/user/tg3-omnisocket-hub.service \
  ~/tg3_migration_backup/eai-hub.service
 cp ~/.config/systemd/user/tg3-data-get-sync.service \
  ~/tg3_migration_backup/ps-sync.service
 ```
 把 `Data_Get` 复制到新磁盘或新主机时，先停同步服务，再执行：
 ```bash
 rsync -aH --info=progress2 \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get/ \
  <新主机>:/home/<新用户>/Desktop/TG3_TS1P_OmniSocket_Teleop/Data_Get/
 ```
 在新主机验证前保留旧主机副本。若状态仍为 `delete_pending`，先在旧主机完成同步回收，不要
 带着未决收据更换机器人地址。
 ## 4. 场景一：只更换 PS 主机
 PS 不在实时控制链路中，因此更换 PS IP 不需要修改 EAI sender、Hub Peer 或机器人
 `config.toml`。需要迁移的是代码、`Data_Get`、SSH 信任和同步服务。
 ### 4.1 安装代码与依赖
 ```bash
 sudo apt update
 sudo apt install -y git rsync python3
 git clone https://gitea.public.snrc.site/meiqi/TG3.git \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop
 cd ~/Desktop/TG3_TS1P_OmniSocket_Teleop
 git checkout main
 ./verify.sh
 ```
 如果迁移时使用的现场提交尚未推到 Gitea，应从旧 PS 用 `rsync` 复制完整仓库；不要只 clone
 一个落后的远端版本。
 ### 4.2 建立到新机器人的 SSH 信任
 ```bash
 ssh-keygen -t ed25519
 ssh-copy-id nvidia@<新机器人SSH地址>
 ssh nvidia@<新机器人SSH地址> true
 ```
 首次 SSH 时应人工核对主机指纹。同步器使用 `StrictHostKeyChecking=yes`，不要为了省事关闭
 主机密钥检查。机器人更换后应删除旧地址的错误 host key，再登记新机器人的真实指纹。
 ### 4.3 安装本机同步服务
 先确认机器人已经部署：
 ```text
 /home/nvidia/tg3_local_teleop/delete_ready_episode.py
 ```
 然后修改仓库中的 `tg3_data_collection/tg3-data-get-sync.service`：
 - `WorkingDirectory` 改成新 PS 的真实项目目录；
 - `ExecStart` 中脚本路径和 `--destination` 改成新目录；
 - `--remote` 改成新机器人 Nvidia SSH 地址；
 - 保留 `--delete-remote-after-sync`；
 - 保留远端固定根 `/home/nvidia/tg3_data_collection/ready`。
 安装并**显式 restart**，仅执行 `enable --now` 不会替换已经运行的旧进程：
 ```bash
 mkdir -p ~/.config/systemd/user
 cp tg3_data_collection/tg3-data-get-sync.service \
  ~/.config/systemd/user/tg3-data-get-sync.service
 systemctl --user daemon-reload
 systemctl --user enable tg3-data-get-sync.service
 systemctl --user restart tg3-data-get-sync.service
 systemctl --user show tg3-data-get-sync.service -p ExecStart -p ActiveState
 ```
 验收：
 ```bash
 python3 -m json.tool Data_Get/sync_status.json
 ```
 必须看到 `state=idle`、`last_error=""`、`pending_remote_cleanup=0`。确认新服务正常后，旧 PS
 同步服务保持停用；不能让两台主机同时运行自动删除模式。
 ## 5. 场景二：只更换 EAI 工控机
 机器人、PS 和 Home 均可保留，但必须先把原厂 xTELE 与 TS1P 在新 EAI 上独立调通。
 ### 5.1 先验收原厂 xTELE
 ```bash
 ss -lntp | grep -E ':(5001|5003)[[:space:]]'
 ```
 必须同时看到本机 TCP 5003 和 5001。可用下面的只读命令读取一个 5003 帧并记录同构臂
 身份：
 ```bash
 python3 - <<'PY'
 import json, zmq
 ctx = zmq.Context.instance()
 s = ctx.socket(zmq.SUB)
 s.setsockopt(zmq.SUBSCRIBE, b"")
 s.setsockopt(zmq.CONFLATE, 1)
 s.connect("tcp://127.0.0.1:5003")
 d = json.loads(s.recv().decode())
 print(d.get("isomorphic_arm_id"), d.get("isomorphic_arm_type"))
 PY
 ```
 输出的 ID 必须写入机器人 `config.toml` 的 `expected_iarm_id`。类型应为 `TS1P`。如果串口、
 CAN、方向、偏置或频率不正常，不要启动本项目 sender。
 ### 5.2 在新 EAI 原生构建 OmniSocketGo
 ```bash
 sudo apt update
 sudo apt install -y git build-essential python3-dev python3-pip
 python3 -m pip install --user pyzmq
 git clone https://gitea.public.snrc.site/limingjie/OmniSocketGo.git \
  /home/eai/OmniSocketGo
 git -C /home/eai/OmniSocketGo checkout \
  de3f5c96779dbe1571c10feb22fc7f2331b6b222
 make -C /home/eai/OmniSocketGo python-ext bin/kcpserver
 PYTHONPATH=/home/eai/OmniSocketGo/python python3 -c \
  'from omnisocket import Session; print(Session)'
 ```
 若新用户名不是 `eai`，把所有 `/home/eai` 改成实际绝对路径。服务模板和 Python 扩展必须
 使用同一个用户环境。
 ### 5.3 部署 sender 和本地 Hub
 在 PS 执行：
 ```bash
 rsync -av --exclude=__pycache__ \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/tg3_omnisocket_transport/ \
  eai@<新EAI地址>:/home/eai/tg3_omnisocket_transport/
 ```
 新 EAI 上修改两个 unit：
 ```text
 tg3-omnisocket-hub.service
  ExecStart=.../kcpserver -mode hub -listen 0.0.0.0:14049
 tg3-omnisocket-sender.service
  --server 127.0.0.1:14049
  --peer-id tg3-<机器人编号>-iarm
  --target-peer tg3-<机器人编号>-robot
  --zmq-endpoint tcp://127.0.0.1:5003
  --cmd-zmq-endpoint tcp://127.0.0.1:5001
 ```
 Peer 等式必须成立：
 ```text
 EAI --peer-id       == 机器人 omnisocket_expected_sender
 EAI --target-peer   == 机器人 omnisocket_peer_id
 ```
 安装服务：
 ```bash
 mkdir -p ~/.config/systemd/user
 cp /home/eai/tg3_omnisocket_transport/tg3-omnisocket-hub.service \
  ~/.config/systemd/user/
 cp /home/eai/tg3_omnisocket_transport/tg3-omnisocket-sender.service \
  ~/.config/systemd/user/
 systemctl --user daemon-reload
 systemctl --user enable --now tg3-omnisocket-hub.service
 systemctl --user enable --now tg3-omnisocket-sender.service
 sudo loginctl enable-linger eai
 ```
 EAI 控制局域网 IP 变化后，在机器人修改：
 ```toml
 [network]
 omnisocket_server = "<新EAI局域网IP>:14049"
 iarm_endpoint = "tcp://<新EAI局域网IP>:5003" # 仅保留作 ZMQ 回退
 ```
 KCP 使用 UDP 14049，不是 TCP。防火墙只允许机器人控制局域网 IP 访问该 UDP 端口。修改后
 重启机器人 `tg3-local-teleop.service`。
 ### 5.4 EAI 验收
 ```bash
 systemctl --user is-active \
  tg3-omnisocket-hub.service tg3-omnisocket-sender.service
 ss -lunp | grep ':14049'
 python3 -m json.tool /home/eai/tg3_omnisocket_transport/status.json
 ```
 待机时应看到：
 - `frames_received` 持续增长；
 - `teleop_active=false`；
 - `connected=0`；
 - `frames_sent` 不增长；
 - `last_error` 为空。
 Hub 未启动时长按 Z+C 只消费本次请求，不会在 Hub 恢复后自行启动。必须稳定松开至少
 0.5 秒，再重新长按 3 秒。
 ## 6. 场景三：只更换机器人
 这是风险最高的单项迁移。旧机器人的 Home、手部校准和编译产物不能直接当成新机器人的
 实测配置。
 ### 6.1 新机器人前置条件
 确认：
 ```bash
 uname -m
 test -f /opt/ros/jazzy/setup.bash
 test -f /home/nvidia/xos/setup.bash
 test -f /opt/robot_tele_server/install/setup.bash
 ros2 topic type /hric/robot/rl_state
 ros2 topic type /freq_change/arm_status
 ros2 topic type /encoder_identical_joint
 ros2 topic type /hric/robot/cmd_vel
 ```
 目标应仍为天工 3.0、14 维双臂，并提供当前项目使用的 Topic。若型号、SDK 或消息类型不同，
 先适配代码，不能只改 IP。
 确认灵巧手：
 ```bash
 grep -E 'left_hand_type|right_hand_type' \
  /home/nvidia/data/param/hand_driver.yaml
 ```
 只有左右均为 BrainCo 时才能直接启用现有 `[hands]`。因时手或其他型号必须单独适配消息和
 映射。
 ### 6.2 在新机器人原生构建 OmniSocketGo
 在 PS 执行，复制源码但排除其他架构的二进制：
 ```bash
 ssh nvidia@<新机器人SSH地址> 'mkdir -p /home/nvidia/OmniSocketGo'
 rsync -av \
  --exclude=.git \
  --exclude=bin \
  --exclude=python/build \
  --exclude='python/omnisocket/_omnisocket*.so' \
  ~/Desktop/OmniSocketGo/ \
  nvidia@<新机器人SSH地址>:/home/nvidia/OmniSocketGo/
 ssh nvidia@<新机器人SSH地址> \
  'cd /home/nvidia/OmniSocketGo && make python-ext'
 ssh nvidia@<新机器人SSH地址> \
  'PYTHONPATH=/home/nvidia/OmniSocketGo/python python3 -c \
  "from omnisocket import Session; print(Session)"'
 ```
 EAI 的 x86_64 `.so` 不能复制给 aarch64 机器人。
 ### 6.3 部署机器人项目并构建消息 overlay
 ```bash
 rsync -av \
  --exclude=__pycache__ \
  --exclude=status.json \
  --exclude=ros2_py/build \
  --exclude=ros2_py/install \
  --exclude=ros2_py/log \
  ~/Desktop/TG3_TS1P_OmniSocket_Teleop/tg3_local_teleop/ \
  nvidia@<新机器人SSH地址>:/home/nvidia/tg3_local_teleop/
 ssh nvidia@<新机器人SSH地址> 'bash -lc '\''
  source /opt/ros/jazzy/setup.bash
  cd /home/nvidia/tg3_local_teleop/ros2_py
  colcon build --symlink-install --packages-select ros2_bridge_msgs
 '\''
 ```
 录制器还需要 `python3-yaml` 和 `rsync`：
 ```bash
 ssh nvidia@<新机器人SSH地址> \
  'sudo apt install -y python3-yaml rsync'
 ```
 ### 6.4 修改新机器人专属配置
 先不要安装或启动 publish-capable service。编辑：
 ```text
 /home/nvidia/tg3_local_teleop/config.toml
 ```
 至少修改或重新确认：
 ```toml
 [network]
 transport = "omnisocket"
 omnisocket_server = "<EAI局域网IP>:14049"
 omnisocket_peer_id = "tg3-<新机器人编号>-robot"
 omnisocket_expected_sender = "tg3-<新机器人编号>-iarm"
 expected_iarm_id = "<实际TS1P ID>"
 expected_iarm_type = "TS1P"
 [home]
 joint_goal_rad = [<新机器人实测的14个弧度值>]
 ```
 还要核对：
 - `[hands].open_normalized` 与新 BrainCo 手的实测打开位；
 - `[hands].closed_normalized` 和单食指姿态；
 - `[control]` 关节限位是否仍对应当前型号和 SDK；
 - `[locomotion]` 的 Topic、方向和厂家速度上限；
 - `base_directory` 是否仍是 `/home/nvidia/tg3_data_collection`；
 - 相机 Topic 是否仍为 `/ob_camera_head/...` 和 `/ob_camera_waist/...`。
 ### 6.5 新机器人必须重新采集 Home
 当前仓库的 Home 是旧机器人实测姿态，不是“型号统一零位”。先用厂家认可方法把新机器人
 双臂移动到希望保存的安全 Home，然后以 monitor-only 方式运行桥，不带
 `--allow-publish`：
 ```bash
 ssh nvidia@<新机器人SSH地址>
 cd /home/nvidia/tg3_local_teleop
 timeout 15 ./run.sh || true
 python3 -c 'import json; p="/home/nvidia/tg3_local_teleop/status.json"; \
 print(json.load(open(p))["robot_arm_position_rad"])'
 ```
 把输出的 14 个弧度值写入 `[home].joint_goal_rad`。在防护、净空和急停有效的前提下，首次
 只做低速 Home 验证。Home 未确认前不要启用正式遥操服务。
 ### 6.6 配对 Peer 并安装服务
 在 EAI sender unit 中把 `--target-peer` 改成新机器人 Peer；如果 EAI Peer 也改名，机器人
 `omnisocket_expected_sender` 必须同步修改。
 在机器人安装：
 ```bash
 mkdir -p ~/.config/systemd/user
 cp /home/nvidia/tg3_local_teleop/tg3-local-teleop.service \
  ~/.config/systemd/user/
 cp /home/nvidia/tg3_local_teleop/tg3-data-recorder.service \
  ~/.config/systemd/user/
 systemctl --user daemon-reload
 systemctl --user enable tg3-data-recorder.service tg3-local-teleop.service
 systemctl --user restart tg3-data-recorder.service
 systemctl --user restart tg3-local-teleop.service
 ```
 在新机器人启用自动回收所需 helper 已包含在 `tg3_local_teleop/` 中：
 ```text
 /home/nvidia/tg3_local_teleop/delete_ready_episode.py
 ```
 最后在 PS 修改 `tg3-data-get-sync.service` 的 `--remote`，重新登记 SSH host key，并显式
 restart 本机同步服务。
 ## 7. 场景四：机器人、EAI 和 PS 全部更换
 按以下顺序，不要同时边改边做运动测试：
 1. 在旧系统退出遥操和数采，等待同步 `idle/pending=0`；
 2. 备份 Git 工作树、Data_Get、机器人 config 和三个用户服务；
 3. 部署新 PS，但暂不启动同步服务；
 4. 在新 EAI 完成原厂 xTELE/TS1P 标定，确认 5003/5001；
 5. 在新 EAI 原生编译 OmniSocket，启动本地 Hub；
 6. 在新机器人原生编译 OmniSocket 和 ROS 消息 overlay；
 7. 生成全新 Peer 对，设置新 TS1P ID；
 8. 以 monitor-only 模式确认机器人 ROS 状态和新 Home；
 9. 启动机器人 recorder、机器人 bridge，再启动 EAI sender；
 10. 在新 PS 登记机器人 SSH key，启动同步服务；
 11. 先做无运动链路验收，再按第 9 节逐级做实机验收；
 12. 验收全部通过后再退役旧设备，旧 Data_Get 至少保留一份只读备份。
 ## 8. 修改项速查表
 | 发生变化 | 必须修改 |
 |---|---|
 | 只换 PS IP | 实时控制无需修改；检查 PS 到 Nvidia SSH 可达 |
 | PS 用户名或项目路径变化 | PS 同步 unit 的 `WorkingDirectory`、脚本路径、`--destination` |
 | Nvidia SSH IP 变化 | PS 同步 unit 的 `--remote`、SSH host key 和运维命令 |
 | EAI SSH IP 变化 | 仅 PS SSH 配置/运维命令；控制配置取决于 EAI 局域网 IP 是否变化 |
 | EAI 控制局域网 IP 变化 | 机器人 `omnisocket_server`；防火墙；保留的 `iarm_endpoint` |
 | Hub UDP 端口变化 | EAI Hub listen、EAI sender `--server`、机器人 `omnisocket_server`、防火墙 |
 | 换机器人 | Robot Peer、EAI target Peer、新 Home、手型/端点、PS `--remote` |
 | 换 TS1P | EAI 原厂标定、EAI Peer、机器人 `expected_iarm_id`，必要时方向和按键复核 |
 | 换灵巧手型号 | 必须改代码和消息映射；不能只换 Topic 字符串 |
 | 相机未安装或未启动 | 不阻塞数采；manifest 标记 `absent` |
 | 头/腰相机启动 | 下一条数采自动包含对应压缩 RGB-D，并记录质量状态 |
 ## 9. 统一启动顺序与现场验收
 ### 9.1 启动顺序
 确认机器人未武装后：
 ```bash
 # 1. EAI 本地 Hub
 ssh eai 'systemctl --user restart tg3-omnisocket-hub.service'
 # 2. 机器人 recorder 和 bridge
 ssh nvidia@<机器人SSH地址> \
  'systemctl --user restart tg3-data-recorder.service tg3-local-teleop.service'
 # 3. EAI sender
 ssh eai 'systemctl --user restart tg3-omnisocket-sender.service'
 # 4. PS 数据同步
 systemctl --user restart tg3-data-get-sync.service
 ```
 ### 9.2 无运动验收
 ```bash
 cd ~/Desktop/TG3_TS1P_OmniSocket_Teleop
 ./verify.sh
 ssh eai 'systemctl --user is-active \
  tg3-omnisocket-hub.service tg3-omnisocket-sender.service'
 ssh nvidia@<机器人SSH地址> \
  'systemctl --user is-active tg3-data-recorder.service tg3-local-teleop.service'
 ssh nvidia@<机器人SSH地址> \
  'python3 -m json.tool /home/nvidia/tg3_local_teleop/status.json | head -120'
 python3 -m json.tool Data_Get/sync_status.json
 ```
 必须确认：
 - 机器人处于 `HBWALK/HBWALK/running`，但 `armed=false`；
 - 14 个手臂反馈错误码为 0；
 - 左右手反馈存在且型号正确；
 - OmniSocket receiver 已连接并注册；
 - EAI 本地 5003/5001 数据持续更新；
 - 待机时 EAI 不发送业务帧；
 - PS 同步无错误且 pending 为 0；
 - 头/腰相机未启动不影响 recorder 服务 active。
 ### 9.3 逐级运动验收
 全程确保防护、净空、急停有效，操作者先按厂家流程进入 HBWALK：
 1. 松开扳机和摇杆，TS1P 与机器人姿态尽量接近；
 2. 长按左 Z + 右 C 3 秒启动；
 3. 先验证双臂小幅单关节跟随；
 4. 小幅验证左右扳机对应的双手；
 5. 长按右 B 1 秒验证右手单食指，再松开 0.5 秒、长按 1 秒退出；
 6. 右 C + 左摇杆小幅验证前后，松开任一输入应立即零速；
 7. 左 Z + 右摇杆小幅验证原地转向；
 8. L3 长按 1 秒开始短数采，再次长按 1 秒结束；
 9. 长按 Z+C 3 秒结束遥操，确认限速回新机器人的 Home。
 不要用本项目发布 `gotoHBWALK`，不要向厂家 `/proc_manager/config/notify` 发送伪进程启停
 JSON，也不要为了迁移删除厂家限位、电流、碰撞或急停保护。
 ### 9.4 数采验收
 结束短数采后，在 PS 检查：
 ```bash
 python3 -m json.tool Data_Get/sync_status.json
 find Data_Get -mindepth 1 -maxdepth 1 -type d -printf '%T@ %f\n' | sort -nr | head
 ```
 最新 episode 必须包含：
 ```text
 READY
 VERIFIED
 manifest.json
 bag/metadata.yaml
 bag/*.mcap
 ```
 `manifest.json` 中应满足：
 - `state=complete`、`status=ready`；
 - `bag_info_validation.passed=true`；
 - 所有 `required_topic_message_counts` 大于 0；
 - 已启动的相机为 `healthy`，未启动为 `absent`；
 - `data_quality_warnings` 为空，或已明确接受其中的相机降级说明。
 同步状态应为 `idle`、`pending_remote_cleanup=0`。Nvidia 的 `active/ready/failed` 最终应为空；
 本机完整验真前不得人工删除机器人 `ready/`。
 ## 10. 回滚与故障边界
 ### 10.1 新机器人 Home 未确认
 保持 `tg3-local-teleop.service` 停止，只运行 monitor-only。不要把旧 Home 当作新机器人的
 零位，也不要测试自动回 Home。
 ### 10.2 EAI 5003 或 5001 不正常
 停止 sender，先修复原厂 xTELE。5003 缺失时双臂和按键无数据；5001 缺失时厂家处理后的
 组合手势不会进入机器人。
 ### 10.3 本地 Hub 不可用
 先恢复 EAI `tg3-omnisocket-hub.service` 和 UDP 14049，再重启机器人桥。已经失败的 Z+C
 请求不会自动恢复，必须松开 0.5 秒后重新长按。
 ### 10.4 同步显示 delete_pending
 本机数据已经发布，但机器人回收尚未确认。不要删除本机 episode。检查 SSH、host key、
 `delete_ready_episode.py` 和机器人磁盘；服务会按 30 秒至 15 分钟退避自动重试。
 若 pending 收据属于旧机器人 IP，系统会保守拒绝把它用于新机器人删除，但不会阻塞其他新
 episode。迁移前应在旧地址完成 pending，或人工核对本机与旧机器人 manifest 后再处理。
 ### 10.5 回到旧设备
 1. 退出遥操并停止新系统的 EAI sender、机器人 bridge 和 PS sync；
 2. 恢复备份的 unit 与机器人专属 config；
 3. 按 Hub → recorder/bridge → sender → sync 顺序启动；
 4. 仍从无运动验收开始，不能直接恢复大幅跟随或行走。
 ## 11. 每套设备的迁移记录模板
 ```text
 迁移日期：
 项目 Git commit：
 OmniSocketGo commit：de3f5c96779dbe1571c10feb22fc7f2331b6b222
 PS 主机：
  用户/项目路径：
  Data_Get 路径：
  Nvidia SSH 地址：
 EAI：
  SSH 地址：
  控制局域网 IP：
  xTELE 版本：
  TS1P ID/类型：
  EAI Peer：
  Hub UDP 地址：
 机器人：
  机器人编号：
  Nvidia SSH 地址：
  控制局域网 IP：
  Robot Peer：
  SDK/固件版本：
  左右手型号：
  Home 14 维值：
  头相机服务/Topic：
  腰相机服务/Topic：
 验收：
  离线测试：
  双臂：
  双手：
  单食指：
  前后行走：
  原地转向：
  自动 Home：
  数采/VERIFIED：
  机器人临时副本回收：
 ```