华为云容器镜像服务SWR对接使用完全指南

1. 什么是华为云容器镜像服务SWR

容器镜像服务（SoftWare Repository for Container，简称SWR）是华为云提供的一项支持容器镜像全生命周期管理的云服务。SWR为用户提供了简单易用、安全可靠的镜像管理功能，帮助开发者和运维团队快速部署容器化应用。

在容器化技术日益普及的今天，镜像管理已经成为应用交付链中至关重要的一环。SWR解决了传统镜像管理中的诸多痛点：镜像分散存储难以统一管理、镜像拉取速度慢影响部署效率、镜像安全缺乏有效保障、权限控制不够精细等。通过SWR，用户可以方便地构建、上传、下载和管理容器镜像，实现应用的标准化打包与分发。

SWR完全兼容Docker的API和命令行工具，这意味着开发者可以使用熟悉的Docker命令来操作SWR镜像仓库。对于国内开发者而言，SWR相比直接使用Docker Hub具有明显的速度优势——实测表明，同样的镜像从SWR拉取比从Docker Hub快3到5倍。这对于需要频繁构建部署的CI/CD流程来说，能显著提升工作效率。

2. SWR的核心功能特性

SWR提供了丰富而完善的镜像管理功能，覆盖了从镜像构建、存储、分发到部署的完整链路。

2.1 镜像全生命周期管理

SWR支持镜像的完整生命周期管理，包括镜像的上传、下载、删除等基本操作。用户可以通过SWR控制台或容器引擎客户端，轻松完成镜像的推送与拉取。SWR支持的镜像制品类型包括Docker Image Manifest V2 Schema 2和Open Container Initiative（OCI）规范。

2.2 私有镜像仓库与细粒度权限管理

SWR提供私有镜像库，并支持细粒度的权限管理，可以为不同用户分配相应的访问权限（读取、编辑、管理）。通过统一身份认证服务IAM，企业可以根据业务组织，给不同职能部门的员工创建IAM用户，让员工拥有唯一安全凭证，并使用SWR资源。

2.3 镜像安全扫描

SWR提供了镜像安全扫描功能，用户只需一键即可对私有镜像进行安全扫描，发现镜像中的漏洞并给出修复建议。扫描内容包括系统漏洞、应用漏洞、恶意文件、软件信息、文件信息、基线配置、弱口令、敏感信息、软件合规和基础镜像信息等。企业版SWR还支持在命名空间上配置镜像下载阻断能力，当镜像存在漏洞时不允许下载，有效降低生产环境风险。

2.4 镜像加速与大规模分发

SWR通过镜像下载加速技术，使CCE集群下载镜像时在确保高并发下能获得更快的下载速度。SWR还提供了镜像加速器功能，可以帮助用户加速常用开源镜像的拉取。

2.5 镜像触发器与自动化部署

SWR可搭配云容器引擎CCE一起使用，实现镜像版本更新时自动更新使用该镜像的应用。用户只需要为镜像添加一个触发器，通过触发器，可以在每次生成新的镜像版本时自动执行更新动作。

2.6 镜像同步与跨区域分发

镜像上传后，用户可以使用镜像同步功能帮助把最新推送的镜像版本同步到其他区域注册表内，支持自动同步和手动同步两种方式。

2.7 基础版与企业版对比

SWR目前有基础版和企业版两个版本。基础版本身不收费，但其部分特性（如镜像扫描、触发器）使用到其他云服务时会根据相应服务的收费策略进行收费。企业版当前处于公测期间暂不收费，企业仓库的镜像存储使用对象存储服务OBS，会按照OBS的存储收费和流量收费标准进行收费。企业版相比基础版增加了标签管理、批量镜像老化、批量镜像同步、镜像签名、镜像版本不可变、网络访问控制、自定义域名等高级功能。

3. 准备工作：开通SWR服务与环境配置

