Jenkins 通用搭建与发布流水线教程:从本地 Docker 到生产服务器

2026-07-17运维7 分钟136 次阅读
AI 摘要鱼粮不足,AI 今天先歇着 · 正文在下面

一、为什么要用 Jenkins

很多个人项目或中小团队项目,最开始都是在 IDEA 里开发、手动打包、手动登录服务器、手动重启 Docker。这个方式前期很快,但服务一多就会出现几个问题:

  • 打包命令容易忘。
  • 上传路径容易错。
  • 哪次发布了什么版本不清楚。
  • 生产服务器密码或私钥容易到处散落。
  • 后续想接 Docker Compose、K8s、回滚、通知时没有统一入口。

Jenkins 的价值不是“高级”,而是把发布流程固定下来:

text 复制代码
提交代码
  -> Jenkins 拉代码
  -> Jenkins 构建
  -> Jenkins 上传产物或镜像
  -> 目标机器执行部署
  -> 查看日志和结果

本文采用非 Docker 方式安装 Jenkins,示例以 macOS 为主,同时给出 Ubuntu 和 Windows 的安装方式。发布示例分两种:

  • 本地 Docker:适合开发机验证。
  • 生产 Docker:适合小团队或个人项目第一阶段上线。

后续要学习 K8s,只需要把最后的 docker compose up -d --build 替换成 kubectl 或 Helm。

二、整体架构

2.1 本地 Docker 发布

text 复制代码
IDEA 开发
  -> Git 提交或 Jenkins 手动构建
  -> Maven/Go/Node 构建产物
  -> 复制产物和 docker-compose.yml 到本机部署目录
  -> docker compose up -d --build

本地部署目录示例:

bash 复制代码
# macOS
/Users/<your-user>/mydata/projects/demo-platform

# Ubuntu
/opt/mydata/projects/demo-platform

# Windows WSL
/mnt/d/mydata/projects/demo-platform

2.2 生产 Docker 发布

text 复制代码
Git push
  -> Jenkins 拉取代码
  -> Jenkins 构建
  -> rsync/scp 上传到生产服务器
  -> ssh 远程执行 docker compose

生产目录示例:

bash 复制代码
/mydata/projects/demo-platform/<service-name>

服务器示例 IP 使用文档保留地址:

text 复制代码
203.0.113.10
203.0.113.11

这些 IP 不能直接使用,实际请替换成你的服务器。

三、官方资料

四、安装 Jenkins

4.1 通用前置检查

macOS、Ubuntu、WSL:

bash 复制代码
java -version
git --version
docker version
docker compose version

Windows PowerShell:

powershell 复制代码
java -version
git --version
docker version
docker compose version

建议:

  • Jenkins LTS 优先准备 Java 21。
  • macOS/Windows 本机 Docker 使用 Docker Desktop。
  • Ubuntu 使用 Docker Engine + Docker Compose plugin。
  • Java 项目优先使用项目自带 ./mvnw。
  • Go、Node、Python 等语言环境要让 Jenkins 服务进程能找到。

4.2 macOS 安装

bash 复制代码
brew update
brew install jenkins-lts
brew info jenkins-lts

按需启动和停止:

bash 复制代码
# 只启动本次,不注册开机自启
brew services run jenkins-lts

# 停止
brew services stop jenkins-lts

# 状态
brew services list

访问:

text 复制代码
http://localhost:8080

初始密码:

bash 复制代码
cat ~/.jenkins/secrets/initialAdminPassword

如果 Homebrew 网络不稳定,或者下载 openjdk、jenkins-lts 很慢,可以改用 WAR 包方式。

4.3 通用方式:下载 Jenkins WAR 包运行

WAR 包方式不局限于 macOS,Windows、Ubuntu 也可以使用,只要机器上有 Java 17 或 Java 21。官方下载页:

text 复制代码
https://www.jenkins.io/download/

在页面里选择:

text 复制代码
Generic Java package (.war)

macOS/Linux 启动示例,端口改成 15555:

bash 复制代码
mkdir -p ~/apps/jenkins
cd ~/apps/jenkins

# 假设 jenkins.war 已经下载到当前目录
java -jar jenkins.war --httpPort=15555

如果希望局域网其他机器访问,可以监听所有网卡:

bash 复制代码
java -jar jenkins.war --httpPort=15555 --httpListenAddress=0.0.0.0

Windows PowerShell 启动示例:

