mirrors/pikasTech-unidesk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d18a8f1e81310c619545f8b50379973c962e09aa
pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010601-controlled-release.md
T
pikastech a47fd7c504 fix: 统一发布计划与 webhook identity
2026-07-21 15:50:28 +02:00

18 KiB
Raw Blame History

PJ2026-010601 发布流水

修改历史

版本 对应 commit id 更新日期 变更说明

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 待提交 版本。

正文

PJ2026-010601 发布流水需求规格

1. 文档控制

字段 内容
编号 PJ2026-010601
短名 发布流水
层级 L2 课题
状态 已生效
需求规格模板 ISO/IEC/IEEE 29148 需求规格模板
上级规格 PJ2026-0106 平台运维
规格治理索引 规格治理

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留受控发布、版本 lane、CI/CD、运行面发布判定和发布入口的通用稳定使命、范围、术语、系统边界、内部分工和原子需求。

2. 目的和范围

2.1 目的

发布流水负责把 HWLAB 平台服务从 source commit 通过受控 CI/CD、镜像、GitOps 和 rollout 交付到目标 runtime，使发布状态、运行版本、镜像来源和发布判定可追踪、可恢复、可审查。具体服务的固定 branch、namespace、pipeline、镜像、验证组合和 lane 数值只进入对应服务专项规格，不写成通用发布规则。

2.2 范围内

  • HWLAB 各服务 lane 的通用发布模型、runtime namespace、CI pipeline、GitOps promotion 和 rollout 入口。
  • Tekton PipelineRun、Argo CD sync、runtime image、env image reuse、digest-pinned image 和 artifact promotion。
  • 发布候选判定中 source revision、GitOps desired state、runtime live state、Postgres migration、SecretRef presence 和 workload readiness 的一致性。
  • UniDesk 受控 CI/CD CLI、服务自有 CLI 和服务 health/readiness 在发布验收中的正式入口边界。
  • 自测试和综合联调在发布决策中的分层口径：自测试允许 mock，综合联调必须使用真实运行面。

2.3 范围外

  • Git mirror、source commit authority、bundle/mirror URL 和 artifact catalog 的来源真相归 源码同步。
  • YAML 配置、SecretRef sourceRef/targetKey、fingerprint 和受控下发归 YAML运维。
  • 具体服务的业务执行事实归对应业务规格；AgentRun run、command、event、runner job 和 terminal status 归 AgentRun核心，AgentRun v0.1 专项发布 lane 归 AgentRun发布Lane。
  • RuntimeAssembly、AipodSpec、gitbundle 和 Secret projection 归 Runtime装配。
  • Backend adapter、provider profile 和真实 provider turn 语义归 后端Profile。
  • 一次性排障、长日志、PR 过程、证据堆叠和文档治理规则不进入本规格正文。

3. 术语表

术语 定义
发布流水 从 source commit 到目标 runtime 的受控构建、promotion、GitOps sync、rollout 和发布状态查询链路。
版本 lane 按版本隔离的 source branch、runtime namespace、GitOps branch、CI pipeline 和发布验收集合。
PipelineRun Tekton 中执行构建、镜像发布或 GitOps promotion 的一次流水线运行。
GitOps desired state GitOps branch 中声明的目标运行面资源状态。
runtime live state 目标 namespace 中实际运行的 workload、image、config、health 和 readiness 状态。
env image reuse 基础执行环境镜像按 env identity 复用，普通业务源码变更只改变 boot commit。
发布计划 对精确 source commit 和目标 lane 的只读发布影响分析，至少包含 env reuse、待构建镜像、rollout 服务和范围变化。
手动发布触发 操作者审阅发布计划后，通过受控 CLI 向 PaC 发送 webhook，由 PaC 创建 commit-pinned PipelineRun 的唯一发布 mutation。
综合联调 在真实目标运行面、真实 SecretRef、真实 backend/provider 或服务入口上完成的发布候选验证。

4. 系统边界和接口

本规格把发布流水作为平台运维内的服务交付系统看待；本章只描述输入、输出和责任边界。

