xtrhrj/docs/图片直传协商与准备取图.md

图片直传协商与准备取图

PXHJ 仍负责操作，采集网关负责传递协商，接收节点负责收原图。准备阶段不需要先启动正式试验，也能从接收节点取图做配置和标定。真实融合算法另行实现。

sequenceDiagram
    participant D as 嵌入式采集器
    participant G as 采集网关
    participant P as PXHJ 后端
    participant C as 总控服务
    participant N as 接收节点
    D->>G: 请求图片上传地址（加密协商）
    G->>P: 原字节转发
    P->>P: 按原登记来源和密钥认证
    P->>C: 登记短期原图接入任务
    C->>N: 心跳计划下发接收许可
    N->>C: 图片入口已就绪
    C-->>P: 接收节点的 IP、UDP 端口和许可期限
    P-->>G: 加密地址回复
    G-->>D: 回到专用协商套接字
    D->>N: 原有加密 JPG 分片直接上传
    P->>N: 准备页面查询原图（内部签名请求）
    N-->>P: 原图元数据、JPEG
    P->>P: 缓存完整验签 JPEG 后发布图片编号
    P-->>P: 沿原 image-frames 接口供页面使用

使用流程

1. 主服务、网关和节点按现有方式部署。节点自动注册时同时上报图片入口，总控的主电脑也可以接收。
2. PXHJ 保存采集器来源和原密钥，现有 UDP 网关映射继续负责数据、心跳与协商。采集器的专用协商套接字发送地址请求。
3. 总控把原图接入算作一路任务，和其他任务一起受每台机器配置路数限制。没有空位时回复等待，采集器继续用原图片地址。
4. 节点准备好端口和认证许可后，下一次协商返回上传目标。采集器直接向节点上传，完整图片不经过网关。
5. PXHJ 的准备页面继续使用原图片查询入口。后端先向当前节点取齐精确帧并验签，再发布临时图片编号；后续按编号返回同一份快照。页面不接触内部服务凭证或设备密钥。
6. 路数调整触发迁移时，短暂给采集器两个上传目标。PXHJ 继续读旧节点；新节点收到首帧后切换，旧目标撤销。

原图接入与正式试验启停独立。后续融合任务可读取这份原图接入结果，避免为准备页面再上传完整的第二份视频。目前演示任务与原图接入是两类任务，各自占用配置路数；未实现跨任务复用融合处理槽位。

配置与端口

项目	默认值	用途
网关 UDP	19002	数据转发及短小协商报文
PXHJ 采集 UDP	19001	原协议解析与协商认证
PXHJ 图片 UDP	6020	原图片接收、协商失败回退
主节点图片 UDP	19100	主节点 HTTP 18100 + 1000
子节点图片 UDP	HTTP 端口 + 1000	各实例独立原图接收

节点可用 fusion.image-port 或安装参数 -ImagePort 单独指定图片端口。fusion.image-port=0 为自动化测试的系统分配端口。多网卡环境使用 -AdvertisedHost 指定采集器和 PXHJ 均可访问的 IPv4，不能发布仅本机可见的地址。需要允许对应 UDP 和节点 HTTP 端口。

嵌入式新增 [image_negotiation]：enabled、gateway_host、gateway_port。默认关闭，已有设备保持原上传方式；启用前确认网关映射、节点地址和网络连通。关闭或协商失败时回到 [image_upload] 的原上传目标。

如果固定采集数据的 fixed_json.udp_host 改为网关，必须单独把 image_upload.udp_host 设置为 PXHJ 图片接收机器的 IP。它不能继续继承固定数据的网关地址，否则回退图片会投向网关的 6020，而该入口并不接收图片。

协议与边界

• 在原 PXHJ-FND/1 中加入 0x14 地址请求、0x15 地址回复；沿用原 SM4、HMAC-SM3、CRC 与采集器编号。图片 0x12 分片格式不变。
• 请求携带协议版本、设备启动号、递增序号、请求号与时间；回复回显本次请求并附总控身份、代次、任务版本、有效期和最多两个目标。
• 地址许可 8 秒，采集器约每 1.5 秒请求续期；有效 WAITING 立即回退，没有许可或旧许可到期时使用原图片上传地址。无效回复被忽略，不能延长既有许可。连续 30 秒没有认证协商释放来源任务。
• 节点只接受当前任务许可的来源 IP、采集器编号和密钥。先验签解密，再组装图片；不完整、过期、CRC 或 JPEG 校验失败的帧不供页面使用。
• 原密钥只在经过签名认证的后端请求和执行计划中传递，不写总控快照、数据库或浏览器响应。
• UDP 缺片仍会丢帧；本阶段没有图片分片重传。直接上传分散了网关压力，但节点和链路的实际容量仍需用现场画面进行压测。
• 当前每个登记采集器对应一路原图。原协议没有独立相机通道号，多相机标识需要后续明确协议扩展。
• PXHJ 原图快照最长保存 30 秒，总计不超过 4096 张或 64 MiB，达到预算时可提前淘汰。快照权限沿用原图片入口；旧编号不会被替换成新图片。节点私有接口仍在任务撤销后拒绝旧版本。
• 准备取图的路由查询、元数据、精确 JPEG 和一次允许的重试共享 1800 ms 预算，完整 HTTP 正文也受超时限制。仅已验签的精确帧 404 可刷新元数据重取一次。

验证范围

本机验证覆盖真实加密分片、节点收图、准备取图代理、容量和迁移、认证失败与许可撤销。2026-10-15 已在实际 RK3588 构建完整 ARM 程序、部署并开启协商，通过现有 PXHJ 准备页面取到直传原图；视频输入为已有文件经 RTP 送入真实板卡。当前结果见 开发板图片协商联调记录。真实摄像机、真实融合和多台物理电脑性能验收另行进行。