研发制品归档的目标，是让每一次对外或对内交付都能回答三个问题：交付了什么、由什么构建而来、是否完整可用。做法上，先把构建产物、发布包和交付文档按版本绑定成归档单元，再按发布节点完成登记、复核与交接，最后用检查清单验证可还原性。本文给出范围判定、字段设计、执行步骤、填写示例和验收清单，并说明 ONES 在归档登记与交付清单核对环节的承载方式。
要点总览（TL;DR）
- 归档范围以一次发布为边界，只留随该次发布交付的构建产物、发布包和交付文档；保留期按正式发布、补丁、内部试用分别设定，并在归档时登记。
- 归档单元以版本为锚点：制品名、版本号、构建号、发布批次构成标识，代码提交、构建任务、构建时间与执行人构成来源，校验值与文件清单构成完整性证据。
- 归档动作嵌入发布流程：发布前冻结制品并生成清单，发布中上传归档并登记来源与校验值，发布后复核、审批与交接，各角色按完成标志交接。
- 验收以可还原为准：校验值复算一致、交付清单与实物逐项对应、来源可追溯，任一阻断项未通过即返工并分析原因。
- 保留期到期按登记方式处置并留存记录，使归档从登记到销毁形成闭环。
归档范围怎么划：哪些制品必须留、留多久
归档范围先按“可交付资产本体”划定，再按发布类型确定保留期。范围过宽会把每次构建的中间产物都塞进归档，检索和维护成本迅速上升；范围过窄则会在客户回溯或问题定位时找不到对应文件。建议以一次发布为边界，只归档随该次发布对外或对内交付的内容。
三类对象的区分方式如下：构建产物是构建任务直接输出的文件，如可执行文件、镜像、前端静态资源包；发布包是面向部署或交付整理后的集合，通常包含构建产物、部署脚本、配置样例和说明文件；交付文档是随版本交付的说明书、接口文档、测试报告、变更说明等。三者可能部分重叠，归档时应明确以发布包为交付主件，构建产物作为其来源证据保留。
保留期按发布类型区分。正式发布面向生产环境或外部客户，保留期最长，通常覆盖产品生命周期加合同约定的追溯期；补丁发布针对已交付版本的修复，保留期应与被修复的基线版本对齐；内部试用版本用于验证和演示，保留期可较短，但需登记到期处置方式。保留期应在归档时写入记录，而不是事后补填。
| 对象类别 | 触发归档的节点 | 保留期建议 | 责任人 |
|---|---|---|---|
| 构建产物 | 发布包冻结时同步留存对应构建输出 | 与所属发布包一致 | 构建负责人 |
| 发布包 | 发布评审通过、正式出包时 | 正式发布：产品生命周期加合同追溯期；补丁：与被修复版本对齐 | 发布经理 |
| 交付文档 | 随发布包一同定稿时 | 与所属发布包一致 | 文档负责人 |
| 内部试用版本 | 试用版本分发前 | 按试用周期设定，到期登记处置 | 发布经理 |
配置基线的建立与维护、制品仓库的底层存储实现属于另外的管理与技术课题，本文不展开。归档范围确定后，应形成一份对象清单并随发布流程固定下来，避免每次发布临时讨论留什么。
归档单元怎么组装：版本标识、来源与完整性
一个可追溯的归档单元，是以版本为锚点把制品、来源证据和交付文档绑定在一起的记录。判断标准很直接：只拿到这条记录，能否定位到具体文件、复算出校验值、追溯到构建来源。字段设计应围绕这三件事展开，字段过多会增加填写负担，过少则无法支撑回溯。
版本标识由制品名、版本号、构建号、发布批次组成。制品名保持稳定，版本号遵循组织统一的语义规则，构建号用于区分同一版本号的多次构建，发布批次标识本次交付所属的发布轮次。四者组合后应能唯一指向一个归档单元，避免出现同名同版本但内容不同的情况。
来源记录包括代码提交标识、构建任务编号、构建时间与执行人。这些信息通常可从构建系统自动采集，减少人工填写错误。来源记录的作用是在出现问题时快速定位到具体代码状态和构建环境，因此采集时应保留原始标识，不做二次改写。
完整性证据包括校验值、文件清单，必要时增加签名。校验值建议使用 SHA-256 等可复算的哈希算法，文件清单列出归档包内每个文件的名称、大小和校验值。复核时重新计算并与登记值比对，一致即通过。交付文档与制品的绑定关系通过归档单元内的关联字段体现，文档版本号应与发布包版本对应。
| 字段 | 采集来源 | 填写责任人 |
|---|---|---|
| 制品名、版本号、构建号、发布批次 | 构建系统与发布计划 | 构建负责人、发布经理 |
| 代码提交标识 | 版本控制系统 | 构建负责人 |
| 构建任务编号、构建时间、执行人 | 持续集成系统 | 构建负责人 |
| 校验值、文件清单 | 归档打包环节自动生成 | 归档管理员 |
| 交付文档及版本号 | 文档库或交付物模板 | 文档负责人 |
| 保留期与到期处置 | 发布类型判定规则 | 发布经理 |
字段清单确定后，应尽量把可自动采集的字段接入构建与发布流程，人工只负责确认和补充。归档单元记录本身也需要版本管理，字段变更时保留修改痕迹，便于审计时说明记录的形成过程。
按发布节点执行归档：操作步骤与角色分工
归档动作嵌入发布流程后，才可能稳定执行。按发布前、发布中、发布后三个阶段安排，每个阶段都有明确的输入、动作、输出和完成标志，角色之间按产物交接，而不是靠口头通知。
发布前，构建负责人冻结本次发布的制品，确认版本标识与构建号，生成文件清单和校验值；发布经理核对发布范围，确认交付文档已定稿并与版本对应。完成标志是制品冻结且清单齐全，此后不再改动制品内容。
发布中，归档管理员上传发布包与构建产物，登记来源记录和校验值，关联交付文档，填写保留期。完成标志是归档单元记录完整，校验值已登记且可复算。
发布后，发布经理组织复核，测试负责人确认测试结论与本次版本对应，审批人确认归档合格后完成交接。完成标志是复核通过、审批记录留存、交付清单与实物一致。
| 步骤 | 输入 | 动作 | 输出 | 完成标志 | 负责人 |
|---|---|---|---|---|---|
| 冻结制品 | 构建输出、发布计划 | 锁定本次发布制品，确认版本标识 | 冻结的制品与版本清单 | 制品不再变更 | 构建负责人 |
| 生成清单与校验值 | 冻结制品 | 生成文件清单，计算校验值 | 清单文件、校验值记录 | 清单与制品一一对应 | 构建负责人 |
| 确认交付范围 | 发布计划、交付文档 | 核对文档版本与发布包版本 | 交付范围确认记录 | 文档与版本对应 | 发布经理 |
| 登记归档 | 制品、清单、校验值、文档 | 上传归档，填写来源与保留期 | 归档单元记录 | 字段完整、校验值已登记 | 归档管理员 |
| 复核与审批 | 归档单元记录 | 抽查校验值，核对清单与实物 | 复核记录、审批结论 | 复核通过并留存审批 | 发布经理、审批人 |
| 交接 | 审批通过的归档记录 | 向交付或运维团队移交 | 交接记录 | 接收方确认 | 发布经理 |
角色分工上，开发人员负责确认代码提交与版本对应关系；构建负责人负责制品冻结与来源记录；测试负责人确认测试结论与版本绑定；发布经理负责范围确认、复核组织与交接；归档管理员负责登记与完整性证据维护。角色可以兼任，但职责需在流程文件中写明。
当团队使用 ONES 承载研发过程时，需求、版本、测试与发布对象可以在同一平台内建立关联，归档登记与交付清单核对可以围绕这些关联对象进行。ONES 研发管理方案覆盖需求、基线、版本、变更、测试与发布，测试用例、缺陷、版本和发布过程可关联到需求链路中，便于在归档时沿关联关系确认本次发布包含的范围与验证结论。制品文件本体的存储与校验能力需结合具体部署核验，归档字段与流程要求不因工具选择而改变。
完整示例：一次版本发布的归档记录
以下为演示情景，用于说明归档单元如何填写，数据为示例值，不代表任何真实项目。
背景：某产品发布 3.2.0 正式版本，包含两个新增功能和一个缺陷修复，交付给外部客户，保留期按产品生命周期加合同追溯期设定。
| 字段 | 填写内容 |
|---|---|
| 制品名 | product-server |
| 版本号 / 构建号 / 发布批次 | 3.2.0 / build-20240612-07 / 2024-Q2-正式-01 |
| 代码提交标识 | 主干分支提交 a1b2c3d |
| 构建任务与时间 | 流水线 #1187，2024-06-12 14:20，执行人：构建负责人 |
| 校验值 | 发布包 SHA-256 值已登记，文件清单共 42 项 |
| 交付文档 | 安装说明 v3.2、接口文档 v3.2、测试报告 v3.2、变更说明 v3.2 |
| 保留期 | 产品生命周期加合同追溯期，到期处置：评审后销毁并登记 |
交付清单核对结果：发布包 1 个、构建产物 3 个、交付文档 4 份，与清单一致；抽查两个文件重新计算校验值，与登记值一致；测试报告结论为通过，覆盖本次新增功能与修复项。复核人签字，审批通过后移交运维团队，接收方确认收到。
这个示例可迁移的规律有三点：版本标识四要素缺一不可；来源记录尽量自动采集，人工只做确认；校验值在归档时登记、复核时复算，形成闭环。换一个产品或发布类型，字段结构不变，只需调整保留期和交付文档清单。
完成检查：归档是否合格的核验项
归档是否合格，以能否还原为准。检查在归档完成后进行，可按发布批次抽查，也可对正式发布逐次核验。任一阻断项未通过即返工，返工后重新核验。
| 检查项 | 通过标准 | 证据 | 负责人 | 阻断判定 |
|---|---|---|---|---|
| 对象完整性 | 发布包、构建产物、交付文档齐全，与交付清单一致 | 文件清单、交付清单 | 归档管理员 | 缺失任一交付对象即阻断 |
| 版本一致性 | 制品名、版本号、构建号、发布批次与发布计划一致 | 归档单元记录、发布计划 | 发布经理 | 版本标识不一致即阻断 |
| 来源可追溯 | 代码提交、构建任务、构建时间与执行人可查 | 来源记录字段 | 构建负责人 | 来源缺失即阻断 |
| 校验值可复算 | 重新计算结果与登记值一致 | 校验值记录、复算结果 | 复核人 | 不一致即阻断 |
| 交付清单与实物一致 | 清单条目与归档内容逐项对应 | 交付清单、归档目录 | 复核人 | 存在差异即阻断 |
| 保留期与到期处置 | 保留期已登记，处置方式明确 | 归档单元记录 | 发布经理 | 未登记为整改项，不阻断发布但需限期补齐 |
| 审批与交接 | 复核记录与审批结论留存，接收方确认 | 审批记录、交接记录 | 审批人 | 未完成交接即阻断 |
检查结果应记录在归档单元或独立的检查记录中，注明检查人、检查时间和结论。对抽查发现的问题，除返工外还应分析原因：是字段采集缺失、流程节点遗漏，还是角色职责不清，据此调整流程而不是只修补单次记录。保留期到期时按登记方式处置并留存处置记录，使归档形成从登记到销毁的完整闭环。
常见问题
发布节奏很快，每个版本都做完整归档会不会拖慢发布？
可以把归档拆成自动与人工两部分来控制耗时。版本标识、代码提交、构建任务、构建时间与执行人、校验值和文件清单都可以在构建与打包环节自动生成，人工只做确认和补充；复核环节按发布类型区分力度，正式发布逐次核验，补丁和内部试用可按批次抽查。真正需要控制的是发布前冻结制品这一步，冻结之后制品不再改动，后续登记与复核才有稳定对象。若发布频率高到无法逐次复核，可先保证登记完整，再按周或按批次集中复核，但阻断项仍需在交接前确认。
补丁发布和内部试用版本，归档要求可以简化到什么程度？
简化的是保留期和复核频次，归档单元的核心字段不建议删减。补丁发布应保留与被修复基线版本的对齐关系，版本标识、来源记录和校验值仍需完整，否则无法说明补丁基于哪个代码状态构建。内部试用版本保留期可较短，但需在归档时登记到期处置方式，避免试用包长期散落。交付文档可按试用范围裁剪，测试报告和变更说明建议保留，用于后续正式发布时复用。
归档记录里登记了校验值，复核时发现不一致该怎么处理？
先判断不一致发生在哪个环节：是归档打包后文件被替换、传输过程损坏，还是登记时抄录错误。处理顺序是暂停该归档单元的交接，重新从冻结制品生成清单和校验值，与原始构建输出比对，确认哪一份是正确版本。若归档内容确实被改动，需要回溯改动来源并重新走复核审批；若只是登记错误，更正记录并保留修改痕迹。无论哪种情况，都应在检查记录中写明原因和处置结果，并检查同类归档是否存在相同问题。
归档由发布经理兼管，还是需要单独设归档管理员？
取决于发布频次和交付对象的数量。发布轮次少、交付对象单一的团队，发布经理可以兼任归档登记，但复核环节建议由另一人执行，避免登记与复核由同一人完成。发布频繁、交付对象多或存在外部合规要求的团队，单独设归档管理员更稳妥，由其维护字段完整性、校验值和保留期登记，发布经理专注范围确认与交接。无论是否兼任，职责都应在流程文件中写明，并在归档记录上留下责任人和时间。
归档完成后，怎么验证真的能还原出可交付的版本？
验证方式是拿归档记录独立走一遍还原路径：按记录定位到发布包和构建产物，重新计算校验值并与登记值比对，按文件清单核对内容是否齐全，再对照交付文档确认版本对应。抽查可选一个正式发布版本完整执行，其余版本按批次抽验。若还原过程中发现某类文件缺失或来源记录无法定位，说明字段采集或流程节点存在缺口，应调整流程而不是只补这一次记录。还原验证的结果同样记入检查记录，作为后续审计依据。