边界项 内容
外部使用者 平台管理员、发布操作人员、服务维护者和需要发布状态的业务模块。
外部输入 source commit、deploy 配置、lane 选择、发布计划请求、带 plan identity 的手动触发请求、SecretRef presence 和验证请求。
受控资源 Tekton PipelineRun、Argo Application、runtime namespace、workload、image、release status、health/readiness 和发布判定结果。
外部输出 PipelineRun 状态、image digest、promotion revision、Argo sync 状态、runtime readiness、发布候选结论和 redacted 失败信息。
用户接口 UniDesk CI/CD CLI、服务自有 CLI 发布/验证相关入口、服务 health/readiness、Tekton/Argo 受控状态查询入口。
系统边界 发布流水负责让变更以可追踪、可恢复、可判定的方式进入运行面；不替代业务功能实现，不绕过受控 CLI，不把 mock 或 source-only 结果当作发布通过。

5. 内部分工与规格索引

本规格前四个 L3 只承载服务无关的通用发布规则。AgentRun 固定 branch、namespace、Pipeline、GitOps path、真实 provider turn 等内容只在 AgentRun 专项 L3 中展开，通用发布条款只保留可复用的发布边界。

编号 模块或课题 规格文档 主责边界 上游依赖 下游支撑
PJ2026-01060101 Lane发布 本规格 6.1 source/GitOps/runtime namespace、CI pipeline 和 rollout 入口 源码同步、YAML运维 全部 runtime 服务
PJ2026-01060102 镜像Promotion 本规格 6.2 env image reuse、digest-pinned image、artifact promotion 和 image readiness Source commit、Containerfile、registry 需要运行镜像的服务
PJ2026-01060103 发布判定 本规格 6.3 source/GitOps/runtime 一致性、health/readiness 和 migration/SecretRef presence CI/CD、GitOps、YAML运维 平台管理员、业务模块
PJ2026-01060104 验证分层 本规格 6.4 自测试、综合联调、CLI/API 交互和真实运行面通过口径 目标 runtime、业务模块测试需求 发布决策
PJ2026-01060108 手动发布 本规格 6.5 L2/L3 发布计划、范围审阅和带 plan identity 的受控手动触发 源码同步、YAML运维、镜像Promotion 全部 L2/L3 runtime 服务
PJ2026-01060105 AgentRun发布 PJ2026-01060105 AgentRun发布Lane AgentRun v0.1 的发布 lane、Pipeline、runtime namespace 和真实联调细则 源码同步、YAML运维、Agent编排 AgentRun runtime
PJ2026-01060106 HWLAB双环境 PJ2026-01060106 HWLAB双环境 HWLAB v0.3 development 与 release production 的分支、流水线、公开入口和数据隔离 源码同步、YAML运维、Workbench实时权威 HWLAB runtime
PJ2026-01060107 NC01 CI资源治理 PJ2026-01060107 NC01 CI资源治理 NC01 构建并发、排队、资源合同、稳定去重和核心运行面保护 发布流水、YAML运维、CI/CD目标治理 NC01 CI 与核心服务

6. 原子需求

6.1 OPS-RELEASE-REQ-001 版本 Lane 发布

编号 短名 主责模块 关联模块
OPS-RELEASE-REQ-001 Lane发布 PJ2026-01060101 Lane发布 源码同步、YAML运维、Agent编排

发布流水应为 HWLAB 平台服务提供版本 lane 发布能力，使 source branch、runtime namespace、GitOps branch、CI pipeline 和 rollout 入口相互隔离。

具体服务的 lane 固定值、历史口径废弃项和运行面名称应写入对应服务专项规格；通用发布流水只定义隔离、受控入口、可追溯和不可绕过原则。

CI/CD 目标必须由当前 issue、PR、CLI 参数或受控 lane 配置解析为明确 node + lane。G14 DEV/PROD、G14 v0.2、D601 v0.3 和后续 lane 都只是实例，不得把某个节点、namespace、GitOps path、FRP 端口或历史 dev/prod 口径写成通用默认。发布流水只能作用于被选中的 node/lane，不接管其他运行面。

6.2 OPS-RELEASE-REQ-002 镜像与 Promotion

编号 短名 主责模块 关联模块
OPS-RELEASE-REQ-002 镜像Promotion PJ2026-01060102 镜像Promotion 源码同步、Runtime装配

发布流水应提供镜像构建、env image reuse、digest-pinned image 和 GitOps promotion 能力，使运行面使用的镜像能够追溯到 source commit、Containerfile、env identity 和 artifact 摘要。