powershell 复制代码
java -jar D:\dev-tools\jenkins\jenkins.war --httpPort=15555

访问地址:

text 复制代码
http://localhost:15555

首次启动初始密码常见位置:

bash 复制代码
# macOS/Linux
cat ~/.jenkins/secrets/initialAdminPassword

Jenkins 初始化完成后,建议设置外链地址:

text 复制代码
Manage Jenkins -> System -> Jenkins Location -> Jenkins URL

本机使用可以填:

text 复制代码
http://localhost:15555/

局域网访问可以填:

text 复制代码
http://<your-lan-ip>:15555/

注意:不要把 Jenkins 直接暴露到公网。初始化完成后,务必设置管理员账号和强密码。

4.4 Ubuntu 安装

bash 复制代码
sudo apt update
sudo apt install -y fontconfig openjdk-21-jre wget gpg

sudo wget -O /usr/share/keyrings/jenkins-keyring.asc \
  https://pkg.jenkins.io/debian-stable/jenkins.io-2023.key

echo "deb [signed-by=/usr/share/keyrings/jenkins-keyring.asc] https://pkg.jenkins.io/debian-stable binary/" \
  | sudo tee /etc/apt/sources.list.d/jenkins.list > /dev/null

sudo apt update
sudo apt install -y jenkins

启动和停止:

bash 复制代码
sudo systemctl start jenkins
sudo systemctl stop jenkins
sudo systemctl status jenkins --no-pager

初始密码:

bash 复制代码
sudo cat /var/lib/jenkins/secrets/initialAdminPassword

如果 Jenkins 要操作本机 Docker:

bash 复制代码
sudo usermod -aG docker jenkins
sudo systemctl restart jenkins

4.5 Windows 安装

Windows 推荐使用 Jenkins LTS Windows Installer,也就是 .msi 安装包。

建议顺序:

  1. 安装 Java 21。
  2. 安装 Git for Windows。
  3. 安装 Docker Desktop。
  4. 安装 Jenkins LTS Windows Installer。
  5. 浏览器打开 http://localhost:8080。

PowerShell 启停:

powershell 复制代码
Start-Service jenkins
Stop-Service jenkins
Get-Service jenkins

Windows 上跑发布任务时,推荐使用 WSL 或 Git Bash 执行 sh、rsync、scp。如果完全使用 Windows 原生环境,需要把 Jenkinsfile 中的 sh 改成 powershell 或 bat。

五、构建环境

5.1 插件

初始化 Jenkins 后建议安装:

  • Pipeline
  • Git
  • SSH Agent
  • Credentials Binding
  • Workspace Cleanup
  • Timestamper
  • AnsiColor
  • Docker Pipeline
  • Kubernetes

5.2 JDK

检查:

bash 复制代码
java -version
javac -version

路径:

bash 复制代码
# macOS
/usr/libexec/java_home -V

# Ubuntu
readlink -f "$(which java)"

# Windows
where.exe java

Jenkins 页面:

text 复制代码
Manage Jenkins -> Tools -> JDK installations

建议命名为:

text 复制代码
jdk21

5.3 Maven

优先使用 Maven Wrapper:

bash 复制代码
./mvnw -v
./mvnw clean package -Dmaven.test.skip=true

常用命令:

bash 复制代码
# 构建整个项目
./mvnw clean package -Dmaven.test.skip=true

# 构建指定模块,同时构建依赖模块
./mvnw clean package -pl <module-path> -am -Dmaven.test.skip=true

# 安装公共模块到本地仓库
./mvnw clean install -pl <module-path> -am -Dmaven.test.skip=true

如果项目没有 mvnw,再安装 Maven:

bash 复制代码
# macOS
brew install maven

# Ubuntu
sudo apt install -y maven

# Windows
winget install Apache.Maven

依赖下载慢时,可以配置:

bash 复制代码
~/.m2/settings.xml

注意 Jenkins 用户的 home 目录可能和你的登录用户不同。

5.4 Go

检查:

bash 复制代码
go version
go env GOROOT
go env GOPATH

交叉编译:

bash 复制代码
# Linux amd64 服务器
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o bin/<service> ./cmd/main.go

# Mac Apple Silicon 本机 Docker
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o bin/<service> ./cmd/main.go

5.5 Docker Compose

检查:

bash 复制代码
docker version
docker compose version
docker ps

典型部署命令:

bash 复制代码
cd /mydata/projects/demo-platform/demo-service
docker compose down || true
docker compose up -d --build
docker compose ps

