xtrhrj/docs/本机验证记录.md

# Java 后台服务本机验证记录

## 图片直传协商版本：2026-10-15

本次增加采集器地址协商、节点直接认证接收原 JPG 分片，以及 PXHJ 原图片 API 的私有回源代理。正式试验未开始时原图任务也可用。网关仅转发短小协商报文，图片直接上传当前接收节点；动态迁移在候选端口就绪后短暂双发，候选收到完整首帧后切换取图。

| 验证 | 结果及范围 |
|---|---|
| XTRH 全部 Java 测试与打包 | 38 项，失败 0、错误 0、跳过 0 |
| PXHJ 后端全回归与达梦配置打包 | 403 项，失败 0、错误 0、跳过 30；产物在 `runtime/pxhj-image-build`，测试数据使用隔离 H2 |
| 节点原图集成 | 随机 HTTP/UDP 端口的真实主服务；未启动正式试验即可接收独立 PXHJ WireCodec oracle 生成的加密分片，HTTP JPEG 与原字节一致；匿名 401、无帧或旧版本为签名 404 |
| PXHJ 协商和准备取图 | 新增 11 项；真实 UDP、原设备密钥及来源认证、可信中转、防重放、会话权限和 opaque 原图回源；总控/节点使用随机端口签名 HTTP 替身，此项属于分段验证 |
| Windows 嵌入式独立组件 | Qt 5.15.2 / MSVC / OpenSSL，7 个业务用例，另含 init/cleanup 共 9 项通过；C++ 与实际 PXHJ Java WireCodec 双向互操作 |
| 前端 | 构建和既有 `fusion-operations-ui.mjs` 回归通过；使用正式组件及 API 拦截，原图与演示预览按类型显示 |
| 中文注释统计 | XTRH 主 Java 21.53%（594/2759）；PXHJ fusion 主 Java 29.46%（476/1616） |

安装脚本还在两个未启动的隔离目录验证：HTTP 18900 默认生成图片端口 19900；worker 显式 `-ImagePort 29920` 正确写入配置。部署产物 SHA256 已与本次构建逐一核对，四个 XTRH 实例及 PXHJ 均一致；匿名图片 API 返回 401，后端会话入口和前端页面返回 200。

已按原稳定身份、数据目录及配置升级本机总控 18100、网关 18110/19002、节点 18120/18121 与 PXHJ 8088 后端。图片 UDP 实际绑定 19100、19120、19121。只读签名状态确认三个执行节点、一个网关在线；升级后 PXHJ 达梦缓存年龄核对值为 955 ms，在线节点 3、网关 1。原有 RUNNING 轮次升级前后都是 1；前端进程 5178 持续运行。

当前节点配置容量实际为主节点 2、A 3、B 3，合计 8；这是核对时保存的管理员配置，升级没有用安装默认值覆盖。当前原图和视频运行任务为 0，设备上传路径尚未切换。实际端口和容量可以随后续操作变化。

没有连接或部署 ARM 板子，也没有进行物理多机、真实图片并发容量或融合算法验收。嵌入式协商默认 disabled；启用前必须独立保留 PXHJ 原图片回退地址。Windows 独立组件及本机分段协议验证不能替代目标板和现场整链联调。

变更前 XTRH 源码、原前端文件、部署前 JAR 和发布脚本备份在 `E:\CodexHome\backups\xtrh-image-negotiation-20261015`；PXHJ 本次实施后源码快照标记为 `pxhj-image-implementation`，不能当作实施前源码备份。

以下为 2026-10-14 阶段的历史记录，测试数量和进程状态以本节新版本为准。

验证日期：2026-10-14。工作空间：`E:\Codex\xtrh`。

这份记录覆盖本项目后台服务和部署脚本。验证使用一台 Windows 电脑上的多个独立 Java 进程，以及本机 UDP 套接字。真实采集器、多台物理电脑、仿真系统和真实视频融合不在这份记录的验收范围内。

当前正式视频融合、仿真数据协议与录制未实现。播放信息由节点先提交对外地址和任务就绪结果，总控登记有效播放地址，再由 PXHJ 后台通过签名轮询同步登记；主动推送回调未实现。真实 PXHJ 业务服务与实际总控、节点的业务串联使用隔离 H2 验证；经用户确认，主达梦后端现已加载新版并接通总控，但真实采集来源未切换。

## 自动化测试