需要 work-ready env image 的服务应在自身专项规格中声明工具和依赖要求；通用发布流水只保证镜像来源、digest、promotion 和运行面引用可追溯，不替业务模块定义运行时功能。

Artifact catalog 的 per-service provenance 是镜像 digest 的身份证明，必须能说明 source commit、component input hash、Containerfile hash、build args hash、base image identity、reuse/build 状态和最终 digest。复用旧 artifact 前必须能证明旧 digest 对应的 source tree 与本轮输入一致；缺 digest、缺 provenance 或 hash 不一致时应重新发布，不得用旧 guard、历史 PipelineRun 成功或 mutable tag 伪装通过。

6.3 OPS-RELEASE-REQ-003 发布一致性判定

编号 短名 主责模块 关联模块
OPS-RELEASE-REQ-003 发布判定 PJ2026-01060103 发布判定 源码同步、YAML运维、Agent编排

发布流水应以 source revision、GitOps desired state、runtime live state、image digest、workload readiness、Postgres migration、SecretRef presence 和 service health/readiness 的一致性判断发布候选。

PipelineRun 成功、Argo Synced、health 可访问或 source check 通过都不能单独替代业务运行面通过。发布判定只能输出 redacted 状态和摘要，不得包含 provider credential、Postgres DSN password、token、URL credential 或 Secret value。

  • CI/CD 发布就绪只承担最小运行面联通判定：
    • 服务 probe 只调用不依赖数据库、Temporal、外部 provider 或业务数据的 live endpoint；
    • rollout gate 只要求目标 source identity 已进入计划内 workload，且期望副本已 updated 和 ready；
    • Argo 聚合 Healthy、业务依赖 readiness 和用户功能验证只能作为发布后独立证据，不得延长或阻塞 CI/CD rollout；
    • 业务综合联调仍按本规格 6.4 独立执行，不得回填到 Kubernetes readiness 或 CI/CD health gate。

6.4 OPS-RELEASE-REQ-004 两层验证口径

编号 短名 主责模块 关联模块
OPS-RELEASE-REQ-004 验证分层 PJ2026-01060104 验证分层 Agent编排、客户端、HarnessRL

发布流水应区分组件自测试和综合联调：自测试允许 mock，用于快速反馈；综合联调必须在真实目标运行面、真实依赖、真实配置和服务原入口上完成。

mock、fake dependency、source-only、dry-run、缺关键配置时的 skip、只读 health 成功或没有真实业务终态的运行面状态，都不能作为综合联调或发布通过证据。具体服务需要哪些真实依赖和终态，由对应服务专项规格定义。

6.5 OPS-RELEASE-REQ-005 L2/L3手动计划与触发

编号 短名 主责模块 关联模块
OPS-RELEASE-REQ-005 手动发布 PJ2026-01060108 手动发布 源码同步、YAML运维、NC01 CI资源治理

L2 与 L3 发布必须使用 plan -> 人工审阅 -> trigger 的受控手动链。PR merge、push、branch update、mirror 同步、定时任务和 L0/L1 开发动作只能更新 source authority 或只读状态，不得创建 PipelineRun、构建镜像、推进 GitOps 或触发 rollout。

plan 必须是只读操作，并针对精确 target、lane 和 source commit 输出：env identity 及 reuse/build 判定、待构建镜像数量与服务列表、待 rollout 服务、全部受影响服务、范围基线和相对基线新增项。plan 不得同步 mirror、创建 snapshot、修改 branch、创建 PipelineRun 或写入运行面。

  • plan identity 必须由规范化的计划输入与执行范围确定：
    • 输入至少绑定 target、consumer、lane、source commit、base commit、catalog authority、catalog source、catalog digest、registry probe 模式和结果；
    • 执行范围至少绑定 build、rollout 和 affected 服务列表；
    • 列表与对象键必须规范排序，时间戳、临时路径和运行编号不得参与 identity；
    • 相同输入与范围必须产生相同 identity，任一绑定输入或范围变化必须产生不同 identity。
  • trigger 必须显式携带操作者刚审阅的 plan identity：
    • 发送 webhook 前必须用当前 source、base、catalog 和 registry 输入重新生成计划；
    • 重算 identity 与已审阅 identity 不一致时不得发送 webhook；
    • webhook 只携带规范化计划事实，不引入可变计划存储或第二 authority。
  • Pipeline 必须在 build 前用同一组输入重新生成计划：
    • 实际 identity 与 webhook 携带的已审阅 identity 不一致时立即失败；
    • build、rollout 或 affected 范围任一扩大时必须输出 expected、actual 和新增服务；
    • identity 校验通过前不得启动镜像构建，CLI 显示 build=0 时 Pipeline 不得构建镜像；
    • 不得通过补跑、提高 timeout、忽略 warning 或继续后续 Task 绕过该失败。

