Jenkins Docker Compose 安装与使用文档

本文档用于说明如何通过 docker-compose.yaml 部署 Jenkins，并完成首次启动、初始化、日常管理与常见问题排查。

1. 环境要求

在开始之前，请确保服务器或本机已经安装：

  • Docker
  • Docker Compose V2
  • 可用的 8080 和 50000 端口
  • Linux、WSL/Linux 或可运行 Docker 的服务器环境

查看版本：

docker --version
docker compose version

如果系统使用旧版 Docker Compose，命令可能是：

docker-compose version

2. 准备目录

建议创建一个独立目录保存 Compose 文件：

mkdir -p ~/jenkins_compose
cd ~/jenkins_compose

Jenkins 数据会保存到 Docker named volume 中，不再直接绑定宿主机目录。这样可以避免不同用户路径、目录权限和环境变量带来的问题。

3. 创建 Docker Volume

Compose 启动时会自动创建 jenkins_home 数据卷，也可以提前手动创建：

docker volume create jenkins_home

查看数据卷：

docker volume ls

查看数据卷详细信息：

docker volume inspect jenkins_home

该数据卷会挂载到 Jenkins 容器的 /var/jenkins_home，用于持久化 Jenkins 的任务、插件、用户配置和系统配置。

4. docker-compose.yaml

请在 ~/jenkins_compose/docker-compose.yaml 中写入以下内容：

version: '3.8'

services:
  jenkins:
    image: jenkins/jenkins:lts
    container_name: jenkins
    privileged: true
    user: root
    ports:
      - "8080:8080"
      - "50000:50000"
    volumes:
      - jenkins_home:/var/jenkins_home
      - /var/run/docker.sock:/var/run/docker.sock
      - /usr/bin/docker:/usr/bin/docker
    restart: unless-stopped

volumes:
  jenkins_home:
    name: jenkins_home

说明：

  • 8080:8080：Jenkins Web 管理页面端口。
  • 50000:50000：Jenkins agent 连接端口。
  • jenkins_home:/var/jenkins_home：使用 Docker named volume 持久化 Jenkins 数据。
  • /var/run/docker.sock：允许 Jenkins 访问宿主机 Docker。
  • /usr/bin/docker:/usr/bin/docker：把宿主机 Docker CLI 映射到 Jenkins 容器中，解决容器内没有 docker 命令的问题。
  • privileged: true 和 user: root：方便 Jenkins 执行 Docker 相关操作，但会提高安全风险。
  • restart: unless-stopped：系统重启或 Docker 重启后自动恢复 Jenkins 容器。
  • volumes.jenkins_home.name：固定数据卷名称为 jenkins_home，便于后续备份、恢复和迁移。

5. 启动 Jenkins

在 docker-compose.yaml 所在目录执行：

docker compose up -d

查看容器状态：

docker compose ps

查看启动日志：

docker compose logs -f jenkins

6. 首次访问与初始化

浏览器访问：

http://服务器IP:8080

本机部署时可访问：

http://localhost:8080

首次登录需要输入 Jenkins 初始管理员密码，执行：

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

然后按页面提示完成：

  1. 输入初始管理员密码。
  2. 选择安装推荐插件。
  3. 创建管理员账号。
  4. 配置 Jenkins URL。
  5. 进入 Jenkins 控制台。

7. 在 Jenkins 中使用 Docker

当前 Compose 配置已经挂载了宿主机 Docker Socket 和 Docker CLI：

- /var/run/docker.sock:/var/run/docker.sock
- /usr/bin/docker:/usr/bin/docker

这表示 Jenkins 可以通过宿主机 Docker 来构建镜像、启动容器或执行部署。

进入 Jenkins 容器检查 Docker 是否可用：

docker exec -it jenkins bash
docker version

如果容器中提示 docker: command not found，说明 Jenkins 镜像内没有 Docker CLI。可以通过映射宿主机 Docker 命令解决：

volumes:
  - /usr/bin/docker:/usr/bin/docker

如果宿主机 Docker 命令不在 /usr/bin/docker，先查看实际路径：

which docker

然后把左侧宿主机路径替换为实际路径，例如：

volumes:
  - /实际/docker/路径:/usr/bin/docker

也可以选择以下方式处理：

  • 在 Jenkins 容器中安装 Docker CLI。
  • 基于 jenkins/jenkins:lts 制作自定义镜像并预装 Docker CLI。
  • 使用 Jenkins agent 节点执行 Docker 构建任务。

8. 常用管理命令

停止 Jenkins：

docker compose down

启动 Jenkins：

docker compose up -d

重启 Jenkins：

docker compose restart jenkins

查看日志：

docker compose logs -f jenkins

进入容器：

docker exec -it jenkins bash

查看容器资源占用：

docker stats jenkins

9. 升级 Jenkins

拉取最新 LTS 镜像：

docker compose pull

重新创建容器：

docker compose up -d

升级前建议备份 Jenkins 数据卷：

docker run --rm \
  -v jenkins_home:/volume \
  -v "$PWD":/backup \
  alpine \
  tar -czf /backup/jenkins_home_backup.tar.gz -C /volume .

10. 备份与恢复

备份：

cd ~/jenkins_compose
docker run --rm \
  -v jenkins_home:/volume \
  -v "$PWD":/backup \
  alpine \
  tar -czf /backup/jenkins_home_$(date +%F).tar.gz -C /volume .

恢复：

cd ~/jenkins_compose
docker compose down
docker run --rm \
  -v jenkins_home:/volume \
  -v "$PWD":/backup \
  alpine \
  sh -c "rm -rf /volume/* /volume/.[!.]* /volume/..?* 2>/dev/null || true; tar -xzf /backup/jenkins_home_2026-05-30.tar.gz -C /volume"
docker compose up -d

请根据实际备份文件名替换 jenkins_home_2026-05-30.tar.gz。恢复前请确认备份文件正确，恢复操作会清空当前 jenkins_home 数据卷中的原有内容。

11. 常见问题

11.1 端口被占用

如果启动时报错 port is already allocated，说明宿主机端口已被占用。

查看占用情况：

sudo lsof -i :8080

可以修改 Compose 端口映射，例如：

ports:
  - "18080:8080"
  - "50000:50000"

之后访问：

http://服务器IP:18080

11.2 Docker Volume 未创建

一般情况下，执行 docker compose up -d 会自动创建 jenkins_home 数据卷。也可以手动创建：

docker volume create jenkins_home

查看数据卷是否存在：

docker volume ls

11.3 Jenkins 数据卷权限问题

如果 Jenkins 启动失败或无法写入 /var/jenkins_home，可以先查看容器日志：

docker compose logs -f jenkins

由于当前容器使用 user: root，通常不会出现数据卷写入权限问题。如果改为普通用户运行，需要重新调整 Jenkins 数据目录的属主和权限。

11.4 Jenkins 页面打不开

检查容器是否运行：

docker compose ps

查看日志：

docker compose logs -f jenkins

检查防火墙或云服务器安全组是否放行 8080 端口。

12. 安全建议

  • 不建议在公网直接暴露 Jenkins 8080 端口。
  • 建议通过 Nginx、HTTPS 和访问控制保护 Jenkins。
  • 谨慎挂载 /var/run/docker.sock，因为这会让 Jenkins 拥有较高的宿主机 Docker 控制权限。
  • 定期备份 jenkins_home Docker volume 数据。
  • 定期更新 Jenkins 和插件。

13. 快速命令汇总

cd ~/jenkins_compose
docker compose up -d
docker compose ps
docker compose logs -f jenkins
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
docker compose restart jenkins
docker compose down