xtrhrj/总控与多机融合服务开发方案.md

# 总控与多机融合服务开发方案

日期：2026-10-15  
项目工作空间：`E:\Codex\xtrh`  
文档状态：本阶段实现说明与后续设计。第 0 节列出当前已实现范围和验证证据，其余涉及真实媒体、仿真和录像的内容属于后续设计，不能视为已实现或通过设备验收。

## 0. 最新开发范围与验证状态

2026-10-15 已加入上传地址协商与节点原图接收：嵌入式通过网关请求接收地址，PXHJ 按原设备密钥认证，再由总控按节点容量分配；图片原分片直接上传节点，准备页面沿已有图片 API 向当前节点取原图，不以正式试验开始为前提。迁移期间最多向两个节点上传，候选收到完整首帧后切换。许可到期或有效等待回复使设备回到已配置的 PXHJ 原图片地址。

Java 服务已在本机加载新版。XTRH 38 项测试全部通过；加入 PXHJ 原图快照缓存、完整正文超时和批量缓存淘汰修复后，PXHJ 411 项回归无失败、错误，跳过 30 项。Windows 独立嵌入式组件与实际 C++ / PXHJ Java 加密报文双向互操作通过；RK3588 已完成完整 ARM 构建、部署并开启协商，现有 PXHJ 准备页面已取得原图。板上日志测试 9 项通过，图片协商 8 项通过、1 项可选夹具跳过。当前视频输入为已有文件经 RTP 输入真实板卡，尚未验收物理摄像机、多台物理电脑或真实融合。流程见 [图片直传协商与准备取图](E:/Codex/xtrh/docs/图片直传协商与准备取图.md)，实际配置和迁移证据见 [开发板联调记录](E:/Codex/xtrh/docs/开发板图片协商联调记录.md)。

### 0.1 上一阶段范围与验证（2026-10-14）

按用户最新要求，本阶段使用 Java 实现总控、节点自动发现注册、动态路数任务分发和原始 UDP 转发，并接入 PXHJ 的正式试验页面统一操作。真实视频融合暂不开发，只提供明确标记的演示 MJPEG 画面。

| 功能 | 当前状态 |
|---|---|
| 总控、网关、多个 Worker | 同一个 Java JAR 的三种部署角色；总控默认在同一进程兼任执行节点，网关独立转发 |
| 主节点执行能力 | 默认开启、默认容量 2 路，与控制接口共用 18100 端口和稳定身份；可配置只调度模式 |
| 自动发现与注册 | mDNS / DNS-SD，发现后验证签名与总控身份；节点不需要预填总控地址 |
| 动态路数分配 | 每节点 0～64 路，准备任务计入容量；先准备新节点，再切换正式输出；容量不足保留原输出 |
| UDP 转发 | 按登记来源识别采集器，不解析、不改写原始字节，使用独立转发源端口；支持反向原字节回执 |
| 重启与失联保护 | H2 持久化、启动会话、任务版本和限时许可；总控重启后要求 PXHJ 重确认试验上下文 |
| PXHJ 统一操作 | 已通过真实业务服务、会话/CSRF、隔离 H2 与实际总控/节点串联验证；主达梦实例已加载新版并实际同步总控状态 |
| 视频地址同步 | 节点注册对外地址并回报就绪，总控登记有效播放地址；PXHJ 后台签名轮询快照并保存播放信息；没有主动推送回调 |
| 真实视频与仿真 | 尚未实现真实输入、仿真数据协议、目标图层、标定、时间匹配、视频融合和录制 |
| 性能感知调度及高可用 | 尚未实现 CPU/GPU 负载测量自动调整容量、总控/网关主备切换 |

2026-10-14 分层后的 XTRH 原有 19 项测试及新增主节点执行能力 5 项测试全部通过，共 **24 项**。新增随机端口测试验证同一主进程自动注册唯一主身份、执行一条 READY 任务，并从该主端口实际读取、解码 JPEG。总控只调度模式、普通 worker 与 gateway 的组件条件也已验证。主执行能力版本已经打包并升级正式本机总控。

PXHJ 上一阶段新增融合后端 17 项针对性测试和 1 项真实业务串联测试通过。业务串联在隔离 H2 中通过正式业务服务创建试验，经登录会话/CSRF 和正式接口层连接实际总控、子节点，验证了保存装备绑定的五路任务、2+3 分配、1+4 动态迁移、正式轮次开始/结束，以及各路 MJPEG 的 JPEG 首帧。

PXHJ 全后端回归和打包已完成，报告共 392 项测试，失败 0、错误 0、跳过 30 项。独立构建目录为 `runtime/pxhj-build`，产物为 [pxhj-server-0.1.0.jar](E:/Codex/xtrh/runtime/pxhj-build/pxhj-server-0.1.0.jar)。跳过的实时外部服务和达梦 opt-in 项不代表现场验证已通过；真实业务串联已另行显式运行。

实际在一台 Windows 电脑上启动总控、网关和两个节点，未配置节点总控 URL，验证了自动发现注册和原字节双向 UDP；结束测试轮次后 UDP 仍正常转发。PXHJ 另有两项中转 UDP 测试，覆盖实际加密数据与心跳接收、来源及密钥校验和动态配置回程地址。

这些结果是本机多进程、隔离 H2 和正式业务实现的软件验证，不能替代多台物理电脑、真实采集器或达梦主实例的现场验收。详细证据见 [本机验证记录](E:/Codex/xtrh/docs/本机验证记录.md)，构建和部署方式见 [README](E:/Codex/xtrh/README.md)。

目前新版默认端口角色已经运行：主总控 18100 同时控制和执行、主容量 2，网关 HTTP 18110 / UDP 19002，子节点 A 18120 / 容量 2、B 18121 / 容量 3。只读签名快照确认 **三个在线执行节点、一个在线网关，总容量 7 路**。主节点只有一条 `COORDINATOR` 记录，主身份与总控一致，子节点为 `WORKER`；子角色配置均无总控 URL。隔离验证的四个 182xx 实例已按身份停止。

PXHJ 达梦主后端已接通总控。本次升级只重启 18100 主进程，原身份、数据和配置保留，PXHJ 后端、前端、网关及两个子节点未再次重启。实际缓存表自动同步三个在线执行节点和一个在线网关，检查时年龄 64 毫秒；UDP 19001、图片 UDP 6020 与网关 UDP 19002 均在运行。原有一轮 `RUNNING` 保持不变，未新增或修改正式试验视频配置，未调整子节点容量，真实设备采集路径也未切换。当前生产视频任务为 0，主端口实际 JPEG 已由隔离随机端口测试验证。

