From 8b0fb0ff209236e287ba3606f2844b0a5e679e08 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 16 Jul 2026 10:03:56 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=9B=BA=E5=8C=96=20PaC=20=E7=A7=81?= =?UTF-8?q?=E6=9C=89=E6=BA=90=E4=B8=8E=E5=A4=A7=E8=BD=BD=E8=8D=B7=E8=BE=B9?= =?UTF-8?q?=E7=95=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/reference/platform-infra.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/reference/platform-infra.md b/docs/reference/platform-infra.md index 184a82b4..d53f5bbc 100644 --- a/docs/reference/platform-infra.md +++ b/docs/reference/platform-infra.md @@ -86,6 +86,18 @@ - CI/CD OTel endpoint、service/resource 属性、采样与 exporter timeout/failure policy 由 `config/platform-infra/pipelines-as-code.yaml` 引用现有 `config/platform-infra/observability.yaml` 并负责渲染。outer PaC 在最早可控 step 生成 W3C trace context，后续 source、image、artifact、GitOps 与 helper 复用同一 traceId；export 失败或超时只输出 `warning=true`、`blocking=false` 的有界事件，不改变 PipelineRun、TaskRun 或业务 step 终态。 - `config/platform-infra/pipelines-as-code.yaml` 可以声明多个 repository 和 consumer。`cicd status --node ` 用于 node 汇总，`history --target ` 用于全 consumer 审计，`status --target --consumer ` 用于 consumer 只读状态；不得跨 repository 混合 PipelineRun 或 env reuse 证据。 - PaC Repository CR `spec.url` 必须匹配 Gitea webhook payload 的 public repository URL；ClusterIP/service URL 只属于 `cloneUrl` 与 `params.git_read_url`。Repository params 必须使用该 consumer 的 node-specific snapshot prefix。 +- 私有 Gitea source checkout 必须复用 PaC Repository 已声明的 Secret： + - source-artifact binding 从 repository 直接投影 `secretName` 与 `tokenKey`，不得在 consumer params 或业务 owning YAML 重复声明； + - Tekton step 通过 `secretKeyRef` 和临时 `GIT_ASKPASS` 读取 token，禁止把 token 拼入 Git URL、PipelineRun 参数或日志； + - `GIT_ASKPASS` 必须在 step 退出时清理，生成清单只能披露 Secret 对象名与 key。 +- PaC bootstrap 的大型清单载荷不得作为导出环境变量传给远端子进程： + - 控制端先在权限为 `0700` 的临时目录解码载荷，只导出短路径； + - 远端脚本从路径读取并在退出时清理，兼容入口可以读取旧的内联载荷； + - 新增 release、admission、RBAC、ServiceAccount 或 Argo 载荷时必须进入同一文件传输集合，避免触发 Linux 单参数长度上限。 +- source-artifact consumer 的最短验证顺序固定为： + - 先执行 `source-artifact plan`，确认唯一 owner、source worktree 与预期漂移； + - 再执行 `source-artifact write --confirm` 和一次 `source-artifact check`，提交生成文件后只由正常 source PR merge 触发交付； + - 自动链终态后，在 clean exact-commit worktree 执行一次 `source-artifact verify-runtime`，同时证明源码、嵌入式 PipelineRun 与 provenance 对齐。 - GitHub 始终是 upstream write authority。Bridge 只允许 GitHub -> Gitea 更新 YAML 声明的 branch 与 immutable snapshot，不得反向写 GitHub，也不得增加 polling 或第二 trigger path。 - 每个 target 必须使用 YAML 独立声明的 webhook path、bridge 与 FRP port；多个节点不得复用 hook URL。Public Gitea Web UI 与 webhook 只能通过明确 Caddy path routing 共享 hostname，k8s 内部 consumer 必须使用 ClusterIP URL。 - Secret 或 ConfigMap 改变后，Gitea connector 的显式平台配置维护必须等待 workload rollout。成功写 Secret 不能证明 `frpc` 已加载新配置；端到端交付证据仍必须来自之后的新正常 PR merge。