📚 课程目录第4章 MERLIC项目文件与配置备份恢复

4. MERLIC项目文件与配置备份恢复

MERLIC 项目并不是一个单独的文件，而是一个以 .mvtc 项目文件为核心、由多个目录和资源共同构成的工程集合。理解这个结构，是做好备份与恢复的前提。很多现场故障并非算法本身出错，而是项目文件被误改、标定数据丢失、图像路径失效或配置版本不一致导致的。因此，本节从项目结构入手，逐步展开备份策略、恢复演练与版本管理。

一、MERLIC 项目的实际结构

在 MERLIC Creator 中保存项目时，默认会生成一个项目文件夹，典型结构如下：

MyProject/
├── MyProject.mvtc          # 项目主文件，记录流程、工具、参数与引用关系
├── config/
│   ├── camera_config.json  # 相机接口与采集参数
│   ├── comm_config.json    # 通信接口（PLC、TCP、串口等）配置
│   └── user_config.json    # 用户权限与界面配置
├── calibration/
│   ├── cam01_calib.json    # 相机标定参数
│   └── handeye_calib.json  # 手眼标定参数
├── images/
│   ├── reference/          # 参考图像、模板图像
│   └── samples/            # 测试样本图像
├── models/
│   └── *.dlm               # 深度学习模型文件（如使用）
└── logs/
    └── merlic_runtime.log  # 运行日志

其中 .mvtc 文件是项目的“索引”，它本身不包含图像和标定数据的全部内容，而是通过相对路径引用 images/、calibration/ 等目录。这意味着：如果只复制 .mvtc 文件而遗漏资源目录，恢复后的项目会出现图像缺失、标定无效、模型加载失败等问题。因此，备份的最小完整单元应是整个项目文件夹，而不是单个文件。

判断项目是否“自包含”：在另一台电脑上打开项目，若所有图像、标定、模型均能正常加载，说明资源路径为相对路径且目录完整；若出现红色缺失提示，则说明存在外部绝对路径引用。

二、配置文件与标定数据的备份要点

配置文件和标定数据是项目中最容易被忽视、却最难重建的部分。相机配置中的曝光、增益、触发模式，通信配置中的 IP、端口、寄存器映射，标定文件中的内参、畸变系数、手眼矩阵，这些参数一旦丢失，往往需要重新标定和联调，耗时可能超过数小时。

建议将备份内容分为三个层级：

核心层：.mvtc 主文件、calibration/ 全部标定文件、models/ 模型文件。这些是项目可运行的最小集合。
配置层：config/ 下的相机、通信、用户配置。这些决定了项目能否与现场硬件正确对接。
资源层：images/ 下的参考图像与样本图像。这些影响模板匹配、深度学习推理的基准。

对于标定数据，尤其要注意版本对应关系。例如相机镜头更换、相机安装位置调整、机器人末端工具变更后，原标定文件即失效。备份时应记录标定日期、镜头型号、工作距离等元信息，避免恢复时误用旧标定。

三、备份策略：从手动复制到版本化归档

现场常见的备份方式有三种，适用场景不同：

方式	操作	优点	风险
手动复制	将项目文件夹复制到U盘或网络盘	简单直接	易遗漏、无版本记录
脚本定时备份	用批处理或脚本按日期打包	可自动化、保留多版本	需维护脚本与存储空间
版本管理工具	Git/SVN 管理文本配置与项目文件	可追溯、可回滚、可对比	图像与模型文件较大，需配置忽略规则

推荐采用“脚本定时备份 + 关键节点版本归档”的组合策略。日常每天定时打包一次，命名格式建议为 项目名_YYYYMMDD_HHMM.zip；在以下关键节点额外做一次带说明的归档：相机或镜头更换后、标定完成后、通信联调通过后、正式投产前。归档说明应记录变更内容，例如“更换镜头为16mm，重新标定，通信寄存器地址调整”。