plan 恢复 artifact catalog 时必须满足：

  • 读取 owning YAML 声明的 GitOps read URL 与 branch；
  • 与 Argo 和 promotion 使用同一 GitOps authority；
  • Source mirror 只用于读取 source commit，不得代替 GitOps authority；
  • catalog 无法读取、来源不一致或落后于已部署 revision 时，停止触发并返回重新 plan 的只读引导。
  • 发布范围基线必须来自 catalog source：
    • 调用方省略 base commit 时，必须使用恢复出的 catalogSourceCommitId；
    • 禁止静默回退到 source commit 的 parent；
    • 显式 base commit 只覆盖请求范围诊断，输出必须同时披露 catalog source 和两者是否对齐；
    • 缺少有效 catalog source 时必须保持只读并 fail closed，不得猜测 parent 或创建 PipelineRun。

范围相对 owning YAML 声明的发布意图扩大时，plan 必须明确列出新增项。操作者应先修正源码、配置或 planner，使范围回到预期后重新生成计划；不得通过确认参数、白名单、忽略 warning 或扩大资源预算继续触发。

  • 依赖与 component path 重叠时必须保持同一语义判定：

    • package.json 只按 dependencies、engine 和模块类型等运行字段参与服务范围与 hash；
    • scripts、格式或其他开发元数据变化不得因 owning YAML 重复声明 package.json 而进入服务 changed paths；
    • planner hash 算法升级后，必须从 catalog source commit 按新算法重算并识别 metadata drift；
    • source tree 在新算法下未变化时不得把 metadata drift 判为构建或 rollout。

  • build=0、rollout=0 且 affected=0 的计划是终态 no-op：

    • 不得发送 webhook 或创建 PipelineRun；
    • 动态 next 必须明确结束，不得指向 release trigger。

  • Renderer rollout 范围必须对应实际 GitOps Pod template diff：

    • renderer 重建完整 runtime tree 并改写未选 workload 的 source identity 时，plan 必须把全部实际受影响 workload 计入 rollout；
    • 只有未选 workload 的 manifest 和 source identity 均保持不变时，才允许显示局部 rollout；
    • renderer 入口拆分到子模块后，全部参与 runtime materialization 的源码路径仍必须属于 planner 的 renderer 输入集合。

唯一 mutation 是受控手动 trigger。它必须显式选择 target、lane、精确 source commit 和 pipeline intent，并向 PaC 发送 webhook；PaC 从同一 source authority 创建 commit-pinned PipelineRun。触发前必须先审阅当前输入的非空 plan；计划输入或范围已变化时必须重新 plan。禁止对零范围 plan 触发，禁止 CLI 直建或裸创建 PipelineRun、由 PR 合并回调 trigger，或为兼容旧自动链保留第二入口。

trigger 被 PaC 接收后，动态 next 必须指向同一 source commit 的只读 delivery-observe。不得引导旧 closeout、自动同步、人工 PipelineRun 或 Argo mutation；触发失败或输入变化时只能回到重新 plan。

  • 手动发布耗时必须按 owning YAML 预算判定：
    • 起点是 CLI webhook 被 PaC durable admission 接收的时间，PR merge 到人工 trigger 的等待不计入发布耗时；
    • 终点是 GitOps promotion 完成且计划内 workload 达到最小运行面联通就绪；
    • env 和服务 artifact 均复用且 build、rollout、affected 全为零时必须以 no-op 结束，不创建 PipelineRun；
    • 超出预算时必须输出 trigger、prepare、plan、build、collect、promote 和 rollout 的可用阶段耗时、最慢阶段与缺失证据，然后停止；
    • 禁止通过提高 timeout、增加业务 health 检查或重复触发掩盖超预算。
Reference in New Issue View Git Blame Copy Permalink