企业官网建设流程全解析

• 示例工程
• 教程
• 后端

导读

本文以 javav2/example_code/ecr 目录下的官方示例为核心，系统讲解如何使用 AWS SDK for Java 2.x 编程式地与 Amazon Elastic Container Registry（Amazon ECR）交互——包括创建与删除镜像仓库、设置与读取仓库策略、获取授权令牌、配置生命周期策略、推送并校验 Docker 镜像等关键操作。读完本文，你将掌握 Hello 级入门示例（listImages分页列镜像）与仓库管理全流程场景（ECRScenario）的完整实现，并能基于仓库中的源码与测试用例自行扩展、运行与验证。

1. 背景与概述

1.1 Amazon ECR 是什么

Amazon ECR 是一个全托管的 Docker 容器镜像仓库，它让开发者可以方便地存储、管理并部署 Docker 容器镜像（见 ecr/README.md 的概述部分）。在实际应用中，团队可以借助EcrAsyncClient编程式地完成镜像的存取与管理，并将其自动化集成到应用部署流水线中，无需自己搭建和运维容器仓库基础设施。

1.2 示例代码组成

本目录下的示例由三个核心 Java 文件和一个 JUnit 测试文件构成：

从源码结构可以看出，场景类使用异步客户端（EcrAsyncClient）+CompletableFuture的编程模型，这与传统同步阻塞式调用有明显差异，是 Java SDK 2.x 高并发场景的推荐用法。

2. 运行前的重要提醒

原文档在“Important”一节明确提示，运行这些示例前必须注意以下四点：

• 可能产生 AWS 费用：运行代码（含测试）都会对 AWS 账户计费，请参阅 AWS Pricing 与 Free Tier 页面了解预期费用。
• 遵循最低权限原则：建议只授予完成任务所需的最小权限（Grant least privilege），不要使用管理员级权限运行示例。
• 区域兼容性：本示例代码并未在每一个 AWS 区域测试过，运行前请确认目标区域支持 Amazon ECR。
• 破坏性操作风险：场景中包含DeleteRepository（可强制删除仓库及其全部镜像），务必在测试专用资源上操作。

3. 环境准备与工程结构

3.1 前置条件

完整的前置条件见 javav2/README.md，要点如下：

• 本地可访问本仓库（clone、fork 或下载 zip）；
• 安装 Apache Maven（版本 > 3.0）；
• Java 示例统一假定 SDK 能通过默认凭证链（default credentials provider chain）获取 AWS 凭证，可配置~/.aws/config（IAM Identity Center SSO）或~/.aws/credentials（临时凭证）；
• 默认区域为us-east-1（未显式配置区域时）。

对应到 pom.xml，本项目锁定Java 21（maven.compiler.source/target=21），通过 BOM 管理 AWS SDK 版本（software.amazon.awssdk:bom:2.35.10），并额外引入docker-java（3.3.6）用于在 Java 进程内直接调用本地 Docker 守护进程完成镜像推送。

3.2 构建与运行方式

在 javav2/example_code/ecr 目录下执行：

mvn package # 编译并打包（生成 target 下的可执行 JAR） mvn test # 运行 JUnit 测试

需要补充一点：由于场景中的pushDockerImage依赖本地 Docker 环境，运行前必须保证 Docker 守护进程可用，并提前在本地准备好名为echo-text的 Docker 镜像（场景程序启动时会先检查该镜像是否存在，不存在则直接退出）。

4. Hello Amazon ECR：入门示例

HelloECR.java 演示了 Java SDK 2.x 中最有代表性的分页器（Paginator）用法。

4.1 运行方式

java -cp target/ecr-1.0-SNAPSHOT.jar com.example.ecr.HelloECR <repositoryName>

其中<repositoryName>为要列取镜像的 ECR 仓库名称。

4.2 核心实现

EcrClient ecrClient = EcrClient.builder() .region(Region.US_EAST_1) .build(); ListImagesRequest listImagesPaginator = ListImagesRequest.builder() .repositoryName(repoName) .build(); ListImagesIterable imagesIterable = ecrClient.listImagesPaginator(listImagesPaginator); imagesIterable.stream() .flatMap(r -> r.imageIds().stream()) .forEach(image -> System.out.println("The docker image tag is: " + image.imageTag()));

实现要点：

• 客户端构建时显式指定Region.US_EAST_1；
• 关键在listImagesPaginator：它返回ListImagesIterable，SDK 会自动处理分页（每次请求默认返回最多 100 条镜像 ID），代码只需对imageIds()流式展开即可拿到每个镜像的imageTag，无需手动翻页。

5. 场景：Learn the basics（仓库管理全流程）

ECRScenario.java 是本文档的核心场景示例，它演示了以下 10 个步骤，对应原文档 “Learn the basics” 的完整清单：

