xtrhrj/docs/开发板图片协商联调记录.md

# 开发板图片协商联调记录

日期：2026-10-15。本文记录实际 RK3588 开发板与现有 PXHJ 的联调。

## 实际部署

| 位置 | 服务 | 入口或配置 |
|---|---|---|
| 开发板 192.168.7.165 | ARM64 `px_JKGL` 完整程序 | 原有 RTP 视频入口 UDP 9200 |
| 电脑 192.168.7.222 | 总控兼执行节点 | HTTP 18100 / 图片 UDP 19100，容量 2 |
| 同一电脑 | 子节点 A | HTTP 18120 / 图片 UDP 19120，容量 3 |
| 同一电脑 | 子节点 B | HTTP 18121 / 图片 UDP 19121，容量 3 |
| 同一电脑 | 网关 | HTTP 18110 / 协商 UDP 19002 |
| 同一电脑 | 原 PXHJ | 前端 5178、后端 8088、采集 UDP 19001、备用图片 UDP 6020 |

板上已开启 `image_negotiation.enabled=true`，协商指向 `192.168.7.222:19002`；图片回退地址明确为 `192.168.7.222:6020`。固定数据和心跳继续使用原来的 `19001`。完整原图经协商后直接发给接收节点，网关只中转短协商报文。

三个 Java 执行实例运行在同一台电脑，使用原稳定身份和数据目录；实际路数配置是 2/3/3。开发板是真实硬件，本次视频输入是已有 `1.mp4` 经 FFmpeg/RTP 送入开发板，经过板上程序解码、压缩、加密和分片。尚未进行物理摄像机、多台物理电脑、带宽容量或真实融合验收。

## 程序部署与回退材料

ARM 程序在目标板隔离目录构建后才激活，保留原有串口、RTP、启动器和程序内 1 GiB 日志保留功能。ARM 日志测试 9 项通过；图片协商测试 8 项通过，1 项可选 Java 互通夹具跳过。Windows 的 Java/C++ 互通验证已另行通过，板上实际协商和原图链路也已跑通。

- 当前 ARM 二进制 SHA256：`6d28db56f9cf20cde843d432dcf148e7a72a3d54e91c37996a18463b0dc00972`。
- 板上构建、候选和原文件备份目录：`/home/Tronlong/SY26-PX-Collect/runtime/image-route-stage-20261015-013802-b11a5ace`。
- 本机状态证据：`runtime/board-image-route/deployment-state.json`、`live-board-check.json`、`arm-artifacts/activation-result.json`。
- 激活与回退工具见 [嵌入式部署步骤](../scripts/嵌入式图片协商部署步骤.md)。回退需要显式运行工具，未因验证通过而自动回退。

没有更改设备密钥、重置节点身份或删除采集数据。PXHJ 网关登记通过已登录的正式配置接口加入当前板卡，保留原选项。

## 准备阶段取图

使用现有试验 `SY_20261012_000005` 的第一轮准备页，轮次仍为 `PENDING`，无需启动正式试验。现有视频采集模块为 `03`。

首次主节点收图后，真实页面取得 `remote-` 图片编号，原图接口返回 JPEG 200，页面解码尺寸为 **480 × 853**。已核对来源连接、采样时间、接收时间、长度和 SHA256，排除了旧 6020 历史图片。证据在 `runtime/board-image-real-verification/preparation-main.json` 及同名截图。

本次只观察准备页，没有保存视频确认、标定、试验配置或开始/结束试验。现有另一轮 `RUNNING` 保持原状态。

## 主节点切换到 A

通过临时调整各节点容量触发正常迁移，没有直接修改任务归属；完成后恢复 2/3/3。

北京时间 **09:49:44—09:50:09** 的节点观测记录了 110 张不同新帧：主节点版本 1 为 17 张，A 节点版本 2 为 93 张。A 的第一帧接收时间为 **09:49:48.389**。新旧节点交接的两条成功帧记录相隔 232 ms，全窗口成功新帧记录最大间隔 438 ms；这是观察间隔，不是端到端延迟指标。

切换后旧主节点/版本 1 的私有图片接口返回经过签名核验的 404，证明旧许可已撤销。另一个三分钟基线窗口记录了 345 张主节点与 A 的原图。两组共 455 张记录已独立核对 JPEG 解码、尺寸、字节数和 SHA256，全部通过。独立审计见 `runtime/board-image-observation/audit-first-migration.json`。

首次页面 30 秒检查启动于这次切换完成之后，30/30 取得新图，只作为 A 稳定期证据；不把它当成覆盖主节点到 A 全过程的页面证据。节点观察工具会重查短暂无帧，记录并未保存每一次 HTTP 尝试，因此也不以工具退出 0 声称所有尝试都返回 200。

## 联调发现的取图窗口

后续 A 稳定期精确取图检查出现过 **1/30 次 404**：页面刚取得帧号，节点仅保留的最近三帧就已淘汰那一帧。该时段没有发生 A 到 B 迁移；旧文件名中含 `a-to-b` 的记录不代表第二次迁移通过。

