📚 课程目录第4章仿真资产版本管理

4. 仿真资产版本管理

仿真项目的可复现性，本质上取决于六类资产能否被精确追溯：几何模型、网格、材料库、求解器配置、脚本与结果。它们的变化频率、文件体积、二进制兼容性和依赖关系差异极大，因此不能用同一套版本策略“一刀切”。本节先建立资产分层模型，再给出可落地的版本化策略与工具选型。

一、六类资产的版本化特征

几何模型（STEP、Parasolid、CATIA 等）通常是二进制或半结构化格式，单文件几十到几百 MB，差异以“特征级”为主，文本 diff 几乎不可读；网格文件（.msh、.cgns、.bdf）体积更大，且与几何、网格划分脚本强绑定；材料库多为 XML、CSV 或 JSON，属于小体积、高变更频率的文本资产，适合精细 diff；求解器配置（如 Fluent journal、OpenFOAM 的 system 字典、Abaqus inp）是纯文本，是版本管理的重点；脚本（Python、Tcl、Bash）天然适合 Git；结果文件（.cas.h5、.dat、场数据）体积可达 GB 级，且可由上游资产完全重算，原则上不纳入常规版本库，而应通过“结果指纹”关联到输入版本。

核心判断：一个资产是否需要版本化，取决于它是否“不可由其他已版本化资产确定性重算”。几何、网格、材料、配置、脚本属于“源资产”，必须版本化；结果是“派生产物”，用元数据关联即可。

二、分层版本策略

建议采用三层结构：源资产层（几何、网格、材料、配置、脚本）用 Git 管理文本与脚本，用 Git LFS 管理大二进制；构建层用 CI 流水线把源资产组合成一次“仿真构建”，生成唯一构建号；结果层把结果文件存入对象存储（S3/MinIO），并在数据库中记录构建号、输入哈希、求解器版本与硬件信息。

以 OpenFOAM 算例为例，典型目录结构如下：

case/
├── 0/                 # 初始场
├── constant/
│   ├── polyMesh/      # 网格（LFS）
│   ├── transportProperties
│   └── turbulenceProperties
├── system/
│   ├── controlDict
│   ├── fvSchemes
│   └── fvSolution
├── geometry/          # STEP/STL（LFS）
├── scripts/           # 网格与后处理脚本
└── materials/         # 材料库 YAML

其中 0/、system/、scripts/、materials/ 走普通 Git；polyMesh/ 与 geometry/ 走 Git LFS。每次提交通过 .gitattributes 明确 LFS 规则，避免大文件污染历史。

三、版本号与依赖锁定

推荐使用“语义化版本 + 构建号”双轨制：源资产用 v1.4.2 标记里程碑，CI 每次运行生成 build-20240612-0037 形式的构建号。构建号必须锁定所有上游依赖的精确版本，例如：

geometry: geom-v2.1.0 (sha256: 9f3a...)
mesh:     mesh-v1.7.3 (sha256: c21b...)
materials: mat-v0.9.1 (sha256: 77de...)
solver:   openfoam-2312
script:   git commit a4f9c2e

这样，任何一次结果都可以反查到唯一的输入组合。若几何更新但网格未重划，构建号会变化，但网格哈希不变，可快速判断“结果差异是否来自几何”。

四、工具选型对比

工具	适用资产	优势	局限
Git + LFS	脚本、配置、材料、中小几何/网格	分支灵活、生态成熟、CI 集成好	大文件并发差，LFS 配额成本
Perforce Helix	大型二进制几何、网格	文件锁、大文件性能强	部署重、学习成本高
DVC	数据与结果追踪	与 Git 解耦、支持远程存储	需额外维护缓存
对象存储 + 数据库	结果文件、场数据	成本低、可扩展	需自建元数据索引

对多数中小团队，Git + LFS + 对象存储 是性价比最高的组合；几何/网格超过 1 GB 且多人并行编辑时，再考虑 Perforce。

五、CI 中的版本校验

在 CI 流水线中加入“资产一致性检查”步骤：拉取代码后，先校验 LFS 文件哈希是否与 manifest.yaml 一致，再检查材料库版本是否被求解器配置引用，最后才启动求解。若校验失败，直接终止并输出差异报告，避免用错误资产跑出无效结果。

实践建议：把 manifest.yaml 作为构建的“单一事实来源”，所有资产版本、哈希、求解器版本都写在这里，CI 与本地脚本共用同一份清单，减少人为不一致。

六、结果关联与复现验证

结果文件不进入 Git，但必须与构建号绑定。推荐在结果目录写入 build_info.json，包含构建号、各资产哈希、求解器版本、CPU/GPU 型号、并行核数与运行时间。复现时，CI 根据构建号拉取对应源资产，重新运行，比较关键监测量（如阻力系数、最高温度）是否在容差内。若偏差超过阈值，则说明存在未记录的隐式依赖（如环境变量、库版本），需要补充到 manifest 中。

版本管理不是“把文件放进 Git”这么简单，而是建立“源资产可追溯、构建可锁定、结果可反查”的闭环。选型时优先考虑团队规模与资产体积，策略上坚持“文本精细管、二进制用 LFS、结果走对象存储”的分层原则，才能让仿真工作流真正具备工程级可复现性。