pnpm – HDUO Lab

GitLab CI 默认的分布式缓存（基于 S3/MinIO）在面对单体巨型仓库（Monorepo）时极易成为性能毒药。本文复盘某次数十 GB 的 node_modules 频繁推拉导致 Runner 节点网络带宽打爆、流水线耗时飙升 400% 的故障。通过引入基于 zstd 压缩与本地 HostPath + S3 的分层缓存架构，结合精准的拉取策略，最终将平均构建时间从 18 分钟压降至 3 分钟以内。

现场：流水线大塞车与网卡被打爆

排查过程中，开发团队反馈前端 Monorepo（Node.js v18.17.0, pnpm v8.6.0）的 CI 流水线从平时的 4 分钟恶化到了近 20 分钟。大量 Job 处于 pending 状态，部分 Job 在 Restoring cache 阶段直接 Timeout 失败。

登录所在的 K8s 集群（GitLab Runner v16.3.0 运行于 Kubernetes Executor），挑一台底层 EC2 节点执行基础排查。Load Average 飙升至 60+，但 CPU User 态使用率并不高，主要集中在 SoftIRQ 和 I/O Wait。

通过 sar -n DEV 1 抓取网络指标，直接锁定死因：

$ sar -n DEV 1
10:15:01 AM     IFACE   rxpck/s   txpck/s    rxkB/s    txkB/s   rxcmp/s   txcmp/s  rxmcst/s
10:15:02 AM      eth0  345210.0  12140.0   452130.4   10240.2      0.0       0.0       0.0
10:15:03 AM      eth0  361021.0  13011.0   471821.1   11520.1      0.0       0.0       0.0

接收带宽达到了惊人的 ~460MB/s（接近 4Gbps），直接触及了该规格 EC2 实例的网卡突发吞吐上限。底层发生了严重的丢包和 TCP 重传。

进一步查看 Runner Pod 的日志：

Downloading cache.zip from https://s3.internal...
WARNING: Retrying...
ERROR: Downloading cache.zip failed: stream timeout

真相大白：超过 200 个并发 Job 同时向内部 S3 发起数百 MB 甚至上 GB 的 cache.zip 拉取请求，触发了典型的“缓存风暴”，直接将 Runner 集群的入带宽彻底打爆。

为什么默认的 GitLab 分布式缓存会演变成性能毒药？

在剖析解决方案前，必须搞明白 GitLab Runner 底层的缓存处理机制。

默认情况下，GitLab Runner 使用一个 helper image（基于 Alpine）来处理缓存。当你配置了 cache 关键字并使用 S3 作为 backend 时，它的工作流如下：

下载阶段：从 S3 下载 cache.zip。
解压阶段：使用默认的 unzip 工具将其解压到工作目录。
压缩与上传：Job 结束时，使用 zip 将目录重新打包，推回 S3。

这里存在三个致命缺陷：

第一，无脑全量网络 IO。 无论你的缓存内容是否发生实质性变化（比如 pnpm-lock.yaml 并未更改），默认配置下的 Job 都会全量下载整个 ZIP。对于 2GB+ 的 node_modules，每次 Job 调度都是一次对网络基础设施的强奸。

第二，单核 gzip 压缩效率极其低下。 GitLab 默认的 zip 工具使用 Deflate 算法，属于 CPU 密集型且单线程操作。当 Runner 节点上同时运行十几个并发 Job 时，CPU 的单核被打满，导致解压耗时甚至超过了网络下载时间。

第三，读写策略（Policy）滥用。 很多开发在 .gitlab-ci.yml 中直接全局定义了缓存，没有指定 policy，导致流水线中的 Lint、Test、Build 等所有下游 Job 执行完毕后，都会重新打包并上传一次毫无变化的缓存，产生海量无效写 I/O。

架构优化实战：分层缓存与降维打击

要彻底根治这个问题，单纯扩容网络带宽只是扬汤止沸，必须从压缩算法、存储介质和拉取策略三个维度进行工程化改造。

1. 降维打击：启用 zstd 与 Fastzip

从 GitLab Runner 14.x 开始，官方引入了 Fastzip 引擎，支持多线程压缩和 zstd（Zstandard）算法。zstd 能够在压缩率与 gzip 相当的情况下，提供 3-5 倍的解压速度，这对于大量小文件的 node_modules 场景是极其有效的。

必须在 Runner 的 config.toml 中通过特性开关（Feature Flags）显式开启：

# /etc/gitlab-runner/config.toml
[[runners]]
  name = "k8s-runner-optimized"
  executor = "kubernetes"
  environment = [
    "FF_USE_FASTZIP=true",           # 启用 Fastzip 引擎
    "ARTIFACT_COMPRESSION_LEVEL=fast", 
    "CACHE_COMPRESSION_LEVEL=fast"   # 配置为 fast，平衡 CPU 与带宽
  ]
  [runners.feature_flags]
    FF_USE_FASTZIP = true

