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。

标签应在构建和部署之间保持不变,这样测试环境验证的就是后续准备发布的同一制品,而不是重新构建出的另一个镜像。
在 Pipeline 中登录并推送
下面是可直接放入 Declarative Pipeline 的核心示例。前提是执行该 Stage 的 Jenkins Agent 已安装 Docker CLI、能够访问 Docker daemon,并且本地已经存在对应标签的镜像。
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"
'''
}
}
}
}
}预期输出
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 查询指定标签。
docker manifest inspect "registry.example.com/team/demo-api:<BUILD_NUMBER>" >/dev/null && echo "remote image exists"预期输出
remote image exists如果仓库要求认证,这条验证命令应在有效登录会话中执行。实际 <BUILD_NUMBER> 替换为本次 Jenkins 构建号。
推送失败时先定位哪一层
出现 unauthorized 或 denied 时,先检查凭据是否有效,以及账号是否拥有目标仓库的 push 权限;出现网络或 TLS 错误时,检查 Agent 到仓库地址的 DNS、代理、证书信任和连通性;出现 tag does not exist 或本地镜像不存在,则回到构建与打标签阶段核对完整镜像名。