使用 Java 25.0.2 执行 Maven，项目按 Java 17 目标编译。增加主节点执行能力后完整 `test` 共 24 项通过，失败 0、错误 0；新版已经打包并升级正式本机总控，部署结果见文末。

| 测试类 | 数量 | 主要验证 |
|---|---:|---|
| `CoordinatorTest` | 10 | 容量预留、超额排队、准备完成后切换、容量不足保留输出、迁移目标掉线、旧会话/版本拒绝、轮次结束与 UDP 解耦、租约到期、系统时间回退、持久化恢复和上下文重确认、未确认的空路由不作为清空指令 |
| `GatewayTest` | 3 | 1～60000 字节不透明二进制 UDP 转发、独立转发源端口、反向回执、未知来源丢弃、总控失联继续转发、重启恢复路由、未确认路由不覆盖缓存、同版本号但明确确认的空路由仍撤销原转发 |
| `ServiceSecurityTest` | 3 | 完整请求/响应签名、一次性随机数防重放、方法/地址/参数/正文篡改拒绝、过期请求拒绝 |
| `PeerClientTest` | 1 | HTTP 头不发送明文凭证，拒绝无签名、错误密钥、错误随机数、正文和状态不匹配的响应 |
| `WorkerTest` | 2 | 准备转为运行后播放连接读取当前任务，延迟到达的计划不能延长过期授权 |
| `WorkerCapabilityTest` | 4 | 总控默认有执行能力、可关闭执行能力及媒体接口/线程池、独立 worker 不受总控开关影响、gateway 无执行能力 |
| `CoordinatorWorkerIntegrationTest` | 1 | 随机端口主进程签名自注册、唯一主身份、任务 READY、同端口实际 JPEG 解码、结束撤销、拒绝伪造主身份 |

测试报告保存在构建目录 `target/surefire-reports`，该目录不提交仓库。

代码已按业务及 controller / service / dao 分层，原 `Coordinator`、`Gateway`、`Worker` 对应当前的 `control.service.CoordinatorService`、`gateway.service.GatewayService`、`node.service.WorkerService`。测试放在对应 service、config、security 或 client 包内。当前报告已确认原 19 项与新增 5 项全部通过。

## 主总控兼任执行节点

新增集成测试在随机 HTTP 端口启动真实 Spring Boot 总控，容量 1，关闭 mDNS，使用独立临时目录和测试凭证。总控进程自身自动通过签名请求注册为唯一 `COORDINATOR` 执行节点，节点 ID 等于总控服务 ID，不需要额外执行进程。下发一条隔离的 PENDING 上下文后任务进入 READY，播放地址使用同一个实际随机端口，实际 HTTP MJPEG 首帧能由 ImageIO 解码；结束上下文后播放地址撤销。主身份冒充普通 WORKER、另一个身份登记 COORDINATOR 均被拒绝。

四项能力条件测试确认：总控默认同时有执行服务、媒体控制器和媒体线程池；关闭 `fusion.coordinator-worker-enabled` 后这些组件都不加载，控制服务保留；普通 worker 即使该开关为 false 也保持执行能力；gateway 始终无视频执行组件。

安装脚本在独立、未启动的测试安装目录中验证：默认总控输出执行开关 true，`-CoordinatorOnly` 输出 false，worker 使用该参数被拒绝。未启动这些安装目录的进程，也未修改正式节点容量、任务或路由。

PXHJ 新增业务已按 controller / service / dao / config / security 分层，针对性验证如下：

| 测试类 | 数量 | 结果与范围 |
|---|---:|---|
| `FusionServiceTest` | 10 | 通过；权威试验配置、节点容量、状态同步和恢复等业务规则 |
| `FusionAccessTest` | 5 | 通过；正式接口权限、会话、CSRF 与允许访问的范围 |
| `FusionRelayUdpIntegrationTest` | 2 | 通过；真实 UDP 接收中的加密采集报文与心跳认证，以及动态配置的中转回程地址 |
| `FusionBusinessIntegrationTest` | 1 | 通过；真实 PXHJ 业务服务和正式接口层连接实际总控、节点的业务串联 |

前三类合计 17 项，业务串联另 1 项。业务串联以显式启用方式运行，与默认常规回归分开核对。