## 1. 要做成什么

做一套可部署在多台电脑上的后台软件，由 **PXHJ 统一操作**。PXHJ 负责设计、试验组织和数据查看，新软件负责采集接入、UDP 转发、任务分发、仿真交互和视频融合。

用户日常只使用 PXHJ。新软件部署好后自动运行，不再设置一套独立的试验操作界面。

核心要求如下：

| 要求 | 设计结果 |
|---|---|
| PXHJ 统一操作 | 配置、准备、开始、结束、节点路数调整及视频查看均在 PXHJ 中完成 |
| 多台电脑参与融合 | 每台电脑运行一个融合节点，一个节点可以同时处理多路视频 |
| 部署后自动加入 | 节点启动后自动发现本项目总控、完成认证及注册，PXHJ 自动出现节点记录 |
| 路数动态配置 | PXHJ 修改各节点的最大并行路数，总控据此分配和调整任务 |
| 采集数据接入迁移 | 采集器向新软件的统一入口发送数据 |
| PXHJ 继续查看采集数据 | 新软件保持原始加密报文内容，通过 UDP 转发给 PXHJ |
| 仿真交互 | 将当前试验所需的装备状态和相机信息发送给仿真系统 |
| 准确融合 | 仿真目标与真实视频的坐标、相机视角和拍摄时间一致 |
| 视频自动同步 | 节点将服务地址和就绪结果报给总控，PXHJ 后台签名轮询总控并登记播放信息，页面自动加载 |

## 2. 总体架构

新软件分成三个后台角色，它们属于同一个项目，可以分别启动和部署。

```mermaid
flowchart TB
    P["PXHJ 后端与页面<br/>试验组织、统一操作、数据和视频查看"]
    M["主节点：同一总控进程<br/>配置管理、任务分配、状态汇总<br/>默认也执行本机视频任务，端口18100"]
    G["采集接入网关<br/>已实现原始报文双向转发<br/>协议解析与数据分发后续实现"]
    D["已登记采集器与采集模块"]
    C["真实摄像头或视频源"]
    S["仿真推演系统<br/>后续接入：统一场景状态、多相机视角输出"]
    W["多台融合节点<br/>接收采集器原图、处理多路演示视频"]

    P -->|试验配置与操作指令| M
    M -->|已确认的来源与转发路由| G
    M -->|视频任务与路数限制| W
    D -->|采集报文、心跳与协商| G
    G -->|原始报文 UDP 转发| P
    D -->|协商后原 JPG 分片直传| W
    W -->|准备阶段原图、内部签名 HTTP| P
    P -->|原字节配置与回执| G
    G -.->|后续：位置、姿态等带时间的数据| W
    G -.->|后续：当前试验装备状态| S
    C -.->|后续：真实视频输入| W
    W -.->|后续：相机视角与渲染请求| S
    S -.->|后续：目标图层、遮罩及帧标识| W
    W -->|对外地址、心跳与任务就绪结果| M
    P -->|签名轮询总控快照并登记播放信息| M
    W -->|当前演示 MJPEG 直接供页面播放| P
```

图中实线表示当前链路，虚线表示后续真实视频与仿真链路。“直接供页面播放”是 PXHJ 浏览器连接融合节点的播放服务。总控和 PXHJ 业务后端主要处理控制与地址信息，避免所有视频都经它们转码或转运。

### 三个后台角色的职责

| 角色 | 主要职责 | 部署建议 |
|---|---|---|
| 总控服务 Coordinator | 当前接收 PXHJ 上下文、登记节点、分配任务、调整路数、管理版本、汇总状态与播放地址，供 PXHJ 轮询 | 第一版一个有效总控实例 |
| 采集接入网关 Gateway | 当前接收已登记来源的原始 UDP 字节并双向转发；解析装备状态、时间缓存和节点数据分发为后续项 | 第一版一个网关实例，与总控可以同机，进程独立 |
| 融合节点 Worker | 当前自动登记、领取多个任务、发布演示画面；真实视频、仿真、融合及录像为后续项 | 每台融合电脑部署一个节点，可运行多个媒体任务 |

主节点在同一个总控进程中加载 `WorkerService` 和媒体控制器，自动向自身总控进行签名身份校验与注册，控制和播放共用默认端口 18100；不需要另外启动主电脑的 worker 进程。主节点使用总控已有的稳定 ID，快照标记 `nodeRole=COORDINATOR`；普通子节点标记 `WORKER`。PXHJ 统一配置主、子节点路数，主身份不会重复登记为第二个普通节点。

**总控或某个融合任务发生异常时，采集接入网关的接收与转发仍独立运行。** 网关使用最近一次确认的来源及转发配置，总控恢复后再同步变化。

## 3. 部署方式

### 单机起步，多机扩展

单机调试时，三个角色可以部署在一台电脑上，使用不同监听端口。正式扩展时，把 Worker 部署到其他电脑，网关和总控可以继续在原来的接入电脑上运行。

| 电脑 | 部署内容 | 作用 |
|---|---|---|
| PXHJ 服务器 | 现有 PXHJ 后端、前端 | 业务数据及统一操作入口 |
| 接入与总控电脑 | Coordinator、Gateway | 收数据、转发、管理节点和任务 |
| 融合电脑 A | Worker、媒体处理程序、播放服务 | 按配置处理多路视频 |
| 融合电脑 B | Worker、媒体处理程序、播放服务 | 按配置处理多路视频 |
| 后续新增电脑 | 同样的 Worker 部署包 | 启动后自动发现总控并登记，满足容量和能力要求后接收任务 |

统一部署配置预置项目集群标识、注册凭证或受信任证书、默认容量策略及媒体程序位置。同一局域网内，新增节点不要求逐台填写总控 IP，也不要求在 PXHJ 中手动添加节点。

节点首次启动自动生成并保存独立节点 ID，自动选择可达网卡并登记服务地址。多网卡或特殊网络需要指定网卡、对外播放地址时，可通过统一部署配置覆盖。后续任务和路数配置均由 PXHJ 管理。

### 自动发现与自动注册

