华为云 SWR 镜像推送/拉取失败排查清单：从登录指令、组织权限到 CCE 拉取

摘要：SWR 推拉镜像和 CCE 拉取失败，报错分散在登录凭证、组织权限、镜像地址、集群密钥和网络五个环节。本文对照华为云官方文档，梳理临时/长期登录指令及过期、组织不存在或无权限、镜像地址格式、unauthorized/denied/x509/超时等报错含义，以及 CCE ImagePullBackOff 中 default-secret、跨区域拉取与节点网络的排查方法，文末附速查表。

标签：容器镜像服务 SWR、云容器引擎 CCE、Docker、运维

把镜像推到华为云容器镜像服务 SWR、再让云容器引擎 CCE 拉起来，是容器上云最常见的一条链路。链路本身不长，但出错的位置很分散：本机 docker login 失败、docker push 被 denied、控制台能看到镜像但 Pod 一直 ImagePullBackOff……很多人看到报错第一反应是"重新复制一遍登录指令"，结果有时好了、有时没用。原因在于这几类报错分别对应登录凭证、组织权限、镜像地址、集群密钥、网络链路五个不同环节。本文按"登录 → 推送 → 拉取 → CCE"的顺序整理一份排查清单，每个报错尽量对应到华为云官方文档里给出的原因和处理方式，文末附一张速查表。

说明：本文以 SWR 基础版、Docker 客户端为主；控制台菜单名称和配额数值可能随版本调整，具体以官方文档为准。文中 <region>、<org>、<AK> 等均为占位符。

1. 先建立一个心智模型：一条镜像地址拆成三段

SWR 的镜像地址统一是下面这个格式：

swr.<区域项目名称>.myhuaweicloud.com/<组织名>/<镜像名>:<版本>

排查时我习惯先把报错里的完整地址抄出来，逐段对照：域名对不对 → 组织在不在、有没有权限 → 镜像名和 tag 对不对。后面所有章节基本都是在某一段上出了问题。

2. 登录环节：临时指令、长期指令与过期

2.1 两类登录指令的区别

SWR 控制台"登录指令"里提供的通用型指令分为临时和长期两种，官方 FAQ 对二者的区别说明如下：

另外两点容易被忽略：

• 获取了长期指令后，有效期内的临时指令仍然可以用，二者不互斥。
• 开启了 IAM 新平面后还有一种"增强型登录指令"，它不支持长期指令，只有临时指令，有效期为 24 小时，权限完全走 IAM。如果控制台里找不到"长期有效登录指令"，先确认自己看的是哪种类型的指令。

2.2 长期指令的拼接方式

控制台没有"长期有效登录指令"页签时，官方文档给出了手动拼接方法，核心是用 SK 对 AK 做 HMAC-SHA256 得到登录密钥：

# 在 Linux 机器上计算登录密钥（AK/SK 用环境变量传入，不要写进脚本或历史记录）
printf "$AK" | openssl dgst -binary -sha256 -hmac "$SK" | od -An -vtx1 | sed 's/[ \n]//g' | sed 'N;s/\n//'

# 按格式拼接登录指令
docker login -u <区域项目名称>@<AK> -p <登录密钥> swr.<区域项目名称>.myhuaweicloud.com

拼接时注意三点：

1. -u 里的区域项目名称、末尾的仓库地址必须是同一个区域，可在 IAM"我的凭证"的项目列表里查到。
2. 使用 AK/SK 的 IAM 用户需要开通"编程访问"。
3. 登录密钥不可逆，无法从中反推出 SK；但长期指令本身等同于一把长期凭证，官方明确要求妥善保管、防止泄露。我习惯把它存进 CI 平台的密钥变量里，而不是写进仓库或流水线脚本明文。

2.3 登录失败的报错对照

官方 FAQ"为什么登录指令执行失败？"列出了几种典型报错，整理如下：

很多人遇到 unauthorized 就反复重新登录，但如果用的是长期指令，更应该先去 IAM 确认那组 AK 是否还处于启用状态——AK 轮换后旧指令就失效了，这在 CI 环境里很常见。

2.4 关于 x509 证书报错

官方给出的处理方式是：在信任服务端的前提下，把仓库地址加入 Docker 的 insecure-registries（不同发行版配置文件位置不同，CentOS 是 /etc/docker/daemon.json，Ubuntu 是 /etc/default/docker，EulerOS 是 /etc/sysconfig/docker），然后 systemctl daemon-reload && systemctl restart docker。官方文档还特别提醒，Docker 29 及以上版本在 daemon.json 中需要同时加上 "features": {"containerd-snapshotter": false}。

这一步本质上是放宽证书校验，不建议作为第一反应。我习惯先排除"本机时间不准"“公司代理做了 HTTPS 中间人”"系统 CA 证书过旧"这些更常见的环境问题，再考虑改配置。

3. 推送环节：组织不存在、无权限与格式问题

登录成功只代表凭证有效，不代表你对目标组织有写权限。推送阶段的报错大多和组织有关。

3.1 推送前的标准步骤

