以下为一个可直接落地的 Jenkins Declarative Pipeline（Jenkinsfile）示例，覆盖你提出的各项流水线需求与最佳实践点。请按需替换其中的占位符（如仓库地址、凭据ID、镜像仓库等）。
Jenkinsfile（Declarative）
pipeline {
agent {
docker {
image 'maven:3.9-jdk-17'
// 缓存 Maven 本地仓库 + Docker Socket 以便构建/推送镜像
args '-v $HOME/.m2:/root/.m2 -v /var/run/docker.sock:/var/run/docker.sock'
reuseNode true
}
}
options {
skipDefaultCheckout(true)
timestamps()
disableConcurrentBuilds()
ansiColor('xterm')
buildDiscarder(logRotator(numToKeepStr: '20'))
}
parameters {
string(name: 'BRANCH', defaultValue: 'main', description: '要构建的Git分支或Tag')
choice(name: 'TARGET_ENV', choices: ['staging', 'prod'], description: '目标环境（将进行分段灰度/发布）')
}
// 可用 GitHub Webhook 或 SCM 轮询（按需选用，二者可并存）
triggers {
githubPush()
pollSCM('H/10 * * * *')
}
environment {
// 仓库、镜像与通用变量（按需替换）
GIT_URL = 'git@github.com:your-org/your-repo.git'
GIT_CRED_ID = 'git-ssh-cred-id'
DOCKER_REGISTRY = 'registry.example.com'
IMAGE_REPO = 'registry.example.com/your-team/your-app'
// Maven 本地仓库缓存目录（已通过 -v $HOME/.m2:/root/.m2 映射）
MAVEN_OPTS = '-Dmaven.repo.local=/root/.m2/repository'
MVN_COMMON = '-B -U -Dmaven.repo.local=/root/.m2/repository'
}
stages {
stage('Checkout') {
options { timeout(time: 5, unit: 'MINUTES') }
steps {
deleteDir()
// 拉取指定分支
git branch: params.BRANCH, credentialsId: env.GIT_CRED_ID, url: env.GIT_URL
script {
env.SHORT_SHA = sh(script: "git rev-parse --short HEAD", returnStdout: true).trim()
// 从 pom 获取语义版本
env.VERSION = sh(script: "mvn -q -DforceStdout help:evaluate -Dexpression=project.version", returnStdout: true).trim()
env.IMAGE_TAG_SEMVER = "v${env.VERSION}"
env.IMAGE_TAG_SHA = "v${env.VERSION}-${env.SHORT_SHA}"
currentBuild.displayName = "#${env.BUILD_NUMBER} ${env.IMAGE_TAG_SHA}"
currentBuild.description = "branch=${params.BRANCH}, sha=${env.SHORT_SHA}, env=${params.TARGET_ENV}"
}
}
}
stage('Dependencies') {
options { timeout(time: 10, unit: 'MINUTES') }
steps {
retry(2) {
sh "mvn ${env.MVN_COMMON} dependency:resolve"
}
}
}
stage('Lint & Static') {
options { timeout(time: 10, unit: 'MINUTES') }
steps {
// 只生成报告，不强制失败，把阈值交给 Jenkins Warnings NG 与质量门控
sh "mvn ${env.MVN_COMMON} checkstyle:checkstyle spotbugs:spotbugs"
// 归档报告
archiveArtifacts artifacts: '**/target/site/**, **/target/spotbugsXml.xml, **/target/checkstyle-result.xml', allowEmptyArchive: true
// 静态分析质量门控（需要 Warnings Next Generation 插件）
recordIssues(
enabledForFailure: true,
qualityGates: [
[threshold: 1, type: 'TOTAL', unstable: true] // 任意问题将标记为不稳定，可按需收紧
],
tools: [
checkStyle(pattern: '**/target/checkstyle-result.xml'),
spotBugs(pattern: '**/target/spotbugsXml.xml')
]
)
}
}
stage('UnitTest') {
options { timeout(time: 15, unit: 'MINUTES') }
steps {
sh "mvn ${env.MVN_COMMON} test jacoco:report"
junit allowEmptyResults: false, testResults: '**/target/surefire-reports/*.xml'
// 覆盖率质量门控（需要 Jacoco 插件）
jacoco(
changeBuildStatus: true,
minimumLineCoverage: '0.80', // 80%行覆盖率作为门槛，按需调整
execPattern: '**/target/jacoco.exec'
)
}
}
stage('Build Artifact') {
options { timeout(time: 10, unit: 'MINUTES') }
steps {
sh "mvn ${env.MVN_COMMON} -DskipTests package"
archiveArtifacts artifacts: 'target/*.jar', fingerprint: true
stash name: 'app-jar', includes: 'target/*.jar'
}
}
stage('Docker Build & Push + Trivy') {
options { timeout(time: 20, unit: 'MINUTES') }
steps {
unstash 'app-jar'
withCredentials([usernamePassword(credentialsId: 'docker-registry-cred', usernameVariable: 'DOCKER_USER', passwordVariable: 'DOCKER_PASS')]) {
sh '''
echo "$DOCKER_PASS" | docker login -u "$DOCKER_USER" --password-stdin ${DOCKER_REGISTRY}
docker build -t ${IMAGE_REPO}:${IMAGE_TAG_SHA} -t ${IMAGE_REPO}:${IMAGE_TAG_SEMVER} .
docker push ${IMAGE_REPO}:${IMAGE_TAG_SHA}
docker push ${IMAGE_REPO}:${IMAGE_TAG_SEMVER}
'''
}
// Trivy 扫描高危/严重漏洞，命中则退出失败
sh '''
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
aquasec/trivy:0.52.3 image \
--timeout 10m --severity HIGH,CRITICAL --exit-code 1 \
${IMAGE_REPO}:${IMAGE_TAG_SHA}
'''
}
}
stage('Parallel Tests') {
failFast true
parallel {
stage('Contract Tests') {
options { timeout(time: 15, unit: 'MINUTES') }
steps {
retry(2) {
sh "mvn ${env.MVN_COMMON} -Pcontract-test verify -DskipITs=false"
}
junit allowEmptyResults: true, testResults: '**/target/failsafe-reports/*.xml'
}
}
stage('API Smoke') {
options { timeout(time: 10, unit: 'MINUTES') }
steps {
retry(2) {
// 示例：可替换为 Postman/Newman 或 curl 脚本
sh "mvn ${env.MVN_COMMON} -Papi-smoke test -Dtest=*Smoke*"
}
junit allowEmptyResults: true, testResults: '**/target/surefire-reports/*Smoke*.xml'
}
}
}
}
stage('Deploy Staging (Canary 10% -> 50%)') {
// staging 与 prod 都先走staging灰度
options { timeout(time: 30, unit: 'MINUTES') }
steps {
script {
// Kubeconfig 文件类型凭据
withCredentials([file(credentialsId: 'kubeconfig-staging', variable: 'KUBECONFIG')]) {
try {
// 10% 灰度
sh """
docker run --rm -v "\${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config \
-v "\$PWD":/work -w /work alpine/helm:3.15.2 upgrade --install your-app charts/your-app \
--namespace staging --create-namespace --wait --timeout 5m \
--set image.repository=${IMAGE_REPO} \
--set image.tag=${IMAGE_TAG_SHA} \
--set canary.enabled=true \
--set canary.weight=10
"""
// 就绪与健康探针门控
sh '''
docker run --rm -v "${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config bitnami/kubectl:1.29 \
rollout status deploy/your-app-canary -n staging --timeout=180s
'''
// 升级到 50%
sh """
docker run --rm -v "\${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config \
-v "\$PWD":/work -w /work alpine/helm:3.15.2 upgrade your-app charts/your-app \
--namespace staging --wait --timeout 5m \
--set image.repository=${IMAGE_REPO} \
--set image.tag=${IMAGE_TAG_SHA} \
--set canary.enabled=true \
--set canary.weight=50
"""
sh '''
docker run --rm -v "${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config bitnami/kubectl:1.29 \
rollout status deploy/your-app-canary -n staging --timeout=180s
'''
// 记录变更（示例：为部署打注解）
sh '''
docker run --rm -v "${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config bitnami/kubectl:1.29 \
annotate deploy/your-app-canary -n staging \
release.jenkins/build="${BUILD_TAG}" \
release.image="${IMAGE_REPO}:${IMAGE_TAG_SHA}" --overwrite
'''
} catch (err) {
// 自动回滚
sh '''
docker run --rm -v "${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config \
-v "$PWD":/work -w /work alpine/helm:3.15.2 rollback your-app 0 --namespace staging
'''
error "Staging 灰度失败，已回滚: ${err}"
}
}
}
}
}
stage('Promote Prod (Manual, 100%)') {
when { expression { params.TARGET_ENV == 'prod' } }
options { timeout(time: 45, unit: 'MINUTES') }
steps {
// 审批门禁（可限定审批人角色）
input message: "确认将版本 ${env.IMAGE_TAG_SHA} 发布至生产并切流量到100%？", ok: 'Promote', submitter: 'ops,devlead'
script {
withCredentials([file(credentialsId: 'kubeconfig-prod', variable: 'KUBECONFIG')]) {
// 切换到100% 或关闭 canary（具体取决于你的 Helm Chart 设计）
sh """
docker run --rm -v "\${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config \
-v "\$PWD":/work -w /work alpine/helm:3.15.2 upgrade --install your-app charts/your-app \
--namespace prod --create-namespace --wait --timeout 10m \
--set image.repository=${IMAGE_REPO} \
--set image.tag=${IMAGE_TAG_SHA} \
--set canary.enabled=true \
--set canary.weight=100
"""
sh '''
docker run --rm -v "${KUBECONFIG}":/kube/config -e KUBECONFIG=/kube/config bitnami/kubectl:1.29 \
rollout status deploy/your-app-canary -n prod --timeout=300s
'''
}
}
}
}
}
post {
always {
// 统一清理
cleanWs()
}
success {
script {
// 可选：打 Git Tag（需要对应 push 权限）
// withCredentials([sshUserPrivateKey(credentialsId: env.GIT_CRED_ID, keyFileVariable: 'SSH_KEY')]) { ... }
// 记录版本与发布说明（示例：输出到描述与归档文件）
sh '''
printf "Release: %s\nImage: %s:%s\nCommit: %s\n"
"${IMAGE_TAG_SEMVER}" "${IMAGE_REPO}" "${IMAGE_TAG_SHA}" "${SHORT_SHA}" > release-notes.txt || true
'''
archiveArtifacts artifacts: 'release-notes.txt', allowEmptyArchive: true
}
// 成功通知（按需替换为企业IM/邮箱）
// slackSend channel: '#deploy', color: 'good', message: "SUCCESS ${JOB_NAME} #${BUILD_NUMBER} ${IMAGE_TAG_SHA}"
}
failure {
// 失败通知（按需替换）
// slackSend channel: '#deploy', color: 'danger', message: "FAILED ${JOB_NAME} #${BUILD_NUMBER}"
echo "Pipeline failed. Please check above logs."
}
}
}
说明：如何用 Jenkins 自动化该过程与最佳实践
可行的优化建议
-
提速与稳定
- 依赖缓存：进一步采用 Maven Repo 缓存代理（如 Nexus/Artifactory），并启用 -T 并行编译。
- 容器分层优化：为 Dockerfile 使用 multi-stage，固定基础镜像版本与阿里云/内部镜像加速。
- Trivy 离线缓存：挂载 trivy 的缓存目录 -v $HOME/.cache/trivy:/root/.cache/trivy 缩短扫描时间。
-
扩展质量与安全
- 引入 SCA（依赖漏洞）、SAST（代码安全）以及 Secret Scanning，配合质量阈值作为 PR Gate。
- 使用 Cosign/Sigstore 为镜像签名，部署阶段启用验证（Policy Controller/准入控制）。
-
更强的环境一致性
- 用 Kubernetes 动态 Pod Agent（Jenkins Kubernetes Plugin）替代 Docker Socket 方式，按需注入 sidecar（maven、docker、trivy、kubectl/helm）保证隔离与可重复。
- 将 Helm/Kustomize 与环境配置集中管理，配置漂移通过 GitOps（ArgoCD/Flux）消解。
-
可观测性与变更管理
- 将部署记录上报到变更管理系统，结合应用日志/指标/追踪构建统一的发布看板。
- 自动生成 Release Notes（比较上一个 Tag 至当前 Commit 的范围），并推送至 Wiki/Issue Tracker。
-
流水线结构化
- 将 Docker 构建、Trivy 扫描、Helm 部署封装成共享库步骤，便于在多个项目复用统一规范。
- 对不同项目/分支使用多分支流水线与 Jenkinsfile 目录化管理（如 Jenkinsfile.ci / Jenkinsfile.cd）更清晰地划分职责。
此 Jenkinsfile 可作为基础模板，结合 Jenkins 插件与共享库进一步工程化，即可实现从代码、质量、制品、镜像安全到灰度/发布的端到端自动化。
