📚 课程目录第3章 Artifact Registry镜像仓库管理

3. Artifact Registry镜像仓库管理

Artifact Registry 是 Google Cloud 上用于存储、管理容器镜像与语言包制品的统一仓库服务，也是当前推荐替代 Container Registry（gcr.io）的方案。它支持 Docker 镜像、Helm Chart、Maven、npm、Python 等多种制品格式，并原生集成 IAM 权限、Vulnerability Scanning 漏洞扫描和清理策略。本节围绕仓库创建、镜像推送拉取、权限控制、漏洞扫描与生命周期策略五个环节展开，帮助你把镜像从本地可靠地交付到 GKE 或 Cloud Run。

一、创建仓库：位置与格式决定访问路径

创建仓库前需要先确定三件事：仓库名称、区域（location）和制品格式（format）。Artifact Registry 的仓库是区域级资源，镜像地址形如 LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG。区域选择直接影响拉取延迟与跨区流量费用，通常建议与 GKE 集群或 Cloud Run 服务处于同一区域。

gcloud artifacts repositories create app-repo \
  --repository-format=docker \
  --location=asia-east1 \
  --description="应用交付镜像仓库" \
  --immutable-tags

gcloud artifacts repositories list --location=asia-east1

其中 --immutable-tags 表示标签不可变，同一个 tag 一旦推送就不能被覆盖，这对生产环境防止“同名不同内容”非常关键。若团队需要频繁覆盖 latest 做开发迭代，可省略该参数，但生产仓库建议开启。创建完成后，推送前还需为 Docker 配置认证助手：

gcloud auth configure-docker asia-east1-docker.pkg.dev

该命令会在本地 Docker 配置中写入凭据助手，后续 docker push 会自动使用当前 gcloud 账号的访问令牌。

二、推送与拉取镜像

推送流程是：本地构建 → 打上完整仓库地址标签 → 推送。假设项目 ID 为 demo-proj，仓库为 app-repo，区域为 asia-east1：

docker build -t asia-east1-docker.pkg.dev/demo-proj/app-repo/web:v1.0.0 .
docker push asia-east1-docker.pkg.dev/demo-proj/app-repo/web:v1.0.0

# 拉取
docker pull asia-east1-docker.pkg.dev/demo-proj/app-repo/web:v1.0.0

在 GKE 中引用同一镜像时，Pod 的 image 字段直接写完整地址即可。需要注意：GKE 节点默认使用节点服务账号拉取镜像，因此该服务账号必须对仓库拥有读取权限，否则会出现 ImagePullBackOff。可用如下命令查看镜像列表与标签：

gcloud artifacts docker images list \
  asia-east1-docker.pkg.dev/demo-proj/app-repo --include-tags

三、权限控制：最小权限与角色划分

Artifact Registry 的权限完全由 IAM 控制，常用角色有三个：roles/artifactregistry.reader（拉取）、roles/artifactregistry.writer（推送与拉取）、roles/artifactregistry.admin（仓库管理）。推荐做法是：CI/CD 服务账号只授予 writer，GKE 节点服务账号只授予 reader，管理员才使用 admin。授权命令示例：

gcloud artifacts repositories add-iam-policy-binding app-repo \
  --location=asia-east1 \
  --member="serviceAccount:ci-runner@demo-proj.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

若使用跨项目拉取，需要在目标项目仓库上为源项目服务账号授予 reader。对于 GKE Autopilot 或使用 Workload Identity 的场景，应把 Kubernetes ServiceAccount 绑定到具备 reader 权限的 Google 服务账号，而不是依赖节点默认账号。

四、漏洞扫描：从推送即扫到结果判读

启用 Container Scanning API 后，Artifact Registry 会在镜像推送时自动触发扫描，并在元数据中记录漏洞。扫描结果按严重级别分为 CRITICAL、HIGH、MEDIUM、LOW。查看方式：

gcloud artifacts docker images describe \
  asia-east1-docker.pkg.dev/demo-proj/app-repo/web:v1.0.0 \
  --show-package-vulnerability

判读结果时不要只看总数，应重点关注 CRITICAL 与 HIGH 中是否存在“有修复版本”的条目。若某漏洞的 fixed_version 为空，说明上游尚未发布补丁，此时应评估是否可通过更换基础镜像或移除依赖来规避。实践中建议把扫描结果接入 CI 门禁：当 CRITICAL 数量大于 0 时阻断发布，HIGH 则告警并记录。

五、生命周期策略：自动清理旧镜像

镜像会持续累积，占用存储并增加管理成本。Artifact Registry 支持清理策略（cleanup policy），可按标签状态、版本数量、存在时长等条件自动删除。例如“保留最近 10 个版本，删除超过 30 天且带 dev- 前缀的镜像”：

gcloud artifacts repositories set-cleanup-policies app-repo \
  --location=asia-east1 \
  --policy=policy.json

其中 policy.json 可定义 keepCount、deleteOlderThan、tagPrefixes 等条件。策略支持 --dry-run 预演，先观察将被删除的镜像列表，确认无误后再正式启用。生产仓库建议至少保留“最近 N 个版本 + 所有带 release 标签的版本”，避免误删可回滚版本。

建议为生产仓库同时开启 --immutable-tags 与清理策略的 --dry-run 预演，先观察再执行，避免误删可回滚版本。

删除镜像或标签是不可逆操作。启用清理策略前，务必确认策略条件不会命中带 release 或 prod 前缀的关键版本。

综合来看，Artifact Registry 的管理闭环可以概括为：用区域与格式定义访问路径，用 IAM 角色划分读写边界，用推送即扫把安全左移，用清理策略控制长期成本。把这四点落实到 CI/CD 流水线与 GKE 部署清单中，镜像交付才算真正可控。