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"
这样既保证了缓存的命中率，又避免了不同分支依赖冲突时的互相毒化。