在使用SWR之前，需要完成一些准备工作。首先需要有一个华为云账号，如果还没有账号，需要先完成注册。

需要先登录华为云控制台，点击：华为云控制台，还没有账号，点击：注册并关联，已有账号点击：登录后关联

3.1 开通SWR服务

登录华为云控制台后，在服务列表中找到"容器镜像服务 SWR"，点击进入服务页面。首次使用时，系统会提示开通服务，按照页面指引完成开通即可。SWR基础版服务本身是免费的，无需额外付费。

3.2 安装容器引擎

使用SWR需要在本地的构建环境或服务器上安装容器引擎。SWR支持Docker容器引擎（版本1.11.2到24.0.9）以及containerd容器引擎。

以CentOS系统为例，安装Docker的命令如下：

curl -fsSL get.docker.com -o get-docker.sh
sh get-docker.sh
sudo systemctl daemon-reload
sudo systemctl restart docker

对于Ubuntu系统，可以使用以下命令安装：

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce

安装完成后，可以通过`docker --version`命令验证安装是否成功。

3.3 网络配置要求

安装容器引擎的虚拟机或服务器需要能够访问互联网。如果是内网服务器，需要绑定弹性公网IP才能访问SWR服务。对于使用华为云ECS或CCE节点的场景，建议优先使用内网访问SWR，这样可以获得更快的上传下载速度并节省流量费用。

4. 创建组织与镜像仓库

在SWR中，"组织"（Namespace）是镜像管理的顶层容器，类似于Docker Hub中的命名空间。组织用于对镜像进行逻辑分组和权限隔离。

4.1 创建组织

登录SWR控制台后，在左侧导航栏选择"组织管理"，点击右上角"创建组织"按钮。在弹出的对话框中输入组织名称，点击"确定"即可完成创建。

组织名称需要遵循命名规范：只能包含小写字母、数字、连字符和下划线，且不能以连字符或下划线开头或结尾。

4.2 镜像仓库命名规则

在SWR中，镜像的完整地址格式为：

[镜像仓库地址]/[组织名称]/[镜像名称]:[镜像版本]

其中镜像仓库地址可以在SWR控制台的"我的镜像"页面，点击"客户端上传"后获取。镜像名称和版本号由用户自定义，但需要注意命名规范，避免使用特殊字符。

5. 获取登录指令与连接SWR

在使用Docker客户端推送或拉取镜像之前，需要先登录到SWR镜像仓库。SWR提供了两种登录方式：临时登录指令和长期登录指令。

5.1 获取临时登录指令

临时登录指令的有效期可以自定义设置，支持15分钟到24小时。获取方式如下：

1. 登录SWR控制台
2. 在左侧导航栏选择"我的镜像"
3. 点击右上角"客户端上传"按钮
4. 在弹出的对话框中点击"生成登录指令"
5. 复制生成的登录指令并在容器引擎所在的虚拟机上执行

生成的登录指令格式类似于：

docker login -u [用户名] -p [密码] [镜像仓库地址]

5.2 获取长期登录指令

如果需要长期有效的登录凭证，可以通过华为云API获取长期登录指令，或者使用永久AK/SK生成登录凭证。长期登录指令适合在CI/CD流水线等自动化场景中使用。

5.3 验证登录状态

执行登录指令后，可以通过以下命令验证是否登录成功：

docker info

或者在执行推送或拉取操作时观察是否提示认证成功。

6. 上传镜像到SWR

SWR支持两种镜像上传方式：通过容器引擎客户端上传和通过SWR控制台页面上传。需要注意的是，上传镜像暂时没有开放镜像上传的API。

6.1 通过Docker客户端上传镜像

这是最常用的镜像上传方式，适用于CI/CD流水线和日常开发场景。操作步骤如下：

步骤一：构建镜像

首先需要编写Dockerfile文件来定义镜像的构建规则。以下是一个简单的Spring Boot应用Dockerfile示例：

