# 开发历程与版本沿革

> 依据 opencode 会话记录（12 个会话、3124 条消息、2026-08-11 → 2026-10-22）、
> 原始工作目录 `/root/hd-ws`（rtsp / rtsp588 / rtsp568）以及 deploy 目录下的
> 18 个部署包整理。

## 1. 项目背景与目录沿革

| 目录 | 说明 | 时间 |
|---|---|---|
| `/root/hd-ws/rtsp` | 最早版本（RK3588 平台原版拷贝） | 2026-08 前 |
| `/root/hd-ws/rtsp588` | 中间快照（RK3588 平台） | 2026-08 前 |
| `/root/hd-ws/rtsp568` | **转 RK3568 后的正式版本**（8-11 定为正式版） | 2026-08-11 |
| `/root/layoutx` | 2026-09-04 迁移并修复后的现行开发目录 | 2026-09-04 起 |

项目：**多路 RTSP 视频流多画面合成显示系统**，运行于 Orange Pi / Rockchip SoC
（RK3568），配合西门子 PLC 点位信号自动切换布局（车间随动监控）。

## 2. 开发时间线

### 阶段一 2026-08-11 ~ 08-14（hd-ws/rtsp568）：RK3588 转 RK3568 与功能重构
- RK3588 → RK3568 平台迁移：编译、依赖、字体缺失检查与修复
- 移除推理（YOLO/检测器）相关无用功能与资源占用
- 单通道 layout 自动使用主码流逻辑（原配置全为子码流）
- 摄像头离线处理：不再卡死最后一帧 + 自动重连
- PLC 离线右下角红字告警（出现"画面闪"问题后暂撤）
- run_local 本地测试安装脚本；进程残余/CPU/闪/tearing 排查与修复
- 布局系统大改造：多行自适应布局（第一行 N 个、第二行 M 个、按比例占高）、
  大/小画面组合（layout0-4：1~3 个大画面 + 其余小画面）、字符占位配置、
  总高度撑满、宽高比不变形
- 网格线叠加
- 海康 ISAPI 批量配置摄像头主/子码流（channels_isapi.conf）
- 画面撕裂（tearing）修复

### 阶段二 2026-08-25：管线优化调研（只读分析）
- 视频管线核心模块（decoder/composer/display）与应用层审计，输出优化点清单

### 阶段三 2026-09-04 ~ 09-05（layoutx 新目录）：部署化准备
- 目录迁移 `/root/hd-ws/rtsp568` → `/root/layoutx`，build.sh 修复、花屏修复
- plc_server.sh 改为前台运行，Ctrl+C 可完全退出全部服务
- 新增 `deploy/` 与 `pack.sh` 一键生成部署包（首次打包 20260904）
- PLC DB 块地址解析与 plc_sim 同步修正
- 自动重启设备功能（日/周周期 + 重启时间，channels.conf 可配）
- 一键部署到新主机脚本（默认 192.168.1.243 / root / 123456）+ README 更新

### 阶段四 2026-09-05 ~ 10-13：部署实战与网页配置
- 离线依赖问题暴露（现场板子不便联网），依赖安装方案调整
- 部署后标题 logo 缺失修复、PLC 未监听 0.0.0.0 修复
- 上下分割布局落地：第一行 30%（5 路小画面）/第二行 70%（1~3 路，随 PLC 切换，
  按宽高比居中放置）
- PLC 规则语义重写（最具体者胜）：点位组的"任一触发/全部触发"规则、
  无匹配时回退默认布局、恢复后回到默认
- web 配置页面（端口 8080，密码 3730）：PLC 地址、摄像头地址、layout、
  tsap 参数可视化修改；中文页面；保存格式（等号空格/多余键）修复
- 断线重连机制完善（摄像头掉线/PLC 离线再上线）
- 现场根目录写满事件（kern.log/syslog 各 12G）：日志清理与治理结论
- 现场闪屏根治：RGA "MMU unsupported memory larger than 4G" → 输出缓冲改用
  `system-uncached-dma32` 优先分配（其次 cma，再普通内存）
