PR路径上cache token只读、buildkit把cache export失败当致命错误，多架构构建全挂怎么绕？

目录

一、导语：一次"非致命"错误如何击穿整条流水线

典型的失败现场往往长这样：维护者在 PR 上看到 buildx bake 或 docker/build-push-action 的日志末尾出现 ERROR: failed to solve: failed to push ghcr.io/...: denied: permission_denied 或 failed to export cache: unexpected status code 403 Forbidden，随后 job 以红色失败告终。诡异之处在于：镜像本身可能已经成功构建，甚至部分平台已经推送成功，真正失败的只是"缓存导出"这一步。然而 BuildKit 的默认语义把这一步视为构建事务的一部分，一旦失败即整体回滚并返回非零码。

更麻烦的是多架构场景。多平台构建通过 --platform linux/amd64,linux/arm64,... 触发 BuildKit 的扇出（fan-out）执行，每个平台独立求解、独立导出缓存。只要其中任一平台的 cache export 失败，整个 solve 图就被判定失败。于是"fork PR 只读 token"这一权限事实，经由"cache export 失败即致命"这一错误语义，被"多架构扇出"放大成整条流水线全挂。

笔者认为，这个问题的本质不是某个工具的 bug，而是权限模型、错误语义与并行扇出三者耦合后产生的系统性脆弱。单独修任何一环都不够：只改权限，fork PR 依然拿不到写权限；只改错误语义，缓存仍然写不进去；只改扇出策略，失败面只是缩小而非消除。因此本文确立一条贯穿全文的分析主线——"三元耦合"——并沿这条主线给出分层绕行路径。

本文评述：社区中大量"把 ignore-error 打开就好了"的经验帖，实际上只处理了第二元（错误语义），却掩盖了第一元（权限）与第三元（扇出）的持续存在。这种"止痛不治病"的做法在缓存命中率下降时会以更隐蔽的方式反噬——构建变慢、配额消耗上升、日志噪声增加。下文会量化这一代价。

二、背景与问题定义：权限、错误语义与多架构扇出

2.1 权限边界：fork PR 的只读 token 是设计而非缺陷

GitHub Actions 对来自 fork 的 pull_request 事件默认采用受限权限模型：GITHUB_TOKEN 为只读，且不注入仓库 Secrets。这一设计的目的在于防止恶意 PR 通过修改工作流文件窃取凭据或污染制品。官方文档在 "Security hardening for GitHub Actions" 与 "Permissions for the GITHUB_TOKEN" 两处均有明确说明。换言之，PR 路径上无法向 GHCR 推送，是预期行为，不是配置错误。

与之相对，pull_request_target 事件虽然拥有写权限，但它运行的是基分支上的工作流定义，且会暴露 Secrets，历史上多次成为供应链攻击的入口（如 2021 年前后多起 Actions 投毒事件）。因此"为了能推缓存就把触发器换成 pull_request_target"是一条危险捷径，本文不推荐将其作为默认方案。

需要区分三类 token 语义：GITHUB_TOKEN（仓库级、短期、受 permissions 块约束）、PAT / GitHub App token（可跨仓库、权限更宽）、以及 registry 自身的 robot account（如 GHCR 的 GITHUB_TOKEN 或独立 PAT）。PR 路径上的只读性主要来自第一类，绕行方案的设计必须明确"用哪一类身份、在哪个事件下、写哪个后端"。

2.2 错误语义：cache export 为何被当作致命错误

BuildKit 的构建过程可抽象为一个求解图（solve graph），每个节点产出结果（result），最终由 exporter 将结果写入目标后端。缓存导出（cache exporter）在实现上挂接在 solve 的收尾阶段，与镜像导出共享同一事务边界。当 --cache-to 指定的后端返回错误时，BuildKit 默认将其视为 solve 失败，返回非零退出码。

这一语义有其合理性：在"缓存即制品"的假设下，缓存写入失败意味着构建产物不完整。但对 CI 场景而言，缓存本质上是性能优化而非正确性依赖——缓存缺失只会导致下次构建变慢，不会导致镜像错误。语义假设与使用场景的错配，正是故障的根源之一。