FROM openjdk:8-jre-alpine
WORKDIR /app
COPY target/myapp.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

使用docker build命令构建镜像：

docker build -t myapp:1.0.0 .

步骤二：为镜像打标签

构建完成后，需要为镜像打上符合SWR地址规范的标签：

docker tag myapp:1.0.0 swr.cn-east-3.myhuaweicloud.com/myorg/myapp:1.0.0

其中`swr.cn-east-3.myhuaweicloud.com`是镜像仓库地址，`myorg`是组织名称，`myapp`是镜像名称，`1.0.0`是版本号。

步骤三：推送镜像

使用docker push命令将镜像推送到SWR：

docker push swr.cn-east-3.myhuaweicloud.com/myorg/myapp:1.0.0

推送成功后，可以在SWR控制台的"我的镜像"页面看到该镜像。

6.2 通过控制台页面上传

对于快速验证或少量镜像的上传，可以使用SWR控制台的页面上传功能。操作步骤如下：

1. 登录SWR控制台
2. 在左侧导航栏选择"我的镜像"
3. 点击右上角"页面上传"按钮
4. 选择目标组织和镜像文件（tar格式）
5. 点击上传完成操作

6.3 使用containerd客户端上传

如果使用containerd作为容器引擎，可以使用nerdctl命令上传镜像：

nerdctl push swr.cn-east-3.myhuaweicloud.com/myorg/myapp:1.0.0

SWR同时支持Docker和containerd两种容器引擎客户端。

7. 从SWR拉取镜像

当需要使用镜像仓库中的镜像时，需要从镜像仓库拉取镜像到本地。SWR中的镜像类型有公开和私有两种。

7.1 拉取公开镜像

公开镜像所有用户默认都能下载。SWR也支持对公开镜像的下载进行权限控制。

7.2 拉取私有镜像

私有镜像受具体权限管理控制。用户需要被授予对应组织或镜像的读取权限才能拉取私有镜像。

7.3 拉取操作步骤

使用Docker客户端拉取镜像的步骤如下：

1. 以root用户登录容器引擎所在的虚拟机
2. 执行登录指令连接容器镜像服务
3. 登录SWR控制台，在左侧导航栏选择"我的镜像"，点击镜像名称进入详情页
4. 在镜像详情页中，点击对应镜像版本"下载指令"列的复制图标，复制镜像下载指令
5. 在虚拟机中执行复制的镜像下载指令

下载指令示例：

docker pull swr.cn-east-3.myhuaweicloud.com/myorg/myapp:1.0.0

使用`docker images`命令可以查看是否下载成功。

如果需要将镜像保存为归档文件，可以使用以下命令：

docker save swr.cn-east-3.myhuaweicloud.com/myorg/myapp:1.0.0 > myapp.tar

8. 镜像安全扫描

镜像安全是容器化部署中不可忽视的重要环节。SWR提供了完善的镜像安全扫描功能，帮助用户识别并修复潜在的安全风险。

8.1 执行镜像扫描

执行镜像扫描的步骤如下：

1. 登录SWR控制台
2. 在左侧导航栏选择"我的镜像"，点击镜像名称进入镜像详情页
3. 在"镜像版本"页签中，选择待操作的镜像版本
4. 点击操作列的"镜像扫描"按钮
5. 如果镜像尚未同步到主机安全服务，点击"点此同步镜像"完成同步
6. 点击"重新扫描"触发安全扫描

8.2 查看扫描结果

扫描完成后，页面会展示详细的扫描结果：

• 漏洞名称：显示镜像上扫描出的具体漏洞名称
• 修复紧急程度：提示是否需要立刻处理该漏洞
• 软件信息：显示受漏洞影响的软件及版本信息
• 解决方案：针对漏洞给出的修复建议和方案

8.3 扫描约束与限制

镜像扫描有以下约束需要注意：