本方案明确包含两个功能：**先自动找到总控，再自动向总控注册**。

这里的局域网发现适用于子节点和网关。主进程的执行组件等待自身 HTTP 服务就绪后，使用本机实际端口访问并验证自家总控，不依赖监听自己的 mDNS 广播。对外播放地址独立选择可访问网卡，测试或单机部署可显式指定地址。

```mermaid
flowchart TD
    A["安装节点服务并启动"] --> B["寻找本项目总控服务"]
    B --> C["验证集群身份及服务认证"]
    C --> D["自动注册节点身份、能力和地址"]
    D --> E["PXHJ 自动出现该节点"]
    E --> F["持续心跳并领取任务"]
    F -->|总控失联| B
```

局域网发现已采用 mDNS / DNS-SD。总控启动时发布项目专用服务类型 `_xtrh-control._tcp.local.`，携带集群标识、逻辑总控身份、接口版本、服务端口等发现信息。节点浏览该服务类型，解析可达地址后发起正式注册。mDNS 用于本地链路发现，DNS-SD 描述服务类型、地址和端口。[mDNS 规范](https://www.rfc-editor.org/rfc/rfc6762.html)、[DNS-SD 规范](https://www.rfc-editor.org/rfc/rfc6763.html)

发现地址的顺序如下：

1. 如统一部署包预置了固定入口或域名，先尝试该入口。
2. 验证上次成功连接的总控地址，成功则直接恢复连接。
3. 前两项不可用时，自动发现同一局域网内本项目的总控。
4. 暂未找到时保持等待，当前采用约 1.5 秒固定退避，按各角色的心跳周期继续重试；总控稍后启动也能自动加入。指数退避和随机抖动属于后续优化。

发现信息只用于寻找地址，正式注册仍校验项目身份和服务凭证。同网内其他项目的总控不会被误选；本项目出现多个相互冲突的有效总控时，上报总控冲突状态，避免随机切换任务归属。

注册与恢复规则如下：

- `nodeId` 首次启动生成并持久化，部署模板不包含所有电脑共用的节点 ID。
- `bootId` 每次节点进程启动重新生成，用于区分旧进程和本次启动。
- 重复注册更新同一节点记录，电脑 IP 改变后仍保持原节点身份。
- 重启后自动注册和核对任务，旧启动会话的回报及授权失效。
- 总控不可用时自动重连及重新发现，节点仍遵守当前任务的授权有效期。
- 首次注册使用部署配置中的容量，后续以 PXHJ 保存的容量为准；重复注册不覆盖已调整的路数。当前尚未进行显卡能力检测或自动容量测量。

Gateway 可使用同一套发现机制，通过网关登记接口加入总控；其角色与 Worker 区分，不领取视频融合任务。

**发现范围：** 同一局域网、允许发现报文通过时，可以自动找到总控。跨路由或 VLAN、网络隔离或禁用组播时，统一部署配置预置可达的总控域名或入口；节点仍自动注册，不需要在 PXHJ 中逐台添加。基础网络与服务凭证由项目部署时统一配置。

### 端口规划

下面是当前安装脚本使用的默认值和后续接入预留值，部署时检查实际占用情况。直接运行 JAR 时应显式配置角色和端口。

| 用途 | 端口 | 说明 |
|---|---|---|
| 总控 HTTP 接口 | 18100 | PXHJ 后端和节点访问 |
| 局域网服务发现 | UDP 5353 | mDNS 组件按标准共享使用，与采集数据及心跳入口独立 |
| 网关 HTTP 接口 | 18110 | 当前接入状态查询；节点数据订阅后续实现 |
| 主节点演示播放接口 | 18100 | 同一个总控进程、身份和端口，无需额外主执行进程 |
| 子节点管理与演示播放接口 | 18120 | 每台不同电脑可以使用相同端口 |
| 新网关采集 UDP 入口 | 19002 | 采集器上传目标；与 PXHJ 原入口区分 |
| PXHJ 采集 UDP 入口 | 现有配置，默认 19001 | 接收网关转发的原始报文 |
| 新网关图片 UDP 入口 | 6021，后续预留 | 当前未实现独立图片分片组装入口；原字节路由如需转送图片须单独配置和验证 |
| PXHJ 原图片 UDP 入口 | 现有配置，默认 6020 | 是否保留原始图片转发由项目配置决定 |
| 原采集器 RTP 输入 | 原有 9200 配置 | 属于采集器视频输入链路，不能当成平台采集入口 |
| 视频播放端口 | 随播放服务配置 | 地址必须从 PXHJ 浏览器所在电脑可访问 |

采集器上传地址应指向稳定的网关入口。调整某台电脑的视频处理路数，不修改采集器上传地址。

## 4. 功能清单

本节保留最终建设目标，包含后续功能。当前可用范围以第 0 节为准：标定资料管理、仿真接口、装备状态解析与订阅、真实媒体、资源感知调度及录像未实现。

### 4.1 PXHJ 需要增加或接入的功能

- 在正式试验中启用采集与融合，使用该试验已保存的装备、实体模块及安装关系。
- 配置视频通道、对应装备与模块、相机标定资料、仿真接口信息。
- 查看节点在线状态、配置路数、当前运行路数、待分配路数和任务异常。
- 修改节点最大并行路数，启用或停用节点；停用采用迁出任务后退出的方式。
- 复用正式试验的准备、轮次开始和轮次结束操作，驱动后台服务。
- 继续显示采集数据，增加融合视频观看及录像索引。

普通试验页面显示业务信息；服务地址、节点部署、协议和相机标定放在有权限的配置入口。

### 4.2 总控服务需要具备的功能

- 接收并校验试验上下文，保存配置版本、装备与模块关系、视频通道及轮次信息。
- 发布本项目的发现信息，支持节点自动找到总控并完成认证登记。
- 管理节点自动登记、启动会话、心跳、能力、并行路数和任务运行状态。
- 为每路视频创建任务，并自动分配到具备空余容量的节点。
- 在路数变化、节点加入、持续过载、节点退出或失联时调整分配。
- 管理任务版本和限时执行授权，过滤旧节点、旧轮次的迟到状态和播放地址。
- 当前汇总网关与演示视频状态，供 PXHJ 后台签名轮询；仿真状态及主动推送为后续项。
- 保存必要状态，重启后核对 PXHJ 当前执行状态，再恢复有效任务。
- 对重复操作去重；失败的指令和上报可重试，PXHJ 能看到实际执行结果。

### 4.3 采集接入网关需要具备的功能

- 接收全部已登记采集器的原始数据和心跳，识别来源及模块身份。
- 保持原始加密报文内容，通过独立转发通道发送给 PXHJ。
- 复用现有协议规则进行校验和解析，为仿真与融合生成标准化数据。
- 根据试验绑定关系，将模块数据对应到装备和安装部位。
- 缓存带采样时间的有效数据，向节点分发所需装备数据。
- 分别统计采集器心跳、模块有效数据、转发数量、接收异常和队列丢弃情况。
- 需要使用图片上传时，独立接收、校验、组装图片分片，按通道分发。
- 当接入的设备使用配置下发与回执时，提供对应的双向转送能力。

### 4.4 融合节点需要具备的功能

- 自动发现总控、注册及重连，接收任务配置，同一台电脑同时执行多路媒体任务。
- 根据分配获取视频源、装备数据、相机参数和仿真目标图层。
- 按帧时间匹配位置与姿态，完成图像校正、目标合成、编码及发布。
- 上报真实运行状态、播放入口、帧率、处理延迟及错误。
- 任务迁移、撤销或执行授权到期时，停止旧任务的有效输出。
- 按试验、轮次和通道保存分段录像，结束后返回录像索引。
- 管理媒体进程异常、日志轮转和磁盘保留上限。

## 5. PXHJ 操作到后台执行的流程

以下含真实媒体的步骤是后续目标。本阶段由 PXHJ 同步保存的试验、绑定和轮次，节点准备演示画面；尚不检查真实视频输入、标定或仿真接口，也不启动录像。

### 5.1 试验准备

1. 用户在 PXHJ 中选择正式试验并进入准备。
2. PXHJ 后端读取该试验保存的装备与模块绑定，组织融合上下文并下发给总控。
3. 总控配置网关的数据对应关系，检查节点容量、视频输入、标定资料和仿真接口。
4. 网关持续接收与转发数据，PXHJ 可以检查模块状态。
5. 节点建立媒体输入和预览链路，确认能取得画面及所需数据后，上报准备结果。
6. PXHJ 显示准备情况以及缺少的条件。

仅打开查看其他试验不应重新绑定正在运行的后台任务。任务切换由明确的准备或执行操作触发。

### 5.2 开始与结束轮次

```mermaid
sequenceDiagram
    participant P as PXHJ 后端
    participant M as 总控服务
    participant G as 接入网关
    participant W as 融合节点
    P->>M: 下发试验配置和准备指令
    M->>G: 来源配置与数据分发关系
    M->>W: 分配任务并准备媒体链路
    W-->>M: 实际准备结果
    M-->>P: 准备状态
    P->>P: 确认正式轮次开始，保存开始时间
    P->>M: 开始指令：试验、轮次、时间、操作ID
    M->>W: 启用该轮融合与录像
    W-->>M: 有效任务状态与播放入口
    P->>M: 签名轮询快照
    M-->>P: 返回视频地址和执行状态
    P->>P: 保存正式轮次结束时间
    P->>M: 结束该轮指令
    M->>W: 撤销任务授权，结束该轮输出与录像
    W-->>M: 结束结果与录像索引
    M-->>P: 汇总结束结果
    Note over G: 轮次结束后，采集接收与原始转发继续运行
```

试验和轮次状态以 PXHJ 为准。PXHJ 正式轮次状态与“融合启动中、运行中、异常、停止中”等后台执行状态分别记录。

建议 PXHJ 在保存正式开始或结束操作时，同时保存待发送指令，由后台可靠重试发送。总控按操作 ID 去重。正式轮次已经开始而融合启动失败时，页面明确显示融合异常，按同一轮次重试，不能显示为已成功融合或另建一轮。

## 6. 每台电脑的路数配置与任务分发

### 6.1 配置含义

主节点同样参与路数配置，默认最大 2 路，与子节点使用相同的容量预留、任务许可和迁移规则。部署参数 `fusion.coordinator-worker-enabled=false` 或安装脚本 `-CoordinatorOnly` 可关闭主执行能力，仅保留总控；关闭后不加载执行服务、媒体控制器和媒体线程池。此开关不关闭独立 worker 的执行能力，gateway 始终只承担转发。

每个节点配置一个“最大同时处理路数”。实际运行路数由总控分配，不能超过已认可的运行容量；任务准备和迁移预热也需要计入资源占用。

| 节点 | 最大并行路数 | 当前运行路数 | 待准备任务 | 状态 |
|---|---:|---:|---:|---|
| A | 4 | 4 | 0 | 正常 |
| B | 6 | 6 | 0 | 正常 |
| C | 2 | 2 | 0 | 正常 |

这只是 12 路任务的分配示例，不表示实际电脑一定能达到这些容量。容量应以指定分辨率、帧率和实际融合处理的测试结果配置；采用 NVIDIA 硬件编码时，还需计入编码资源和并发限制。[NVENC 官方说明](https://docs.nvidia.com/video-technologies/video-codec-sdk/13.0/nvenc-application-note/index.html)

### 6.2 分配规则

一个任务对应“一个试验、一个轮次、一条视频通道”，每条通道的连续帧由同一个当前有效节点处理。

总控分配时依次检查：

1. 节点在线且允许接收新任务。
2. 节点支持该输入格式、输出格式和融合处理方式。
3. 配置路数内存在空余位置，实际处理资源也可用。
4. 优先使用已有有效分配，减少运行中的迁移。
5. 新任务优先分配给空余容量充足、运行表现稳定的节点。

总容量不足时，任务进入“等待分配”，PXHJ 显示待分配数量和原因。持续过载时，可以在配置上限内迁移任务；瞬时负载波动不触发频繁搬迁。

### 6.3 动态调整示例

原来 A / B / C 分别跑 4 / 6 / 2 路，修改为 2 / 6 / 4 路：

1. 总控先确认 C 的新增容量可用，将变更显示为“调整中”。
2. 为 A 上需迁出的两路任务建立 C 上的候选执行版本；切换成功前，A 的原版本仍是当前有效版本。
3. 当前 C 生成演示画面并确认可播放；后续真实融合时再获取视频源、标定参数、采集数据缓存和仿真图层。
4. 总控切换该通道的有效版本及播放入口，PXHJ 下一次签名轮询获取更新。
5. 撤销 A 上的旧版本，释放其资源，完成路数调整。

配置上限下降后，迁出期间实际运行路数可能暂时高于新目标，必须显示调整进度。没有可接管容量时，不宣称变更已完成；由 PXHJ 选择增加容量、保留原任务或明确停止部分任务。

迁移需要源节点和目标节点的资源配合。候选版本获得准备许可，完成切换后才获得正式输出许可；准备失败时取消候选版本，不误撤销仍有效的原版本。没有预热余量时采用先停后启，允许短暂断画；是否需要接近连续的切换，应在实际链路上单独验证。

## 7. 所有采集模块的数据接收与 UDP 转发

当前网关只执行来源匹配、原始字节双向转发和统计。后面的协议解析、采样时间缓存、装备数据分发及独立图片组装是后续设计；当前协议认证与业务样本解析仍在 PXHJ 的正式接收入口执行。

### 7.1 接收一次，按用途分发

```text
已登记采集器
    → 网关识别来源并校验报文
        → 保留原始加密报文字节，转发给 PXHJ
        → 解析模块数据，按试验绑定对应到装备
            → 仿真系统所需的装备状态
            → 各融合节点所需的带时间的位置和姿态
```

已登记来源的原始数据完整转发给 PXHJ。当前试验名单决定哪些解析数据参与仿真和融合，不用于删改一个原始包内的模块数据。

网关保存采样时间、启动会话及原有序号，不为了中转重新生成采集时间或修改原始加密内容。同一装备的数据可以分发给多个视频任务。

UDP 转发、数据解析、节点分发分别使用有界队列和独立处理流程。慢节点与仿真异常不阻塞原始转发；队列满时按通道记录丢弃数量和原因。

UDP 本身不保证送达、有序或自动补发，因此必须区分“网关已发送”和“PXHJ 实际接受”。需要无损记录时，应另行设计确认、缓存及补发规则，并兼容现有的去重和时间窗口。[UDP 使用指南](https://www.rfc-editor.org/rfc/rfc8085.html)

### 7.2 保持 PXHJ 的采集器身份对应

现有 PXHJ 会检查来源 IP、来源端口及协议身份，再按登记密钥校验解码。中转后，网络来源变为网关，必须同步维护身份映射。

建议每个采集器分配独立、固定的转发源端口：

| 原采集器 | 网关转发源端口，示例 | PXHJ 中对应的连接 |
|---|---:|---|
| 采集器 A | 31001 | 保留采集器 A 原连接 ID，登记网关 IP 和 31001 |
| 采集器 B | 31002 | 保留采集器 B 原连接 ID，登记网关 IP 和 31002 |

保持原连接 ID、协议身份与密钥关联，避免已有试验绑定失效。多个采集器经同一网关转发时，PXHJ 来源端口必须明确，避免多个端口通配配置造成来源歧义。

切换前保存原始来源配置，逐个采集器验证：原始字节一致、PXHJ 来源校验通过、数据归属正确、心跳正常。失败时恢复该采集器的上传目标及 PXHJ 来源配置。

### 7.3 协议接入范围

- 优先覆盖当前固定模块数据及采集器心跳，沿用现有加密协议。
- 图片分片采用独立接入链路，按采集器和帧标识组装及分发。
- 当试验使用动态配置模块时，配置下发、回执及数据上报要作为一组链路适配并验证，再切换该来源。
- 当前网关不需要设备解密密钥，协议认证和解析仍由 PXHJ 完成。后续如在网关内启用解析，再增加受控密钥配置或引用，密钥不放入页面、源码、任务日志或公开接口返回。

网关持续接收全部已登记来源，模块数据以正式实体身份识别，并兼容已有采集器来源及模块编号组合。采集器有心跳、模块有有效样本、视频有新帧分别报告。

### 7.4 数据接收的后续扩容

第一版使用一个采集接入网关。若实测接收量超出单机能力，再按采集器分组增加网关实例，每个来源归一个当前有效接入节点。

网关按采集器分组扩容，融合节点按视频路数扩容。两种分配关系独立，调整视频路数不改变来源接入归属。

## 8. 仿真交互与真实视频融合

本节全部为后续设计，本阶段尚未实现。演示 MJPEG 不包含真实相机或仿真目标，不用于评估融合精度、编码性能或正式录像能力。

### 8.1 正确融合需要的信息

| 信息 | 作用 |
|---|---|
| 统一空间基准、单位和目标尺寸 | 真实装备、相机和仿真目标的位置及大小能够对应 |
| 相机镜头参数和畸变参数 | 生成与真实镜头一致的投影，并校正图像 |
| 相机安装位置、朝向和云台角度 | 从装备姿态计算实际相机视角 |
| 真实拍摄时间、视频帧标识 | 对应同一时刻的装备数据和仿真图层 |
| 仿真目标透明图层或目标遮罩 | 在真实画面上合成目标 |
| 可选真实场景深度或遮挡区域 | 实现真实树木、建筑等前景对目标的遮挡 |

相机标定资料按具体相机、镜头和使用分辨率管理。变焦、安装改变或图像裁剪影响投影时，更新相应参数。[OpenCV 相机标定说明](https://docs.opencv.org/4.13.0/dc/dbb/tutorial_py_calibration.html)

仅有车体角度和车辆经纬度，还需要校准相机安装关系并核对测量精度。数据精度不足时，应增加定位或视觉校正措施，再验证融合误差。

### 8.2 媒体处理流程

```text
读取真实视频帧及拍摄时间
    → 查找或插值该时刻的有效装备位置与姿态
    → 得到实际相机位置、朝向及投影参数
    → 请求仿真系统输出对应帧的目标图层
    → 匹配帧标识、校正画面、合成目标
    → 编码、发布实时视频、按需分段录像
```

网关和节点保留可配置时长的数据短缓存，用于按拍摄时间匹配。采集器、视频源和仿真系统应使用统一时间基准；只有接收时间的输入需要测量链路延迟并补齐拍摄时间关系。

仿真图层延迟、所需姿态过期或定位无效时，节点上报融合状态异常，停止使用失效图层；可配置继续显示真实视频。不能将冻结的目标持续展示为有效实时融合。

### 8.3 多节点与仿真系统的关系

同一试验的仿真场景状态统一维护，各节点按各自的视频通道获取相机视角图层。不能因为有多个节点，就各自独立推进一个互不一致的试验世界。

仿真侧需要支持多相机输出；渲染本身成为瓶颈时，需要支持多实例或多机渲染，并共享一致的场景状态和时间。单纯增加融合节点不会自动增加仿真端的渲染能力。

仿真产品的具体协议、透明图层能力、坐标定义和渲染并行方式，在接入资料和联调中确定，通过适配器封装。

## 9. 融合视频地址如何上报给 PXHJ

```text
Worker 注册对外服务地址，并在心跳中回报当前任务版本已就绪
    → 总控验证节点会话、任务归属和当前有效版本
    → 总控生成并登记对应任务的完整 MJPEG 播放地址
    → PXHJ 后台约每 1.5 秒用签名 HTTP 请求轮询总控快照
    → PXHJ 将快照持久保存到 biz_fusion_cache，并按试验、轮次筛选视频
    → 页面查询 PXHJ 后端，直接连接对应节点播放
```

**当前采用签名轮询同步，尚未实现总控主动调用 PXHJ 的推送回调。** 节点当前上报的是对外基础地址与任务就绪结果，完整播放路径由总控依据任务 ID、版本和媒体许可生成。

当前总控快照中的视频任务包含：

| 字段 | 含义 |
|---|---|
| `trialId`、`roundId` | 试验与轮次 |
| `equipmentId`、`channelId` | 装备与固定视频通道 |
| `taskId`、`version` | 媒体任务及当前有效执行版本 |
| `nodeId` | 当前执行节点 |
| `playProtocol`、`playUrl` | 播放方式及对应入口 |
| `status`、快照 `serverTime` | 任务准备、运行、迁移或结束状态，以及该快照的时间 |

演示任务使用 `MJPEG_DEMO`，由 Java Worker 产生演示画面；原图任务使用 `MJPEG_ORIGINAL`，展示采集器实际上传图片，准备页面经 PXHJ 原图片 API 读取。后续正式融合视频可以增加 WebRTC 或 HLS 输出，这些流媒体输出尚未实现。WebRTC 入口由对应播放器完成连接协商，不能按普通 MP4 文件地址直接使用。[MediaMTX 浏览器播放说明](https://mediamtx.org/docs/read/web-browsers)

地址使用观看电脑可访问的 IP 或域名。注册时核验节点对外地址，不能用节点自己的回环地址或本地文件路径代替网络播放入口。

任务迁移后，`channelId` 保持不变，`version` 递增，目标就绪后更新播放入口。PXHJ 根据总控身份、调度代次和修订号过滤旧快照，页面随查询结果更新连接。旧节点迟到的回执不能重新登记旧地址。

录像和录像索引尚未实现。后续若增加录制，需要单独管理实时播放入口与分段录像索引，迁移前后的片段归属同一试验、轮次和视频通道。

## 10. PXHJ 集成与当前接口

### 10.1 可以利用的现有基础

已核对现有 PXHJ：

- `GET /api/trials` 提供试验概要列表。
- `GET /api/trials/{id}` 提供正式试验详情、保存的绑定关系和轮次。
- 现有轮次开始、结束接口作为业务执行的统一入口。
- 现有 UDP 接入包含来源校验、加密校验和固定模块解析。
- 现有视频展示包含图片帧查询，融合流需要增加对应播放器及登记能力。

集成时由 PXHJ 后端组织权威上下文，通过受控接口下发。现有用户会话接口不能直接当成无鉴权的后台集成接口。

本阶段接入正式试验页面、后端接口和权限体系，不建设独立演示操作界面。正式业务服务与实际后台节点的 H2 串联测试已通过，主达梦后端也已升级并实际同步节点状态；真实设备采集切换、正式试验现场融合和物理多机验收仍需要另外完成。

### 10.2 PXHJ 当前新增接口

以下名称与当前 `FusionController` 一致。

| 接口 | 用途 |
|---|---|
| `GET /api/fusion/status` | 查询节点、容量、任务与网关汇总状态 |
| `GET /api/trials/{id}/fusion?roundId=...` | 查询该正式试验当前配置及指定轮次视频任务 |
| `PUT /api/trials/{id}/fusion` | 保存该试验的通道配置并同步权威上下文 |
| `PATCH /api/fusion/nodes/{id}/capacity` | 修改最大并行路数与启用状态 |
| `GET /api/fusion/relay-sources` | 查询正式采集器来源及中转配置 |
| `PUT /api/fusion/relay-sources` | 保存所选正式采集器的中转来源和目标 |

开始和结束融合由现有正式轮次操作触发，后端向总控发送对应指令，页面不增加另一套独立的“开始试验”流程。

本阶段没有 `video-reports` 或 `status-reports` 推送回调接口；PXHJ 后台签名读取 `/control/snapshot` 后完成状态和播放信息同步。

### 10.3 新软件当前内部接口

| 方向 | 接口或通道 | 用途 |
|---|---|---|
| PXHJ 后端 → 总控 | `GET /control/info`、`GET /control/snapshot` | 校验总控身份并同步当前状态、任务及播放地址 |
| PXHJ 后端 → 总控 | `POST /control/contexts/sync` | 统一下发权威试验上下文及 PENDING、RUNNING 或 SAVED 轮次状态 |
| PXHJ 后端 → 总控 | `PATCH /control/nodes/{id}/capacity` | 下发容量变更 |
| Worker → 总控 | `POST /control/nodes/register` | 自动登记节点 ID、启动会话、能力和对外地址；重复登记更新原记录 |
| Worker → 总控 | `POST /control/nodes/{id}/heartbeat` | 汇报运行情况，获取更新后的任务计划和执行授权 |
| PXHJ 后端 → 总控 | `PUT /control/routes` | 保存完整来源和转发映射 |
| Gateway → 总控 | `POST /control/gateways/heartbeat` | 心跳即自动登记，汇报网关统计并获取已确认的版本化路由 |

节点就绪结果包含在心跳中，当前没有独立任务回报接口。网关到 Worker 的采集数据订阅尚未实现。

当前上下文携带配置版本，任务计划携带任务 ID、执行版本、节点会话和授权有效期。PXHJ 持久保存期望配置并定时重新核对正式轮次；尚未实现单独的操作 ID 事件流水。用户操作由 PXHJ 权限控制，后台服务间使用凭证生成请求和响应签名，不在请求头发送明文凭证。

## 11. 状态、重启与异常处理

### 11.1 需要保存的状态

当前总控用 H2 保存节点配置、试验上下文版本、任务目标状态、分配、会话和任务版本。播放状态通过快照供 PXHJ 查询，没有待推送回调队列，也没有独立操作 ID 去重流水。

网关保存来源及转发映射、已确认配置版本。实时数据采用有界缓存；需要留存原始报文时，单独配置容量和保留策略。

当前节点持久保存自身身份和成功连接的总控地址，签名响应中的总控逻辑身份用于当次认证和地址去重，任务计划保存在内存中，录像索引未实现。总控重启后先核对 PXHJ 的轮次状态，对旧任务重新确认并发放新版本授权，再恢复有效输出。不能仅加载磁盘记录就宣称旧视频仍在正常运行。

### 11.2 异常处理规则

| 情况 | 处理方式 |
|---|---|
| 节点容量不足 | 任务等待，PXHJ 显示原因 |
| 节点失联或媒体进程崩溃 | 作废旧任务有效版本；有容量时重建任务，记录中断 |
| 节点因网络分区收不到控制信息 | 原授权到期后停止有效发布，等待重新确认 |
| 旧节点迟到上报 | 按任务版本和执行授权拒绝，不覆盖新地址 |
| 路数调整过程中目标节点准备失败 | 保留仍有效的原任务，变更返回失败或待处理状态 |
| 总控暂时不可用 | 网关继续按已确认配置转发；节点按授权规则处理当前任务 |
| PXHJ 暂时不可用 | 总控保留当前状态；PXHJ 恢复后后台重新轮询并核对正式上下文；当前没有推送回调重试队列 |
| 视频或姿态数据过期 | 单独报告数据异常，停止使用过期图层 |
| 原始转发队列满 | 记录数量和原因，PXHJ 显示接入异常 |
| 录像磁盘不足 | 后续实现录像时报告录像失败；本阶段未实现录制 |

执行授权是一段有限时间内有效的任务许可，节点心跳正常时续期。任务迁移或失联重建后，旧许可失效；业务上同一通道只有一个当前有效输出版本。预热过程可以临时存在两个媒体任务，但不能把两个版本同时登记为当前有效视频。

第一版采用单有效总控和单接入网关，支持持久化重启恢复。总控与网关的主备切换需要另行实现、测试，不能将多个 Worker 等同于接入服务已经具备高可用。

## 12. 技术实现思路

| 层 | 当前实现与后续方向 | 原因 |
|---|---|---|
| 总控及网关 | Java 17、Spring Boot；总控默认在同一进程兼任执行节点 | 控制和执行共享主身份，网关保持独立转发 |
| 总控状态保存 | 第一版 H2 文件数据库及事务记录 | 避免仅靠内存或临时 JSON 保存任务状态 |
| Worker 控制与演示视频 | Java 后台服务，Java2D / ImageIO 产生 MJPEG | 验证任务生命周期、迁移和实际播放 |
| 真实媒体处理 | 后续在 Java 项目内增加真实输入、仿真和合成适配；具体编解码/GPU 库待接入资料确定 | 本阶段尚未实现校正、合成或正式编码 |
| 正式流媒体发布 | 后续提供 WebRTC 或等效播放服务 | 当前只提供演示 MJPEG，正式低延迟输出待实现 |
| PXHJ 页面 | 在现有 Vue 试验页面接入管理及播放器 | 统一用户操作和权限 |

协议公共模块只抽取编解码、校验和标准数据结构，不把 PXHJ 的数据库访问和试验组织逻辑整体搬入新软件。

媒体执行层建议封装视频输入、仿真接入、时间匹配、图像合成、流发布和录像六个部件。缺少真实仿真或标定条件时，明确记录该环节未验证，不能以透传普通视频代替准确融合验收。

当前代码结构如下。现阶段保持一个 Maven 项目，通过角色配置运行三个服务，不提前拆出尚未实现的媒体和协议子模块：

```text
xtrh/
├─ pom.xml
├─ src/main/java/com/xtrh/
│  ├─ Application.java    Spring Boot 入口
│  ├─ control/
│  │  ├─ controller/      CoordinatorController：总控 HTTP 转接
│  │  └─ service/         CoordinatorService：节点、上下文、容量、任务与版本调度
│  ├─ gateway/
│  │  ├─ controller/      GatewayController：网关状态接口
│  │  └─ service/         GatewayService：双向 UDP、路由应用与统计
│  ├─ node/
│  │  ├─ controller/      WorkerController：媒体播放和节点状态接口
│  │  ├─ service/         WorkerService：领取任务、授权及演示视频
│  │  └─ config/          WorkerCapabilityCondition：主/子执行条件；AsyncMediaConfiguration：媒体线程
│  ├─ discovery/
│  │  ├─ service/         Discovery、CoordinatorLocator：发现与身份核验
│  │  └─ util/            NodeAddress：对外地址选择
│  ├─ communication/
│  │  ├─ client/          PeerClient：签名 HTTP 通信
│  │  └─ security/        Signatures、ServiceSecurity：签名及防重放
│  └─ common/
│     ├─ config/          Settings：角色与部署配置；SchedulerConfiguration：并发调度线程
│     ├─ controller/      HealthController、ApiErrors：健康与错误接口
│     ├─ dao/             StateStore：H2 状态；NodeIdentityDao：部署身份文件
│     └─ util/            Jsons：公共 JSON 辅助
├─ src/main/resources/    Spring Boot 默认配置
├─ src/test/java/com/xtrh/ 调度、恢复、真实 UDP 和签名测试
├─ scripts/               构建、私有凭证、安装、启停、自启及 PXHJ 连接配置
├─ config/                无密钥的配置示例
├─ docs/                  本机验证记录
├─ README.md              构建、部署、范围与接口说明
└─ runtime/               本机部署产物、身份、数据库和私有配置；不提交仓库
```

控制层只完成 HTTP 参数和服务转接，不承载调度或数据库业务；服务层处理当前业务规则；DAO 层专门保存和读取状态。关键中文注释解释节点会话、旧版本隔离、限时许可、迁移准备、路由缓存及签名校验的原因。测试按对应业务包放置，保留既有测试名称。

`StateStore.open(Path, ObjectMapper)` 将 H2 文件 JDBC 地址组装下沉到 DAO，保留 String URL 构造器供测试使用。`NodeIdentityDao` 只维护节点身份文件，不承担网络注册或调度。PXHJ 新增业务采用 `fusion.controller/service/dao/config/security` 分层，`FusionDao` 承接 SQL。

注释按 `scripts/Measure-Comments.ps1` 统计完整注释行占非空源码行的比例，包含 Javadoc 与块注释边界，不计空行和代码末尾的行内注释。当前全部 XTRH 主 Java 为 **21.53%（594/2759）**，PXHJ 新增 fusion 业务为 **28.83%（501/1738）**。

## 13. 开发顺序与各阶段交付

第一、二阶段的服务骨架与 PXHJ 集成代码已完成本机和 H2 正式业务链路验证，主达梦实例已实际接通总控；实际 RK3588 原图准备取图和接收节点迁移也已完成联调，当前证据见第 0 节。下面列的是完整阶段验收目标，真实摄像机和跨物理电脑验收仍未完成。第三阶段真实融合与录制暂不实施。

| 阶段 | 开发内容 | 可检查的交付结果 |
|---|---|---|
| 第一阶段：接入及服务骨架 | 总控、网关、Worker 部署；自动发现及注册；容量配置；原始 UDP 转发及身份映射 | 三个可部署后台角色，新增节点自动出现，真实协议报文被 PXHJ 接受，节点能领取和汇报任务 |
| 第二阶段：任务分发及正式集成 | PXHJ 正式试验上下文、轮次操作、持久化指令、动态路数、任务版本、视频信息上报 | 从真实 PXHJ 试验发起，多节点任务分配与状态展示可用 |
| 第三阶段：真实融合 | 相机标定、时间匹配、仿真目标图层接入、合成编码、实时播放与录像 | 真实视频中的目标位置、大小和视角按实际设备验证 |
| 第四阶段：多机与稳定性 | 跨机部署、容量测试、任务迁移、失联重建、重启恢复、资源和日志管理 | 至少两台实际融合电脑协同，形成容量及故障测试记录 |

开发中使用的隔离协议样本和测试视频仅用于相应功能验证。正式交付需要真实 PXHJ 试验、实际采集器和跨机部署证据；准确融合另需真实相机及仿真接口的验证。

优先完成第一、二阶段的基础链路，同时确定仿真和相机资料，使第三阶段有可实现、可验收的输入条件。

## 14. 验收重点

1. 同一局域网新部署的节点能自动发现、认证及注册，PXHJ 自动出现记录；总控晚启动、地址变化和节点重启后能恢复，重复注册不新增重复节点。
2. 用户在 PXHJ 内完成配置及试验操作，后台节点自动执行，任务与正式试验、轮次一致。
3. 多个采集器经网关转发后，原始加密报文字节一致，PXHJ 正确识别来源与模块，实际样本接收正常。
4. 一个节点可同时执行多个视频任务，最大并行路数可在 PXHJ 修改。
5. 配置不足时明确等待；容量降低时能显示迁移过程，任务版本和实际占用一致。
6. 任务跨电脑迁移后，相应数据订阅和视频播放入口同步更新，旧版本回报不能覆盖新版本。
7. 轮次结束、节点调整及仿真异常均不会停止独立的采集接收与原始转发。
8. 总控、网关和节点重启后按正式状态恢复；网络分区及授权过期有可观察结果。
9. 仿真与真实相机使用一致的坐标、投影和时间，按静止、转动和移动场景验证融合位置误差。
10. 在指定分辨率、帧率、算法和网络条件下测试每节点实际容量、端到端延迟、掉帧、带宽和编码资源。
11. 形成真实跨机测试记录；同机多进程测试只证明对应的软件行为，不替代跨机验收。

融合误差、允许中断时长、目标帧率及端到端延迟的数值，需要结合相机、定位精度、仿真能力和电脑配置确定。此设计稿不预先承诺未经测量的性能指标。

## 15. 接入实施前需要明确的资料

| 资料 | 用于确定什么 |
|---|---|
| 真实视频通道数、分辨率、帧率、输入格式 | 节点处理容量及媒体输入适配 |
| 各电脑配置、显卡、网络及操作系统 | 编解码、合成能力和部署包 |
| 采集器身份、模块编号、协议和时间字段 | 来源映射、数据解析和按帧同步 |
| 相机型号、安装关系、云台及变焦方式 | 标定与实际相机位姿 |
| 仿真接口、坐标定义、目标图层和多视角能力 | 正确渲染及多节点融合 |
| 实时观看和录像要求 | 发布格式、存储策略及容量 |

这些资料逐项落实到配置和适配器。服务骨架、UDP 转发和调度部分可以先开发，资料缺失的媒体环节保留明确的待接入状态。

## 16. 已核对的 PXHJ 代码依据

- [TrialController.java](E:/pxhj/backend/src/main/java/com/pxhj/trial/controller/TrialController.java)：试验列表、详情及正式创建接口。
- [TrialService.java](E:/pxhj/backend/src/main/java/com/pxhj/trial/service/TrialService.java)：试验详情包含保存的绑定信息及轮次，列表为概要。
- [UdpFoundation.java](E:/pxhj/backend/src/main/java/com/pxhj/telemetry/service/UdpFoundation.java)：来源、消息类型和加密校验，固定数据及心跳处理。
- [FixedModuleService.java](E:/pxhj/backend/src/main/java/com/pxhj/telemetry/fixed/FixedModuleService.java)：来源与认证身份一致性、模块样本识别及去重保存。
- [ModuleVideoDialog.vue](E:/pxhj/frontend/src/equipment/ModuleVideoDialog.vue)：当前模块视频展示采用图片帧方式，融合流需要对应的播放接入。
- [FusionController.java](E:/pxhj/backend/src/main/java/com/pxhj/fusion/controller/FusionController.java)：新增融合配置、节点容量和中转来源的正式接口。
- [FusionService.java](E:/pxhj/backend/src/main/java/com/pxhj/fusion/service/FusionService.java)：权威试验上下文、签名轮询及播放信息同步。
- [FusionDao.java](E:/pxhj/backend/src/main/java/com/pxhj/fusion/dao/FusionDao.java)：融合配置、状态缓存与中转登记的数据库访问。

实施时以当前代码和正式接入资料再次核对，不直接用旧演示中的虚构试验或模拟接口替代以上业务能力。