BuildKit 提供了 --cache-to type=registry,ignore-error=true 这一开关（在 buildx 中对应 cache-to 的 ignore-error 属性），用于把导出失败降级为警告。但该开关的粒度是"整个 cache exporter"，无法区分"权限拒绝"与"网络抖动"——前者应静默降级，后者或许应重试。这一粒度不足是后文方案设计需要处理的关键约束。

2.3 多架构扇出：失败面的乘法效应

多平台构建通过 --platform 列表触发 BuildKit 的并行求解。每个平台拥有独立的求解子图与独立的 cache exporter 实例。设平台数为 n，单平台 cache export 失败概率为 p（在只读 token 下 p 接近 1），则整条流水线失败概率为 1 − (1 − p)ⁿ。当 p = 0.9、n = 4 时，失败概率约为 99.99%。这就是"全挂"的数学解释。

更隐蔽的是部分成功状态：某些平台先完成导出并推送，另一些平台失败，导致 registry 中留下不完整的 manifest list。若下游有 docker pull 按 digest 拉取，可能遇到 "no matching manifest for linux/arm64" 之类的错误。因此绕行方案不仅要让流水线变绿，还要保证制品状态的一致性。

表 1：PR 路径与主分支路径的权限—缓存对照（依据 GitHub 官方权限文档整理）

三、原理拆解：BuildKit 缓存导出的事务模型与失败传播

3.1 求解图与 exporter 的挂接点

BuildKit 前端（frontend）将 Dockerfile 解析为 LLB（Low-Level Build）指令图，后端（solver）对图进行调度与执行。执行完成后，结果通过 exporter 写出。缓存导出器（cacheexporter）与镜像导出器（imageexporter）在 solve 收尾阶段被依次调用。关键点在于：二者共享同一个 Solve 调用的返回路径，任一 exporter 返回 error，整个 Solve 即返回 error。

本文评述：这一设计在单机开发场景下合理——开发者希望"缓存没写成功"能被立即感知；但在 CI 场景下，缓存是跨 job、跨事件的共享资源，其写入失败不应影响当前 job 的制品产出。BuildKit 后来引入的 ignore-error 正是对这一错配的补丁，但补丁的粒度问题（见 2.2）仍未彻底解决。

3.2 多平台扇出下的失败传播路径

以 docker buildx bake 为例，多平台构建在内部被展开为多个 solve 实例（或一个 solve 内的多平台子图，取决于 buildx 版本与 driver）。每个实例独立执行 cache export。失败传播路径可概括为：

platform(amd64) → solve → cache export → 403 → error
platform(arm64) → solve → cache export → 403 → error
                      ↓
              bake 汇总 → 非零退出码 → job 失败
                      ↓
        registry 中可能残留不完整 manifest list

注意"可能残留"这一措辞：是否残留取决于镜像导出与缓存导出的相对顺序，以及 registry 的 manifest 提交语义。不同 buildx 版本、不同 driver（docker-container / kubernetes / remote）下行为存在差异，这正是该问题难以用单一补丁根治的原因。

3.3 缓存后端的类型与权限要求

BuildKit 支持多种 cache 后端，其权限要求差异显著：

表 2：cache 后端的权限要求与 PR 路径可用性（依据 BuildKit 与 buildx 官方文档整理）

这张表揭示了一个关键事实：在 fork PR 的只读约束下，没有任何"写远端"的缓存后端是天然可用的。因此绕行的核心不是"换一个后端"，而是"改变缓存写入的时机与身份"。

四、四层绕行方案：从流水线分级到自托管缓存

本节给出可落地的操作路径，按"侵入性从小到大"排序。读者可单独采用任一层，也可组合使用。每层均给出具体配置片段与适用边界。

4.1 第一层：流水线分级——PR 只验证，主分支才写缓存

最直接的做法是把"写缓存"从 PR 路径剥离。PR 路径只做构建验证（--load 或 --output type=cacheonly），主分支路径才执行 --cache-to 与 --push。这样 PR 路径根本不触发 cache export，自然不会被其失败拖垮。