• 镜像总大小不能超过50G
• 镜像层数不能超过127层，单个镜像层不能超过10G
• Schema v1镜像不支持扫描，建议升级到V2版本
• 多架构镜像不支持镜像扫描
• 扫描时间超过3小时会自动中止

用户需要具备企业主机安全HSS相关权限才能使用镜像扫描功能。在使用HSS进行镜像扫描时会根据其收费策略进行收费。

9. SWR权限管理

SWR通过IAM（统一身份认证服务）提供精细的权限管理能力。通过IAM，企业可以给不同职能部门的员工创建IAM用户，并授权控制他们对SWR资源的访问范围。

9.1 SWR系统策略

IAM中预置了以下SWR系统策略：

• SWR FullAccess：SWR容器镜像仓库所有权限，包括创建、删除、修改等操作
• SWR OperateAccess：SWR操作权限，可以执行镜像的上传、下载等操作，但不包括删除等高危操作
• SWR ReadOnlyAccess：SWR只读权限，只能查看镜像信息，不能进行任何修改操作

9.2 授权流程

为IAM用户授予SWR权限的流程如下：

1. 在IAM控制台创建用户组，并授予容器镜像服务的相应权限（如"SWR Admin"）
2. 在IAM控制台创建用户，并将其加入上一步创建的用户组
3. 新创建的用户登录SWR控制台，切换至授权区域验证权限

9.3 SWR资源路径

在SWR中，资源包括组织和镜像仓库。资源路径格式如下：

• 镜像仓库：`swr:*:*:repo:镜像仓库名称`
• 组织：`swr:*:*:namespace:组织名称`

支持通配符匹配，例如`swr:*:*:repo:test/nginx*`表示test组织下所有以nginx开头的镜像仓库。

10. 镜像加速器配置

为了提升镜像拉取速度，SWR提供了镜像加速器功能。镜像加速器可以帮助用户加速常用开源镜像的下载。

10.1 获取加速器地址

获取加速器地址的步骤如下：

1. 登录SWR控制台
2. 在左侧导航栏选择"镜像资源 > 镜像中心"
3. 点击"镜像加速器"，在弹框中找到"加速器地址"
4. 点击复制按钮将加速器地址复制到剪切板

加速器地址格式类似于：`https://[ID].mirror.swr.myhuaweicloud.com`

10.2 配置Docker使用加速器

编辑Docker的配置文件`/etc/docker/daemon.json`（如果没有则创建），添加以下内容：

{
  "registry-mirrors": ["https://[ID].mirror.swr.myhuaweicloud.com"]
}

配置完成后，重启Docker服务使配置生效：

sudo systemctl daemon-reload
sudo systemctl restart docker

10.3 验证加速器配置

执行以下命令验证加速器是否配置成功：

docker info

如果输出中的`Registry Mirrors`字段显示为SWR加速器地址，说明配置成功。

10.4 注意事项

使用镜像加速器时需要注意以下几点：

• 仅支持通过镜像加速器拉取常用的开源镜像
• 镜像加速器无法保证一定拉取到所有的镜像版本
• 建议将需要的镜像同步到SWR私有仓库使用
• 仅限华为云用户在华为云上的容器产品中使用该镜像加速能力
• 暂不支持containerd容器引擎设置镜像加速器

11. 镜像触发器与自动化部署

SWR的触发器功能可以实现镜像版本更新时自动更新使用该镜像的应用。这对于自动化部署和持续交付场景非常有用。

11.1 添加触发器

添加触发器的步骤如下：

1. 登录SWR控制台
2. 在左侧导航栏选择"我的镜像"，点击镜像名称进入详情页
3. 点击"触发器"页签
4. 点击"添加触发器"按钮
5. 配置触发器参数，包括触发器类型（CCE等）、触发条件等
6. 点击确认完成添加

11.2 触发器工作原理