- 无显示器开机只显示桌面修复：display_init 参与等待显示器重试，
  HDMI 分配器/录像机切换场景排查，`display: AtomicCommit EINVAL` 修复
- `--hdmi` 参数调研后取消，start.sh 还原，不改现场 service
- 紫色画面问题：HDMI RGB 输出 `color_format` 代码硬编码 `display_set_color_format(1)`

### 阶段五 2026-10-13 ~ 10-22：生产板部署与稳定性
- **部署到生产板 216**：标题栏字体问题修复、TSAP（西门子 1200）、
  PLC 连接状态角标（右上角绿/红）、网页可配 tsap
- **216 / 217 双板部署**：完全离线安装（install.sh 依赖自检 ldd+gst-inspect）
- **布局防抖**：`plc_debounce_ms`（默认 300ms，连续稳定才切换），
  修复"点位瞬间触发闪切"；网页可配防抖参数
- **网页添加多网段 IP 改走 NetworkManager**（nmcli con mod + reapply，
  持久化到 /etc/NetworkManager/system-connections/），
  替换 ifupdown 旧路径（/etc/network/interfaces）
- **systemctl stop 卡 90 秒修复**：display_init 等显示器循环增加 `g_running`
  检查，SIGTERM 及时退出（实测 90s → 363ms）
- **安装包内置静态 IP 步骤**：给 eth0 追加 `192.168.100.245/24`（保留 DHCP）
- **画面左下角 IP 角标**：显示 eth0 全部 IPv4（每秒刷新），
  忘记 IP 时直接从画面读出
- **拔插显示器死机修复（核心修复）**：根因=启动时按当时显示器模式分配的
  NV12 缓冲区（如 1280x720）在拔插后显示器改为首选模式（1920x1080），
  `drmModeAddFB2(NV12)` 用模式尺寸+缓冲区 stride → EINVAL 死循环；
  修复：重建时优先选与缓冲区匹配的模式 + plane SRC/CRTC 几何分离（支持缩放）
- 换新显示器仍需重新上电才出原生分辨率（缓冲区只建一次，用户决定保持现状）

## 3. 部署包（平台版本）沿革

deploy/ 下共 18 个 tar.gz（20260904 → 20261020），关键版本：

| 部署包时间戳 | 二进制 md5 | 主要变化 |
|---|---|---|
| 20260904_092418 / 093406 | - | 首批打包（部署化试行） |
| 20260905_003525 / 20260909_045758 | - | 部署脚本调整 |
| 20261013_080759 / 084753 | - | ⚠️ 已弃用（紫色画面修复前） |
| 20261013_085429 ~ 092459 | - | color_format 硬编码、生产板初部署 |
| 20261014_022843 | 69ad… | ⚠️ 已弃用 |
| 20261014_025142 | ce428058 | 布局防抖 |
| 20261014_030341 | 7b8460d6 | + 网页防抖参数 |
| 20261014_032433 | 0d8e313f | + 网页加 IP 走 NetworkManager |
| 20261014_034552 | 5785af80 | + systemctl stop 秒退修复 |
| 20261014_062749 | d2b642cc | + 画面 IP 角标（217 现仍是此版） |
| **20261020_010600** | **63252ff9** | **+ 拔插显示器分辨率自适应（当前最新）** |

## 4. 当前版本状态（2026-10-22）

- 开发机（232）编译产物：`63252ff9afca147bd89edd1c3907280d`
- 生产板 216：`63252ff9…`（最新，含拔插修复）
- 生产板 217：`d2b642cc…`（缺拔插修复，离线待更新）
- 现场约定：换不同分辨率显示器后**重新上电**即可出原生分辨率

## 5. git 版本管理

- 仓库位置：`/root/layoutx`（自 2026-10-22 起）
- 忽略项（.gitignore）：build/、build_asan/、deploy/*.tar.gz、models/（143M 权重文件，
  教程见 convert_yolov8_rknn.py；推理已移除）、plc_sim/capture_fb 二进制、运行日志
- ⚠️ channels.conf* 内含摄像头验证账号（URL 中）与网页密码，仓库仅限内网/离线保存
- 原始历史（/root/hd-ws 三个目录）保持原样不纳入 git，如需可作为分支导入