六、Jenkins 凭据

路径:

text 复制代码
Manage Jenkins -> Credentials -> System -> Global credentials

建议添加:

凭据 ID 类型 用途
git-ssh-key SSH Username with private key 拉取私有 Git 仓库
prod-server-ssh SSH Username with private key 发布到生产服务器
docker-registry Username/Password 推送镜像
kubeconfig-prod Secret file 发布到 K8s

安全建议:

  • 不要把私钥、密码、Token 写进 Jenkinsfile。
  • 不要在博客里贴真实 IP、账号、私钥路径。
  • 生产发布建议使用专用部署用户,例如 deploy,不要长期使用 root。

七、示例项目结构

假设有一个微服务项目 demo-platform:

text 复制代码
demo-platform/
  mvnw
  pom.xml
  demo-gateway/
  demo-admin/
  demo-auth/
  services-go/
  docker/compose/
    demo-gateway/
      Dockerfile
      docker-compose.yml
    demo-admin/
      Dockerfile
      docker-compose.yml
  jenkins/
    pipelines/
      Jenkinsfile-local-docker
      Jenkinsfile-prod-docker

服务清单示例:

服务 类型 端口 模块路径 构建产物 Compose 目录 生产路径 默认主机
demo-gateway Java 18080 demo-gateway demo-gateway/target/demo-gateway.jar docker/compose/demo-gateway /mydata/projects/demo-platform/demo-gateway app-01
demo-admin Java 18081 demo-admin demo-admin/target/demo-admin.jar docker/compose/demo-admin /mydata/projects/demo-platform/demo-admin app-01
demo-auth Java 18083 demo-auth/demo-auth-service demo-auth/demo-auth-service/target/demo-auth.jar docker/compose/demo-auth /mydata/projects/demo-platform/demo-auth app-01
demo-worker Go 18090 services-go/worker services-go/bin/demo-worker docker/compose/demo-worker /mydata/projects/demo-platform/demo-worker app-02

生产主机示例:

text 复制代码
APP_HOST_01=203.0.113.10
APP_HOST_02=203.0.113.11
DEPLOY_USER=deploy
REMOTE_BASE=/mydata/projects/demo-platform

八、本地 Docker 发布 Jenkinsfile

示例参数:

  • SERVICE:选择服务。
  • SKIP_BUILD:跳过构建,仅重启。
  • LOCAL_BASE:本机部署目录。
  • LOCAL_GOARCH:本机 Go 架构,Apple Silicon 选 arm64,x86 Linux 选 amd64。

示例 Jenkinsfile:

groovy 复制代码
pipeline {
    agent any

    options {
        timestamps()
        disableConcurrentBuilds()
    }

    parameters {
        choice(name: 'SERVICE', choices: ['demo-gateway', 'demo-admin'], description: '选择服务')
        booleanParam(name: 'SKIP_BUILD', defaultValue: false, description: '跳过构建')
        string(name: 'LOCAL_BASE', defaultValue: '/Users/<your-user>/mydata/projects/demo-platform', description: '本机部署目录')
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            when {
                expression { !params.SKIP_BUILD }
            }
            steps {
                sh './mvnw clean package -pl demo-gateway -am -Dmaven.test.skip=true'
            }
        }

        stage('Deploy Local Docker') {
            steps {
                sh '''
                  SERVICE_DIR="${LOCAL_BASE}/${SERVICE}"
                  mkdir -p "${SERVICE_DIR}"
                  rsync -av "docker/compose/${SERVICE}/" "${SERVICE_DIR}/"
                  cp "demo-gateway/target/demo-gateway.jar" "${SERVICE_DIR}/"
                  cd "${SERVICE_DIR}"
                  docker compose down || true
                  docker compose up -d --build
                  docker compose ps
                '''
            }
        }
    }
}

九、生产 Docker 发布 Jenkinsfile

生产发布要使用 Jenkins 凭据,不要把私钥写在脚本里:

groovy 复制代码
pipeline {
    agent any

    options {
        timestamps()
        disableConcurrentBuilds()
    }

    parameters {
        choice(name: 'SERVICE', choices: ['demo-gateway', 'demo-admin'], description: '选择服务')
        booleanParam(name: 'CONFIRM_DEPLOY', defaultValue: false, description: '确认发布生产')
    }

    environment {
        DEPLOY_USER = 'deploy'
        APP_HOST = '203.0.113.10'
        REMOTE_BASE = '/mydata/projects/demo-platform'
        SSH_CREDENTIALS_ID = 'prod-server-ssh'
    }

    stages {
        stage('Confirm') {
            steps {
                script {
                    if (!params.CONFIRM_DEPLOY) {
                        error '未确认生产发布,已取消'
                    }
                }
            }
        }

        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build') {
            steps {
                sh './mvnw clean package -pl demo-gateway -am -Dmaven.test.skip=true'
            }
        }

        stage('Deploy') {
            steps {
                sshagent([env.SSH_CREDENTIALS_ID]) {
                    sh '''
                      REMOTE_DIR="${REMOTE_BASE}/${SERVICE}"
                      ssh -o StrictHostKeyChecking=no "${DEPLOY_USER}@${APP_HOST}" "mkdir -p ${REMOTE_DIR}"
                      rsync -avz "docker/compose/${SERVICE}/" "${DEPLOY_USER}@${APP_HOST}:${REMOTE_DIR}/"
                      rsync -avz "demo-gateway/target/demo-gateway.jar" "${DEPLOY_USER}@${APP_HOST}:${REMOTE_DIR}/"
                      ssh "${DEPLOY_USER}@${APP_HOST}" "cd ${REMOTE_DIR} && docker compose down || true && docker compose up -d --build && docker compose ps"
                    '''
                }
            }
        }
    }
}

十、手工验证命令

在接 Jenkins 前,建议先手工验证一遍:

bash 复制代码
cd /path/to/demo-platform
./mvnw clean package -pl demo-gateway -am -Dmaven.test.skip=true

LOCAL_BASE=/Users/<your-user>/mydata/projects/demo-platform
mkdir -p ${LOCAL_BASE}/demo-gateway
rsync -av docker/compose/demo-gateway/ ${LOCAL_BASE}/demo-gateway/
cp demo-gateway/target/demo-gateway.jar ${LOCAL_BASE}/demo-gateway/

cd ${LOCAL_BASE}/demo-gateway
docker compose down || true
docker compose up -d --build

生产服务器验证:

bash 复制代码
ssh deploy@203.0.113.10 "hostname && docker version && docker compose version"

十一、K8s 预留

后续接 K8s 时,建议目录:

text 复制代码
k8s/
  namespaces/
  configmaps/
  secrets/
  services/
    demo-gateway/
      deployment.yaml
      service.yaml
      ingress.yaml

Jenkins 发布阶段可以改成:

groovy 复制代码
withCredentials([file(credentialsId: 'kubeconfig-prod', variable: 'KUBECONFIG_FILE')]) {
    sh '''
      export KUBECONFIG=${KUBECONFIG_FILE}
      kubectl apply -f k8s/services/${SERVICE}/
      kubectl rollout status deployment/${SERVICE} -n demo-platform
    '''
}

更完整的镜像路线:

text 复制代码
Jenkins 构建 jar 或二进制
  -> docker build
  -> docker tag
  -> docker push
  -> helm upgrade 或 kubectl set image

十二、常见问题

Jenkins 找不到 docker

bash 复制代码
whoami
which docker
docker version
docker compose version

macOS/Windows 检查 Docker Desktop 是否启动。Ubuntu 检查 Jenkins 用户是否加入 docker 组。

Jenkins 找不到 Java、Maven、Go

bash 复制代码
echo $PATH
java -version
./mvnw -v
go version

Jenkins 作为服务启动时,环境变量经常比终端少。可以在 Jenkins 全局工具里固定路径,或者在 Jenkinsfile 的 environment 中补 PATH。

Maven 下载慢

配置 Jenkins 运行用户下的 Maven settings:

bash 复制代码
~/.m2/settings.xml

端口冲突

bash 复制代码
lsof -i :8080
docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

SSH 不通

bash 复制代码
ssh deploy@203.0.113.10 "hostname"

Jenkins 中使用 sshagent 包裹远程命令,并确认凭据 ID 正确。

十三、落地顺序

  1. 安装 Jenkins LTS。
  2. 安装插件。
  3. 配置 JDK、Git、Maven Wrapper、Go、Docker。
  4. 配置 Git 和生产服务器 SSH 凭据。
  5. 先跑本地 Docker 发布任务。
  6. 再跑生产 Docker 发布任务。
  7. 最后再考虑镜像仓库、K8s、回滚和通知。
觉得有用就点个赞,不用登录也能读

评论

0 条
登录 之后才能评论
—
还没有评论,来说第一句