当用户推送新版本的镜像到SWR时，触发器会自动检测到镜像版本更新，并触发预设的动作。对于CCE类型的触发器，会自动更新CCE中使用该镜像部署的应用。这实现了从镜像构建到应用部署的自动化闭环。

11.3 使用场景

触发器特别适用于以下场景：

• 持续集成/持续部署流水线：代码提交后自动构建镜像并触发部署
• 灰度发布：新版本镜像推送后自动更新到测试环境
• 微服务架构：多个服务独立更新，互不影响

12. 镜像同步与跨区域分发

对于需要在多个区域部署应用的场景，SWR提供了镜像同步功能。

12.1 同步方式

SWR支持两种镜像同步方式：

• 自动同步：配置同步规则后，每次推送新镜像版本时自动同步到目标区域
• 手动同步：用户手动选择需要同步的镜像版本进行同步操作

12.2 跨区域同步的价值

跨区域镜像同步可以有效降低跨地域拉取镜像的网络延迟，提升部署效率。对于全球化部署的应用，通过在各个区域维护镜像副本，可以实现就近拉取，大幅缩短部署时间。

13. 镜像迁移方案

对于已有镜像仓库需要迁移到SWR的场景，华为云提供了多种迁移方案。

13.1 使用image-migrator迁移

image-migrator工具支持将基于Docker Registry v2搭建的Docker镜像仓库中的镜像迁移到华为云SWR中。

13.2 跨云Harbor同步

对于使用Harbor作为镜像仓库的用户，可以通过Harbor的同步功能将镜像同步到SWR。配置方法如下：

1. 在Harbor中配置目标仓库，提供者选择"Huawei SWR"
2. 目标URL使用VPC终端节点中的内网域名，必须以https开头
3. 配置Harbor所在容器内的域名映射

14. SWR与CI/CD集成

SWR可以与各种CI/CD工具集成，实现从代码提交到镜像构建、推送、部署的自动化流程。

14.1 与华为云CodeArts集成

华为云CodeArts提供了与SWR的无缝集成。在CodeArts的构建流程中，可以在"Maven构建"步骤后添加"制作镜像并推送到SWR仓库"构建步骤。配置完成后，每次代码提交都会自动触发镜像构建并推送到SWR。

14.2 与Jenkins集成

在Jenkins流水线中，可以通过执行Shell脚本或使用Docker Pipeline插件来实现与SWR的集成。典型的Jenkins Pipeline片段如下：

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                sh 'docker build -t myapp:${BUILD_NUMBER} .'
            }
        }
        stage('Tag') {
            steps {
                sh 'docker tag myapp:${BUILD_NUMBER} swr.cn-east-3.myhuaweicloud.com/myorg/myapp:${BUILD_NUMBER}'
            }
        }
        stage('Push') {
            steps {
                withCredentials([string(credentialsId: 'swr-password', variable: 'SWR_PWD')]) {
                    sh 'docker login -u ${SWR_USER} -p ${SWR_PWD} swr.cn-east-3.myhuaweicloud.com'
                    sh 'docker push swr.cn-east-3.myhuaweicloud.com/myorg/myapp:${BUILD_NUMBER}'
                }
            }
        }
    }
}

14.3 与GitHub Actions集成

也可以通过GitHub Actions实现自动化构建和推送，已有开源项目（如docker2swr）可以帮助将Docker镜像自动发布到SWR。

15. 镜像老化策略配置

随着镜像版本的不断增加，镜像仓库的存储空间会逐渐被消耗。SWR提供了镜像老化功能，帮助用户自动清理不再需要的镜像版本。

15.1 老化规则类型

SWR支持两种老化处理规则：

• 按存活时间：保留最近N天内推送的镜像版本，超过N天的版本自动删除
• 按保留版本数：每个镜像保留最新的N个版本，超过N个的旧版本自动删除

15.2 配置老化规则

在镜像详情页的"老化规则"页签中，可以添加和配置老化规则。规则设置完成后，系统会根据已定义的规则自动执行镜像老化操作。

