📚 课程目录第3章交付物清单与版本基线

3. 交付物清单与版本基线

GitLab平台验收与交付的核心难点，不在于“装好了没有”，而在于“交付了什么、交付的是哪个版本、后续如何证明它没有被悄悄改过”。一个可验收的GitLab平台，必须把散落在代码仓库、服务器、对象存储、镜像仓库和运维人员电脑里的东西，收敛成一份可核对、可追溯、可复现的交付物清单，并在此基础上建立版本基线与变更记录。

一、交付物的六个类别

结合GitLab平台的部署形态（Omnibus、Helm Chart、Docker Compose或源码编译），交付物通常可以归为六类。分类的目的不是做文档归档，而是让每一类都有明确的“版本标识方式”和“校验方式”。

代码类：GitLab CE/EE 源码或二次开发代码、自研的 CI Runner 插件、Webhook 处理服务、备份脚本源码。版本标识用 Git commit SHA + tag，例如 v16.11.3-custom.2。
配置类：gitlab.rb、gitlab-secrets.json、Helm 的 values.yaml、Nginx/负载均衡配置、LDAP/SAML 对接参数、对象存储与数据库连接串。配置必须脱敏后入库，敏感值用 Vault 或 SealedSecret 管理。
文档类：部署手册、升级手册、备份恢复演练记录、网络端口清单、验收测试报告、运维交接说明。
镜像类：GitLab 主镜像、Runner 镜像、辅助组件镜像。必须记录镜像仓库地址、tag 和 sha256 摘要，不能只写 latest。
脚本类：安装脚本、健康检查脚本、备份与恢复脚本、数据迁移脚本、证书轮换脚本。
许可证类：GitLab EE 许可证文件、第三方组件许可证清单（SBOM）、开源合规声明。

二、版本基线的定义与建立

版本基线（Baseline）是“经过评审、被正式确认、后续变更必须走审批”的一组交付物快照。它不是把所有文件打包一次，而是给每一类交付物指定一个不可变的标识，并记录它们之间的对应关系。

建立基线时，建议采用“基线编号 + 交付物清单 + 校验值”的三段式结构。基线编号建议包含日期和序号，例如 GL-BL-20250612-01。清单中每一项都要有版本标识和校验值，示例如下：

基线编号: GL-BL-20250612-01
基线日期: 2025-06-12
适用环境: 生产 / 华东1区

交付物清单:
1. GitLab 主镜像
   registry.example.com/gitlab/gitlab-ce:16.11.3-ce.0
   sha256: 9f2c...a71d
2. Helm Chart
   gitlab/gitlab:7.11.3
   values.yaml 版本: git@gitlab.example.com:ops/gitlab-values.git
   commit: 4b8e1c2
3. 配置文件
   gitlab.rb 版本: commit 4b8e1c2
   gitlab-secrets.json: Vault 路径 secret/gitlab/prod
4. 备份脚本
   backup-gitlab.sh 版本: v1.4.0
   sha256: 3d7a...c902
5. 许可证
   GitLab EE License: 有效期至 2026-06-30
6. 文档
   部署手册 v2.1 / 验收报告 v1.0

基线一旦确认，任何交付物的变更都必须产生新的基线编号，而不是在原基线上直接修改。这样做的价值在于：当验收方问“三个月前上线的是哪个版本”时，可以精确回答，而不是靠回忆。

三、变更记录的最小字段

变更记录不是流水账，而是“谁在什么时候、因为什么、把哪个交付物从哪个版本改到了哪个版本、影响范围是什么、谁批准的”。最小字段建议包括：变更编号、变更日期、变更人、审批人、交付物类别、变更前版本、变更后版本、变更原因、影响范围、回滚方式、验证结果。

其中“影响范围”和“回滚方式”最容易被忽略，却最关键。例如把 gitlab.rb 中的 external_url 从 HTTP 改为 HTTPS，影响范围包括：所有 Runner 的注册地址、Webhook 回调地址、OAuth 回调地址、监控探针地址；回滚方式则是恢复上一版 gitlab.rb 并执行 gitlab-ctl reconfigure。这些信息如果不记录，故障时只能靠现场推断。

四、交付物与基线的对应关系

下面这张图把六类交付物、版本标识方式、基线快照和变更记录之间的关系画在一起。它想表达的核心是：交付物不是孤立文件，而是通过版本标识汇聚到基线，再通过变更记录形成可追溯链条。

五、落地时的三个关键动作

第一，把交付物清单做成可执行的校验脚本，而不是只写在文档里。例如对镜像类交付物，用 docker inspect --format='{{index .RepoDigests 0}}' 提取摘要，与基线清单中的 sha256 比对；对配置文件，用 sha256sum gitlab.rb 生成校验值。验收时逐项比对，比人工翻文档可靠得多。

第二，把基线清单纳入 Git 管理。基线文件本身也是一个交付物，它的变更同样需要记录。建议在 GitLab 中建立 delivery-baseline 仓库，每个基线一个 tag，例如 GL-BL-20250612-01，这样基线之间可以 diff，能直接看出两次交付之间到底改了什么。

第三，变更记录与 GitLab Issue/Merge Request 联动。每次变更开一个 Issue，变更完成后关闭并关联到对应基线 tag。这样验收方在 GitLab 界面上就能看到完整的变更历史，而不需要额外维护一份 Excel。

实操建议：基线清单中的每一项都应能回答三个问题——“它是什么版本”“怎么校验它没被改过”“如果它坏了怎么回滚”。如果某一项回答不了，说明它还不具备进入基线的条件。

常见误区：把 latest 标签的镜像写入基线，或者把 gitlab-secrets.json 明文提交到仓库。前者导致无法复现，后者导致密钥泄露。正确做法是镜像必须写 digest，密钥必须走 Vault 或 SealedSecret，基线清单中只记录引用路径。

交付物清单与版本基线的最终价值，是让“交付”从一次性的动作变成可审计、可复现、可回滚的工程过程。当验收方拿着基线编号就能定位到每一个镜像、每一份配置、每一个脚本的确切版本，并且能看到它们之后发生的每一次变更时，GitLab平台的交付才算真正完成。