📚 课程目录第3章缓存键设计原则

3. 缓存键设计原则：精确匹配、通配符与哈希值组合

CI/CD缓存一致性首先取决于缓存键（Cache Key）的设计。键的粒度和组合方式直接影响命中率、正确性和维护成本。本章从精确匹配、通配符匹配和哈希值组合三个维度，讲解缓存键设计原理、实现流程及优化策略。

3.1 精确匹配（Exact Match）

精确匹配使用完全一致的字符串作为缓存键。同一构建上下文下，相同的输入必定映射到相同的键。这是最直观、最安全的方式，但灵活性最低。

场景	示例键	命中条件
依赖锁文件	`pdm-lock-v2-3.12-fd8a2b`	锁文件哈希相同
源码目录快照	`src-snapshot-$(git rev-parse HEAD)`	Git commit相同
编译器版本	`clang-18.1.0`	版本号字符串完全一致

实现要点：精确匹配常与checksum或git commit拼接。确保所有输入变量（环境变量、工具链版本、依赖声明文件）都参与键生成，避免遗漏导致误命中。

# GitLab CI 缓存键精确匹配示例
cache:
  key: "$CI_JOB_NAME-$CI_COMMIT_SHA"
  paths:
    - node_modules/
    - .pnpm-store/

3.2 通配符匹配（Glob / Pattern Match）

通配符使缓存键能够匹配一组模式，适用于多分支、多平台共享同一构建缓存的场景。常见通配符包括 *（任意字符）、**（跨目录）和 ?（单个占位）。

使用通配符时，必须设计层级范围：

粗粒度：同一仓库所有分支共享一个缓存键（如 repo-cache），节省存储但冲突风险高。
中粒度：按主要版本或平台通配，如 cache-linux-*。
细粒度：在通配符外附加哈希因子，如 cache-$(git rev-parse origin/main)。

风险提示：过度使用通配符可能导致缓存污染。例如，*-deps 键可能被不同分支写入不兼容的依赖包，后续构建使用错误缓存而产生不一致。建议在通配符后面追加至少一个可变因子（如构建系统标识或锁文件哈希）。

# 使用通配符 + 哈希保持粒度（CircleCI 缓存恢复）
restore_cache:
  keys:
    - v1-deps-{{ checksum "pdm.lock" }}
    - v1-deps-

3.3 哈希值组合（Hash Combination）

当输入维度较多（多个文件、环境变量、构建参数）时，简单拼接可能导致键长度失控或变更检测不准确。哈希值组合将多个输入源通过一致性哈希算法（如 SHA-256 / MD5）合并成固定长度的摘要，兼顾唯一性与可管理性。

维度	来源	组合方式
依赖锁	`pdm.lock`	SHA256(`pdm.lock`内容)
构建配置	`.ci/config.yml`	SHA256(`.ci/config.yml`内容)
Python 版本	`3.12.2`	直接字符串
架构	`linux/amd64`	直接字符串

推荐实践：在 CI 流程中将上述字符串按固定顺序拼接，再用 echo -n "$KEYS" | sha256sum 生成 64 位十六进制键。既保证唯一性，又避免长键超出存储系统的限制（如 Redis 键最大 512 MB）。

# GitHub Actions 中生成组合哈希缓存键
- name: Generate cache key
  id: cache-key
  run: |
    echo "key=$(echo -n "${{ runner.os }}-${{ hashFiles('pdm.lock') }}-${{ hashFiles('.ci/golden') }}" | sha256sum | cut -d' ' -f1)" >> $GITHUB_ENV

3.4 三策略对比与选择矩阵

策略	唯一性	灵活性	安全（防污染）	典型场景
精确匹配	最高	最低	最高	单分支、锁文件未变
通配符	中	高	低	多分支共享基线
哈希组合	高	中	高	多变量输入、多平台

