研发制品归档是把研发过程中产生的可交付资产本体，按版本和交付节点收拢、固定并长期保存的管理动作。归档对象通常分为两类：制品（构建产物、安装包、镜像、依赖清单、数据库脚本、配置模板等）和交付文档（需求与设计说明、接口文档、测试报告、发布说明、验收记录等）。本文说明这两类对象的具体范围、归档要完成的动作，以及容易与配置基线、版本发布、备份混淆的地方。
要点总览（TL;DR）
- 研发制品归档是在交付或发布节点，按版本将可交付资产本体收拢、校验、固定并登记保存的管理动作，目的是可追溯、可复现、可移交。
- 归档对象分两类：制品（构建产物、安装包、镜像、依赖清单、数据库脚本、配置模板等）和交付文档（需求与设计说明、接口文档、测试报告、发布说明、验收与移交记录等）。
- 归档范围以是否随版本交付、接收方是否需要其部署或验收为判断标准；组织级配置基线管理、制品仓库底层运维、过程性草稿不纳入归档。
- 一次完整归档包含按版本收集、校验完整性与一致性、固定版本并登记、设定保存期限与访问方式四个环节。
- 归档不等于把文件放进共享盘、不等于只存代码，也不是一次完成即可长期不管；需按版本持续维护追溯链。
研发制品归档指什么
研发制品归档，是在一个版本完成开发、准备交付或已经发布的时间点上，把该版本对应的可交付资产本体集中收拢、校验、固定版本并登记保存的过程。它处理的对象是资产本体，即最终要交到使用方或运维方手里的那些文件和包，而不是过程中的讨论记录或临时草稿。
理解这个概念可以抓住三个要素：
- 对象是可交付资产本体。归档收的是构建产物、安装包、镜像、脚本、配置模板和随版本交付的文档，判断标准是“这个东西是否随版本交出去”。
- 时点在交付或发布节点。归档按版本发生，一个版本对应一份归档记录，版本号是归档的基本索引。开发过程中的中间产物不进入归档范围。
- 目的是可追溯、可复现、可移交。可追溯指能查到某个版本当时交付了什么；可复现指依据归档内容能重新部署或重建该版本环境；可移交指接收方拿到归档内容后能独立接手运维或验收。
一句话概括：归档回答的是“这个版本当时到底交了什么、能不能还原出来”的问题。
归档范围的边界：哪些算、哪些不算
归档范围容易越划越大，把配置管理、仓库运维、日常文档存储都装进来。划清边界的办法是看对象是否随版本交付、是否属于资产本体。
| 类别 | 是否纳入归档 | 说明 |
|---|---|---|
| 随版本交付的构建产物、安装包、镜像、部署包 | 纳入 | 资产本体，交付和复现都依赖它 |
| 依赖清单、第三方组件清单、数据库脚本、配置模板 | 纳入 | 决定环境能否重建，属于交付内容的一部分 |
| 随版本发布的用户文档、接口文档、发布说明、测试报告 | 纳入 | 与制品配套交付，需与版本号对应 |
| 组织级配置基线与变更控制 | 不纳入 | 属于配置管理范畴，管的是基线定义与变更审批，归档只接收其产出的版本结果 |
| 制品仓库的底层开发与运维 | 不纳入 | 存储系统的建设、扩容、高可用属于平台运维工作 |
| 过程性草稿、临时文件、个人工作笔记 | 不纳入 | 未定稿、不随版本交付，归档价值低且会稀释归档清单 |
边界判断可以简化为两个问题：这份东西是否随这个版本交出去？交出去之后接收方是否需要它来部署、验收或运维？两个问题都是肯定答案，才进入归档清单。组织级配置基线管理负责“应该做成什么样”，归档负责“实际交出去的是什么”，两者衔接但不重叠。
通常归档哪些制品
制品是归档中体量最大、也最容易被漏掉的部分。按类别整理，每类都有需要一并固定的关键信息。
| 制品类别 | 典型内容 | 归档要点 |
|---|---|---|
| 构建产物与安装包 | 可执行程序、安装包、补丁包 | 记录版本号、构建时间、构建来源（对应哪次代码提交），确保包与源码版本可对应 |
| 容器镜像与部署包 | 镜像、编排文件、部署脚本包 | 固定镜像标签或摘要值，避免使用浮动标签导致无法定位当时部署的具体镜像 |
| 依赖清单与第三方组件清单 | 依赖锁定文件、组件及许可证清单 | 与制品同版本保存，用于复现构建环境和后续的组件合规核查 |
| 数据库脚本与配置模板 | 建表与升级脚本、初始化数据、环境配置模板 | 标注执行顺序和适用版本，配置模板中的敏感值以占位符形式保存 |
| 随版本发布的用户文档与说明 | 用户手册、操作指南、升级说明 | 与制品同版本绑定，文档版本号与产品版本号保持一致 |
制品归档的关键不在数量，而在“包与版本、包与源码、包与依赖”三组对应关系是否完整。缺少任何一组，后续排查问题或重建环境时都会断链。
通常归档哪些交付文档
交付文档与制品是配套关系：制品说明“交了什么”，文档说明“为什么这样交、怎么用、验证过什么”。常见类别及与版本的对应方式如下。
| 文档类别 | 典型内容 | 与版本的对应关系 |
|---|---|---|
| 需求与设计说明 | 需求规格、概要设计、详细设计 | 记录该版本实现的需求范围与设计决策，作为验收依据 |
| 接口与集成文档 | 接口定义、字段说明、集成方案 | 与该版本对外提供的接口一致，接口变更需在文档中标注版本差异 |
| 测试报告与质量记录 | 测试计划、用例执行结果、缺陷统计、性能报告 | 对应本版本的测试轮次和结论，说明质量状态 |
| 发布说明与版本记录 | 变更清单、已知问题、升级步骤、回滚方案 | 以版本号为索引，是归档清单的入口文档 |
| 验收、移交与运维交接文档 | 验收记录、移交清单、运维手册、应急预案 | 记录交付确认结果和接收方接手所需信息 |
文档归档的常见问题是“文档在，但不知道对应哪个版本”。解决办法是在归档时以版本号为主键组织文档，每份文档标注适用的产品版本和最后修订时间，发布说明作为索引串联其余文档。
归档机制：一次归档要完成哪些动作
归档不是把文件复制到一个目录就结束，一次完整的归档通常包含四个环节，每个环节都有可检查的完成标志。
- 按版本收集。依据发布范围确定本版本应归档的制品和文档清单，逐项收集。完成标志是清单上的每一项都有对应实物，缺项有明确说明。
- 校验完整性与一致性。核对制品与源码版本的对应关系、依赖清单是否齐全、文档版本号是否与产品版本一致、脚本执行顺序是否正确。完成标志是校验记录可查，异常项已处理或登记。
- 固定版本并登记归档记录。将归档内容置于不可随意修改的状态，登记版本号、归档时间、归档人、内容清单和存放位置。完成标志是形成一条可检索的归档记录，能据此定位到全部内容。
- 设定保存期限与访问方式。按交付合同、合规要求或内部制度确定保存时长，明确哪些角色可读、哪些角色可修改归档记录。完成标志是权限和期限有书面约定，接收方知道从哪里取用。
这四个环节中，校验和登记最容易被简化。缺少校验，归档内容可能看似齐全实则断链；缺少登记，归档就退化为一个没人说得清内容的存储目录。
在协作工具中落地时，可以把归档清单做成与版本关联的工作项或文档：需求、测试、发布记录挂在同一条版本链路上，归档时按链路核对交付物是否齐全，评审和交接记录留在同一处。ONES 的方案覆盖需求、基线、版本、变更、测试与发布，围绕需求、基线、版本和变更建立统一管理对象，支撑交付结果回溯；测试用例、缺陷、版本和发布过程关联到需求链路，便于在出现问题时定位影响范围。文档侧，ONES Wiki 可用于集中沉淀产品需求、技术文档、项目规范、操作说明等需要长期保存的内容。归档清单的具体模板形态和保存期限规则需结合团队自身制度确定。
容易混淆的相邻概念
归档与几个相邻概念经常被混用，区别主要在管理对象和目的上。
| 概念 | 管理对象 | 核心目的 | 与归档的关系 |
|---|---|---|---|
| 配置基线管理 | 基线定义、变更申请与审批 | 控制“应该做成什么样”，管变更 | 基线管理产出被批准的版本结果，归档接收并固定该结果 |
| 版本发布 | 发布动作、发布范围、上线过程 | 把版本推到目标环境并对外可用 | 发布是动作，归档是发布前后对资产本体的固定保存 |
| 备份 | 存储介质上的数据副本 | 故障后恢复数据，按周期自动执行 | 备份保的是“数据还在”，归档保的是“这个版本交了什么”，备份不能替代归档清单 |
| 普通文档库存储 | 日常文档的存放与协作编辑 | 方便团队查找和共同编辑 | 文档库允许持续修改，归档要求版本固定、内容不可随意变更 |
四组区别可以归结为一点：归档强调“按版本固定”，其他概念或者管变更、或者管动作、或者管数据副本、或者管日常协作，都不以版本固定为核心目标。
一个具体例子与常见误解
假设某团队发布 3.2 版本，按前面的范围整理，归档清单大致包括：3.2 版安装包及对应构建记录、镜像及摘要值、依赖锁定文件与第三方组件清单、数据库升级脚本与配置模板、用户手册和升级说明、本版本需求与设计说明、接口文档、测试报告、发布说明与回滚方案、验收记录与运维交接文档。清单以版本号 3.2 为索引，每项标注存放位置和责任人，归档后形成一条登记记录。
围绕这个例子，有三种典型误解需要纠正：
- 误解一：归档等于把文件放进共享盘。共享盘只解决存放问题，不解决版本对应、完整性校验和登记检索。没有清单和校验，文件放进去也说不清对应哪个版本、是否齐全。
- 误解二：归档只存代码。代码只是制品的一部分。缺少安装包、依赖清单、数据库脚本和配置模板，环境无法重建；缺少测试报告和验收记录，交付状态无法证明。
- 误解三：归档一次即可长期不管。归档记录需要随保存期限、访问权限和存储位置的变化维护；后续版本发布时还要按同样口径持续归档，否则版本之间的追溯链会中断。
对照自己团队的交付物时，可以先从最近一个已发布版本入手，按“制品五类、文档五类”逐项核对，缺项就是归档范围需要补齐的地方。
常见问题
归档时发现某个版本的依赖清单缺失，还能完成归档吗？
可以完成归档，但需要在归档记录中明确标注缺项及其影响。依赖清单缺失会影响环境复现和组件合规核查，建议在归档校验环节将其列为异常项，登记缺失原因和补录计划。若该版本已对外交付，应评估缺失对接收方运维的影响，必要时补充提供依赖信息或说明。归档记录的价值在于如实反映交付状态，而非要求所有内容绝对齐全。
归档的保存期限一般怎么确定？
保存期限通常由交付合同、行业合规要求或内部制度决定，没有统一标准。常见做法是至少覆盖合同约定的质保期或运维支持期，涉及安全或审计要求的版本按相关规定延长。团队应在归档时书面约定保存时长，并随制度变化更新。归档记录中注明期限和到期处理方式，便于后续维护。
配置基线管理和制品归档在实际工作中如何衔接？
配置基线管理负责定义“应该做成什么样”，包括基线组成和变更审批；制品归档负责固定“实际交出去的是什么”。衔接点在于：基线管理产出的被批准版本结果，作为归档的输入；归档时按基线定义的交付物范围核对实际制品和文档是否齐全。两者可以共用版本号作为索引，但管理目的不同，不应互相替代。
归档后的内容还能修改吗？
归档的核心要求是版本固定，归档内容原则上不应随意修改。若发现归档内容有误或缺失，应通过变更记录说明修改原因、修改内容和影响范围，保留修改痕迹。访问权限上，通常只有归档管理角色可以修改归档记录，其他角色只读。这样既能保证归档的严肃性，也能在必要时纠正错误。
团队刚开始做归档，应该从哪些制品和文档入手？
建议从最近一个已发布版本入手，按“制品五类、文档五类”逐项核对：制品包括构建产物与安装包、容器镜像与部署包、依赖清单与第三方组件清单、数据库脚本与配置模板、随版本发布的用户文档；文档包括需求与设计说明、接口与集成文档、测试报告与质量记录、发布说明与版本记录、验收与移交文档。核对后缺项即为需要补齐的范围。后续版本按同样口径持续归档，逐步形成稳定清单。
