华为云Docker镜像拉取失败如何解决？

Question

问题：在使用华为云容器镜像服务（SWR）时，执行 `docker pull` 命令拉取镜像失败，提示“unauthorized: authentication required”或“access denied”。该问题常见于未正确配置访问凭证或未绑定IAM权限。如何解决华为云Docker镜像因鉴权失败导致的拉取异常？需检查Docker登录状态、访问密钥配置及项目区域匹配性。

Answer 1

1. 问题现象与初步诊断

在使用华为云容器镜像服务（SWR）时，执行 docker pull 命令拉取私有镜像失败，常见错误提示为：

unauthorized: authentication required
access denied

此类报错表明 Docker 客户端未能通过 SWR 的身份验证机制。该问题通常出现在以下几种场景中：

• 未执行 docker login 登录操作
• 登录使用的访问密钥（Access Key / Secret Key）无效或过期
• IAM 用户未被授予 SWR 相关权限（如 SWRReadOnlyAccess 或 SWRAdministratorAccess）
• Docker 登录地址与镜像所在区域不匹配（例如华南-广州的镜像却登录了华北-北京四）
• 多项目环境下未正确指定项目名称（Project Scope）

首先应确认当前是否已成功登录 SWR。

2. 检查 Docker 登录状态

可通过如下命令查看本地 Docker 是否已登录 SWR：

$ docker logout swr.cn-south-1.myhuaweicloud.com
$ docker login swr.cn-south-1.myhuaweicloud.com

其中域名需替换为实际使用的 SWR 实例地址，格式为：
swr.{region}.myhuaweicloud.com

若提示用户名/密码错误，请检查所用凭证类型。华为云推荐使用 临时安全令牌（STS） 或 永久 AK/SK 配合 IAM 用户 进行认证。

登录示例：

参数	说明
Username	IAM 用户名 或 AK
Password	SK 或 临时 Token
Server	swr.{region}.myhuaweicloud.com

3. 验证访问密钥（AK/SK）配置有效性

确保使用的 AK/SK 属于具有 SWR 权限的 IAM 用户。可在华为云控制台进行如下验证：

1. 进入“IAM 控制台” → “用户” → 找到对应用户
2. 检查其绑定的策略是否包含：
   - SWRAdministratorAccess
   - SWRReadOnlyAccess
3. 确认该用户处于“启用”状态
4. 若使用编程式访问，需确保生成的是“启用”状态的 AK/SK 对

可通过环境变量方式测试登录：

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key

docker login -u $AWS_ACCESS_KEY_ID \
             -p $AWS_SECRET_ACCESS_KEY \
             swr.cn-east-3.myhuaweicloud.com

4. 区域与项目匹配性校验

华为云 SWR 是区域化服务，不同 Region 的镜像仓库相互隔离。必须保证：

• Docker 登录地址与镜像所在 Region 一致
• 若启用了多项目（Project），需在镜像名中显式指定项目名

合法镜像拉取格式如下：

docker pull swr.{region}.myhuaweicloud.com/{project}/repo:tag

例如：

docker pull swr.cn-south-1.myhuaweicloud.com/demo-project/nginx:v1

常见错误是将 cn-south-1 写成 cn-south，或忽略 project 路径。

5. 使用临时凭证提升安全性（推荐方案）

为避免长期暴露 AK/SK，建议使用 STS 临时凭证结合 kubelet 或 CI/CD 工具自动刷新 token。

流程图如下：

graph TD A[IAM 用户请求临时Token] --> B{调用AssumeRole API} B --> C[获取临时AK/SK/SecurityToken] C --> D[docker login --password-stdin] D --> E[执行 docker pull/push] E --> F[凭证有效期到期自动失效]

此方法适用于 Kubernetes Pod、Jenkins Agent 等动态运行环境。

6. 自动化脚本排查模板

可编写 Shell 脚本统一检测鉴权链路：

#!/bin/bash
REGION="cn-south-1"
PROJECT="demo-project"
REPO="nginx"
TAG="v1"

SERVER="swr.${REGION}.myhuaweicloud.com"
IMAGE="${SERVER}/${PROJECT}/${REPO}:${TAG}"

# Step 1: Logout first
docker logout $SERVER >/dev/null

# Step 2: Login
echo "Logging into $SERVER..."
docker login -u $HUAWEI_AK -p $HUAWEI_SK $SERVER

if [ $? -ne 0 ]; then
    echo "❌ Login failed. Check AK/SK and region."
    exit 1
fi

# Step 3: Pull image
echo "Pulling image: $IMAGE"
docker pull $IMAGE

if [ $? -eq 0 ]; then
    echo "✅ Image pulled successfully."
else
    echo "❌ Pull failed. Verify IAM permissions and project scope."
    exit 1
fi