如何使用 Jenkins 流水线自动构建并推送 Docker 镜像到私有仓库

使用 Jenkins 流水线自动构建并推送 Docker 镜像到私有仓库，核心在于配置好 Jenkins 与 Docker 的权限交互，并在 Pipeline 脚本中正确调用 Docker 命令完成登录、构建和推送。

先说结论：通过 Jenkins Pipeline 结合 Docker 插件，可以实现代码提交后自动构建镜像并推送到 Harbor 或 ACR 等私有仓库。

适合：需要持续集成且使用私有镜像仓库（如 Harbor、ACR）的团队。
先看：Jenkins 服务器是否已安装 Docker 且用户有权限执行 docker 命令。
建议：使用 Jenkins 凭证管理存储仓库密码，避免明文写在脚本里；生产环境建议配置 HTTPS 而非 HTTP。
风险：将 jenkins 用户加入 docker 组等同于赋予 root 权限，存在容器逃逸风险，仅限受信任的内网环境使用。

前置准备

在开始配置前，请确保满足以下基础环境要求：

Jenkins 服务器：已安装 Docker 引擎，且版本 compatible 。
私有仓库：Harbor 或类似仓库已部署并可访问，已知晓仓库地址、用户名和密码。
代码仓库：项目根目录下预留了编写 Jenkinsfile 的位置。

权限与安全配置

Jenkins 服务通常使用 jenkins 普通用户运行，调用 docker 命令时需要权限。以下是配置步骤及安全警告：

用户组配置：在 Jenkins 所在的服务器上执行以下命令，将 jenkins 用户加入 docker 组：
```
sudo usermod -aG docker jenkins
```
生效验证：配置完成后必须重启 Jenkins 服务才能生效：
```
sudo systemctl restart jenkins
```
安全警告：此操作相当于赋予 jenkins 用户 root 权限。若 Jenkins 允许用户执行任意脚本，可能存在容器逃逸风险。在高安全要求环境，建议使用 Docker Socket Proxy 或专用构建节点隔离。

凭证与仓库配置

为避免密码明文泄露，需通过 Jenkins 凭证管理存储仓库信息，并配置 Docker 守护进程信任仓库地址。

1. 创建 Jenkins 凭证

登录 Jenkins 管理界面，点击左侧菜单"管理 Jenkins"。
选择"凭证" -> "系统" -> "全局凭证"。
点击左侧"添加凭证"。
种类选择"Username with password"。
输入私有仓库的用户名和密码，ID 填写便于识别的字符串（如 docker-registry-credentials），描述可填"Harbor 仓库凭证"。
点击"确定"保存，记录该凭证 ID。

2. 配置 Docker 信任仓库

若私有仓库使用 HTTP 协议或自签名 HTTPS 证书，需配置 Docker 守护进程信任该地址，否则推送会失败。

编辑 Docker 配置文件 /etc/docker/daemon.json（若不存在则创建）。

添加 insecure-registries 配置项：

{
  "insecure-registries": [
    "http://your-harbor-ip",
    "your-harbor-domain.com"
  ]
}

重启 Docker 服务使配置生效：
```
sudo systemctl restart docker
```

编写 Jenkinsfile

在项目代码根目录下创建名为 Jenkinsfile 的文件。以下是构建并推送镜像的核心脚本片段，可根据实际仓库地址修改：

pipeline {
  agent any
  stages {
    stage('Build and Push') {
      steps {
        script {
          // 使用凭证 ID 登录仓库，自动处理 docker login/logout
          docker.withRegistry('http://your-harbor-ip', 'docker-registry-credentials') {
            // 构建镜像，标签使用构建号确保唯一性
            def customImage = docker.build("my-app:${env.BUILD_NUMBER}")
            // 推送镜像
            customImage.push()
            // 可选：推送 latest 标签
            customImage.push("latest")
          }
        }
      }
    }
  }
}

注意：脚本中的 http://your-harbor-ip 需替换为实际仓库地址，docker-registry-credentials 需替换为之前创建的凭证 ID。

创建流水线任务

配置好脚本后，需在 Jenkins 中创建任务来执行：

点击 Jenkins 首页"新建任务"。
输入任务名称，选择"Multibranch Pipeline"（推荐）或"Pipeline"。
在"Branch Sources"中配置代码仓库地址（如 Git URL）。
若选择 Pipeline 类型，在"Pipeline"配置项中选择"Pipeline script from SCM"，指向包含 Jenkinsfile 的仓库。
保存并点击"立即构建"。

验证与常见故障排查

验证方法

查看控制台：构建完成后，查看 Jenkins 控制台输出，确认没有"permission denied"或"unauthorized"报错。
检查仓库：登录私有镜像仓库 Web 界面，检查是否存在新推送的镜像标签（如 my-app:123）。
拉取测试：在任意机器上尝试 docker pull your-harbor-ip/my-app:123，若能成功下载则说明链路打通。

常见故障排查

权限拒绝 (permission denied)：通常是 jenkins 用户未加入 docker 组，或加入后未重启 Jenkins 服务。
证书验证失败：私有 Harbor 仓库若使用自签证书，未在 Jenkins 服务器配置 Docker daemon 信任该证书，推送会被拒绝。检查 daemon.json 配置。
认证失败 (unauthorized)：检查 Jenkins 凭证 ID 是否填写正确，用户名密码是否过期。
网络连通性问题：确保 Jenkins 构建节点能访问镜像仓库地址。若是 Kubernetes 环境，还需配置 ImagePullSecrets 以便 Pod 拉取私有镜像。