构建提速：本地与远程缓存协同的 CI 优化设计
一、重复构建的资源黑洞
CI 每次都从零编译，是最常见的浪费。
同样的依赖、同样的源码，反复下载与编译。
机器在空转，工程师在等待，账单在上涨。
构建缓存就是为此而生。
把"上次的成果"存起来，下次直接复用。
但缓存怎么分、放哪、何时失效，决定了提速的上限。
本文探讨本地缓存与远程缓存的协同设计。
让单机快、集群更快。
二、缓存命中与失效机制
缓存的核心是两件事：算 key，管失效。
key 由输入决定：源码哈希、依赖锁文件、编译参数。
输入不变，key 不变，就能命中历史产物。
远程缓存是把单机产物上传到共享存储。
同团队任何人构建相同输入，都能直接拉取。
这让"第一次构建"也变快。
下面是缓存查询的链路：
flowchart TD A[计算构建输入哈希] --> B[查询本地缓存] B --> C{命中?} C -->|是| D[直接复用产物] C -->|否| E[查询远程缓存] E --> F{命中?} F -->|是| G[下载并复用] F -->|否| H[执行真实构建] H --> I[上传产物到远程] I --> J[写入本地缓存] D --> K[返回构建结果] G --> K J --> K style D fill:#e8f5e9 style G fill:#e8f5e9关键在 key 的粒度。
太粗会漏掉必要重建，太细几乎不命中。
依赖锁文件变更必须让 key 失效，否则会用错版本。
三、生产级缓存实现
下面用代码描述一个缓存客户端骨架。
import hashlib import json import os from pathlib import Path from typing import Optional def compute_key(inputs: dict) -> str: """把构建输入序列化为稳定哈希，作为缓存 key""" payload = json.dumps(inputs, sort_keys=True, ensure_ascii=False) return hashlib.sha256(payload.encode("utf-8")).hexdigest() class BuildCache: def __init__(self, local_dir: Path, remote_url: Optional[str] = None): self.local_dir = local_dir self.remote_url = remote_url self.local_dir.mkdir(parents=True, exist_ok=True) def get(self, key: str) -> Optional[Path]: local = self.local_dir / key if local.exists(): return local if self.remote_url: # 真实场景用 HTTP 下载，此处表达回退逻辑 return self._fetch_remote(key) return None def put(self, key: str, artifact: Path) -> None: try: target = self.local_dir / key target.write_bytes(artifact.read_bytes()) except OSError as exc: # 缓存写入失败不应阻断构建，仅记录 print(f"本地缓存写入失败: {exc}") if self.remote_url: self._upload_remote(key, artifact) def _fetch_remote(self, key: str) -> Optional[Path]: # 占位：实际依据 remote_url 拉取，失败返回 None return None def _upload_remote(self, key: str, artifact: Path) -> None: # 占位：实际上传，带重试与超时 pass if __name__ == "__main__": cache = BuildCache(Path(".build-cache"), "https://cache.internal") key = compute_key({"src": "a1b2", "deps": "v3", "flag": "-O2"}) hit = cache.get(key) print("缓存命中" if hit else "需重新构建")真实系统会加 TTL 与容量上限。
本地缓存超容量时按 LRU 淘汰，远程按分支保留近期。
四、边界分析与架构权衡
缓存提速明显，但陷阱不少。
正确性优先于速度。错误的缓存命中比慢更可怕。
任何可能改变输出的因素都必须进 key。
编译器版本、环境变量、平台位宽都不能遗漏。
远程缓存的安全。产物可能含内网路径或密钥。
上传前必须扫描脱敏，且按仓库鉴权隔离。
否则一个团队能读到另一个团队的构建产物。
缓存投毒风险。若任何人可写远程缓存，可植入恶意产物。
远程写入必须签名校验，只允许可信 CI 身份。
命中率监控。命中率过低说明 key 设计有问题。
应监控并告警，避免"以为在加速其实在摆设"。
缓存的"冷启动"体验要单独设计。远程缓存首次为空时，所有构建都未命中，团队会瞬间感受到变慢，容易误判方案无效。建议上线初期保留全量兜底，并预热常用分支的缓存，让团队先看到收益再逐步依赖。另一个被忽视的点是缓存的存储成本：长期累积的产物会占满磁盘，需设 TTL 与容量上限，按分支与热度淘汰。最后，缓存命中率应作为构建健康的看板指标，持续监控，一旦异常下跌能快速定位是 key 设计还是依赖变更的问题。
五、总结
构建缓存的本质是用"空间换时间"。
本地缓存解决单机重复，远程缓存解决团队重复。
一切都建立在"key 能精确反映输入"之上。
落地路线：先定义覆盖全部输入的哈希 key；再接本地缓存兜底；上远程缓存做团队共享；最后加 TTL、鉴权与命中率监控。缓存对了，流水线才能真正快起来。
