制品版本标识要回答四个问题：这是什么制品、来自哪次构建、对应哪份源码、当前处于什么状态。本文给出一套可执行的落地路径：先界定标识对象，再设计“可读名称+不可变元数据”的双层结构，然后把生成与校验写进构建、发布、归档环节，最后用抽样追溯和重复检测确认规则真的被执行。文中示例为演示情景，ONES 相关内容仅作流程承载方式的说明。
要点总览（TL;DR）
- 制品版本标识要同时回答四件事：是什么制品、哪次构建、来自哪份源码、当前处于什么状态；标识对象是可交付资产本体，配置基线与制品仓库底层实现不在本文范围。
- 采用“可读名称+不可变元数据”双层结构：名称层由产品标识、语义化版本、构建号、目标平台组成，负责排序与比较；元数据层承载构建号、源码提交、构建时间、构建环境、校验和与状态，负责唯一性与追溯。
- 落地按四步推进：梳理制品类型确定字段、制定命名与版本递增规则、在流水线中自动生成并写入元数据、在发布与归档环节校验完整性与唯一性，每步都有输入、输出与完成标志。
- 标识机制需要角色分工支撑：构建与发布工程师负责生成与校验，研发负责人或配置管理员审批规则与例外，测试与交付角色按标识取件核对，交接时凭标识独立核对。
- 用抽样追溯、重复与冲突检测、自动化覆盖、例外记录和状态一致性五项检查判断规则是否真正执行，发现问题回到对应环节修正。
制品版本标识要解决什么问题
制品版本标识的对象是可交付资产本体，包括构建产物（如 jar、war、二进制包）、发布包、容器镜像、安装介质，以及随版本交付的说明文档、配置样例和交付清单。标识的作用是让任何一个人拿到一个制品，都能在不询问原作者的情况下判断它的来源和状态。
具体来说，标识要回答四件事：
- 是什么：制品类型、所属产品线或项目、面向的交付对象。
- 哪次构建：由哪条流水线、哪次构建任务产生，构建序号是多少。
- 来自哪份源码：对应的源码提交标识，以及所在分支或标签。
- 当前处于什么状态：开发自测、测试通过、已发布、已归档、已废弃。
需要划清两条边界。其一，配置基线管理的是需求、设计、源码等配置项在某一时刻的稳定组合，制品标识只描述单个可交付资产，二者可以关联但管理对象不同。其二，制品仓库的存储分片、校验和计算、去重策略属于仓库底层实现，本文只规定标识规则和写入校验动作，不讨论仓库如何存储。
落地前建议先产出一份标识对象清单：列出团队实际交付的制品类型，标注每类的产生环节、存放位置和使用方。这份清单是后续字段设计的基础，也决定了哪些制品必须纳入强制标识范围。
核心规则：可读名称加不可变元数据的双层结构
只靠文件名承载版本信息，会在制品流转中迅速失效：文件被重命名、被复制到聊天工具、被加上“最终版”后缀，来源信息就丢了。可行的做法是把标识拆成两层，名称层负责人读和排序，元数据层负责唯一性和追溯。
名称层：人可读、可排序、可比较
名称层通常由产品标识、语义化版本、构建号、目标环境或交付渠道组成，用固定分隔符连接。语义化版本表达对外可见的功能与兼容性变化，构建号表达同一版本下的第几次产出。两者分工明确：语义化版本由发布决策确定，构建号由流水线自动递增，不能互相替代。
名称层要满足三个条件：同一产品线的名称可按字典序或版本序正确排列；从名称能直接看出是否预发布；分隔符和大小写规则全团队统一，避免出现下划线、空格、大小写混用导致的“看起来不同、实际相同”。
元数据层：不可变字段承载追溯
元数据层是标识的真正唯一性来源，随制品一起写入并保持不可变。常用字段如下：
| 字段 | 说明 | 是否必填 | 示例 |
|---|---|---|---|
| 制品名称 | 名称层完整字符串 | 必填 | order-service-2.4.0-b118 |
| 制品类型 | 构建产物、镜像、发布包、文档 | 必填 | 容器镜像 |
| 构建号 | 流水线自动递增序号 | 必填 | 118 |
| 源码提交标识 | 提交哈希或标签 | 必填 | a3f9c21 |
| 源码分支 | 产生该制品的分支 | 必填 | release/2.4 |
| 构建时间 | ISO 8601 格式，统一时区 | 必填 | 2025-03-11T09:42:00+08:00 |
| 构建环境 | 流水线标识与执行节点 | 必填 | ci-prod-03 |
| 制品校验和 | 内容摘要，用于防篡改与去重 | 必填 | sha256:… |
| 状态 | 当前所处生命周期阶段 | 必填 | 测试通过 |
| 关联工作项 | 需求或缺陷编号 | 建议 | REQ-2041 |
唯一性由“制品类型+名称+校验和”共同保证：名称相同但校验和不同，说明内容被重新构建或篡改，必须作为新制品处理；校验和相同但名称不同，说明存在重复产出，需要合并或标记。不可变性要求元数据一旦写入，只允许追加状态变更记录，不允许修改构建号、源码提交等来源字段。
操作步骤：从规则制定到写入校验
规则落地分四步，每步都应有明确的输入、动作、输出和完成标志，避免规则停留在文档里。
步骤一：梳理制品类型并确定标识字段
输入是团队现有的交付物清单和发布记录。动作是按制品类型逐类确认必填字段，区分“所有制品通用字段”和“某类制品特有字段”，例如镜像需要镜像摘要，发布包需要包含文件清单。输出是一份字段对照表。完成标志是每类制品都有对应字段集合，且没有字段存在两种解释。
步骤二：制定命名规则与版本递增规则
输入是字段对照表和现有版本习惯。动作是确定名称串的段位顺序、分隔符、大小写规则，以及语义化版本在什么情况下升主版本、次版本、修订号，构建号如何递增、何时重置。输出是命名规则文档和版本递增判定表。完成标志是团队能对三个历史制品独立套用规则并得到一致结果。
步骤三：在构建流水线中自动生成并写入元数据
输入是命名规则和流水线配置。动作是把名称生成、构建号递增、源码提交读取、校验和计算、元数据写入做成流水线固定步骤，禁止人工填写版本字段。输出是每次构建自动产生的完整标识。完成标志是连续若干次构建产出的制品，其元数据字段无缺失、无手工修改痕迹。
步骤四：在发布与归档环节校验标识完整性与唯一性
输入是待发布或待归档的制品。动作是校验必填字段是否齐全、名称是否符合规则、校验和是否与仓库记录一致、是否与已有制品重复，校验通过后才允许进入发布或归档。输出是校验记录和放行结论。完成标志是发布清单中每个制品都能通过自动校验，例外情况均有审批记录。
在构建与发布环节，标识还需要和需求、缺陷、测试结果建立关联，否则追溯只能到构建记录为止。ONES 的方案覆盖需求、基线、版本、变更、测试与发布，可围绕需求、基线、版本和变更建立统一管理对象，支撑过程状态追踪和交付结果回溯；测试用例、缺陷、版本和发布过程也能关联到需求链路中，便于在出现问题时定位影响范围。团队可以把制品标识中的关联工作项字段与这些记录对应起来，形成从制品到需求链路的查询路径。制品本体字段与唯一性机制的具体实现方式，建议在选型时向厂商确认。
角色分工与各环节交付物
标识机制失效最常见的原因不是规则不好，而是没有人对生成和校验负责。建议按下表明确职责与交接物。
| 角色 | 主要职责 | 交付物 | 交接点 |
|---|---|---|---|
| 构建与发布工程师 | 在流水线中实现名称生成、元数据写入与自动校验 | 流水线配置、标识生成脚本、校验报告 | 向测试与交付角色交付通过校验的制品及标识 |
| 研发负责人或配置管理员 | 审批命名规则与版本递增规则，处理例外与回退 | 规则文档、例外审批记录、规则变更说明 | 规则变更后通知构建与测试角色同步调整 |
| 测试角色 | 按标识取件测试，核对标识与测试对象一致 | 测试记录中的制品标识、问题单中的标识引用 | 测试通过后向发布环节移交带标识的测试结论 |
| 交付角色 | 按标识核对交付清单，确认归档完整 | 交付清单、归档记录、追溯查询结果 | 交付完成后将标识与交付记录一并归档 |
交接点的关键是“带标识交接”：任何一次制品转手，接收方都应能凭标识独立核对，而不是依赖转手人的口头说明。例外处理要有固定入口，例如紧急修复需要复用版本号时，必须由配置管理员审批并记录原因、影响范围和后续修正计划。
示例：一个发布包的完整标识
以下为演示情景，非真实项目数据。假设订单服务发布 2.4.0 版本，第 118 次构建产出一个发布包，名称串为：
order-service-2.4.0-b118-linux-x64.tar.gz
逐段解释：order-service 是产品标识；2.4.0 是语义化版本，表示本次发布包含新功能且保持向后兼容；b118 是构建号，说明这是该版本下的第 118 次构建；linux-x64 是目标平台；tar.gz 是打包格式。名称层能让人快速判断适用对象，但不能单独证明来源。
对应的元数据记录示例：构建号为 118，源码提交标识为 a3f9c21，源码分支为 release/2.4，构建时间为 2025-03-11T09:42:00+08:00，构建环境为 ci-prod-03，校验和为 sha256 摘要，状态为测试通过，关联工作项为 REQ-2041 与 BUG-3187。
反查路径是：从名称或校验和查到元数据记录，由源码提交标识定位到代码仓库的具体提交，由构建号定位到流水线构建日志，由关联工作项回到需求与缺陷记录，由状态字段确认该制品是否允许交付。这条路径上的每一环都应能在系统中独立打开，而不是靠人工记忆串联。
常见错误有四类：手工改名导致名称与元数据不一致；复用旧版本号发布新内容，造成同名不同物；元数据缺失构建号或源码提交，追溯在第一步就断掉；把“最终版”“最新版”写进名称，使排序和比较失效。这四类问题都可以通过下一节的检查项发现。
完成检查：规则是否真正被执行
规则是否落地，用检查结果说话。建议按季度或每个大版本发布前执行一次，检查项与通过标准如下：
| 检查项 | 做法 | 通过标准 |
|---|---|---|
| 抽样追溯 | 随机抽取若干制品，仅凭标识反查源码提交、构建记录和关联工作项 | 抽样制品全部可在规定时间内完成追溯，无断点 |
| 重复与冲突检测 | 按名称和校验和两个维度比对制品库 | 不存在同名不同物；同物多名的情况已合并或标注 |
| 自动化覆盖 | 检查标识字段是否由流水线生成，抽查是否存在手工填写记录 | 必填字段全部自动生成，手工修改为零或有审批记录 |
| 例外与回退 | 查阅例外审批和版本回退记录 | 每次例外都有原因、审批人和后续处理结论 |
| 状态一致性 | 比对元数据状态与发布、归档记录 | 状态字段与实际流转一致，无“已发布但状态仍为测试中”的情况 |
检查发现的问题应回到对应环节修正：字段缺失回到流水线补自动化，同名不同物回到版本递增规则补判定，手工改名回到发布校验环节加拦截。规则本身也需要版本管理，命名规则变更时保留变更说明，便于解释历史制品的标识差异。把标准流程、评审节点和交付物模板沉淀为可复用资产，有助于让标识规则从文档要求转化为项目中的实际执行动作。
常见问题
团队已经有语义化版本号，为什么还需要单独的构建号和元数据？
语义化版本表达对外可见的功能与兼容性变化，由发布决策确定，同一个版本号可能对应多次构建。构建号由流水线自动递增，用来区分同一版本下的不同产出。元数据层记录源码提交、构建时间、构建环境和校验和，这些信息无法从版本号本身推导出来。只靠版本号会出现“同名不同物”：版本号相同但内容不同，追溯时无法判断测试的是哪一次构建。
紧急修复需要复用已有版本号时，应该怎么处理？
复用版本号属于例外，需要有固定入口：由配置管理员或研发负责人审批，记录复用原因、影响范围和后续修正计划，并在元数据中保留新的构建号与源码提交标识，确保内容不同即可区分。发布与归档环节的校验应能识别同名不同物并拦截，审批记录作为放行依据。事后应评估是否需要在下一个版本修正版本递增规则，减少同类例外重复发生。
制品标识和配置基线是什么关系，需要合并成一套吗？
两者管理对象不同。配置基线管理需求、设计、源码等配置项在某一时刻的稳定组合；制品版本标识描述单个可交付资产本体的来源与状态。实践中可以关联：基线记录本次交付包含哪些制品标识，制品标识的关联工作项字段指回需求与缺陷。合并成一套容易让字段含义混乱，建议保持各自规则，在交付清单层面建立对应关系。
流水线自动生成标识后，还需要人工校验吗？
自动化覆盖的是生成与写入，发布与归档环节仍需校验动作，只是校验本身也应尽量自动执行：检查必填字段是否齐全、名称是否符合规则、校验和是否与仓库记录一致、是否与已有制品重复。人工介入集中在例外审批和规则变更评审，常规放行由自动校验完成。抽查时重点关注是否存在手工填写或手工改名的痕迹，这类痕迹往往说明流水线步骤有缺口。
检查发现历史制品标识不完整，应该回溯补齐还是只对新制品执行？
建议区分处理：仍在支持期内、可能被再次交付或用于问题定位的历史制品，优先补齐关键字段，至少能定位源码提交和构建记录；已归档且不再交付的制品，保留现有记录并标注标识规则版本，避免用新规则改写历史数据造成混淆。同时把发现的问题反馈到流水线，防止新制品重复出现同类缺失。
