Docker Buildx缓存配置问题解析：GHCR推送时误向默认容器仓库导出缓存

在使用Docker Buildx构建镜像并推送到GitHub容器注册表（GHCR）时，开发者遇到了一个典型的缓存配置问题。当使用--cache-to inline参数时，系统错误地尝试将缓存数据推送到默认容器仓库（registry.docker.io），导致授权失败。

问题现象

在GitHub Actions工作流中配置了以下构建命令：

docker buildx build \
    --cache-from type=registry,ref=ghcr.io/effigies/buildx-repro:main \
    --cache-to inline \
    --tag ghcr.io/effigies/buildx-repro:main \
    --push \
    .

执行时出现错误提示：

ERROR: failed to solve: error writing layer blob: failed to authorize: failed to fetch oauth token: unexpected status from GET request to https://auth.docker.io/token?scope=repository%3Alibrary%2Finline%3Apull%2Cpush&service=registry.docker.io: 401 Unauthorized

根本原因

这个问题源于对--cache-to参数格式的误解。当仅使用inline作为参数值时，Buildx会将其解析为默认容器仓库上的镜像引用docker.io/library/inline，而不是预期的内联缓存模式。

正确配置方法

正确的缓存配置应该明确指定类型为inline：

docker buildx build \
    --cache-from type=registry,ref=ghcr.io/effigies/buildx-repro:main \
    --cache-to type=inline \
    --tag ghcr.io/effigies/buildx-repro:main \
    --push \
    .

技术背景

Docker Buildx的缓存机制支持多种存储方式：

1. 内联缓存（inline）：将缓存数据直接嵌入到镜像中
2. 注册表缓存（registry）：将缓存数据推送到指定的容器注册表
3. 本地缓存（local）：将缓存数据存储在构建主机上

当不明确指定缓存类型时，Buildx会尝试将参数值解释为镜像引用，这是Docker CLI的常见行为模式（如docker run ubuntu实际指向docker.io/library/ubuntu）。

最佳实践建议

1. 始终明确指定缓存类型（type）
2. 对于GHCR等非默认容器仓库，确保认证配置正确
3. 在CI/CD流水线中，建议先检查缓存是否存在再尝试使用
4. 考虑结合多种缓存方式提高构建效率

通过正确配置缓存参数，可以充分利用Buildx的缓存功能加速构建过程，同时避免不必要的认证错误。