不要将备份文件存放在与项目相同的磁盘分区。若磁盘故障，项目与备份会同时丢失。至少保留一份异地或网络存储副本。

四、恢复演练：验证备份是否真正可用

备份的价值只有在恢复成功时才能确认。建议每季度至少进行一次恢复演练，流程如下：

准备一台与现场环境相近的电脑，安装相同版本的 MERLIC Runtime 与 Creator。
将备份压缩包解压到不含中文和空格的路径，例如 D:\MERLIC_Restore\。
用 MERLIC Creator 打开 .mvtc 文件，观察是否提示资源缺失。
逐项检查：相机能否连接、通信能否建立、标定是否加载、参考图像是否显示、模型是否可推理。
运行一次完整流程，用同一张测试图像对比恢复前后的输出结果（如测量值、分类标签、OK/NG判断）。
记录恢复耗时、遇到的问题及解决方式，更新备份清单。

恢复演练中常见的失败原因包括：MERLIC 版本不一致导致项目无法打开、相机 IP 与现场不同导致连接失败、标定文件路径为绝对路径导致加载失败、模型文件缺失或版本不匹配。针对这些情况，应在备份说明中明确记录软件版本、相机 IP、标定文件相对路径等关键信息。

五、版本管理：让每一次变更可追溯

MERLIC 项目在调试阶段会频繁修改参数、更换图像、调整流程。如果没有版本记录，一旦新版本效果变差，很难回到之前的状态。建议采用轻量级版本管理：

每次修改前，先复制一份当前项目文件夹，命名为 项目名_v序号_日期，例如 BottleInspect_v03_20250612。
在项目根目录维护一个 CHANGELOG.txt，记录版本号、日期、修改人、修改内容和验证结果。
对于文本类配置文件（JSON、XML），可使用 Git 进行差异对比，快速定位参数变化。
图像和模型文件体积较大，不建议全部纳入 Git，可单独存放在版本化目录中，用版本号关联。

一个可参考的变更记录格式如下：

版本：v03
日期：2025-06-12
修改人：张工
修改内容：
  - 相机曝光由 8000us 调整为 5000us
  - 模板匹配角度范围由 ±15° 调整为 ±10°
  - 更换参考图像 ref_20250612.png
验证结果：
  - 30 张测试样本全部正确分类
  - 单帧处理时间由 42ms 降至 35ms
备注：现场光照条件变化，需持续观察

版本管理的核心不是工具本身，而是纪律。只要坚持“改前备份、改后记录、关键节点归档”，就能在出现问题时快速定位和回退。对于产线设备，建议将当前稳定版本标记为“生产版本”，任何新修改先在测试环境验证，确认无误后再替换生产版本。

六、常见问题与处理建议

在实际维护中，以下几类问题出现频率较高：

恢复后图像缺失：检查 .mvtc 中图像路径是否为绝对路径。若是，需改为相对路径或重新指定图像目录。
标定数据不生效：确认标定文件与当前相机、镜头、工作距离匹配，检查 calibration/ 目录是否完整复制。
通信无法建立：对比 comm_config.json 中的 IP、端口、协议与现场设备是否一致，注意恢复后可能覆盖了现场已调整的参数。
项目打开报版本错误：MERLIC 高版本项目通常无法在低版本中打开。恢复前确认目标电脑的 MERLIC 版本不低于备份时的版本。

建议将“项目文件夹完整备份 + 关键配置单独导出 + 版本变更记录”作为 MERLIC 项目维护的三项基本动作，并在每次恢复演练后更新备份清单和联系人信息。

综上，MERLIC 项目的备份与恢复不是简单的文件复制，而是围绕项目结构、配置数据、标定资源、版本记录形成的一套可执行、可验证的维护流程。只有把备份做成习惯、把恢复做成演练、把版本做成记录，才能在设备故障或误操作时快速恢复生产，减少停机损失。