PXHJ 全后端回归和打包已在独立目录 `runtime/pxhj-build` 完成。已读取该目录的 Surefire XML 汇总：392 项测试，失败 0、错误 0、跳过 30 项。常规回归默认跳过实时外部服务和达梦等 opt-in 测试；不能把跳过项算成已验证的真实环境能力。新版产物 [pxhj-server-0.1.0.jar](E:/Codex/xtrh/runtime/pxhj-build/pxhj-server-0.1.0.jar) 已生成。

回归过程中修正了已有报告测试的比较对象：对比 DAO 的原始报告事件，而不是执行 DTO 派生的 `eventParameters`；产品业务代码没有因此改动。修正后完整回归通过。

## PXHJ 真实业务串联

`FusionBusinessIntegrationTest` 显式连接隔离验证总控及两个独立 Java 节点。PXHJ 使用实际 Spring 业务服务与 MockMvc 正式接口层，执行登录、会话及 CSRF 校验；业务数据写入独立 H2，正式试验由既有业务服务创建，使用保存的固定方案、装备和冻结绑定。

验证过程通过：按已绑定装备配置五路演示视频，准备阶段由 A 处理两路、B 处理三路；各路返回实际 MJPEG 流，读到完整 JPEG 首帧并确认首尾标记。通过正式轮次开始接口后五路进入运行状态；在 PXHJ 接口中调整为 A 一路、B 四路，一路自动迁移，版本递增，迁移后各路仍能读取 JPEG。正式结束轮次后撤销旧播放地址，远端任务也结束。清理时恢复验证节点容量和路由。

这验证了真实业务实现到后台节点的链路，未启动浏览器走人工页面流程，不属于物理多机或真实视频融合验收。

## 结构与注释核对

节点身份文件操作已下沉到 `common.dao.NodeIdentityDao`；H2 文件地址由 `common.dao.StateStore.open(Path, ObjectMapper)` 组装。`common` 和 `discovery` 已整理格式与关键中文注释，解释身份与启动会话、持久化失败、未认证广播、多网卡地址选择、认证后总控去重以及服务根地址校验。本项为源码与统计核对，不等同于重构后的运行回归。

按 `scripts/Measure-Comments.ps1 -SourceRoots @(...) -MinimumPercent 20` 运行，当前统计如下：

| 目录 | 完整注释行 | 非空源码行 | 比例 |
|---|---:|---:|---:|
| `common` | 69 | 290 | 23.79% |
| `discovery` | 80 | 374 | 21.39% |
| 全部 XTRH 主 Java | 429 | 1964 | 21.84% |
| 当前 PXHJ 新增 fusion 业务 | 370 | 1101 | 33.61% |

统计包含以注释标记开头的整行注释、Javadoc 及块注释边界，不包含空行或代码末尾的行内注释。XTRH 全部主 Java 和 PXHJ 新增 fusion 业务均达到约 20% 的要求；这些数字不包含两项目的测试文件和前端文件。

## 独立进程与自动发现

通过部署脚本启动以下四个真实 Java 进程：

| 实例 | 角色 | HTTP 端口 | 其他配置 |
|---|---|---:|---|
| coordinator | 总控 | 18200 | 隔离验证集群 |
| gateway | 采集网关 | 18210 | UDP 接收入口 19202 |
| worker-a | 节点 A | 18220 | 初始容量 2 路 |
| worker-b | 节点 B | 18221 | 初始容量 3 路 |

网关和两个节点配置中均没有 `fusion.coordinator-url`。通过 mDNS 自动发现总控，完成带签名的身份校验和自动注册；总控快照确认两个节点、一个网关在线。中文节点名称保存与上报正确。

在隔离验证集群中下发五路后台演示视频任务，节点 A 处理两路、节点 B 处理三路。通过实际 HTTP 播放连接读取到 MJPEG 帧。运行中将 B 容量修改为四路、A 修改为一路，总控自动迁移任务，最终保持五路可播放，无需重启 Java 进程。

上述初始验证使用明确标记的本机测试上下文；后续已由前述 PXHJ 真实业务串联补充正式权限、保存绑定和轮次关联的验证，业务数据仍限于隔离 H2。

## UDP 与轮次结束

在隔离网关中配置一条本机验证路由，目的端为临时 UDP 套接字，未向 PXHJ 正式采集入口发送测试报文。

