制品元数据记录要回答四个问题：这个制品是什么、从哪里来、是否完整、应当保留多久。本文提供一份虚构但自洽的填写示例，覆盖制品标识、版本号、来源构建信息、完整性校验值、保留期限与交付去向等字段，并逐项说明取值理由和常见填写误区，帮助读者把这套写法迁移到自己的发布包、交付文档或镜像清单中。
要点总览（TL;DR）
- 制品元数据记录围绕四组字段展开：标识与版本、来源、完整性、保留与交付，四组互相印证才能支撑追溯、校验和交付。
- 示例以发布包 order-service-release-2.4.0.zip 演示填写：标识写服务名加版本，来源记录提交哈希、构建任务和带时区的构建时间，完整性用 SHA-256 校验值加文件大小。
- 常见误区有三处：只写文件名、来源笼统、校验值缺失或算错对象，三者都会让记录停留在登记层面。
- 换成交付文档或容器镜像时按四组字段取舍：需要交付核对就保留完整性字段，内部流转的中间产物可简化交付去向，标识和来源仍应保留。
- 示例为虚构演示数据，保留期限需按行业监管要求另行确认，配置基线与制品仓库底层存储不在本文范围。
这份示例要解决什么问题
示例设定一个常见交付场景：研发团队完成一次版本发布，需要把一个发布包交给测试环境验证，并在后续交付给运维或客户支持团队。发布包本身是一个压缩文件，内部包含应用安装程序、配置样例和一份变更说明。团队需要为这个发布包建立一条元数据记录，使任何拿到它的人都能判断它是否为目标版本、是否被篡改、应该保存到什么时候、最终交给了谁。
这条记录要支撑三类用途。第一是追溯：从制品反查到具体的代码提交和构建任务，确认它由哪次构建产生。第二是校验：通过完整性校验值确认文件在传输、拷贝、归档过程中没有损坏或被替换。第三是交付：明确制品的存放位置、交付对象和保留期限，让交接双方对同一份记录达成一致。三类用途对应不同的字段，缺少任何一类，记录都会在某个环节失去作用。
需要说明的是，本文中的制品名称、版本号、提交哈希、校验值、文件大小、人员角色和保留期限均为演示数据，用于说明填写方式，不代表任何真实项目或客户案例。读者可以参照字段结构和填写逻辑，替换为自己项目的实际值。
完整示例：一个发布包的制品元数据记录
下表是一份填写完成的制品元数据记录。字段按“标识—来源—完整性—保留与交付”的顺序排列，便于对照检查。示例中的发布包名为 order-service-release-2.4.0.zip，由一次持续集成构建产生，计划交付给测试团队验证后再移交运维。
| 字段 | 填写值 | 说明 |
|---|---|---|
| 制品标识 | order-service-release-2.4.0.zip | 制品文件名，包含服务名、制品类型和版本号 |
| 制品类型 | 发布包（二进制归档） | 区分发布包、交付文档、容器镜像等类型 |
| 版本号 | 2.4.0 | 与发布计划中的版本标识一致 |
| 代码提交 | commit a1b2c3d（release/2.4 分支） | 构建所基于的提交与分支 |
| 构建任务 | CI 流水线 order-service-build #1873 | 产生该制品的构建任务编号 |
| 构建时间 | 2025-03-18 14:22（UTC+8） | 构建完成时间，注明时区 |
| 完整性校验值 | SHA-256：9f2c…（64 位十六进制） | 对最终制品文件计算，构建后生成 |
| 文件大小 | 86.4 MB | 用于传输核对和存储估算 |
| 存放位置 | 制品库 release/order-service/2.4.0/ | 制品的归档路径 |
| 保留期限 | 24 个月，或至下一主版本发布后 12 个月 | 按组织归档规范确定 |
| 交付去向 | 测试团队验证；通过后移交运维部署 | 记录交付对象与用途 |
| 关联交付清单 | 发布清单 REL-2.4.0 第 3 项 | 与版本发布清单中的条目对应 |
这份记录的特点是把“文件本身”和“文件的来历”放在同一张表里。只看文件名，无法判断它是否由 release 分支构建；只看构建任务，无法确认交付出去的文件与构建产物一致。标识、来源、校验值三组字段互相印证，才构成一条可用的记录。
逐项解释：每个字段为什么这样填
制品标识采用“服务名—制品类型—版本号”的组合，而不是单独写一个文件名。原因是同名文件在不同目录、不同构建中可能重复出现，加入服务名和版本号后，标识在团队范围内具备唯一性。版本号 2.4.0 与发布计划中的版本标识保持一致，避免出现“文件叫 2.4.0、清单写 2.4”的错位。如果组织使用语义化版本，主版本、次版本和修订号的变化应能对应到发布范围的变化。
来源字段由代码提交、构建任务和构建时间三项组成。代码提交记录到具体哈希和分支，构建任务记录到流水线编号，构建时间注明时区。这三项合起来支撑回溯：从制品出发，可以定位到是哪次构建、基于哪个提交产生的；从提交出发，也可以查到它被构建成了哪些制品。只写“由 CI 构建”或只写构建日期，回溯时仍需人工翻查记录，追溯价值会打折扣。
完整性校验值在构建完成后对最终文件计算，常用 SHA-256。它的作用是在交付核对时提供比对基准：接收方对收到的文件重新计算校验值，与记录中的值一致，说明文件在传输和拷贝过程中未发生变化。校验值必须针对最终交付的那个文件计算，如果在打包前对中间产物计算，比对就会失败。文件大小作为辅助核对项，能在不计算校验值的情况下快速发现明显异常。
保留期限和交付去向依据组织的归档规范和交付流程确定。示例中的“24 个月，或至下一主版本发布后 12 个月”表达的是两个条件取其一，具体口径应与团队约定一致。交付去向写明交付对象和用途，便于后续确认这份制品是否已经交付、交付给了谁。关联交付清单则把单条记录放回版本发布的整体语境中，避免制品记录与发布清单各自维护、互不对应。
常见填写误区集中在三处。第一是只写文件名，缺少版本和类型信息，同名文件无法区分。第二是来源缺失或过于笼统，只写构建日期而不写提交和构建任务，出问题时无法定位。第三是校验值缺失或计算对象错误，导致交付核对环节没有可比对的基准。这三类问题都会让记录停留在“登记”层面，难以支撑追溯和校验。
可迁移规律：换一个制品怎么套用
不同制品类型对字段的需求有差异，可以按“标识、来源、完整性、保留与交付”四组来取舍。发布包和二进制归档通常四组字段都需要；交付文档的来源可以记录到文档版本和评审记录，完整性校验值按需使用；容器镜像的标识通常使用镜像名加标签或摘要，来源记录到构建流水线和基础镜像版本，完整性以镜像摘要为准。下表给出一个对照参考。
| 字段组 | 发布包 | 交付文档 | 容器镜像 |
|---|---|---|---|
| 标识与版本 | 必填：文件名、版本号 | 必填：文档名称、版本 | 必填：镜像名、标签或摘要 |
| 来源 | 必填：提交、构建任务、构建时间 | 按需：编写人、评审记录、基线版本 | 必填：构建流水线、基础镜像版本 |
| 完整性 | 必填：校验值、文件大小 | 按需：文件校验值或审批记录 | 必填：镜像摘要 |
| 保留与交付 | 必填：存放位置、保留期限、交付去向 | 必填：归档位置、保留期限、分发范围 | 必填：镜像仓库路径、保留策略、部署环境 |
区分必填与按需字段的原则是看该字段是否支撑一项必须完成的动作。需要交付核对，完整性字段就是必填；只在团队内部流转、不对外交付的中间产物，可以简化交付去向，但标识和来源仍应保留。记录与交付清单的关联方式也应统一：每条制品记录对应清单中的一个条目，条目编号写回记录，清单汇总时按编号核对，避免两边各自维护。
在协作工具中，这类记录可以挂到对应的工作项或文档上，让制品信息与需求、版本和发布过程处于同一条链路。ONES 当前方案覆盖需求、基线、版本、变更、测试与发布，围绕需求、基线、版本和变更建立统一管理对象，支撑过程状态追踪和交付结果回溯；测试用例、缺陷、版本和发布过程可以关联到需求链路中，出现问题时便于定位影响范围。团队可以把制品记录作为发布工作项的附件或说明文档，通过 ONES Wiki 沉淀交付物模板与实践经验，使每次发布沿用同一套字段结构。具体字段配置和挂接方式以团队实际使用的工具设置为准。
适用边界：哪些情况需要调整这份示例
这份示例聚焦单个可交付制品的元数据记录，不涉及配置基线的组织方式。配置基线关注一组配置项在某一时点的整体状态和变更控制，制品记录只描述单个制品本身，两者层级不同。如果团队需要管理基线，应另行设计基线的组成、审批和变更流程，本文的字段结构不能直接替代。
示例也不涉及制品仓库的底层存储与开发，包括存储介质选择、分片与去重、仓库高可用等内容。这些属于制品库平台的建设范畴，与元数据记录的填写方法是两个层面。记录中的存放位置字段只描述归档路径，不规定仓库如何实现。
保留期限需要按所在行业和监管要求另行确认。金融、医疗、汽车等行业可能对交付物留存有明确规定，示例中的期限仅为演示值，不能直接作为合规依据。涉及对外交付或审计场景时，应先确认适用的规范，再确定字段和期限。
最后，示例中的全部数据均为演示用途，不代表真实项目、客户或实测结果。读者套用时，应替换为实际制品信息，并根据团队交付规范调整字段的必填范围和命名规则。
常见问题
如果构建产物在打包后又做了签名或压缩，校验值应该对哪个文件计算？
校验值应对最终交付出去的那个文件计算。如果打包完成后又追加了签名、重新压缩或修改了文件属性，这些操作都会改变文件内容，之前对中间产物算出的校验值就失效了。稳妥的做法是把校验值计算放在交付前的最后一步，并让构建流水线自动输出，避免人工补算时对错文件。记录中同时写明文件大小，接收方可以先比对大小，再计算校验值，两步都一致才确认文件完好。
团队规模不大、制品数量不多，是否可以把这些字段简化成一张共享表格？
可以，前提是表格能稳定回答追溯、校验和交付三个问题。小团队用共享表格登记制品时，建议至少保留制品标识、版本号、代码提交、构建任务、校验值、存放位置和交付去向这几项，并约定由谁在构建完成后填写。表格的风险在于多人编辑容易漏填或覆盖，随着制品数量增长，查找和核对成本会上升。当发布频率提高、需要按版本汇总交付清单时，可以再考虑把记录挂到工作项或文档上，让字段结构和填写责任固定下来。
交付给客户的制品和内部测试用的制品，记录要求有什么不同？
对外交付的制品通常需要更完整的记录。交付去向要写明客户或接收方、交付时间和交付方式，完整性校验值应作为交付凭证的一部分随附，保留期限按合同或行业规范确定。内部测试用的制品可以简化交付去向，但标识、来源和校验值仍建议保留，否则测试发现问题时难以确认被测文件与哪次构建对应。两类制品可以共用同一套字段结构，通过必填范围区分严格程度，避免维护两套模板。
制品记录和版本发布清单是什么关系，需要两边都维护吗？
两者是明细与汇总的关系。制品记录描述单个制品，发布清单汇总一次发布包含哪些制品。可行的做法是每条制品记录对应清单中的一个条目，把条目编号写回记录，清单只保留条目编号、制品标识和状态，详细字段仍以制品记录为准。这样核对时按编号逐条比对，避免两边各写一份完整信息、更新时出现不一致。清单的汇总口径和条目编号规则应在团队内统一约定。
保留期限到期后，制品和它的元数据记录应该一起删除吗？
需要分开考虑。制品文件体积大，到期后通常按归档规范清理或转冷存储；元数据记录体积小，保留成本低，建议比制品文件多保留一段时间，用于回答“这个版本当时交付给了谁、由哪次构建产生”这类事后问题。具体保留多久取决于组织的审计要求和行业规范，涉及对外交付或合规审计的场景应先确认适用要求再定。清理前应确认没有未关闭的问题单或变更还在引用该制品。
