流水线执行记录要回答的是“这次运行用了什么、做了什么、结果如何、谁批准放行”。围绕可追溯、可复现、可审计，记录应保留四组信息：执行标识与触发来源、环境与输入、过程与结果、审批与处置。字段按必留、按需留、仅留引用分级，日志与产物保留引用地址而非全量复制。本文给出可直接照抄的字段清单、采集时点、角色分工、留存与权限设定方法，以及一份填写示例和验收检查表。
要点总览（TL;DR）
- 执行记录按四组信息组织：执行标识与触发来源、环境与输入、过程与结果、审批与处置，覆盖定位、复现与放行判断。
- 字段按必留、按需留、仅留引用三级取舍：日志、产物、镜像保留引用地址与校验值，不复制正文，控制存储成本与敏感信息暴露面。
- 采集以自动写入为主，人工只补录变更单关联、失败原因归类、回滚说明等系统无法判断的信息，并约定采集失败时的兜底与阻断规则。
- 留存期限按记录类型分层设定，结构化字段长期保存，日志按排查窗口保存，密钥只留引用名称；权限与项目可见范围一致，敏感字段单独控制。
- 用可追溯、可复现、可审计三项逐条核对，必留字段缺失、引用失效或审批为空即判定记录不合格，不得作为发布依据。
先定记录边界：哪些信息必须留、哪些只留引用
执行记录的价值在于事后能定位“哪次运行、基于哪份代码、产出了什么、谁放行”，因此字段取舍先看用途，再看成本。建议在列字段前先确定三级分类，再逐项归位。
| 分级 | 判断依据 | 典型内容 | 保存方式 |
|---|---|---|---|
| 必留 | 缺少后无法定位运行、无法复现代码与产物、无法判断是否合规放行 | 运行编号、流水线名称与版本、触发人与方式、提交哈希与分支、产物标识、各阶段状态与起止时间、准入结论与审批人 | 结构化字段，随记录长期保存 |
| 按需留 | 用于问题排查、度量或争议追溯，缺失不影响基本定位 | 失败原因描述、重试次数与原因、测试覆盖率、依赖清单明细、执行节点信息 | 结构化字段，按留存期限保存 |
| 仅留引用 | 体积大、更新频繁或含敏感内容，复制成本高且无必要 | 完整构建日志、测试报告附件、构建产物文件、镜像、配置文件快照 | 保存地址、校验值与访问入口，不复制正文 |
全量复制日志和产物会快速推高存储成本，也会扩大敏感信息的暴露面。日志中常含环境变量、内部地址甚至凭据片段，产物则可能包含未公开的业务数据。保留引用地址加校验值，既能证明“当时确实存在这份内容”，又便于按权限控制访问。
记录边界还要与相邻环节分工。发布准入与质量门禁负责“什么条件下允许放行”的规则设计，执行记录负责如实记下这次运行的输入、结果和放行结论；流水线与平台的对接配置属于工具链集成范畴，记录规范只需约定从集成中取哪些字段、以什么口径写入。边界清楚，字段清单才不会膨胀成平台配置手册。
核心字段清单：执行记录应包含的四组信息
以下清单按四组信息组织，可直接作为字段规范的初稿。标注“必留”的字段建议设为流水线模板的强制项，缺失时阻断记录归档；“按需”字段由团队按业务复杂度增补。
第一组：执行标识与触发来源
| 字段 | 用途 | 分级 |
|---|---|---|
| 流水线名称与版本 | 区分同名流水线的不同配置，复现时知道用哪版脚本 | 必留 |
| 运行编号 | 唯一标识一次执行，作为日志、产物、审批的关联主键 | 必留 |
| 触发方式 | 区分提交触发、定时触发、手动触发、上游流水线触发 | 必留 |
| 触发人 | 手动触发时记录操作者；自动触发时记录提交人或调度账号 | 必留 |
| 关联提交与分支 | 定位代码来源，支持按提交反查运行 | 必留 |
| 关联需求或变更单 | 把技术运行与业务变更对应，支撑审计与影响分析 | 按需 |
第二组：环境与输入
| 字段 | 用途 | 分级 |
|---|---|---|
| 代码版本（提交哈希、分支、标签） | 复现的起点，精确到提交而非仅分支名 | 必留 |
| 构建产物标识（名称、版本号、校验值） | 证明产物与本次运行的对应关系，防止产物被替换 | 必留 |
| 依赖与镜像版本 | 排查“代码没变但结果变了”的环境漂移问题 | 按需 |
| 运行环境与配置版本 | 记录目标环境、配置模板版本或配置中心版本号 | 必留 |
| 运行参数 | 记录本次使用的非敏感参数取值 | 按需 |
| 密钥引用 | 只记录密钥名称或凭据库条目编号，不记录明文 | 必留（引用形式） |
第三组：过程与结果
| 字段 | 用途 | 分级 |
|---|---|---|
| 各阶段名称、起止时间、执行节点 | 定位耗时瓶颈与节点异常 | 必留 |
| 步骤状态（成功、失败、跳过、中止） | 还原执行路径，判断是否完整跑完 | 必留 |
| 日志引用地址 | 排查细节，按权限访问 | 仅留引用 |
| 产物引用地址与校验值 | 取回产物并验证完整性 | 仅留引用 |
| 测试与质量结果（通过率、失败用例、门禁结论） | 支撑质量判断与趋势度量 | 必留（结论）、按需（明细） |
| 失败原因与重试记录 | 区分环境抖动与真实缺陷，避免重试掩盖问题 | 按需 |
第四组：审批与处置
| 字段 | 用途 | 分级 |
|---|---|---|
| 发布准入结论 | 记录本次是否满足放行条件及依据 | 必留 |
| 审批人与审批时间 | 明确放行责任，支撑审计 | 必留 |
| 回滚动作与回滚目标版本 | 出现问题时还原现场，评估影响范围 | 按需（发生即必留） |
| 修复动作与关联缺陷 | 把失败运行与后续修复串起来 | 按需 |
采集与写入：字段从哪里来、由谁在什么时点写入
字段可靠性取决于采集方式。原则是：能从流水线工具、代码库、制品库自动获取的字段一律自动写入，人工只补录系统无法判断的业务信息，例如变更单关联、失败原因归类、回滚决策说明。
| 字段 | 来源 | 写入时点 | 负责人 |
|---|---|---|---|
| 运行编号、流水线版本、触发方式与触发人 | 流水线工具自动生成 | 触发时 | 流水线维护者配置模板 |
| 提交哈希、分支、关联工作项 | 代码库与项目管理工具 | 触发时 | 开发提交人确保提交信息规范 |
| 阶段起止时间、步骤状态、执行节点 | 流水线工具自动采集 | 执行中实时写入 | 流水线维护者 |
| 日志与产物引用、校验值 | 流水线工具与制品库 | 阶段结束时 | 流水线维护者 |
| 测试与质量结论 | 测试工具回传 | 测试阶段结束时 | 测试负责人确认口径 |
| 失败原因归类、重试说明 | 人工补录 | 运行结束后 | 当次处理人 |
| 准入结论、审批人、回滚动作 | 审批流程与人工填写 | 发布前后 | 发布负责人 |
三个写入时点各有重点。触发时写入标识与输入，保证运行一开始就有可追溯的主键；执行中持续写入阶段状态与时间，便于实时观察阻塞；结束后补齐结果结论、失败归类和审批处置，形成完整记录。
采集失败要有兜底。常见情况包括集成中断导致状态未回传、测试工具未上报结果、产物上传失败。建议约定：状态未回传时，记录标记为“数据不完整”并保留原始日志链接，由流水线维护者在当日内补录或标注原因；关键必留字段缺失的运行不得作为发布依据；连续多次采集失败应作为工具链问题单独跟踪，而不是逐次人工修补。
角色与交付物：谁负责记录、谁负责核对
记录质量靠分工而非自觉。建议明确三类角色，每类角色对应可检查的交付物。
| 角色 | 职责 | 交付物 |
|---|---|---|
| 流水线维护者 | 在流水线模板中固化必留字段，配置自动采集与引用写入，处理采集失败 | 字段模板配置、采集异常处理记录 |
| 开发提交人 | 保证提交信息包含关联工作项编号，触发后确认运行归属正确 | 规范提交记录、关联关系 |
| 测试负责人 | 确认测试与质量结果的上报口径，核对结论字段与实际报告一致 | 质量结论字段、口径说明 |
| 发布负责人 | 填写准入结论、审批信息，发生回滚时记录回滚目标与原因 | 审批记录、回滚说明 |
| 记录核对人（可由质量或工程效能角色兼任） | 按周期抽查执行记录完整性，汇总缺失项并推动模板修正 | 抽查记录、缺失项清单、改进项 |
核对建议按周或按发布批次进行，抽查范围覆盖成功与失败运行。核对输出不是打分，而是两类结论：模板需要补哪些自动采集项，以及哪些环节的人工补录可以取消。这样记录规范会随使用逐步收敛，而不是越加越重。
当团队已使用 ONES 管理需求与任务时，可以把执行记录与工作项关联起来：ONES DevOps 解决方案支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步流水线数据、更新执行状态和日志，并在项目、迭代、需求中呈现代码提交、流水线构建与产品发布过程。这样“关联需求或变更单”这类字段可以直接从工作项关联中获得，减少人工补录；审批结论与回滚说明也可随发布记录一并留档，便于后续按项目追溯。
留存期限、存储与访问权限怎么定
留存策略按记录类型分层设定，依据是审计要求、问题回溯窗口和存储成本。以下为常见做法，具体期限需结合行业合规与内部制度确定。
| 记录类型 | 建议留存思路 | 存储位置 | 访问权限 |
|---|---|---|---|
| 执行记录结构化字段（标识、输入、状态、审批） | 长期保存，覆盖审计周期与产品生命周期 | 流水线平台或研发管理平台数据库 | 项目成员可读，跨项目需授权 |
| 完整日志 | 按排查窗口设定，如数月，重要发布可延长 | 日志系统，记录中保存引用地址 | 按角色开放，含敏感内容的日志限维护者与安全角色 |
| 构建产物与镜像 | 与线上版本存续期一致，下线版本按制度清理 | 制品库，记录中保存标识与校验值 | 发布与运维角色可下载，其他角色按需申请 |
| 测试报告与质量明细 | 覆盖质量追溯周期 | 测试管理工具，记录中保存结论与链接 | 项目成员可读 |
| 密钥与敏感参数 | 不进入执行记录正文，仅保留引用名称 | 凭据管理系统 | 按最小权限授予，访问留痕 |
权限设计遵循两条规则：记录可读范围与项目可见范围一致，避免执行记录成为信息孤岛；敏感字段单独控制，密钥、令牌、内部地址在日志输出前做脱敏，记录中只出现引用标识。审计需要查看时，通过授权访问引用地址，而不是把敏感内容复制进记录。
示例：一次发布流水线的执行记录长什么样
以下为演示情景，展示字段如何填写与引用。
| 字段组 | 填写内容 |
|---|---|
| 执行标识 | 流水线：订单服务发布流水线 v12；运行编号：RUN-20240612-037；触发方式：手动；触发人：张工；分支：release/2.4；提交：a1b2c3d；关联需求：ORD-1187 |
| 环境与输入 | 目标环境：预发布；配置版本：cfg-2.4.3；镜像：order-service:2.4.3（校验值 sha256:9f…）；密钥引用：cred-prod-db（不记录明文） |
| 过程与结果 | 构建阶段 10:02–10:06 成功，节点 builder-03；单元测试 10:06–10:11 成功，通过率 100%；集成测试 10:11–10:24 成功，用例 86/86；日志引用：log://run-037；产物引用：artifact://order-service/2.4.3 |
| 审批与处置 | 准入结论：通过；审批人：李工；审批时间：10:31；发布结果：成功；回滚：无 |
失败重试场景需要补充三类信息：首次失败发生在哪个阶段、失败原因归类（环境问题、用例失败、依赖超时等）、重试的触发人与重试次数。例如集成测试首次在 10:18 因数据库连接超时失败，归类为环境问题，由张工在 10:20 重试一次后通过。记录中保留两次运行的编号与各自日志引用，避免只留最终成功结果而丢失问题线索。
完成检查：记录是否可追溯、可复现、可审计
用以下清单逐项核对，全部通过方可认为记录合格。
| 维度 | 检查项 | 通过标准 |
|---|---|---|
| 可追溯 | 运行编号唯一且可检索；触发人与触发方式明确；关联提交、分支、需求可反查 | 任取一条线上版本，能在记录中定位到对应运行与代码提交 |
| 可复现 | 代码版本精确到提交；产物标识与校验值齐全；配置版本与依赖版本可查；密钥以引用形式存在 | 按记录可重新取回同一份代码与产物，并说明当时环境配置 |
| 可审计 | 准入结论、审批人与时间完整；失败与重试有说明；回滚有目标版本与原因；敏感信息未明文出现 | 审计人员无需询问当事人即可判断放行是否合规 |
| 阻断条件 | 必留字段缺失且未标注原因；日志或产物引用失效；审批信息为空 | 出现任一项，该运行记录判定为不合格，不得作为发布依据 |
检查频率可与发布节奏对齐：每次发布前核对当次记录，按周期抽查历史记录。发现的问题回流到字段模板与采集配置，形成“记录—核对—修正模板”的循环，执行记录才能长期保持可用。
常见问题
流水线执行记录和发布审批记录是同一份东西吗，需要分开保存吗？
两者内容有交集，但职责不同。执行记录回答“这次运行用了什么代码、产出了什么、各阶段结果如何”，发布审批记录回答“在什么条件下、由谁批准放行”。实践中可以让审批结论、审批人与时间作为执行记录的一组字段存在，同时审批流程本身保留独立的审批单据。这样执行记录能完整反映一次运行的全貌，审批单据也能按审批制度单独归档和检索。需要避免的是两边各记一半、互不关联，导致事后无法把放行结论对应到具体运行编号。
团队规模小、发布频率低，字段清单可以精简到多少？
可以先保留支撑三项判断的最小集合：能定位到哪次运行（运行编号、流水线名称与版本、触发人与方式、提交哈希与分支）、能取回当时的产物（产物标识与校验值、配置版本、密钥引用名称）、能判断放行是否合规（准入结论、审批人与时间）。失败原因归类、依赖明细、覆盖率等按需字段可以后补。精简的前提是必留字段仍由流水线模板强制写入，而不是靠人记得填。随着发布频率上升或出现审计要求，再按需逐项增补，比一开始列几十个字段却无人维护更可持续。
流水线工具自动采集的字段和人工补录的字段冲突时，以哪个为准？
以自动采集的系统数据为准，人工补录只负责系统无法判断的业务含义。例如阶段状态与起止时间由流水线工具写入，人工不应改写；失败原因归类、变更单关联、回滚决策说明属于人的判断，由当次处理人填写。出现冲突时，保留原始采集值，人工说明写入单独的说明字段，并注明修改人与时间。若发现自动采集本身有误，应作为工具链配置问题单独跟踪修正，而不是逐次在记录里手工覆盖，否则记录会逐渐失去可信度。
日志和产物只留引用地址，审计时引用失效了怎么办？
引用失效意味着记录的可复现性被破坏，应视为不合格项处理。预防上可以做三件事：为引用保存校验值，便于判断内容是否被替换；日志与产物的留存期限不短于对应结构化记录的审计周期；清理下线版本产物前核对是否仍有审计或回溯需求。发生失效时，先确认是否有备份或归档副本，再在记录中标注失效原因与处理过程。若同类失效反复出现，需要调整留存策略或存储位置，而不是在单条记录上反复补救。
已经用了 ONES 管理需求和任务，执行记录里的关联字段还需要人工填吗？
可以大幅减少人工补录。ONES DevOps 解决方案支持集成 Jenkins、GitLab CI 等第三方流水线工具，集成后自动同步流水线数据、更新执行状态和日志，并在项目、迭代、需求中呈现代码提交、流水线构建与产品发布过程。因此“关联需求或变更单”这类字段可以直接从工作项关联中获得。同步的具体字段范围以实际集成为准，团队仍应在字段规范中明确哪些字段取自集成、哪些需要人工补录，并对集成中断的情况保留兜底做法。