# PR 路径：只构建，不导出缓存
- name: Build (PR, verify only)
  if: github.event_name == 'pull_request'
  uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: false
    cache-from: type=gha
    # 注意：不写 cache-to

# 主分支路径：构建 + 推镜像 + 写缓存
- name: Build (main, push + cache)
  if: github.event_name == 'push'
  uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    cache-from: type=gha
    cache-to: type=gha,mode=max

这一层的优点是零风险、零额外基础设施；缺点是 PR 路径无法贡献缓存，长期看主分支缓存的新鲜度依赖主分支构建频率。笔者认为，对于大多数中小团队，这一层已经能解决 80% 的痛点，应作为默认起点。

4.2 第二层：缓存策略降级——ignore-error 与只读 cache-from

若确实需要在 PR 路径尝试写缓存（例如使用 type=gha，其在 fork PR 下的行为与 registry 不同），应显式打开 ignore-error，把导出失败降级为警告：

- name: Build (PR, best-effort cache)
  uses: docker/build-push-action@v6
  with:
    platforms: linux/amd64,linux/arm64
    push: false
    cache-from: type=gha
    cache-to: type=gha,mode=max,ignore-error=true

需要强调的是，ignore-error 只解决"失败被当作致命"这一语义问题，不解决"缓存写不进去"这一事实问题。它会让流水线变绿，但缓存命中率不会因此提升。本文评述：把 ignore-error 当作唯一手段，等于用日志噪声换流水线绿灯，长期会掩盖缓存策略的真实健康度。建议同时采集 cache export 的成功率指标（见 5.3）。

此外，cache-from 在只读 token 下通常仍可工作（读取公开或同仓库的缓存），因此 PR 路径应保留 cache-from，以最大化复用主分支产出的缓存。

4.3 第三层：身份切换——用受信任事件写缓存

若希望 PR 的构建结果也能贡献缓存，可采用"两段式"：PR 路径只构建并上传构建上下文摘要（或直接跳过），由受信任的后续事件（如 push 到主分支、或维护者手动触发的 workflow_dispatch）执行真正的 cache export。这一模式在安全性与缓存收益之间取得平衡。

具体实现上，可用 workflow_run 事件串联：PR 工作流完成后触发一个受信任工作流，后者在基分支上下文中运行，拥有写权限。但需注意 workflow_run 的上下文隔离与 artifact 传递细节，避免把不可信制品带入受信任流程。相关机制可参考 GitHub 官方文档 "Events that trigger workflows" 中 workflow_run 一节。

安全提示：任何"让 PR 获得写权限"的方案都必须回答一个问题——恶意 PR 能否借此污染缓存或镜像？若缓存键可被 PR 控制，攻击者可能投毒缓存层。因此第三层的实现必须配合缓存键的命名空间隔离（如按 github.ref 或 github.event.pull_request.number 分区）。

4.4 第四层：自托管缓存后端——把写权限留在内网

对于构建量大、缓存收益显著的团队，可部署自托管缓存后端（如 registry 的 pull-through cache、S3 兼容存储、或 BuildKit 的 remote driver 配合内网 registry）。PR 路径通过内网只读凭据读取缓存，写操作由受信任的 runner 在受控网络中完成。这一层成本最高，但能同时解决权限、语义与扇出三个问题。

一个常见的落地组合是：GitHub Actions 的 self-hosted runner + 内网 Harbor/Registry + type=registry 缓存。runner 位于内网，凭据由 runner 的环境注入而非 GitHub Secrets，从而绕开 fork PR 的 Secrets 限制。需注意 runner 的隔离与清理策略，防止跨 PR 的缓存污染。

拓展阅读：BuildKit 官方文档的 cache 配置章节（docs.docker.com/build/cache/backends）与 buildx 的 GitHub Actions 示例（github.com/docker/build-push-action）是排查此类问题的一手资料。

五、关键数据、案例与可验证的对照实验

5.1 失败概率的量化模型

前文给出失败概率公式 1 − (1 − p)ⁿ。为便于工程估算，下表列出不同 p 与 n 组合下的失败概率（模拟数据，基于公式计算，非实测）：

表 3：多平台扇出下的流水线失败概率（模拟数据，按 1−(1−p)ⁿ 计算）

