3. 发布记录定义：数据结构、元数据字段、版本标识、时间戳与审批链

发布记录（Release Record）是 GitOps 声明式模型在跨环境迁移过程中，用于追踪、审计和验证每一次配置变更的核心数据载体。它不仅是运维操作的日志，更是环境状态对账的“事实来源”。一个设计良好的发布记录，必须包含完整的数据结构、精确的元数据字段、唯一的版本标识、可信的时间戳以及可追溯的审批链。

3.1 发布记录的核心数据结构

发布记录采用分层结构，从上到下依次为：记录头、变更清单、环境快照、审批链、对账结果。每一层承载不同的职责，共同构成完整的发布凭证。

3.2 元数据字段定义

元数据字段是发布记录的“身份证”，用于快速检索、过滤和关联。以下为必选与可选字段的详细定义：

• record_id（必选）：全局唯一标识，推荐使用 UUID v7 或 Snowflake ID，保证时间有序性。
• release_version（必选）：语义化版本号，格式为 v<major>.<minor>.<patch>+<build_metadata>，例如 v2.1.0+20250315。
• source_commit（必选）：触发本次发布的 Git 提交 SHA，精确到 40 位完整哈希。
• target_environment（必选）：目标环境名称，如 staging、production-us-east。
• operator（必选）：执行发布操作的主体，可以是人工账号或自动化服务账号。
• manifest_ref（可选）：声明式清单的 Git 引用路径，如 refs/heads/release/2.1.0。
• rollback_target（可选）：若本次为回滚操作，记录回滚目标版本号。
• tags（可选）：键值对标签，用于自定义分类，如 team:platform、risk:high。

3.3 版本标识策略

版本标识是发布记录对账的关键索引。在跨环境迁移场景中，版本标识必须满足全局唯一、单调递增、可排序三个条件。推荐采用以下策略：

1. 语义化版本 + 构建元数据：v2.1.0+20250315.120000.abcd1234，其中构建元数据包含时间戳与短 SHA，确保唯一性。
2. 基于 Git 标签的版本：每次发布在 Git 仓库中创建对应的 annotated tag，标签名即版本号，如 release-v2.1.0。
3. 单调递增序列号：在发布系统中维护一个全局自增序列，适用于无法使用语义化版本的项目。

3.4 时间戳规范

时间戳是发布记录对账的时间锚点。所有时间戳必须遵循以下规范：

所有时间戳必须使用 UTC 时区，并在字段名中明确标注时区信息，例如 created_at_utc。避免使用本地时间或未标注时区的格式。

3.5 审批链设计

审批链是发布记录中用于记录人工或自动审批过程的结构化数据。在跨环境迁移场景中，审批链必须支持多级审批、并行审批和自动审批三种模式。

审批链的每个节点包含以下字段：

• step：审批步骤序号，从 1 开始递增。
• approver：审批人标识，可以是用户 ID、服务账号或自动化策略名称。
• role：审批角色，如 tech-lead、security-officer、change-manager。
• decision：审批决策，枚举值：approved、rejected、pending、skipped。
• comment：审批意见，可选字段，用于记录审批理由或附加说明。
• signed_at：审批时间戳，格式同 ISO 8601。
• signature：数字签名或 HMAC，用于验证审批记录的完整性，防止篡改。

3.6 发布记录数据结构总览

以下 SVG 图展示了发布记录的完整数据结构，包括记录头、变更清单、环境快照、审批链和对账结果五个层级，以及它们之间的关联关系。

3.7 审批链流转示例

以下 SVG 图展示了一个典型的跨环境迁移审批链流转过程，从开发环境到生产环境，经过三级审批节点。

3.8 发布记录对账的关键字段映射

在跨环境迁移对账过程中，发布记录的以下字段直接参与对账逻辑：