如何本地搭建全自动化Jenkins与Docker构建代理环境？

核心选型说明 #

• Jenkins主节点：采用官方jenkins/jenkins:lts镜像，稳定且支持Configuration as Code（CASC）自动配置，彻底替代手动操作。
• 构建代理：选用官方维护的jenkins/agent镜像，废弃第三方过时镜像，支持JNLP协议与主节点通信，可按需启用Docker-in-Docker（DinD）模式满足容器化构建需求。

关键实现步骤 #

1. CASC配置文件编写：通过YAML定义Jenkins全局配置、节点注册规则，实现代理自动接入，无需手动在前端添加节点。
2. Docker Compose编排：整合主节点与代理容器，配置共享网络、数据卷，确保主从通信顺畅，同时持久化Jenkins数据。
3. 权限适配：处理Docker挂载权限（若需代理执行Docker命令）、Jenkins目录权限，避免启动或构建时出现权限错误。
4. 构建任务验证：创建指定代理标签的任务，手动触发后确认任务在代理节点执行。

完整示例代码 #

1. 项目目录结构 #

jenkins-docker-agent/
├── docker-compose.yaml
└── casc_configs/
    └── jenkins_config.yaml

2. docker-compose.yaml 内容 #

version: '3.8'

networks:
  jenkins-net:
    driver: bridge

volumes:
  jenkins_home:
  jenkins_docker_certs:

services:
  jenkins-master:
    image: jenkins/jenkins:lts
    container_name: jenkins-master
    networks:
      - jenkins-net
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      - jenkins_home:/var/jenkins_home
      - ./casc_configs:/usr/share/jenkins/ref/casc_configs/
      - /var/run/docker.sock:/var/run/docker.sock
      - jenkins_docker_certs:/certs/client
    environment:
      - CASC_JENKINS_CONFIG=/usr/share/jenkins/ref/casc_configs/jenkins_config.yaml
      - JENKINS_ADMIN_ID=admin
      - JENKINS_ADMIN_PASSWORD=admin123  # 可自定义密码
    user: root  # 解决Docker socket挂载权限问题，测试环境可用，生产环境需按需调整

  jenkins-agent:
    image: jenkins/agent
    container_name: jenkins-agent
    networks:
      - jenkins-net
    environment:
      - JENKINS_URL=http://jenkins-master:8080
      - JENKINS_AGENT_NAME=docker-agent
      - JENKINS_SECRET=${AGENT_SECRET}  # 由CASC自动生成，无需手动指定
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock  # 若需代理执行Docker命令则保留
    depends_on:
      - jenkins-master

3. casc_configs/jenkins_config.yaml 内容 #

jenkins:
  systemMessage: "Jenkins with auto-configured Docker agent"
  securityRealm:
    local:
      allowsSignup: false
      users:
        - id: "${JENKINS_ADMIN_ID}"
          password: "${JENKINS_ADMIN_PASSWORD}"
  authorizationStrategy:
    loggedInUsersCanDoAnything:
      allowAnonymousRead: false

nodes:
  - permanent:
      name: "docker-agent"
      remoteFS: "/home/jenkins/agent"
      labelString: "docker-agent"
      launcher:
        jnlp:
          workDirSettings:
            disabled: false
            internalDir: "remoting"
            failIfWorkDirIsMissing: false
      nodeProperties:
        - envVars:
            env:
              - key: "PATH"
                value: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

操作说明 #

1. 启动环境：在项目目录下执行docker compose up -d，等待容器启动完成。
2. 验证节点注册：访问http://localhost:8080，用配置的admin账号登录，进入「管理Jenkins」→「节点管理」，可看到docker-agent节点已在线。
3. 创建测试任务：
   • 新建自由风格项目，在「General」中勾选「限制项目运行的节点」，输入标签docker-agent。
   • 在「构建」步骤添加「执行shell」，输入命令echo "Build executed on agent: $(hostname)" && docker --version（若挂载了Docker socket）。
   • 保存后手动触发构建，查看控制台输出，确认任务在代理节点执行。

常见问题解决 #

• CASC未生效：检查CASC_JENKINS_CONFIG环境变量路径是否正确，确保配置文件挂载到容器内的/usr/share/jenkins/ref/casc_configs/目录，Jenkins启动时会自动加载该目录下的配置。
• 代理节点连接失败：确认主从容器在同一网络下，JENKINS_URL环境变量指向主节点的容器名（jenkins-master）而非localhost，因为容器内部无法直接访问宿主机的localhost。
• Docker权限问题：主节点容器使用root用户（测试环境），或给Jenkins用户添加Docker组权限，避免permission denied错误。

内容的提问来源于stack exchange，提问作者Andez