Jenkins拉取Git代码后，如何自动构建Docker镜像并推送到私有仓库？

Question

常见问题：Jenkins构建Docker镜像时提示“Cannot connect to the Docker daemon at unix:///var/run/docker.sock”或“Permission denied while trying to connect to the Docker daemon socket”。 这通常因Jenkins Agent（尤其是Linux节点）未正确配置Docker运行环境所致：Docker服务未启动、Jenkins用户未加入docker组、或使用Docker-in-Docker（DinD）但未挂载socket卷。若Jenkins运行在Kubernetes中，还可能因SecurityContext限制或缺少hostPath挂载导致无法访问宿主机Docker守护进程。此外，在推送镜像到私有仓库（如Harbor）时，常因未配置Docker Registry Credentials（如未在Jenkins凭据管理中添加用户名/密码，或Pipeline中未调用withCredentials）而报错“unauthorized: authentication required”。这些问题会导致CI流程中断，镜像构建或推送失败，直接影响自动化交付链路稳定性。

Answer 1

```html

一、现象层：典型错误日志与触发场景

• Cannot connect to the Docker daemon at unix:///var/run/docker.sock —— Docker守护进程不可达
• Permission denied while trying to connect to the Docker daemon socket —— 权限不足，非docker组用户访问socket
• unauthorized: authentication required —— 推送镜像至Harbor/Artifactory等私有Registry时认证失败
• 常见于Jenkins Agent（Linux物理机/VM）、Docker-in-Docker（DinD）Pod、Kubernetes Jenkins Controller + Node-Labelled Agents等混合架构

二、诊断层：五维根因分析矩阵

维度	检查项	验证命令	预期输出
服务状态	Docker daemon是否运行	sudo systemctl is-active docker	active
用户权限	Jenkins用户是否在docker组	groups jenkins 或 id -nG $USER	含 docker
Socket可达性	/var/run/docker.sock是否存在且可读	ls -l /var/run/docker.sock	srw-rw---- 1 root docker
K8s安全策略	Pod SecurityContext是否禁用hostPath或privileged	kubectl get pod <agent> -o yaml | yq '.spec.securityContext'	无privileged: true或缺失hostPath挂载

三、解决层：分场景精准修复方案

1. Linux Agent基础配置：
   sudo usermod -aG docker jenkins && sudo systemctl restart jenkins
   ⚠️ 注意：需重启Jenkins服务（非仅reload），且确保Jenkins以该用户身份运行（ps aux | grep jenkins）
2. Docker-in-Docker（DinD）模式：
   在Jenkins Agent Pod定义中必须显式挂载：
   

   volumeMounts:
     - name: docker-socket
       mountPath: /var/run/docker.sock
   volumes:
     - name: docker-socket
       hostPath:
         path: /var/run/docker.sock

3. Kubernetes原生构建（推荐替代方案）：
   放弃宿主机Docker daemon，改用kaniko或buildkitd，通过emptyDir缓存层，完全规避socket权限问题

四、凭证层：Registry认证的工业级实践

以下为Jenkins Pipeline中安全注入Harbor凭据的标准写法：

pipeline {
  agent any
  stages {
    stage('Build and Push') {
      steps {
        withCredentials([usernamePassword(
          credentialsId: 'harbor-registry-creds',
          usernameVariable: 'REG_USER',
          passwordVariable: 'REG_PASS'
        )]) {
          sh 'echo "$REG_PASS" | docker login https://harbor.example.com -u "$REG_USER" --password-stdin'
          sh 'docker build -t harbor.example.com/project/app:${BUILD_ID} .'
          sh 'docker push harbor.example.com/project/app:${BUILD_ID}'
        }
      }
    }
  }
}

五、架构层：面向未来的CI容器化演进路径

graph LR
A[Jenkins Master] -->|Declarative Pipeline| B[Agent Pod]
B --> C{构建方式}
C -->|Legacy| D[Host Docker Socket]
C -->|Secure| E[Kaniko w/ gcr.io/kaniko-project/executor]
C -->|High-Performance| F[BuildKit + rootless mode]
D --> G[❌ Security Risk, ❌ Multi-tenancy]
E --> H[✅ No socket, ✅ Non-root, ✅ K8s Native]
F --> I[✅ Layer Caching, ✅ OCI-compliant]

六、验证层：自动化健康检查脚本

建议将以下脚本集成至Agent启动探针（Liveness Probe）或Pre-build Hook：

#!/bin/bash
# check-docker-health.sh
set -e
[[ $(systemctl is-active docker) == "active" ]] || { echo "Docker service down"; exit 1; }
[[ -S /var/run/docker.sock ]] || { echo "Docker socket missing"; exit 1; }
[[ $(id -nG | grep -w docker | wc -l) -eq 1 ]] || { echo "Jenkins not in docker group"; exit 1; }
docker info --format '{{.ServerVersion}}' &>/dev/null || { echo "Docker CLI permission denied"; exit 1; }
echo "✅ Docker environment healthy"

```