GitLab Runner分布式缓存config.toml的Path参数作用及用法问询

核心作用确认 #

你对该参数的路径拼接逻辑理解完全正确：Path仅作为S3缓存对象的公共路径前缀，会固定插入到S3桶名和GitLab Runner自动生成的缓存子路径（/runner/runner-id/project/id/cache-key）之间，最终完整的S3对象路径结构为：

http(s)://ServerAddress/BucketName/[Path配置值]/runner/runner-id/project/id/cache-key

相关配置示例如下：

[runners.cache]
    Type = "s3"
    Path = "path/to/prefix"
    Shared = false

修改/新增Path参数的影响 #

• 新增Path参数：未配置该参数时默认无公共前缀，缓存直接存放在桶根目录的runner/路径下。新增配置后，新生成的缓存会全部写入指定前缀的路径下，历史旧缓存不会被自动迁移，相关Job首次运行时会出现缓存未命中，需要重新生成缓存，不会触发业务报错。
• 修改已有Path参数：逻辑与新增一致，原有前缀下的旧缓存不会被读取，新缓存会写入更新后的前缀路径，会出现阶段性的缓存命中率下降，直到新前缀下的缓存逐步生成覆盖。
• 配置空Path值：等价于未配置该参数，回到默认无公共前缀的路径结构。

适用场景与使用方法 #

常见使用场景 #

• 多Runner集群共享同一个S3桶：不同集群配置不同的Path前缀，可避免不同集群的缓存文件冲突，也方便分集群做缓存权限、生命周期管理，例如测试环境集群配置Path = "gitlab-runner/test"，生产环境集群配置Path = "gitlab-runner/prod"。
• 桶内同时存储其他业务文件：添加公共前缀可将缓存文件和其他业务文件隔离，避免互相干扰，也方便单独对缓存目录做权限配置。
• 需要统一管理集群缓存：将所有缓存归集到同一个前缀目录下，可直接在S3侧配置目录级别的生命周期规则（如自动删除30天以上的缓存），不需要匹配分散的路径规则。

使用注意事项 #

• 配置时不需要额外在Path值前后加路径分隔符/，GitLab Runner会自动补全路径拼接所需的分隔符。
• 如果多个Runner实例开启了Shared = true共享缓存，必须保证所有实例的Path参数配置完全一致，否则会出现缓存互相找不到的问题。

内容的提问来源于stack exchange，提问作者mps