PXHJ 已改为先取得完整、验签通过的原图快照，再公布这个图片编号。缓存中的每个编号对应固定字节，节点淘汰和任务切换不再影响这份快照。缓存最长保存 30 秒，同时限制 4096 张和 64 MiB，达到预算时可以提前淘汰；权限沿用原图片入口。完整 HTTP 正文受查询预算限制；批量取图结束时也会去掉本批已被预算淘汰的编号，避免公布悬空地址。

修复相关 24 项测试全部通过；全后端 **411 项，失败 0、错误 0、跳过 30 项**，已以达梦依赖打包并替换实际 PXHJ 后端。跳过项仍是原有外部环境测试，不能视为现场验收通过。构建日志为 `runtime/board-image-route/pxhj-snapshot-package.log`，测试报告在 `runtime/pxhj-image-build/surefire-reports`。修改仍位于原 `fusion.service` / `fusion.client` 分层，XTRH Java 注释占比 21.53%，PXHJ fusion 业务 28.83%。

重启后重新经正式登录恢复准备页。北京时间 **10:13:52—10:14:22**，30/30 次取得新鲜远程原图及精确 JPEG 200，30 个不同 SHA；601 次 DOM 采样均有已解码图片，浏览器 HTTP 错误、页面 JS 错误和试验业务写入均为 0。20 秒前的同一公开编号重取返回 200，SHA 与当时完全相同。证据为 `preparation-snapshot-stable-a*`，旧失败窗口原样保留。

## 修复后复测与 A 到 B

使用随机请求号和数字 Unix 毫秒门闩联动浏览器采样与正常容量操作，避免人工启动先后差使页面漏掉切换瞬间。实际页面窗口为北京时间 **10:16:18.043—10:17:03.051**，包含以下完整交接：

| 事件 | 北京时间 | 结果 |
|---|---|---|
| 浏览器先确认 A 原图，再启动门闩 | 10:16:18.043 | A / 版本 2；随后执行已授权容量调整 |
| B 收到完整首帧 | 10:16:21.255 | B / 实际版本 4，图片已就绪 |
| 观察到 B 已接管 | 10:16:21.306 | 当前原图路由切到 B |
| 旧 A 私有接口核验 | 10:16:21.530 | 版本 2 返回已验签 404，旧许可撤销 |
| 重新读取切换前公开图片编号 | 10:16:30.058 | 200，SHA 与切换前字节完全相同 |
| 浏览器窗口结束 | 10:17:03.051 | 持续取得 B 新图 |

45 次页面检查均为新鲜远程原图、精确 JPEG 200，45 个不同 SHA，接收时间距检查最大 357 ms。899 次 DOM 采样没有观察到空图或未解码图片，实际最大采样间隔 197 ms；浏览器 HTTP 错误为 0。这是该观察窗口的结果，不承诺任意负载和网络条件下绝对不丢帧。新证据前缀为 `runtime/board-image-real-verification/preparation-snapshot-migration-a-to-b`，包含数字门闩、逐次数据、DOM、HTTP、旧图重取及汇总。

同时节点 35 秒窗口保存 157 张不同新帧：A 13 张、B 144 张。全部独立完成 JPEG 解码、尺寸、长度和 SHA256 核对；交接两条成功帧记录相隔 227 ms，全窗口最大成功新帧记录间隔 644 ms。接收和采样时间存在板卡/电脑钟差，不能用这些数值宣称网络延迟。节点证据为 `runtime/board-image-observation/real-a-to-b/summary.json`、`frames.jsonl` 和逐帧 JPG。

## 最终状态

- 板上协商保持开启，当前原图由 **B：192.168.7.222:19121** 接收，原图任务状态 `READY`、版本 4。
- 主节点、A、B 和网关全部在线；容量恢复 **2/3/3**，B 占用 1 路，其他占用 0，预留为 0；没有为验证创建额外正式视频任务。
- PXHJ 仍在现有第一轮准备页，截图见 [preparation-b.png](../runtime/board-image-real-verification/preparation-b.png)。页面原图 480 × 853，正式图片接口 200，已解码。
- 达梦只读前后比较确认：当前准备轮次及冻结装备/采集模块绑定未变，原运行中轮次及绑定未变，仍有 1 轮运行中。正式网关路由保留为当前板卡的 31001 转发源端口，没有清除采集记录。
- 板上程序与当前 FFmpeg 文件输入保持运行，便于继续从 PXHJ 查看；真实融合、仿真目标叠加和录像仍未实现。

轮次和绑定终检在 `runtime/board-image-real-verification/trial-integrity-final.json` 与 `trial-business-invariants.json`。旧帧私有接口的 404 是许可撤销验证，和此前已修复的公开原图偶发 404 含义不同。

网关最后约 73 秒只读增量检查中，接收、转发和回包各增加 48，错误增量、队列丢弃和未知来源均为 0；整个进程累计错误为 5，记录未给出逐条原因，因此不声称全程网关零错误。B 最终图片接收拒绝和队列丢弃均为 0。详细计数见 `real-a-to-b/gateway-post-migration-delta.json` 与 `node-final.json`，没有重置计数来隐藏历史记录。