# 1. 登录（复制控制台指令或使用长期指令）
docker login -u <区域项目名称>@<AK> -p <登录密钥> swr.<region>.myhuaweicloud.com

# 2. 打标签：本地镜像 -> 仓库地址/组织/镜像:版本
docker tag myapp:v1 swr.<region>.myhuaweicloud.com/<org>/myapp:v1

# 3. 推送
docker push swr.<region>.myhuaweicloud.com/<org>/myapp:v1

前提是组织已经在同一区域创建好。官方文档的约束：组织名在当前区域内唯一；创建组织需要 IAM 中的 SWR Admin 或 Tenant Administrator 权限；library 是系统保留名，不能用。

3.2 推送报错对照

命名规范方面，官方给出的正则如下（组织名必须以小写字母开头，镜像名可以以数字开头）：

• 组织名：^([a-z]+(?:(?:(?:_|__|[-]*)[a-z0-9]+)+)?)$，长度 1–64
• 镜像名：^([a-z0-9]+(?:(?:(?:_|__|[-]*)[a-z0-9]+)+)?)$，长度 1–128

最常见的情况是镜像名里带了大写字母，比如 MyApp，直接改成全小写即可。

关于 OCI 格式，新版 buildx 默认可能生成 provenance 清单，官方给出的规避参数是：

docker buildx build --provenance=false --platform linux/amd64 \
  -t swr.<region>.myhuaweicloud.com/<org>/myapp:v1 \
  --output=type=image,push=true,oci-mediatypes=false .

该方法只适用于自己构建的镜像，第三方镜像不适用。

3.3 IAM 用户没有组织权限怎么授权

官方提供两种方式：

1. SWR 本地授权：由有 SWR 管理员权限的用户在"组织管理"页面，给目标 IAM 用户授予该组织的权限（读取 / 编辑 / 管理三档），各档具体能执行的操作以官方说明为准。只拉取给读取，需要推送至少给编辑。
2. IAM 细粒度授权：创建自定义策略，例如只允许向某个组织推送：

{
  "Version": "1.1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["swr:repo:upload"],
      "Resource": ["SWR:*:*:repo:<org>/*"]
    }
  ]
}

把策略授给用户所在的用户组后，稍等约 1 分钟再重试。很多人授权完立刻重推，看到还是 denied 就以为授权没生效，其实只是还没同步。

如果使用的是增强型登录指令，权限只走 IAM，不再看 SWR 的本地授权，这时要去 IAM 侧检查策略。

3.4 配额与限制

推送失败但报错不明显时，可以顺手核对一下这些限制（以官方文档当前说明为准）：

• Docker 客户端需 18.06 及以上；
• 单个镜像 layer 不超过 50G；
• 单租户同时并发推送的 layer 总数不超过 20 个；
• 单租户镜像配额 500 个、镜像版本配额 300 个，超出会推送失败，可通过镜像老化清理或提工单扩容。

4. CCE 拉取环节：ImagePullBackOff 怎么查

4.1 第一步永远是看事件

工作负载显示"实例未就绪：Back-off pulling image …“时，对应的 K8s 事件是"实例拉取镜像失败"或"重新拉取镜像失败”。先拿到具体报错：

kubectl get pod -n <namespace>
kubectl describe pod <pod-name> -n <namespace>   # 看最底部 Events

ImagePullBackOff 只是结果，Events 里 Failed to pull image 后面的那一段才是原因。下面按报错分类。

4.2 denied: You may not login yet：缺少 imagePullSecrets

SWR 里推送的镜像默认是私有镜像。用 kubectl 或 YAML 创建工作负载时，如果没写 imagePullSecrets，节点就会以未登录身份去拉，得到这个报错。官方要求：拉取 SWR 镜像时，name 固定为 default-secret。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
  namespace: <namespace>
spec:
  replicas: 1
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
      - name: myapp
        image: swr.<region>.myhuaweicloud.com/<org>/myapp:v1
      imagePullSecrets:
      - name: default-secret

关于 default-secret，CCE 文档有几点值得记住：

• 它由 CCE 在每个命名空间下自动创建，类型为 kubernetes.io/dockerconfigjson，内容是访问 SWR 的凭据。
• 它的数据会定期更新，当前内容一段时间后会过期，可以用 kubectl describe secret default-secret -n <namespace> 在注解 swr-auth-may-expires-at 中看到过期时间。
• 不要把它的内容复制出来另建一个 Secret，复制品不会自动刷新，过期后就拉不到镜像了。这是从别的集群"搬配置"时很常见的坑。
• 不想每个工作负载都写 imagePullSecrets，可以参考 SWR 最佳实践"CCE 免密拉取 SWR 基础版镜像"，把 default-secret 关联到 ServiceAccount 上：

kubectl patch serviceaccount default -n <namespace> \
  -p '{"imagePullSecrets": [{"name": "default-secret"}]}'