常见错误：直接使用hashFiles('**')作为唯一键，会导致任何文件变动（包括注释、空白）都使缓存失效，大幅降低命中率。应只对影响构建输出的关键文件（锁文件、编译配置、工具链声明）计算哈希。

3.5 缓存键设计流程图：三种策略的决策路径

3.6 性能与稳定性优化

减少哈希计算次数：将多次哈希合并为一次，避免在单个流水线中重复计算大文件。示例：只对锁文件计算一次，将结果作为环境变量传递给多个 job。
缓存键预热：在每次 merge request 创建时主动生成预估值键，使主干构建缓存提前就绪。
降级策略：当匹配不到精确键时，使用通配符回退到上一级缓存（如分支级别 refs/heads/main → refs/heads/*），保证至少可命中最接近的缓存。
监控缓存命中率：在 CI 配置中增加 cache-hit: true/false 日志输出，定期分析键分布，调整策略。

# 降级缓存恢复示例（GitLab）
cache:
  key:
    files:
      - pdm.lock
      - .tool-versions
  paths:
    - .venv/
  policy: pull-push
  # 若精确键未命中，自动尝试不带哈希的键
  fallback_keys:
    - "$CI_JOB_NAME"

3.7 调试与常见错误

问题	原因	解决
缓存总是未命中	键中包含临时变量（如时间戳、随机串）	检查键生成脚本，移除无关变量
不同分支互相污染	键层级过宽，无分支隔离	在通配符后追加分支名或哈希值
缓存键长度超限	拼接过多文件路径或环境变量	改为合并后 hash (SHA-256 固定64字符)
通配符匹配顺序错误	`*` 和 `` 混用时歧义	使用明确前缀如 `cache-$(CI_COMMIT_REF_SLUG)-*`

调试命令：本地生成缓存键并与 CI 日志中的键对比。例如在终端中模拟：

# 模拟 GitHub Actions 的 hashFiles
KEY=$(echo -n "Linux-$(sha256sum pdm.lock | cut -d' ' -f1)-$(sha256sum .clang-format | cut -d' ' -f1)" | sha256sum | cut -d' ' -f1)
echo "Generated key: $KEY"

3.8 部署实践：多平台统一哈希键

针对同时支持 Linux、macOS、Windows 的 CI/CD 流水线，可设计如下统一键策略：

# 使用平台 + 架构 + 锁文件 + 核心配置文件生成 key
generate_cache_key:
  image: alpine:3.19
  script:
    - |
      PLATFORM=$(uname -s | tr '[:upper:]' '[:lower:]')
      ARCH=$(uname -m)
      LOCK_HASH=$(sha256sum pdm.lock | cut -d' ' -f1)
      CONF_HASH=$(sha256sum .gitlab-ci.yml | cut -d' ' -f1)
      KEY="v2-${PLATFORM}-${ARCH}-${LOCK_HASH%???????????????????????????????????????????????????????????????????????????????????????}-${CONF_HASH%???????????????????????????????????????????????????????????????????????????????????????}"
      echo "CACHE_KEY=$KEY" >> build.env
  artifacts:
    reports:
      dotenv: build.env

该键兼顾平台差别和文件变更，同时控制长度在合理范围内。将其注入后续作业的缓存配置中，即可实现跨作业一致性。

核心公式：

cache_key = v<version>-<platform>-<arch>-<lock_hash(%32)>-<config_hash(%32)>

其中 %32 表示截取 SHA256 前32字符，既保证碰撞概率极低，又控制键总长不超过120字符。

3.9 性能稳定性优化清单

优先使用哈希组合，避免纯通配符导致的缓存膨胀。
在 job 定义中显式设置 cache:policy: pull-push，减少不必要的上传。
对大型 monorepo，按模块拆分缓存键（如 cache-frontend-* 和 cache-backend-*）。
定期清理过期缓存键，使用 CI 平台的 TTL 或手动 API 删除。
在 CI 日志中添加键名和命中标志，便于调试。