Jenkins 安装部署

本篇以 Docker Compose 方式部署一个生产可用的 Jenkins 实例，数据持久化、构建权限与首个 Job 一起验证。其他部署方式（war 包、Kubernetes Helm）在本篇末尾对比。

本篇目标：能独立部署一套带持久化的 Jenkins，跑通第一个构建任务。

---

1. Docker Compose 部署

1.1 目录与 compose 文件

jenkins/
├── docker-compose.yml
├── jenkins_home/          # 数据目录（宿主机挂载，持久化 $JENKINS_HOME）
└── .env

# docker-compose.yml
version: "3.8"

services:
  jenkins:
    image: jenkins/jenkins:lts-jdk17
    container_name: jenkins
    restart: always
    ports:
      - "8080:8080"          # Web UI
      - "50000:50000"        # Agent 连接端口（JNLP/Remoting）
    environment:
      TZ: Asia/Shanghai
    volumes:
      - ./jenkins_home:/var/jenkins_home     # 数据持久化，绝不能丢
      # - /var/run/docker.sock:/var/run/docker.sock   # 如需在构建中调用 Docker
    networks:
      - jenkins-net

networks:
  jenkins-net:
    driver: bridge

数据目录是命根子

$JENKINS_HOME 保存了所有 Job 配置、凭证、插件状态和构建记录。必须挂载到宿主机持久卷，并纳入备份策略（见第 14 篇）。容器重建前先备份该目录。

1.2 启动与解锁

cd jenkins
docker compose up -d
docker compose logs -f jenkins

# 查看初始管理员密码
docker compose exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

浏览器访问 http://<服务器>:8080，输入初始密码解锁。首次启动会引导安装插件——建议选择 Install suggested plugins，也可以后续按需安装。

修改默认端口和 Agent 端口

如果 8080 被占用，改 compose 里的端口映射即可。50000 是 Agent 通过 Remoting/JNLP 连接 Master 的端口，被防火墙挡掉会导致 Agent 无法注册，排障时容易漏掉。

1.3 创建管理员与初始化

1. 按引导创建管理员账号（不要用默认 admin + initialAdminPassword）；
2. 设置实例地址（与用户访问的 URL 一致，否则 Webhook 和通知链接会错）；
3. 到 Manage Jenkins → System 检查时区、日志保留策略和 URL。

---

2. HTTPS 与反向代理

生产环境不应裸 HTTP 访问 Jenkins。用 Nginx 反代 + HTTPS 是常见方案：

server {
    listen 443 ssl;
    server_name ci.example.com;

    ssl_certificate     /etc/nginx/ssl/ci.example.com.crt;
    ssl_certificate_key /etc/nginx/ssl/ci.example.com.key;

    client_max_body_size 100m;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_request_buffering off;   # 大数据上传必需
    }
}

配置完成后，在 Manage Jenkins → Security 中设置 Jenkins URL 为 https://ci.example.com/。

不要用 API Token 绕过 HTTPS

反向代理提供加密，但 Jenkins 本身的账号密码仍应使用强密码 + 2FA（可用 Authenticator 插件）。不要把明文密码写在 Webhook URL 或脚本里。

---

3. 部署方式对比

方式	优点	缺点	适用
Docker Compose（本篇）	快速、数据目录清晰	单机、扩展靠多 Agent	中小团队、测试环境
官方 war 包 + Tomcat/systemd	传统、可控	需自管 JVM 与进程	有 Java 运维能力的团队
Kubernetes Helm	弹性、与集群统一	需要维护 PVC、Init 容器权限	已全面容器化的团队
官方 Docker 镜像直跑	最简单	无编排、不易扩展	临时体验

Kubernetes 方式详见本手册第 10 篇，这里不展开。

---

4. 首个 Job 验证

安装 Pipeline 插件（一般默认已有），新建一个自由风格或 Pipeline Job：

pipeline {
    agent any
    stages {
        stage('Hello') {
            steps {
                echo '第一个 Jenkins 构建成功！'
            }
        }
    }
}

点击 Build Now，控制台输出出现 第一个 Jenkins 构建成功！ 即验证通过。

---

5. 验证与排障

现象	检查
访问不了 Web UI	端口映射、防火墙、docker compose ps 是否 Running
首次解锁密码错误	重新 cat 容器内的 initialAdminPassword
插件安装缓慢 / 失败	配置国内插件镜像源（见第 2 篇），重试
保存 URL 后跳转异常	System 配置中的 Jenkins URL 与实际访问地址不一致

---

6. 练习与验收

练习 A

1. 用 Docker Compose 部署一套 Jenkins，成功解锁并创建管理员
2. 配置 Nginx HTTPS 反代，用 https:// 访问 Jenkins
3. 新建一个 Pipeline Job，跑通 echo 构建

练习 B

1. 用 docker compose restart 重启 Jenkins，确认 Job 配置和凭证仍然存在（验证持久化）
2. 把 jenkins_home 目录打成 tar 备份一份，模拟第 14 篇的恢复流程

验收清单

• 能独立用 Docker Compose 部署 Jenkins
• 知道 $JENKINS_HOME 是持久化命根，必须挂载并备份
• 能配置 HTTPS 反向代理
• 能跑通第一个 Pipeline 构建
• 了解三种部署方式的取舍

下一篇：Jenkins 配置管理。