补充一个变更：CCE 在 2026 年 1 月发布公告，新版本集群（如 v1.28.15-r80、v1.29.15-r40、v1.30.14-r40、v1.31.14-r0、v1.32.9-r0、v1.33.7-r0、v1.34.2-r0 及以上）将 default-secret 的默认权限收窄为只允许拉取。如果集群里的构建 Pod 依赖它向 SWR 推送镜像，升级后会推送失败，需要按公告为节点委托授予相应权限。拉取不受影响。

4.3 跨区域拉取：地址、凭证和网络三件事

CCE 集群在 A 区域、镜像在 B 区域的 SWR，是另一类高频问题。官方文档相关的事实有：

• SWR 支持跨区域公网下载，但需要使用镜像所在区域的登录指令；
• 机器与仓库同区域时走内网，不同区域时需要走公网，节点必须能访问公网；
• 部分区域支持跨区域镜像同步（自动或手动），其他区域可以先拉到本地再推到目标区域。

default-secret 是否能用于其他区域的 SWR，官方文档没有给出明确说明，以官方文档为准。实际操作上我更推荐下面的顺序：

1. 首选：把镜像放到集群所在区域。 用 SWR 的镜像同步功能，或手动 docker pull → docker tag → docker push 到本区域组织，然后用本区域地址 + default-secret 拉取，走内网、不额外收流量费。
2. 确需跨区直拉时：先确认节点有公网出口（见 4.5），再用目标区域的登录凭据创建一个 docker-registry 类型的 Secret，并在 imagePullSecrets 中引用。凭据建议用专门的 IAM 用户、只授该组织的读取权限：

kubectl create secret docker-registry swr-<region>-pull -n <namespace> \
  --docker-server=swr.<region>.myhuaweicloud.com \
  --docker-username='<区域项目名称>@<AK>' \
  --docker-password='<登录密钥>'

这里的用户名、密码对应长期登录指令里 -u 和 -p 的值；如果用临时指令的凭据，到期后同样会拉取失败。

4.4 其他拉取报错

官方 FAQ"工作负载异常：实例拉取镜像失败"列出的其他事件：

还有一种"不报错的失败"：镜像内容更新了但 tag 没变，imagePullPolicy 为 IfNotPresent 时节点会直接用本地旧镜像。官方建议每次构建都使用新的版本号，或者把策略设为 Always。

4.5 节点访问 SWR 的网络

把官方"配置访问网络"最佳实践的结论浓缩一下：

注意一个细节：SWR 的镜像层存放在 OBS 上。官方提醒，如果通过 VPC 终端节点访问 OBS 并设置了严格的访问策略，或通过 /etc/hosts 固定解析，需要把 SWR 对应的 OBS 桶集群也加入，否则可能出现下载失败或偶发失败（具体桶集群信息需提工单获取）。这类"能登录、能看到 manifest、但拉层失败"的现象，可以往这个方向查。

验证网络时，我习惯直接登录到出问题的节点上手动拉一次，把 K8s 层面的因素排除掉：

# containerd 节点
crictl pull swr.<region>.myhuaweicloud.com/<org>/myapp:v1
# docker 节点
docker pull swr.<region>.myhuaweicloud.com/<org>/myapp:v1

节点上能拉、Pod 拉不了，问题多半在 imagePullSecrets；节点上也拉不了，再看网络和凭证。

5. 一套推荐的排查顺序

把前面的内容串起来，遇到问题时可以按这个顺序走：

1. 抄出完整镜像地址，核对区域域名、组织、镜像名、tag 四段。
2. 本机能否登录：docker login 失败看第 2 节报错表；长期指令先查 AK 状态。
3. 组织是否存在、在不在同一区域：控制台切到对应区域查看"组织管理"。
4. 当前用户对组织的权限：推送至少需要编辑权限；授权后等 1 分钟。
5. CCE 看 Events：kubectl describe pod 找 Failed to pull image 后的原文。
6. imagePullSecrets 是否为 default-secret，且没有被复制成静态 Secret。
7. 是否跨区域：优先同步到本区域；确需跨区则确认公网出口和对应区域凭据。
8. 节点上手动拉一次，区分是 K8s 配置问题还是节点网络/凭证问题。

6. 速查表

参考文档

• 容器镜像服务 SWR：登录问题（临时/长期指令区别）
• 容器镜像服务 SWR：获取长期有效的登录或推拉镜像指令
• 容器镜像服务 SWR：为什么登录指令执行失败？
• 容器镜像服务 SWR：为什么使用客户端上传镜像失败？
• 容器镜像服务 SWR：推送镜像到镜像仓库
• 容器镜像服务 SWR：镜像拉取常见问题、是否支持跨区域同步镜像？
• 容器镜像服务 SWR：配置访问网络（内网访问 / 公网访问）、CCE 免密拉取 SWR 基础版镜像
• 云容器引擎 CCE：工作负载异常：实例拉取镜像失败
• 云容器引擎 CCE：集群系统密钥说明、设置镜像拉取策略
• 云容器引擎 CCE：关于 CCE 集群 default-secret 密钥权限变更的说明

以上内容根据华为云官方文档整理，控制台界面、配额与版本号可能更新，实际操作请以官方文档最新版本为准。