CI/CD / 系统课时

登录镜像仓库并推送制品

登录镜像仓库并推送制品

镜像构建完成后,流水线还需要把它安全地交付到镜像仓库。本节使用 Jenkins Credentials 保存仓库账号,在 Pipeline 中临时注入凭据完成登录和推送,并通过远端镜像查询确认制品确实可用于后续部署。

学习目标

  • 使用 Jenkins Credentials 管理镜像仓库认证信息
  • 在流水线中安全执行 docker login 与 docker push
  • 使用不可变版本标签并验证远端镜像是否存在

把仓库密码留在凭据系统中

不要把用户名、密码或访问令牌直接写进 Jenkinsfile。应先在 Jenkins 中创建 Username with password 类型的凭据,例如凭据 ID 为 registry-credentials,再由流水线按 ID 获取。

流水线真正需要长期保存的是凭据引用,而不是秘密本身。withCredentials 会在代码块执行期间把用户名和密码注入环境变量,离开作用域后不再提供这些变量。

为镜像建立可追踪版本

部署链路不应只推送 latest。更稳妥的做法是使用能够追踪到一次构建的标签,例如 Jenkins 的 BUILD_NUMBER。假设仓库地址为 registry.example.com,项目为 team/demo-api,一次构建可以得到 registry.example.com/team/demo-api:128。

Jenkins 从凭据注入到镜像仓库推送的制品链路

标签应在构建和部署之间保持不变,这样测试环境验证的就是后续准备发布的同一制品,而不是重新构建出的另一个镜像。

在 Pipeline 中登录并推送

下面是可直接放入 Declarative Pipeline 的核心示例。前提是执行该 Stage 的 Jenkins Agent 已安装 Docker CLI、能够访问 Docker daemon,并且本地已经存在对应标签的镜像。

groovy
pipeline {
    agent any
    environment {
        REGISTRY = 'registry.example.com'
        IMAGE_REPO = 'team/demo-api'
    }
    stages {
        stage('Push Image') {
            steps {
                withCredentials([usernamePassword(
                    credentialsId: 'registry-credentials',
                    usernameVariable: 'REGISTRY_USER',
                    passwordVariable: 'REGISTRY_PASS'
                )]) {
                    sh '''
                        set -eu
                        IMAGE="${REGISTRY}/${IMAGE_REPO}:${BUILD_NUMBER}"
                        printf '%s' "$REGISTRY_PASS" | docker login "$REGISTRY" --username "$REGISTRY_USER" --password-stdin
                        docker image inspect "$IMAGE" >/dev/null
                        docker push "$IMAGE"
                        docker logout "$REGISTRY"
                    '''
                }
            }
        }
    }
}

预期输出

text
Login Succeeded
The push refers to repository [registry.example.com/team/demo-api]
<IMAGE_LAYER>: Pushed
<BUILD_NUMBER>: digest: sha256:<ID> size: <SIZE>
Removing login credentials for registry.example.com

<IMAGE_LAYER>、<BUILD_NUMBER>、<ID> 和 <SIZE> 会随实际构建变化。--password-stdin 避免把密码作为命令行参数直接传递;docker image inspect 则让流水线在本地镜像不存在时立即失败,而不是进入含糊的推送错误。

验证远端制品

docker push 成功已经是重要验证,但在关键交付链路中还可以从仓库端再次确认 manifest 可访问。当前 Docker CLI 可使用 docker manifest inspect 查询指定标签。

bash
docker manifest inspect "registry.example.com/team/demo-api:<BUILD_NUMBER>" >/dev/null && echo "remote image exists"

预期输出

text
remote image exists

如果仓库要求认证,这条验证命令应在有效登录会话中执行。实际 <BUILD_NUMBER> 替换为本次 Jenkins 构建号。

推送失败时先定位哪一层

出现 unauthorized 或 denied 时,先检查凭据是否有效,以及账号是否拥有目标仓库的 push 权限;出现网络或 TLS 错误时,检查 Agent 到仓库地址的 DNS、代理、证书信任和连通性;出现 tag does not exist 或本地镜像不存在,则回到构建与打标签阶段核对完整镜像名。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

登录镜像仓库并推送制品

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通