GitLab Runner已存在缓存目录仍提示权限拒绝的原因排查

核心原因分析 #

错误日志里的mkdir ../../../../../cache说明Runner尝试写入的缓存路径上下文和你手动创建的/home/gitlab-runner/cache不匹配，或者当前Runner运行用户没有该目录的读写权限。

具体解决步骤 #

1. 检查缓存目录的权限与所属用户 #

登录Runner部署服务器，执行命令查看目录权限详情：

ls -ld /home/gitlab-runner/cache

确保目录所有者为gitlab-runner用户，权限至少为drwxr-xr-x（755）。如果不符合，执行以下命令修正：

sudo chown -R gitlab-runner:gitlab-runner /home/gitlab-runner/cache
sudo chmod -R 755 /home/gitlab-runner/cache

2. 确认GitLab Runner配置中的缓存路径 #

打开Runner配置文件（默认路径为/etc/gitlab-runner/config.toml），检查[[runners]]段的缓存配置是否正确指向你创建的目录：

[[runners]]
  # 其他配置项...
  [runners.cache]
    Type = "local"
    Path = "/home/gitlab-runner/cache"

如果缺失该配置，添加后重启Runner服务：

sudo gitlab-runner restart

3. Docker执行器的额外校验（若使用Docker模式） #

如果你的Runner采用Docker执行器，需补充以下检查：

• 确保容器内用户（通常是root或镜像指定用户）有权访问主机缓存目录
• 配置文件中正确设置缓存目录的挂载规则：

[[runners]]
  # 其他配置项...
  executor = "docker"
  [runners.docker]
    # 其他配置项...
    volumes = ["/home/gitlab-runner/cache:/cache:rw"]

这里的/cache是容器内的默认缓存路径，必须和主机目录正确映射，且权限设置为读写（rw）。

4. 流水线缓存路径的合理性验证 #

你的流水线配置中，node_modules/和.npm都是项目目录内的路径，本身无问题，但需确保Runner有权限访问项目工作目录（默认路径为/builds/<命名空间>/<项目名>），不过核心问题仍聚焦于主机缓存目录的权限与Runner配置的匹配度。

内容的提问来源于stack exchange，提问作者Marsel.V