开启后，观察日志中的输出，原先 Creating cache.zip 将会变成利用 fastzip 进行操作，解压 1.5GB 缓存的时间从 120 秒骤降到了 25 秒。

2. L1/L2 分层缓存架构设计 (本地 Store + S3 Fallback)

针对 pnpm/npm/yarn 的 Monorepo 场景，最有效的手段是绕过项目级的网络缓存，直接利用包管理器的全局 Store 作为 L1 缓存。S3 仅作为 L2 的灾备补充。

我们在 K8s Runner 中挂载一个跨 Pod 共享的本地 PVC（或 HostPath，配合节点亲和性），将 pnpm 的全局缓存指向该目录：

# config.toml 中的 K8s volumes 配置
[runners.kubernetes]
  [[runners.kubernetes.volumes.host_path]]
    name = "pnpm-store"
    mount_path = "/var/cache/pnpm"
    host_path = "/data/gitlab-runner-cache/pnpm"

在项目的 .gitlab-ci.yml 中，调整缓存策略：不再缓存巨型的 node_modules，而是缓存 metadata。安装依赖时，pnpm 会直接通过硬链接（Hardlink）从 L1 本地挂载卷中极速生成 node_modules，完全不消耗网络带宽。

variables:
  # 将 pnpm store 指定到本地持久化挂载目录
  PNPM_STORE_PATH: /var/cache/pnpm

.cache_template: &cache_template
  cache:
    # 使用 lock 文件计算 hash 作为精确的 Cache Key
    key:
      files:
        - pnpm-lock.yaml
    # 仅在下游依赖这个小巧的 metadata 缓存，摒弃 node_modules
    paths:
      - .npm/
    # 默认只拉取，杜绝无效推回 S3
    policy: pull

install_dependencies:
  stage: .pre
  <<: *cache_template
  cache:
    # 只有安装依赖的 Job 才允许 Push 缓存
    policy: pull-push
  script:
    - pnpm config set store-dir $PNPM_STORE_PATH
    - pnpm install --frozen-lockfile

3. 严格的 Policy 与精准 Key 控制

上述配置中，核心理念在于防御性 CI 编写：

按需读写：除了 install 阶段拥有 pull-push 权限，后续的 lint、test、build 阶段一律配置为 policy: pull。
精确摘要：使用 files 提取特定锁文件的 hash 值作为 key。只要 pnpm-lock.yaml 不变，缓存哈希就不会变，避免因分支名改变引发的缓存击穿。

改造完成后，重跑压测。node_modules 的构建全靠本地 HostPath 的 pnpm store 硬链接瞬间完成，S3 的网卡吞吐量从 4Gbps 暴降至不到 50Mbps，流水线耗时稳定在 3 分钟以内，彻底告别了网络 I/O 导致的阻塞假死。

常见问题

Q: K8s Executor 模式下，Pod 是随机调度到不同节点的，HostPath 缓存无法命中怎么办？ A: 这是分层缓存常遇的痛点。你有两种解法：1. 通过 runners.kubernetes.node_selector 将这批 Runner 固定在一组专门的构建节点上（例如 3-5 台），HostPath 在这几台节点上预热后命中率极高；2. 如果集群完全弹性，使用高性能的内部 NFS/CephFS 挂载 PVC 替代 HostPath，虽然有一定网络开销，但内网原生文件系统的高速缓存依然远胜基于 HTTP(S) 的 S3 ZIP 推拉。

Q: 开启 Fastzip 和 zstd 后，发现 Runner 所在节点的 CPU Load 依旧很高，如何排查？ A: zstd 虽然解压快，但在高压缩比下依然吃 CPU。检查你环境变量中的 CACHE_COMPRESSION_LEVEL 配置。GitLab 提供 fastest, fast, default, slow, slowest。对于 CI 场景，强烈建议配置为 fastest 或 fast。CI 缓存的核心是“用一点网络开销换取宝贵的计算时间”，不要试图在 CI 里追求极限压缩率。可以使用 pidstat -t 1 确认是否是 gitlab-runner-helper 进程内的多线程吃满了 CPU。

Q: 跨分支的高并发构建导致 S3 缓存经常被相互覆盖损坏，怎么解决？ A: 必须使用回源策略（Fallback Keys）。在 GitLab 15.0+ 之后，引入了 fallback_keys 功能。主分支维护一份全量缓存，特性分支使用自己的 Key，如果没命中，自动回退拉取主分支的缓存：

cache:
  key: "$CI_COMMIT_REF_SLUG-pnpm"
  fallback_keys:
    - "main-pnpm"

这样既保证了缓存的命中率，又避免了不同分支依赖冲突时的互相毒化。

标签： pnpm

深入 GitLab CI 陷阱排查：单体仓库缓存风暴引发的 Runner 网络拥塞与分层缓存优化实战