该模型的价值不在于精确预测，而在于说明：在只读 token 下，平台数越多，失败越接近必然。因此"减少平台数"本身也是一种缓解手段——例如 PR 路径只构建 amd64，主分支才构建全平台。

5.2 案例：一次典型的 PR 全挂复盘

某开源项目在引入 arm64 支持后，PR 流水线失败率从约 5% 升至接近 100%。日志显示 amd64 构建成功、arm64 构建成功，但两者在 cache export 阶段均返回 403。根因是工作流在 PR 路径上配置了 cache-to: type=registry,ref=ghcr.io/org/app:buildcache，而 fork PR 的 GITHUB_TOKEN 无 push 权限。

修复采用第一层 + 第二层组合：PR 路径移除 cache-to，保留 cache-from；主分支路径保留 cache-to 并加 ignore-error=true 作为兜底。修复后 PR 失败率回落至基线，主分支缓存命中率未受显著影响（因主分支构建频率足以维持缓存新鲜度）。

本文评述：该案例的教训不是"要加 ignore-error"，而是"缓存写入策略必须与事件权限模型对齐"。很多团队在本地或主分支验证通过后，直接把同一份 build 配置复制到 PR 路径，忽略了权限差异，这是此类故障的高频成因。

5.3 可观测性：把 cache export 成功率变成指标

无论采用哪一层方案，都建议采集 cache export 的成功/失败计数。实现方式可以是在工作流中解析 buildx 日志，或使用 buildx 的 --metadata-file 输出。一个简化的日志解析脚本如下：

#!/usr/bin/env bash
# 统计 buildx 日志中的 cache export 结果（示例）
LOG="$1"
ok=$(grep -c "exporting cache" "$LOG" || true)
fail=$(grep -c "failed to export cache" "$LOG" || true)
echo "cache_export_ok=$ok cache_export_fail=$fail"
# 建议将结果写入 CI 的 metrics 后端，按周聚合

该脚本仅为示意，实际日志格式随 buildx 版本变化，需按版本调整正则。笔者认为，把"缓存健康度"纳入 CI 可观测性，是比任何单点修复都更长久的治理手段。

六、对比与局限：各方案的边界条件

四层方案并非互斥，而是适用于不同阶段。下表给出对比：

表 4：四层绕行方案的对比（笔者根据工程经验整理）

需要指出的是，本文未覆盖所有 CI 平台。GitLab CI、Azure Pipelines 等的权限模型与缓存机制不同，但"权限 × 语义 × 扇出"的分析框架可迁移。例如 GitLab 的 fork MR 默认不暴露受保护变量，与 GitHub 的只读 token 在效果上类似，绕行思路亦相通。

另一个局限是版本差异。BuildKit 与 buildx 迭代较快，ignore-error 的行为、多平台扇出的实现细节在不同版本间可能变化。本文建议在升级 buildx 时，专门回归测试 PR 路径的 cache export 行为，避免"升级后突然全挂"。

七、结论与展望

回到最初的问题：PR 路径上 cache token 只读、BuildKit 把 cache export 失败当致命错误、多架构构建全挂，怎么绕？本文的答案是分层的：先用流水线分级把写缓存从 PR 路径剥离，再用 ignore-error 兜底语义，必要时用身份切换或自托管后端 reclaim 缓存收益。四层不是四选一，而是按团队成熟度递进。

更长远地看，这一问题的根治依赖两个方向的演进：其一，CI 平台的权限模型能否提供"受限写"能力（例如仅允许写缓存命名空间、不允许写镜像 tag），从源头消除权限与缓存的冲突；其二，BuildKit 能否提供更细粒度的错误策略（如按错误类型区分重试、降级、致命），而非当前的全局开关。本文评述：前者是平台责任，后者是工具责任，二者缺一不可。

在等待上游演进的同时，工程团队能做的是把"缓存健康度"变成可观测、可回归的指标，并在流水线设计阶段就把权限模型纳入考量。毕竟，最贵的不是一次构建失败，而是把一次本可预期的权限冲突，误诊为随机故障，反复排查数周。

主要参考文献