Gitlab Runner S3分布式缓存失效问题求助

看起来你已经配置了S3共享缓存，但缓存只在本地生效、S3桶为空，结合你的配置和使用的Runner版本（12.1.0），我整理了几个关键的排查和修复步骤：

1. 修正Runner配置的细节问题 #

你的config.toml中，[runners.cache]的配置有几处可以调整的地方：

• 确保Type值为小写的s3（虽然部分版本兼容大写，但严格遵循官方规范更稳妥）
• 显式添加Path参数（12.x版本的Runner有时需要这个参数才能正确识别S3缓存配置）
• 给ServerAddress加上端口号，避免连接歧义

调整后的[runners.cache]块如下：

[runners.cache]
Type = "s3"
Shared = true
Path = ""

[runners.cache.s3]
ServerAddress = "s3.amazonaws.com:443"
AccessKey = "XXX"
SecretKey = "XXX"
BucketName = "XXX"
BucketLocation = "eu-west-2"
Insecure = false

2. 在CI配置中启用跨Runner共享 #

虽然Runner端配置了Shared = true，但在.gitlab-ci.yml的cache块中添加shared: true，可以明确告知GitLab这个缓存是跨Runner共享的：

cache:
  untracked: true
  key: $ECR_REPO
  paths:
    - "sbt-cache/ivy/cache"
    - "sbt-cache/boot"
    - "sbt-cache/sbtboot"
  shared: true  # 新增这一行，开启跨Runner共享

3. 查看Runner系统日志找线索 #

流水线日志不会输出缓存同步的底层细节，你需要查看GitLab Runner的系统日志（通常路径是/var/log/gitlab-runner.log），执行以下命令实时观察：

tail -f /var/log/gitlab-runner.log

然后重新触发流水线，日志中会显示S3缓存的上传/下载尝试，比如认证失败、存储桶访问权限不足等具体错误，这是定位问题的关键。

4. 再次验证AWS权限的精准性 #

确认你的IAM用户拥有针对目标存储桶的完整缓存操作权限，所需权限包括：

• s3:ListBucket
• s3:GetObject
• s3:PutObject
• s3:DeleteObject
  权限的资源范围要覆盖整个存储桶（比如arn:aws:s3:::your-bucket-name/*），避免只给了桶级权限但没给对象级权限。

5. 考虑升级Runner版本 #

你使用的12.1.0版本是比较早期的12.x版本，存在一些已知的S3缓存兼容性bug，比如部分场景下缓存上传逻辑失效。建议升级到12.x系列的最新稳定版本（如12.10.0），或者直接升级到更近期的稳定版本，很多缓存相关的问题在后续版本中已经修复。

6. 手动测试S3存储桶访问 #

在Runner所在服务器上用AWS CLI手动测试存储桶的读写权限，排除网络或权限问题：

# 上传测试文件
echo "test cache" > test-cache.txt
aws s3 cp test-cache.txt s3://your-bucket-name/test-cache.txt --region eu-west-2

# 下载测试文件
aws s3 cp s3://your-bucket-name/test-cache.txt downloaded-cache.txt

如果这个操作失败，说明是AWS权限或网络配置问题；如果成功，那问题肯定出在Runner的配置上。

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