Jenkins 通用搭建与发布流水线教程:从本地 Docker 到生产服务器
一、为什么要用 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 macOS 安装文档:https://www.jenkins.io/doc/book/installing/macos/
- Jenkins Linux 安装文档:https://www.jenkins.io/doc/book/installing/linux/
- Jenkins Windows 安装文档:https://www.jenkins.io/doc/book/installing/windows/
- Jenkins LTS 下载页:https://www.jenkins.io/download/lts/
- Jenkins Pipeline 文档:https://www.jenkins.io/doc/book/pipeline/
- Jenkins Pipeline 语法:https://www.jenkins.io/doc/book/pipeline/syntax/
- Jenkins 凭据管理:https://www.jenkins.io/doc/book/using/using-credentials/
- SSH Agent 插件:https://plugins.jenkins.io/ssh-agent/
- Docker Compose 文档:https://docs.docker.com/compose/
- Kubernetes 插件:https://plugins.jenkins.io/kubernetes/
四、安装 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 安装包。
建议顺序:
- 安装 Java 21。
- 安装 Git for Windows。
- 安装 Docker Desktop。
- 安装 Jenkins LTS Windows Installer。
- 浏览器打开
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 正确。
十三、落地顺序
- 安装 Jenkins LTS。
- 安装插件。
- 配置 JDK、Git、Maven Wrapper、Go、Docker。
- 配置 Git 和生产服务器 SSH 凭据。
- 先跑本地 Docker 发布任务。
- 再跑生产 Docker 发布任务。
- 最后再考虑镜像仓库、K8s、回滚和通知。