16. 常见问题与故障排查

16.1 登录指令执行失败

登录指令执行失败通常有以下原因：

• 容器引擎未安装正确：重新安装容器引擎
• 登录指令已过期：重新生成登录指令
• 网络连接问题：检查网络连通性

16.2 镜像推送失败

镜像推送失败的常见原因包括：

• 镜像命名不规范：检查镜像名称和标签是否符合规范
• 权限不足：确认IAM用户是否有对应组织的推送权限
• 镜像地址错误：确认镜像仓库地址是否正确

16.3 镜像拉取失败

镜像拉取失败的主要原因有：

• 镜像地址错误
• 没有镜像拉取权限
• 边缘节点无法解析SWR和OBS域名

17. 最佳实践建议

17.1 安全最佳实践

SWR安全最佳实践包括以下几个方面：

• 定期镜像扫描：建议定期对存储在SWR中的镜像进行安全扫描，确保所有部署到生产环境的镜像都已通过严格的安全检查
• 加强权限管理：禁止子用户通过管理员权限访问SWR，根据业务需要配置各个子账号对不同容器镜像的访问权限
• 通过VPCEP访问：通过VPC终端节点访问SWR，实现更精细的数据边界控制
• 开启审计日志：SWR审计功能可以实时记录用户对SWR的所有相关操作，帮助事后生成合规报告和事故追根溯源

17.2 性能优化建议

• 优先使用内网地址访问SWR，获得更快的上传下载速度
• 配置镜像加速器加速常用开源镜像的拉取
• 利用镜像同步功能将镜像分发到目标区域，实现就近拉取
• 合理配置镜像老化策略，控制仓库存储成本

18. 总结

华为云容器镜像服务SWR为企业级容器化应用提供了完整的镜像管理解决方案。从镜像的构建、上传、存储、分发到部署，SWR覆盖了镜像全生命周期的每一个环节。通过SWR，开发团队可以实现标准化的镜像管理流程，运维团队可以获得安全可控的镜像分发能力，而DevOps团队则可以利用SWR的触发器、同步等高级功能构建高效的自动化交付流水线。

无论是刚刚开始容器化探索的小型团队，还是已经大规模使用容器技术的大型企业，SWR都能提供与之匹配的服务能力。基础版的免费策略降低了入门门槛，企业版的高级功能则满足了大规模生产环境的严苛要求。结合华为云CCE、CCI等容器服务，SWR可以帮助用户构建完整的云原生应用平台，实现应用的快速迭代和稳定运行。

问答环节

问1：SWR基础版是否收费？
答：SWR基础版本身不收费，但其部分特性（如镜像扫描、触发器）使用到其他云服务时，会根据相应服务的收费策略进行收费。

问2：如何获取SWR的登录指令？
答：登录SWR控制台，在"我的镜像"页面点击"客户端上传"，然后点击"生成登录指令"即可获取临时登录指令。临时登录指令的有效期支持15分钟到24小时自定义设置。

问3：SWR支持哪些容器引擎？
答：SWR支持Docker容器引擎（版本1.11.2到24.0.9）以及containerd容器引擎。

问4：如何对SWR中的镜像进行安全扫描？
答：登录SWR控制台，在"我的镜像"中点击镜像名称进入详情页，在"镜像版本"页签选择待扫描的版本，点击"镜像扫描"即可触发安全扫描。

问5：SWR触发器的作用是什么？
答：SWR触发器可以实现镜像版本更新时自动更新使用该镜像的应用。通过为镜像添加触发器，可以在每次生成新的镜像版本时自动执行更新动作，如自动更新CCE中部署的应用。

问6：如何将其他镜像仓库的镜像迁移到SWR？
答：华为云提供了多种迁移方案，包括使用image-migrator工具迁移基于Docker Registry v2搭建的镜像仓库，以及通过Harbor的同步功能将镜像同步到SWR。