1. 创建一个 Amazon ECR 仓库；
2. 设置仓库策略（Repository Policy）；
3. 读取并展示仓库策略；
4. 获取 ECR 授权令牌（Authorization Token）；
5. 获取仓库 URI；
6. 为仓库设置生命周期策略（Lifecycle Policy）；
7. 将本地 Docker 镜像推送到 ECR 仓库；
8. 校验镜像是否已存在于仓库；
9. （可选）通过 AWS CLI 与 ECR 中的镜像交互；
10. 删除 ECR 仓库。

5.1 运行方式与参数

java -cp target/ecr-1.0-SNAPSHOT.jar com.example.ecr.scenario.ECRScenario <iamRoleARN> <accountId>

两个参数含义：

• iamRoleARN：拥有访问与管理 ECR 仓库权限的 IAM 角色 ARN（用于写入仓库策略的 Principal）；
• accountId：你的 AWS 账户 ID（用于拼接第 9 步的 CLI 指令中的 registry 地址）。

程序启动后是交互式的，输入1运行完整流程，输入2可直接清理上一次未跑完留下的echo-text仓库；流程中每一步都需要输入c回车继续。

5.2 场景前置条件

根据 ECRScenario.java 的注释：

• 需按 AWS SDK for Java 开发者指南完成开发环境与凭证配置；
• 需要预先创建一个具有 Amazon ECR 操作权限的IAM 角色；
• 必须在本地 Docker 中存在名为echo-text的镜像，否则程序会直接退出。

6. 核心单动作 API 深度解析

所有单动作实现集中在 ECRActions.java，采用EcrAsyncClient+CompletableFuture的异步模型。下面按原文档列出的动作逐一展开。

6.1 CreateRepository：创建仓库

对应 ECRActions.java 中的createECRRepository：

• 对仓库名做空值校验，抛出IllegalArgumentException；
• 通过getAsyncClient().createRepository(request)发起异步调用，join()等待结果；
• 返回值是仓库 ARN（result.repository().repositoryArn()）；
• 异常容错：若捕获到EcrException且错误码为RepositoryAlreadyExistsException，程序不报错而是转为describeRepositories查询已有仓库并返回其 ARN（幂等处理）。

6.2 DeleteRepository：删除仓库

对应 ECRActions.java 中的deleteECRRepository：

• 请求中设置force(true)：当仓库非空时，强制删除并让 ECR 代为清理其中全部镜像（场景第 10 步明确提示了这一点）；
• 使用whenComplete回调 +join()等待，失败时区分EcrException与未知运行时异常。

6.3 DescribeImages：校验镜像存在

对应 ECRActions.java 中的verifyImage：

• 请求通过imageIds(ImageIdentifier.builder().imageTag(imageTag).build())指定待查 Tag；
• 响应中imageDetails()非空即表示镜像存在，输出Image is present in the repository.，否则输出不存在提示；
• 该动作同时用于场景第 8 步与GetAuthorizationToken前的依赖校验。

6.4 DescribeRepositories：获取仓库 URI 与详情

对应 ECRActions.java 中的getRepositoryURI：

• 通过describeRepositories获取仓库列表，取第一个仓库的repositoryUri()输出；
• 仓库 URI 是部署到 EKS/ECS 时必须使用的镜像完整地址前缀，这也是场景第 5 步专门讲解它的原因；
• 异常处理中特别处理了InterruptedException（恢复线程中断标志后抛出）。

6.5 GetAuthorizationToken：获取授权令牌

对应 ECRActions.java 中的getAuthToken：

• 无参调用getAuthorizationToken()；
• 从响应authorizationData().get(0)中取出authorizationToken；
• 该令牌是后续docker login/ Docker 客户端 push 镜像的认证基础——没有它，就无法对 ECR 仓库执行推拉与管理镜像操作。

6.6 GetRepositoryPolicy：读取仓库策略

对应 ECRActions.java 中的getRepoPolicy：

• 按仓库名调用getRepositoryPolicy，成功时返回policyText()（JSON 字符串），场景第 3 步将其打印出来用于确认策略已生效。

6.7 SetRepositoryPolicy：设置仓库策略

对应 ECRActions.java 中的setRepoPolicy：

• 接收repoName与iamRole两个参数；
• 使用文本块模板生成策略 JSON，通过String.format将 IAM 角色 ARN 填入Principal.AWS：

{ "Version" : "2012-10-17", "Statement" : [ { "Sid" : "new statement", "Effect" : "Allow", "Principal" : { "AWS" : "<iamRole>" }, "Action" : "ecr:BatchGetImage" } ] }

• 该策略向指定主体授予ecr:BatchGetImage权限，使其能从该仓库拉取 Docker 镜像；
• 异常分支中单独处理了RepositoryPolicyNotFoundException。