- 实际网关进程转发 4096 字节随机二进制报文，目的端收到的字节完全一致。
- 目的端看到固定的独立转发源端口。
- 目的端回复的二进制字节返回原发送套接字，返回源端口为网关入口 19202。
- 将该测试轮次同步为 `SAVED` 后，五路媒体任务均结束；同一采集路由继续正常转发。

另外，`FusionRelayUdpIntegrationTest` 在隔离 PXHJ 应用中开启真实 UDP 套接字，使用正式 `WireCodec` 生成加密采集报文与加密心跳。未登记中转来源先被拒绝；登记映射后报文被接受、样本落入 H2，原采集器连接记录与密钥关联保持不变；未知来源和错误密钥被拒绝，加密心跳独立确认在线。该类第二项验证动态配置目的地址使用已登记的中转回程，原设备地址不被修改。此处验证的是实际协议实现和本机测试套接字，未使用真实硬件采集器。

## 新版本本机角色启动后的只读确认

新版本已部署到本机默认端口：总控 18100、网关 HTTP 18110 / UDP 19002、节点 A 18120 / 容量 2、节点 B 18121 / 容量 3。在主后端升级前，只读签名请求 `/control/snapshot` 的响应验证通过，两个节点和一个网关在线；网关与节点配置中均没有固定总控 URL。当时节点没有运行任务，网关路由状态为等待，尚未接管真实采集来源。主后端后续接通结果见下一节。

本次确认只读取状态，不下发任务、路由，不修改试验、采集器或服务进程。该默认端口集群与 `runtime/validation` 隔离验证集群使用不同私有凭证。

## 达梦主实例实际接通

用户明确允许立即重启后，仅重启 PXHJ 主后端并加载新版 JAR，前端进程保持运行。实际主后端 PID 为 38344，前端 PID 为 33616；后端 8088 的 `/api/auth/csrf` 与前端 5178 页面 HTTP 检查均返回 200，未登录 `/api/fusion/status` 返回 401。PXHJ UDP 19001 和图片 UDP 6020 恢复，网关 UDP 19002 继续运行。

只读查询实际达梦 `biz_fusion_cache`，检查时缓存年龄 1104 毫秒，内容包含两个在线节点和一个在线网关，证明主实例已实际签名同步总控状态。原有 `RUNNING` 轮次数仍为 1，没有自动结束或修改现有试验；原端点上传和采集接收路径未切换，也没有为正在运行的正式试验新增演示视频配置。

用户从 PXHJ 融合节点管理和试验组织中的节点/视频区域统一操作。主实例连接已经接通，隔离 H2 中的正式业务流程和演示视频串联已验证；真实硬件迁移、真实融合和多台物理电脑验收仍未完成。

## 主总控执行能力正式部署

本次仅重启总控 18100，新 PID 为 41276，保留原稳定身份、H2 状态和私有配置。PXHJ 后端 PID 38344、前端 PID 33616、网关及两个子节点均未再次重启。总控健康信息确认执行能力已开启。

实际签名快照复核通过：主节点 `nodeRole=COORDINATOR`，节点 ID 等于总控服务 ID，仅有一条主记录；主节点播放基础地址为 `http://192.168.8.237:18100`，在线、容量 2。A/B 保持 `WORKER`、容量 2/3。当前合计三个在线执行节点和一个在线网关，总容量 7，运行任务和等待任务均为 0。

只读达梦缓存检查时年龄 64 毫秒，在线执行节点数 3、在线网关数 1，证明 PXHJ 未重启也能同步新的主节点记录。原正式 `RUNNING` 轮次数仍为 1，未新增或变更正式试验视频任务，未调整 A/B 容量，未切换采集器上传或路由。本机主端口实际 JPEG 播放使用随机端口集成测试验证，生产总控当前没有新视频任务运行。

前述两节点和 1104 毫秒缓存记录属于加入主执行能力之前的阶段；当前运行状态以本节三个执行节点为准。

## 部署脚本

PowerShell 脚本语法解析通过。集群凭证生成、私有文件访问限制、已有实例重新安装、四个实例启动及健康身份校验、中文 properties 转义、按进程身份停止均已实际执行。

隔离验证目录 `runtime/validation` 中保留本机身份、数据库、日志与私有配置，便于复查；该目录被 `.gitignore` 排除。业务联调结束后，四个 182xx 验证实例已按身份停止；只读端口查询确认 18100、18110、18120、18121 继续监听，182xx 验证端口已释放。未验证注册登录自启任务的实际重登录行为。