5.3 KiB
嵌入式图片协商候选部署
该工具准备可审阅的候选版本，默认仅检查。创建stage和构建不会停止采集程序、修改在用配置或替换在用可执行文件；实际SSH、切换、业务联调由总任务执行。
已核对的边界
历史部署及本次根任务SSH只读确认：采集板 root@192.168.7.165、ARM64 RK3588，工程 /home/Tronlong/SY26-PX-Collect，启动入口 start.sh，程序 bin/px_JKGL。本机平台地址 192.168.7.222；本次网卡路由需SSH显式 -b 192.168.7.222。主机密钥使用现有 E:/pxhj/runtime/board-known-hosts 严格核验，不自动忽略未知主机密钥。
先由root核对板时钟，当前发现其严重落后。采集协议要求时间差不超过60秒，不能只修复make循环而保留错误时钟。SSH接入和校时由root负责，此工具不配置网络、系统时间或服务。
本次包只含6份图片协商相关C++源码和两套隔离QtTest。板上当前源码及SDK作为构建基线；main.cpp、内置1GiB日志、RTP收流、串口桥、现有启动脚本和其他源码均保留。px_Collect.pro只追加缺少的编译单元。旧 runtime/embedded-log-retention/deploy.py 会修改日志服务及旧启动重定向，不能直接用于本次。
生成和传输
在Windows运行：
python E:\Codex\xtrh\scripts\Stage-EmbeddedImageRoute.py package --source E:\Codex\qrs\SY_26_PX_Collect --package E:\Codex\xtrh\runtime\board-image-route\collector-image-route.tar.gz
同名包不会覆盖。命令输出文件数和SHA256，包不含INI、设备密钥、运行日志或旧程序。root通过已确认SSH连接上传该包以及两个 .py 工具；不在命令或日志中放密码/密钥。
板端stage和构建
在已确认的板端目录执行下列命令，包路径按实际上传位置填入：
python3 Stage-EmbeddedImageRoute.py inspect
python3 Stage-EmbeddedImageRoute.py stage --package /path/collector-image-route.tar.gz --gateway-host 192.168.7.222 --gateway-port 19002 --fallback-ip 192.168.7.222 --fallback-port 6020
python3 Stage-EmbeddedImageRoute.py build --stage /home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-<实际ID>
python3 Stage-EmbeddedImageRoute.py verify --stage /home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-<实际ID>
stage输出真实候选路径。stage目录权限700，配置及其备份权限600。构建必须在ARM64目标环境，完整Qt应用、GStreamer、相机SDK、OpenSSL和hiredis依赖全部保留；不存在去掉依赖勉强通过的分支。make -o Makefile仅防止板时钟引起Makefile重复生成，不省略正常编译。新目录使用自己的qmake缓存。
完整程序构建成功后检查动态库，并执行内置日志和图片协商隔离QtTest。只有全部成功才记为 built=true。候选主程序不会在此阶段启动，不抢真实6000/9200端口。跨语言加解密已在Windows独立验证；ARM默认缺少Java互操作夹具时该可选测试会标记跳过，其他业务断言仍执行。
候选程序在 <stage>/source/bin/px_JKGL，候选配置在 <stage>/candidate-config.ini，完整回退材料在 <stage>/backup，日志和哈希在该stage内。verify若发现现网源码、程序或配置在stage后变化会停止，root应重新核对，不能覆盖新修改。
切换与回退
root先核对真实PXHJ网关路由已经授权该采集端，再切换。候选配置只新增/启用地址协商以及独立PXHJ原图fallback IP；不修改fixed_json、heartbeat、串口/RTP或密钥文件。图片目的地址不能从fixed_json网关地址推断。保持原图片帧率、质量和尺寸。
实际切换前，运行 Activate-EmbeddedImageRoute.py 默认预览。它核验live未变、候选bin/config/源码/pro哈希及两套QtTest结果；显式 --apply 才停止本工程采集进程、原子安装候选并调用当前 start-network-simulation.sh。原串口桥和PID管理方式保留，禁止恢复旧的无限增长 run.log 重定向。启动后核对新写入且连续稳定的native日志状态（owner、1GiB预算、failedWrites=0、withinLimit=true）。失败自动调用该stage回退。准备原图可见、来源身份不变、迁移首帧与租约回退由真实PXHJ继续验收。
python3 Activate-EmbeddedImageRoute.py --stage /home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-<实际ID>
python3 Activate-EmbeddedImageRoute.py --stage /home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-<实际ID> --apply
回退先只检查，所有路径和哈希通过后由root显式执行：
python3 Rollback-EmbeddedImageRoute.py --stage /home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-<实际ID>
python3 Rollback-EmbeddedImageRoute.py --stage /home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-<实际ID> --apply
回退仅恢复本stage拥有的6份源码、pro、程序和config；默认无写操作。检测到其他部署后的更新、备份哈希改变或未知进程守护重启时停止。默认重用当前 start-network-simulation.sh，串口桥与collector.pid由原启动器管理；显式 --launcher start.sh 才选择直接启动。不会修改网络、systemd、设备密钥、原始采集数据或试验记录。
此文档和候选包属于部署准备；实际ARM构建、切换及准备/迁移验收需要分别记录真实结果，不能用本机测试替代。