6.8 SetLifeCyclePolicy：设置生命周期策略

对应 ECRActions.java 中的setLifeCyclePolicy：

• 通过StartLifecyclePolicyPreviewRequest提交策略文本，触发生命周期策略预览（注意原文档将该动作链接标记为StartLifecyclePolicyPreview）；
• 示例策略自动清理 14 天以上、任何 Tag 状态的旧镜像：

{ "rules": [ { "rulePriority": 1, "description": "Expire images older than 14 days", "selection": { "tagStatus": "any", "countType": "sinceImagePushed", "countUnit": "days", "countNumber": 14 }, "action": { "type": "expire" } } ] }

• 策略含义：按“距推入时间超过 14 天”为条件，对any（任意 tag 状态）的镜像执行expire动作，从而控制仓库体积与成本。

6.9 PushImageCmd：推送本地 Docker 镜像

对应 ECRActions.java 中的pushDockerImage，是整个场景中技术最综合的一步：

1. 先调用getAuthorizationToken()拿到令牌；
2. 对令牌做Base64 解码，取decodedToken.substring(4)（跳过AWS:前缀）作为 Docker 登录密码；
3. 通过describeRepositories获取仓库repositoryUri()，并截取/之前的部分作为 registry 地址；
4. 构造docker-java的AuthConfig（用户名AWS、上一步的密码、registry 地址）；
5. 使用getDockerClient().tagImageCmd(...)将本地镜像echo-text:latest打上仓库 URI 的 Tag；
6. 调用pushImageCmd(registryUrl).withTag(...).withAuthConfig(authConfig).start().awaitCompletion()完成推送。

Docker 客户端的构建逻辑（ECRActions.java）也做了平台适配：Windows 下通过tcp://localhost:2375连接 Docker Desktop（配 20 秒读写/连接超时），其他平台使用默认本地 socket。

6.10 异步客户端的底层配置

场景中所有操作共用一个 getAsyncClient()，值得单独说明：

• HTTP 客户端选用NettyNioAsyncHttpClient：基于 Netty + Java NIO 的非阻塞事件驱动实现，maxConcurrency(50)控制并发连接数，连接/读/写超时均设 60 秒；
• 通过ClientOverrideConfiguration设置整体 API 调用超时 2 分钟、单次尝试超时 90 秒；
• 客户端以单例形式惰性初始化，复用连接池，避免重复建连开销。

7. 集成测试：验证动作正确性

测试文件 ECRTest.java 使用 JUnit 5（@Order控制执行顺序，@Tag("IntegrationTest")标注集成测试）：

• testScenario（Order 1）：按顺序依次执行创建仓库 → 设置策略 → 读取策略 → 获取令牌 → 获取 URI → 设置生命周期策略 → 推送镜像 → 校验镜像，全部通过assertDoesNotThrow断言；任一环节失败时会在 catch 中先删除仓库进行清理再抛出失败；
• testHello（Order 2）：复用HelloECR.listImageTags对已有仓库执行列镜像操作；
• 敏感参数来源：仓库名、IAM 角色 ARN 等运行期参数通过 AWS Secrets Manager（依赖中引入secretsmanager与gson）从名为test/ecr的密钥中读取，避免硬编码。

运行测试的命令与 Java 示例一致：

mvn test

需要特别强调：运行这些集成测试会操作真实 AWS 资源，可能产生费用，且要求本机 Docker 可用、AWS 凭证有效。

8. 附加资源与延伸学习

• 场景第 9 步演示的 CLI 等价操作（来自 ECRScenario.java）：

# 1. 认证 aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <accountId>.dkr.ecr.us-east-1.amazonaws.com # 2. 查看镜像详情 aws ecr describe-images --repository-name echo-text --image-ids imageTag=echo-text # 3. 运行容器 docker run --rm <accountId>.dkr.ecr.us-east-1.amazonaws.com/echo-text:echo-text

• 服务级文档：Amazon ECR User Guide（what-is-ecr）、Amazon ECR API Reference；
• SDK 参考：SDK for Java 2.x 的software.amazon.awssdk.services.ecr包摘要；
• 与本示例配套的完整前置条件与测试说明见 javav2/README.md。

9. 小结

通过本仓库的 ecr/README.md 及其配套源码，你可以获得一条完整的 ECR 编程实践路径：从HelloECR的分页列镜像入门，到ECRScenario的“建仓 → 授权 → 设策略 → 取令牌 → 推镜像 → 校验 → 清理”全流程闭环，再到ECRTest的可复用集成测试骨架。所有动作均基于EcrAsyncClient异步客户端实现，配合 docker-java 打通了“本地 Docker → ECR 云端仓库”的完整链路，可直接作为 Java 服务端容器化发布流水线的参考实现。

• 示例工程
• 教程
• 后端