解决 Docker Build 时 "pull access denied" 错误

问题描述

在使用 Docker 构建镜像时，您可能会遇到以下错误信息：

failed to load cache key: pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed

这个错误通常发生在执行 docker build . 命令时，Docker 尝试从远程仓库拉取基础镜像或构建阶段镜像但无法访问。

常见原因和解决方案

1. 构建阶段引用错误

最常见的错误是在 Dockerfile 的 COPY --from 指令中引用了不存在的构建阶段。

错误示例

# 错误的 COPY 指令
COPY --from=publish/app /app .

解决方案：确保 COPY --from 引用的是 Dockerfile 中定义的合法构建阶段名称。

正确示例

# 引用已定义的构建阶段
COPY --from=build /app .

2. 基础镜像名称变更或拼写错误

Docker 官方镜像的仓库名称有时会发生变更，需要更新到正确的镜像名称。

解决方案：使用正确的微软官方 .NET 镜像名称：

# 从
FROM mcr.microsoft.com/dotnet/core/aspnet:3.1-buster-slim

# 改为
FROM mcr.microsoft.com/dotnet/aspnet:3.1-buster-slim

3. 认证问题

如果使用的是私有仓库镜像，需要先进行登录认证。

解决方案：

docker login [registry-url]
docker build .

4. 架构不匹配问题

在某些情况下，镜像架构与当前系统架构不匹配会导致授权错误。

解决方案：明确指定构建平台：

docker build . --platform linux/amd64

完整修复示例

以下是一个修复后的正确 Dockerfile 示例：

# 使用正确的基础镜像名称
FROM mcr.microsoft.com/dotnet/aspnet:3.1-buster-slim AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:3.1-buster AS build
WORKDIR /src
COPY ["src/App.Web/App.Web.csproj", "src/App.Web/"]
RUN dotnet restore "App.Web.csproj"
COPY . .
WORKDIR "/src/App.Web"
RUN dotnet build App.Web.csproj -c Debug -o /app

FROM build as debug
RUN dotnet publish "App.Web.csproj" -c Debug -o /app

FROM base as final
WORKDIR /app
# 引用正确的构建阶段名称
COPY --from=build /app .
ENTRYPOINT ["dotnet","App.Web.dll"]

排查步骤

当遇到 "pull access denied" 错误时，建议按照以下步骤排查：

1. 检查 Dockerfile 中的镜像名称和阶段引用
2. 确认是否有拼写错误或不存在的阶段名称
3. 验证是否需要登录到私有镜像仓库
4. 尝试添加 --platform 参数指定架构
5. 检查网络连接和 Docker 服务状态

提示

使用 docker build --no-cache . 可以避免缓存问题，确保重新拉取所有镜像。

通过以上方法和排查步骤，您应该能够解决 Docker 构建过程中的 "pull access denied" 错误。