直接说结论Jenkins Docker 这套组合是目前中小团队做微服务自动化部署最接地气、也最容易落地的方案。你不需要一开始就上 K8s也不需要买很贵的 CI/CD 平台只要有一台能跑 Docker 的服务器再装一个 Jenkins就能把“代码提交 → 自动构建 → 镜像打包 → 远程部署”这条链路完整跑通。这篇文章不是泛泛讲概念而是把我自己实际搭建的过程、踩过的坑、改过的配置全部写出来。从安装 Docker 和 Jenkins 开始到配置 JDK/Maven/Git 环境再到写 Dockerfile、编排 docker-compose、创建流水线任务每一步都给了可复制的命令和配置。不管你是后端开发想自己搞 CI/CD还是运维同学要给团队搭一套自动部署环境照着做基本都能跑起来。1. 整体设计与思路拆解1.1 为什么选 Jenkins Docker而不是其他方案先说一个很多新手容易纠结的问题现在 GitLab CI、GitHub Actions 都挺火为什么还要用 Jenkins我的看法很简单Jenkins 的“不挑食”特性是它最大的竞争力。GitLab CI 和 GitHub Actions 都跟自己的代码仓库强绑定如果你的仓库不在对应平台上用起来就别扭。而 Jenkins 是一个完全独立的调度平台它可以对接 GitLab、Gitee、GitHub甚至 SVN还可以同时管理多个项目的构建任务。对于团队里同时存在多种代码托管平台的情况Jenkins 是唯一一个能统一纳管的方案。另外一个原因是 Jenkins 的插件生态太成熟了。微服务自动化部署涉及到的 Git 拉取、Maven 构建、SSH 远程执行、Docker 命令调用每一个环节都有现成插件。虽然很多功能用 Shell 命令也能实现但插件的价值在于它帮你处理了凭据管理、日志归档、构建历史这些脏活累活而且配置界面比裸写脚本友好得多。当然Jenkins 也有缺点最明显的就是部署和维护成本。它跑在 Java 虚拟机里启动慢、吃内存而且如果插件装太多架构复杂了之后流水线的排查难度会上升。但对一个初次落地 CI/CD 的团队来说这些缺点并不致命。我的建议是先拿 Jenkins 把流程跑通等业务量大了、需要在多台机器上动态扩容了再往 K8s 迁移也不迟。1.2 微服务自动化部署的目标架构在动手安装之前先明确最终要部署成什么样子。我当时的项目是五个微服务模块网关服务、认证服务、用户服务、订单服务、商品服务另外还有 Nacos 注册中心和若干基础中间件。目标架构是这样的开发把代码推到 GitLab 的某个分支Jenkins 通过 Webhook 或者轮询感知到变更然后自动执行流水线——拉代码、执行 Maven 打包、构建 Docker 镜像、推送到镜像仓库、再通过 SSH 到目标服务器上执行 docker-compose 重启服务。这套架构里每个组件都有自己的角色GitLab代码托管的唯一入口也是触发整个流水线的起点。Jenkins负责调度所有构建任务是整个 CI/CD 流程的大脑。Docker提供一致的运行环境把应用和依赖一起打包成镜像。docker-compose在服务器上定义和运行多容器应用解决服务编排问题。Nacos微服务注册中心服务之间通过它做发现和配置管理。数据库、Redis 这些基础组件单独用 docker-compose 管理不参与每次发布避免重复启动导致数据丢失。只有业务服务才走“构建镜像 → 重启容器”的发布流程。1.3 一条完整的发布链路长什么样拿用户服务来举例一条完整的自动化部署链路是这样的开发人员把代码 push 到 GitLab 的 master 分支。如果配置了 WebhookGitLab 会立刻通知 Jenkins否则 Jenkins 每隔一段时间轮询一次仓库。Jenkins 从 GitLab 拉取最新代码到工作空间。Maven 执行clean package跳过测试打出 jar 包。Dockerfile 以 jar 包为基础构建应用镜像给镜像打上版本标签。项目循环完成把镜像推送到私有仓库Harbor 或者 Registry。Jenkins 通过 SSH 登录到部署服务器拉取最新镜像。docker-compose 根据镜像重启对应服务完成发布。整个过程只需要开发人员完成第一步剩下的全部由 Jenkins 自动完成。一次构建成功的话从 push 代码到服务更新完成大概只需要两三分钟。2. 环境准备与基础组件安装2.1 服务器与操作系统选择先说服务器选型。我自己用的是 CentOS 7.9 系统8核 16G 内存100G SSD 磁盘。这个配置对中小团队来说够用了。内存是重点因为 Jenkins 本身要占 2G 左右Nacos、MySQL、Redis 各占 512M 到 1G再跑三五个微服务容器8G 内存会比较紧张16G 是稳妥的起步配置。如果你只是想本地练手用虚拟机跑一个 CentOS 也行但一定要保证 Docker 能正常使用。Windows 上装 Docker Desktop 比较麻烦容易遇到虚拟化没开的问题而且 Docker Desktop 默认用的是 WSL2 后端和 Linux 原生的 Docker 引擎有差异。我的建议是生产环境老老实实用 Linux 服务器开发环境可以在 Windows 上用 WSL2 装一个 Ubuntu然后在里面装 Docker体验跟服务器基本一致。2.2 安装 Docker 引擎Docker 的安装过程其实很简单关键是找到适合你的发行版的安装源。我这边直接用了官方脚本的方式sudo yum install -y yum-utils sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin sudo systemctl start docker sudo systemctl enable docker安装完成后验证一下docker version能看到 client 和 server 的版本信息就基本没问题了。如果是在国内服务器上安装 Docker下载速度可能会比较慢甚至超时。这时候可以把 Docker 的镜像源改成国内镜像站在/etc/docker/daemon.json里配置 registry-mirrors然后重启 Docker 服务。这个步骤不是必须的但建议还是配置一下后面拉基础镜像会快很多。为了让当前用户不需要每次都用 sudo 执行 docker 命令可以把用户加到 docker 组sudo usermod -aG docker $USER改完之后需要退出重新登录才能生效。这个操作在生产环境要谨慎docker 组的权限等同于 root如果团队成员比较多建议按需分配不要所有人都加到 docker 组里。2.3 用 docker-compose 部署基础中间件微服务跑起来首先得有注册中心、数据库、缓存这些基础设施。这些组件更新频率低、配置相对固定不适合走 Jenkins 自动发布流程更适合用 docker-compose 一次性编排启动。我当时的 docker-compose 文件里包含了 Nacos、MySQL、Redis 三件套。Nacos 用了单机模式暴露 8848 端口MySQL 映射了 3306 端口并挂了数据卷Redis 映射 6379 端口并启用了密码认证。这三个服务的镜像都比较重第一次拉取需要一点时间之后就都是秒级启动了。这里分享一个我踩过的坑docker-compose 里定义的 MySQL 容器第一次启动时会执行初始化脚本但如果数据卷已经挂载过后续启动就不会再执行初始化脚本了。所以一定要在第一次启动之前把初始化 SQL 准备好放到官方指定的 docker-entrypoint-initdb.d 目录下。否则等容器跑起来之后才想起来要建库建表就得手动进容器执行脚本非常麻烦。2.4 Jenkins 的安装方式选择Jenkins 的安装方式主要有三种war 包直接跑、原生安装包安装、Docker 容器方式运行。这三种方式我都用过说说各自适合什么场景。war 包方式最轻量下载一个 jenkins.war 直接用java -jar启动适合临时测试但不适合生产环境管理。原生安装包比如用 yum 安装是传统做法配置文件都在服务器上管理起来最直接适合已经习惯了传统运维方式的团队。Docker 方式隔离性最好升级方便但要注意挂载目录和数据卷否则重启容器数据就丢了。我自己最终选择了原生安装包方式原因很简单Jenkins 需要访问 Docker 命令来构建镜像如果 Jenkins 本身跑在容器里还要处理 Docker 套接字挂载、权限映射这些麻烦事。直接装在宿主机上Jenkins 用户调用 docker 命令只有一个用户组成员的事简单直接。安装 Jenkins 之前先确保 JDK 已经装好了。Jenkins 最新版本要求 JDK 8 以上我用的是 JDK 11。装好之后用 yum 安装 Jenkinssudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key sudo yum install -y jenkins sudo systemctl start jenkins sudo systemctl enable jenkins启动之后访问http://服务器IP:8080会看到一个解锁页面要求输入初始密码。初始密码在/var/lib/jenkins/secrets/initialAdminPassword文件里cat 出来复制粘贴就行。2.5 Jenkins 初始化与国内镜像加速第一次进入 Jenkins 会提示安装插件这里选择“Install suggested plugins”就好系统会帮你装好 Git、Pipeline 等核心插件。如果你用的是海外服务器这一步等几分钟就能装完如果是国内服务器下载速度会很感人甚至直接超时失败。我当时就卡在这一步后来发现 Jenkins 的插件更新中心是可以更换的。在 Jenkins 管理界面里进入“Manage Jenkins → Plugins → Advanced settings”把 Update Site 的 URL 替换成国内镜像站的地址然后提交并强制刷新再回头装插件就快多了。这个地址是公开的 Jenkins 仓库镜像不是私有地址可以放心用。插件装完之后建议立即创建一个管理员账号然后设置 Jenkins URL。之后就不建议用 admin 的默认 token 去接 GitLab 了而是单独为每个项目创建具体的凭据方便审计和收回权限。3. 核心配置JDK、Maven、GitLab 与权限管理3.1 全局工具配置Jenkins 要执行 Maven 构建必须告诉它 JDK 和 Maven 在哪里。有两种配置方式一种是让 Jenkins 自动下载并管理工具另一种是指定你服务器上已经安装的工具路径。自动下载的好处是 Jenkins 自己管理这些软件的版本坏处是下载比较慢而且国内网络可能不太稳定。我选择的是手动指定路径因为我的服务器上本来就装了 JDK 和 Maven直接用系统路径最省事。在“Manage Jenkins → Tools”里配置JDK 安装选择“Install automatically”并指到 JAVA_HOME 的路径比如/usr/lib/jvm/java-11-openjdk-amd64。Maven 安装同样是取消自动下载手动填写 MAVEN_HOME 路径比如/opt/maven/apache-maven-3.8.6。Git 安装填写 Git 的可执行文件路径通常就是/usr/bin/git。配置完成之后在流水线脚本里就可以直接用tools { jdk JDK11 maven Maven3 }来引用这些工具。3.2 凭据管理与 GitLab 连接Jenkins 连接 GitLab 需要用到凭据Credentials这里推荐使用 SSH Key 方式而不是用户名密码。原因是 SSH Key 更安全不会在日志里暴露密码而且配置一次之后可以长期生效。在 GitLab 后台生成一对 SSH Key把公钥加到 GitLab 账号的 SSH Keys 里私钥配置到 Jenkins 凭据中。配置路径是“Manage Jenkins → Credentials → Global → Add Credentials”Kind 选择“SSH Username with private key”把私钥内容粘贴进去。然后在 Jenkins 的系统配置里设置 GitLab 连接。这部分需要安装一个 GitLab 插件安装完成后在“Manage Jenkins → Configure System → GitLab”里添加连接Connection name随便填比如my-gitlabGitLab host URL填你的 GitLab 地址比如http://gitlab.example.comCredentials选择刚才创建的 GitLab API 凭据如果你用的是 GitLab API Token 方式需要在 GitLab 个人设置里生成一个 Access Token权限范围勾选api即可。3.3 用户权限与角色管理随着团队人数增多Jenkins 里会出现一个非常现实的问题所有人都是管理员谁都可以删任务、改配置风险极大。所以建议装一个 Role-based Strategy 插件把权限收拢到角色模型里。在“Manage Jenkins → Configure Global Security”里把授权策略改成“Role-Based Strategy”然后在“Manage and Assign Roles”里创建角色管理员角色拥有所有权限给一两个核心负责人。开发角色只能查看和构建与自己项目相关的任务不能修改全局配置不能删除任务。只读角色只能查看构建历史和日志适合测试人员。每个角色对应具体的正则或项目名称比如project-user-service、project-order-service这样开发人员只能操作自己负责的模块避免误触其他人的任务。这里有个小技巧在分配角色的时候项目匹配规则支持通配符比如project-.*就能匹配所有以project-开头的任务。但如果你要精确控制权限建议还是写完整名字越精确越安全。3.4 微服务配置中心与 API 文档组件的接入微服务架构下服务配置往往会放到 Nacos 配置中心统一管理API 文档也会集成 Knife4j 在网关层聚合展示。这两块虽然和 Jenkins 自动化部署没有直接关系但在部署流程里会影响到服务能否正常启动。Nacos 的接入很简单微服务模块在 pom.xml 里引入spring-cloud-starter-alibaba-nacos-discovery和spring-cloud-starter-alibaba-nacos-config然后在 bootstrap.yml 里配置 Nacos 地址和命名空间。要注意的是如果配置中心的配置出错服务启动时可能报“找不到配置”的错误这时候就算 Jenkins 构建成功了容器起来了也会马上退出。Knife4j 是 Swagger 的增强版文档组件它在微服务里的典型做法是每个服务引入knife4j-micro-spring-boot-starter然后在网关层做聚合。也就是说你在网关服务里集成 Knife4j访问网关的/doc.html地址就能看到所有微服务模块的 API 文档。我实际排查过这类问题就是为了 Jenkins 构建的时候检查日志服务容器启动后立即退出十有八九是连接不上 Nacos 或者配置加载失败。这时候不要急着改 Jenkins 流水线脚本先去服务日志里看具体的异常信息通常docker logs 容器名就能看到关键报错。4. 镜像构建Dockerfile 与 docker-compose 编排4.1 一个标准的 Spring Boot 服务 Dockerfile微服务模块构建镜像是整个自动化部署里最关键的一环。Dockerfile 写得好镜像体积小、启动快、安全写得不好镜像可能比实际需要的体积大好几倍启动也慢。以 Java 微服务为例我的做法是分阶段构建multi-stage build。第一阶段用 Maven 镜像编译代码第二阶段只要把编译好的 jar 包复制到运行环境中不需要安装 JDK 和 MavenFROM maven:3.8.6-openjdk-11 AS builder WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline -B COPY src ./src RUN mvn clean package -DskipTests FROM openjdk:11-jre-slim WORKDIR /app COPY --frombuilder /app/target/*.jar app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]这个 Dockerfile 在构建阶段会先拷贝 pom.xml 并执行依赖下载目的是利用 Docker 的层缓存如果你的源码没变依赖层就不会重建速度会快很多。之后用-DskipTests跳过测试可以显著缩短构建时间。但是注意“跳过测试”不应该是常规操作如果是生产环境的正式发布建议至少保留-Dmaven.test.skiptrue和-Dmaven.test.failure.ignorefalse的组合保证测试不过就不发版。4.2 镜像仓库选择Harbor 还是 Registry构建出来的镜像不能只存在 Jenkins 那台机器上最好推送到一个内部镜像仓库这样部署服务器才能拉取。镜像仓库我试过 Docker Registry 和 Harbor。Docker Registry 是官方提供的简洁方案支持基本的镜像推送和拉取但缺少 Web UI 和权限控制。Harbor 是专门面向企业场景的镜像仓库提供了基于角色的访问控制、镜像漏洞扫描、回收策略等能力更适合团队协作。如果你只有三五个人、一台服务器Docker Registry 够用了一条命令就能启动docker run -d -p 5000:5000 --name registry --restartalways \ -v /data/registry:/var/lib/registry registry:2但如果你们团队要在多台服务器之间共享镜像或者需要给不同项目分配不同的访问权限直接上 Harbor。Harbor 虽然部署略微复杂一点但它是用 docker-compose 编排的照着官方文档来基本上半小时以内能搞定。4.3 docker-compose 编排多个微服务当项目里有多个微服务模块时手动一个个 docker run 显然不现实docker-compose 就是来解决这个问题的。下面是简化版的编排示例version: 3.8 services: gateway: image: registry.internal.com/micro/gateway:1.0.0-SNAPSHOT ports: - 8080:8080 environment: - NACOS_ADDR192.168.1.10:8848 networks: - micro_net user-service: image: registry.internal.com/micro/user-service:1.0.0-SNAPSHOT depends_on: - gateway environment: - NACOS_ADDR192.168.1.10:8848 networks: - micro_net networks: micro_net: driver: bridge这里的网络模式要注意所有微服务之间是通过服务名互相调用的所以必须让它们处于同一个 Docker 网络里。我用的是自定义 bridge 网络这样服务间通信可以使用容器名而不是 IP 地址在配置文件中配置服务地址时也更灵活。还有一个细节depends_on 只是控制容器启动顺序不保证服务真的“就绪”。比如你配置了 user-service 依赖 nacos但 nacos 可能还没有完全启动完成user-service 就已经启动了导致连接注册中心失败。要解决这个问题可以在服务启动命令里加入等待逻辑等 Nacos 端口通了再启动业务服务。不过这个属于锦上添花第一次跑通之前不用纠结。4.4 进服务器校验镜像与容器的状态从 Jenkins 完成构建和推送到镜像仓库之后部署服务器上的操作其实很简单——拉取镜像并重启服务。但这里有个很常见的坑如果使用了固定版本的标签比如:latest或:v1.0.0服务器上已经存在同名镜像时docker-compose 的up命令不会主动拉取新镜像。我的做法是让 Jenkins 每次构建都生成带构建号的标签比如user-service:1.0.0-SNAPSHOT-202501160952然后在部署的时候直接指定这个新标签。这样既不担心缓存也方便回滚——万一新版本有问题把版本号改回上一个就能快速恢复。如果你确实想用固定标签记得在部署命令里加--pull参数让 compose 每次启动前都先尝试拉取最新镜像。不过我的建议还是用时间戳或 Git commit 号做标签回滚和排查都更直观。5. Jenkins 流水线任务创建与自动化流程实现5.1 新建自由风格任务还是流水线任务在 Jenkins 里实现构建逻辑有两条路线自由风格任务Freestyle Project和流水线任务Pipeline。自由风格任务适合简单场景——配置 Git 地址、构建命令、构建后操作全部用界面完成。流水线任务则是把整个流程写成代码存到 Jenkinsfile 里版本化管理。我最终选择了流水线任务。原因很简单当微服务模块多起来之后如果每加一个服务都要在界面上手动配置一遍效率太低而且配置无法复用。用流水线脚本我可以把公共逻辑抽出来不同服务只改几个参数甚至用参数化构建来让同一个任务构建不同的模块。流水线脚本有两种语法Declarative声明式和 Scripted脚本式。声明式更贴近实际场景结构清晰适合团队协作脚本式更灵活适合做复杂逻辑。我的建议是从声明式开始等需要处理动态并行、复杂条件判断的时候再用脚本式。5.2 使用 Jenkinsfile 编写自动化流水线下面是我用的 Jenkinsfile 模板完整实现了“拉代码 → Maven 打包 → 构建镜像 → 推镜像 → 远程部署”五个阶段pipeline { agent any tools { maven Maven3 jdk JDK11 } environment { DOCKER_REGISTRY registry.internal.com APP_NAME user-service APP_VERSION 1.0.0-${env.BUILD_NUMBER} DEPLOY_SERVER 192.168.1.20 DEPLOY_DIR /opt/micro } stages { stage(Checkout) { steps { git credentialsId: gitlab-ssh-key, url: gitgitlab.example.com:micro/user-service.git, branch: master } } stage(Maven Build) { steps { sh mvn clean package -DskipTests } } stage(Docker Build) { steps { sh docker build -t ${DOCKER_REGISTRY}/micro/${APP_NAME}:${APP_VERSION} . } } stage(Push Image) { steps { sh docker login ${DOCKER_REGISTRY} -u admin -p Harbor12345 docker push ${DOCKER_REGISTRY}/micro/${APP_NAME}:${APP_VERSION} } } stage(Deploy) { steps { sshagent([deploy-server-ssh]) { sh ssh root${DEPLOY_SERVER} cd ${DEPLOY_DIR} docker login ${DOCKER_REGISTRY} -u admin -p Harbor12345 docker pull ${DOCKER_REGISTRY}/micro/${APP_NAME}:${APP_VERSION} docker compose up -d --force-recreate --no-deps ${APP_NAME} } } } } }这段脚本里有几个值得注意的细节。Maven 和 JDK 的工具名称要和全局配置保持一致否则 Jenkins 会报找不到工具的错误。Docker 仓库的账号密码直接写在环境变量里适用于内网环境如果仓库在公网上建议先创建带有用户名密码的凭据在流水线里引用别硬编码。每个 stage 的日志会按阶段分隔一旦某个环节崩了可以直接在 Stage View 里跳转到对应日志排查效率高很多。但注意Jenkins 的“Deploy”阶段如果 SSH 到远程服务器执行失败默认不会回滚。生产环境发布失败时你还需要根据日志判断是重新构建还是直接回滚到上一个镜像版本。5.3 Webhook 触发与参数化构建手动点击“立即构建”肯定不够自动化。要让开发 push 代码后自动触发构建有两种思路轮询和 Webhook。轮询就是在流水线配置里设置triggers { pollSCM(H/2 * * * *) }Jenkins 每两分钟检查一次仓库有没有新提交。这种方式简单可靠但有两个问题构建可能延迟到轮询周期之后频繁轮询会给 GitLab 造成一定压力。对演示和测试环境来说是够用的。更推荐的做法是配置 GitLab Webhook。在 GitLab 项目的 Settings → Webhooks 中添加 Jenkins 地址http://jenkins.example.com/project/your-project触发条件选择 Push events然后在 Jenkins 安装 GitLab Plugin给流水线任务添加gitlab触发器。这样开发 push 代码的瞬间GitLab 就会通知 Jenkins 构建实时性最好。参数化构建是我后期加的功能。在流水线任务配置里勾选“参数化构建过程”添加一个 String Parameter比如BRANCH默认值是master。然后在流水线脚本里把 Git 分支改成${params.BRANCH}。这样既可以用 Webhook 自动触发默认分支的测试构建也可以手动输入分支名来测试某个开发分支。5.4 Linux 上安装 Jenkins 与流水线任务创建实录这里记录一下我实际在服务器上完整的操作命令尽量贴近实操过程。插件列表如果不一样也不要慌核心就是 Git 插件、Pipeline 插件、SSH Agent 插件、GitLab 插件这几个。# 安装 JenkinsCentOS 环境 sudo wget -O /etc/yum.repos.d/jenkins.repo https://pkg.jenkins.io/redhat-stable/jenkins.repo sudo rpm --import https://pkg.jenkins.io/redhat-stable/jenkins.io-2023.key sudo yum install -y jenkins sudo systemctl start jenkins sudo systemctl enable jenkins # 查看初始密码 sudo cat /var/lib/jenkins/secrets/initialAdminPassword等插件装完、管理员账号建好之后我把项目的 SSH 私钥加到了 Jenkins 凭据里把 GitLab 地址、Harbor 地址都配置到了系统设置里。因为这是我的第一次配置之后新建流水线任务时只需要在任务里引用凭据 ID 就可以了。在建流水线任务的时候我的习惯是选用“多分支流水线”Multibranch Pipeline而不是普通的流水线任务。多分支流水线会自动扫描 GitLab 仓库里的所有分支如果某个分支下存在 Jenkinsfile就会自动创建一个对应的 Jenkins 子任务。这个方式比“为每个分支手动创建任务”省太多事了强烈推荐。首次创建流水线任务之后建议先手动触发一轮构建一步步检查每个阶段是否正常。这一步实际发生过很多次问题——Maven 依赖下载失败、Dockerfile 写法错误、远程登录超时等。手动构建可以快速定位不用等 Webhook 触发后才发现问题。5.5 如何快速排查一个失败的 Stage流水线失败之后第一件事是看 Stage View 里红色的阶段点进去看具体日志。日志里信息量很大需要学会过滤关键的错误信息。如果 Maven Build 失败大概率是依赖冲突或编译报错。在本地先执行一次mvn clean package能编译过才到 Jenkins 上构建。如果 Docker Build 失败大概率是 Dockerfile 的路径或 COPY 指令有问题。如果远程 Deploy 失败先确认 Jenkins 机器到部署服务器的 SSH 网络通不通。一个从日志里找关键信息的技巧直接搜索日志里的ERROR、FAILURE、Caused by关键字。如果日志太多可以在 Jenkins 控制台输出里用浏览器搜索功能Ctrl/Cmd F来快速定位。还有一点Jenkins 的构建日志默认保存是有时限的建议在系统设置里把“Build Log Retention”调长一些至少保留 30 天方便追溯问题。6. 工程化细节与常见问题排查实录6.1 Windows 环境下的 Docker 与代理坑虽然在服务器上推荐 Linux但很多同学本地开发用的都是 Windows。Windows 上装 Docker Desktop 最大的坑是虚拟化没开启。遇到virtualization support not detected或Docker Desktop failed to start because virtualization support wasnt detected这类报错时需要检查 BIOS 里是否开启了 VT-x / AMD-V以及在 Windows 功能里是否启用了 WSL2。如果是笔记本还要注意部分杀毒软件和虚拟机软件会占用 Hyper-V 能力导致 Docker Desktop 无法使用。我碰到过安装了 VirtualBox 之后 Docker Desktop 启动失败的情况把 VirtualBox 卸载或者关掉 Hyper-V 冲突后再启动就正常了。6.2 国内服务器下载镜像慢的解决方案国内服务器在拉取 Docker Hub 镜像时经常出现超时或者速度极慢的情况。除了配置镜像加速器之外还有一个非常有效的替代方案在比较快的机器上把镜像打成 tar 包传到目标服务器再 load 进去。虽然这个方式没办法自动化但在初始化环境、拉取某些较大的基础镜像时非常好使。如果用的是 Harbor 作为内网镜像仓库内网拉取速度快到无感。建议在 installing Docker 完成后把 Nacos、MySQL、Redis 这些基础镜像提前推到 Harbor后续服务器初始化就不需要再从 Docker Hub 拉取了。6.3 Nacos 启动慢导致的容器启动失败Nacos 在 Docker 里启动速度不算快从容器启动到完全可以提供服务可能需要几十秒。如果你的微服务容器在它完全启动之前就开始注册往往就会失败。我的解决办法是在每个微服务容器里都加一个健康检查脚本或者用 wait-for-it 工具等待端口通。其实更推荐在 docker-compose 里配置 healthcheck再用 depends_on 的 condition 来控制启动顺序但这种方式在某个版本的 Docker Compose 里开始支持版本太老可能没有这个能力需要根据实际情况调整。6.4 docker-compose 升级或重启导致服务不可用在发布过程中如果直接执行docker compose up -d即使服务代码已经变了也可能因为镜像标签没变而沿用旧容器。而且对多服务来说compose 会比较所有服务的配置拓扑如果只在某个阶段代码变了重启其他不相关服务是不必要的。我的建议是把发布命令限定为docker compose up -d --no-deps --force-recreate 服务名其中--no-deps表示不级联重启依赖服务--force-recreate强制用新镜像重建容器。这样就能做到只更新目标服务其他服务完全不受影响。6.5 常见的 Jenkins 环境变量和参数说明流水线里经常要使用 Jenkins 内置的环境变量这里列几个常用的BUILD_NUMBER当前构建号适合作为镜像标签后缀。JOB_NAME当前任务名称。GIT_COMMIT当前构建对应的 Git 提交哈希。WORKSPACEJenkins 工作区路径。ENV你可以自定义的环境变量在 Configure System 的 Global Properties 里设置。我在流水线脚本里用APP_VERSION 1.0.0-${env.BUILD_NUMBER}这种方式每次构建都会生成唯一的版本号发布后通过版本号就能对应到具体的构建记录回滚时也只需要把镜像标签指回旧版本号非常清晰。另外关于jenkins.ini的常见配置有一种误解。实际上 Jenkins 的核心配置文件是/etc/default/jenkinsDebian 系或者/etc/sysconfig/jenkinsRedHat 系里面可以调整端口、JVM 参数、用户等。默认端口 8080 如果想改成 8090可以在这里设置JENKINS_PORT记得同时放行防火墙端口。6.6 想清楚哪些场景不适合用这套方案很多人把 Jenkins Docker 当成银弹但它并不是万能的。如果你的业务量很小就两三个服务手动构建部署反而更快如果已经在生产环境大规模用 K8s 了再引入 Jenkins 处理容器调度反而重复造轮子如果团队没有人愿意维护 CI/CD 环境这套系统就会变成没人管的孤儿系统。有时也会遇到某些场景必须绕开自动化部署比如后台 odata 接口需要访问数据库删改数据的任务这类需要 DBA 人工审校的不太适合在流水线里自动执行。所以 Jenkins 自动化部署的目的是解决重复劳动而不是完全替代人工。需要决策和审批的地方恰恰应该保留人工介入。7. 实操过程记录参照某微服务项目完整部署流程7.1 前置条件以下是我在某个项目中的真实部署过程项目名称为“microshop”包含五个微服务模块micro-gateway网关、micro-user用户、micro-product商品、micro-order订单、micro-pay支付代码托管在 GitLab 上镜像仓库使用 Harbor。前置条件服务器CentOS 7.92 台一台安装 Jenkins一台用于应用运行。Docker 版本20.10。Jenkins 版本2.414.2。JDK11Jenkins 运行环境微服务运行镜像为 openjdk:11-jre-slim。Maven3.8.6。GitLab12.9.1。Harbor2.5.0。7.2 第一步部署基础环境在 Jenkins 这台机器上安装 Docker、JDK、Git、Maven并启动 Jenkins 服务。这一步的操作命令在之前的章节已经写了不再重复。关键点是确认 Jenkins 用户对 Docker 命令有访问权限否则脚本里执行 docker 命令会权限不足。我的操作是把jenkins用户加入docker组sudo usermod -aG docker jenkins然后重启 Jenkins 服务。这里特别提醒刚加入 docker 组的用户在当前 session 里不会立刻生效一定要重启服务或者 reboot否则依然会报“permission denied while trying to connect to the Docker daemon socket”。7.3 第二步在 GitLab 和 Jenkins 之间建立信任关系这一步主要是配置 SSH Key 和 API Token。我之前已经生成了 SSH Key 并添加到了 GitLab 的 SSH Keys 里现在只需要在 Jenkins 里新建凭据填入私钥内容和用户名。同时在 Jenkins 系统配置里添加 GitLab 连接填 GitLab URL 和之前生成的 Access Token测试连接显示成功这一步就完成了。7.4 第三步创建 Harbor 项目与配置权限在 Harbor 控制台里创建一个名为micro的项目项目级别选择“私有”。然后为 Jenkins 创建专用的机器人账号或者普通用户分配只读权限用于拉取镜像和读写权限用于推送镜像。在 Jenkins 流水线脚本里登录 Harbor 时用这个账号。因为要保持脚本在不同环境下的可移植性我用了凭据引用的方式不直接把密码写在脚本里。在实际操作中我使用的是 Jenkins 自带的“Username/Password”凭据类型把 Harbor 的用户名密码存进去在流水线里用withCredentials块来安全引用。7.5 第四步编写 Dockerfile 和 docker-compose这一步为每个微服务模块编写 Dockerfile。除了微服务本身之外我还在应用服务器上准备了一台 MySQL 和 Nacos也用 docker-compose 管理。应用的 docker-compose 文件我放到了/opt/micro/docker-compose.yml里面定义了五个服务的启动配置、端口映射和 Nacos 地址services: micro-gateway: environment: - NACOS_ADDRnacos-server:8848 networks: - micro_net micro-user: environment: - NACOS_ADDRnacos-server:8848 networks: - micro_net micro-product: environment: - NACOS_ADDRnacos-server:8848 networks: - micro_net micro-order: environment: - NACOS_ADDRnacos-server:8848 networks: - micro_net micro-pay: environment: - NACOS_ADDRnacos-server:8848 networks: - micro_net networks: micro_net: driver: bridge启动命令我用的是docker compose up -d --force-recreate --no-deps 服务名这样能保证只重建目标服务不影响其他服务。7.6 第五步在 Jenkins 里创建流水线任务在 Jenkins 首页点击“New Item”输入名称选择“Pipeline”然后进入配置页。在 Pipeline 区域里选择“Pipeline script from SCM”SCM 选择 Git填写仓库地址和凭据脚本路径填Jenkinsfile。如果你在仓库根目录放了 Jenkinsfile这种配置方式可以直接从 Git 拉取流水线脚本改动脚本是跟着代码版本走的不需要每次手动去 Jenkins 界面改。如果仓库里还没有 Jenkinsfile可以先选择“Pipeline script”直接把脚本内容粘贴进去。等跑通之后再把脚本抽到 Git 仓库里统一管理。7.7 第六步首次构建与验证构建完成后验证步骤很关键。我先登录目标服务器执行docker ps看所有容器是否处于正常状态。发现 micro-user 容器启动后马上退出了于是执行docker logs micro-user查看启动日志。日志里显示的是一条 Nacos 连接不上的异常。排查后发现应用容器的/etc/hosts里解析不到nacos-server因为容器的网络是 bridge而 Nacos 容器在另一个网络上。解决办法是把 Nacos 也加到micro_net网络里或者把应用容器和基础中间件容器放在同一个 docker-compose 项目里管理。最终我把 Nacos 整体迁移到了同一个 compose 编排文件里服务名由 IP 改为nacos-server问题就解决了。这个坑值得标记一下跨网络的服务名解析是基于 Docker 的 DNS 机制来实现的只要容器在同一网络上服务名就能自动解析不需要手动维护 hosts 文件。7.8 第七步配置 Webhook 实现自动触发环境正常之后我开始配置 Webhook。在 GitLab 项目的 Settings → Webhooks 里添加 Jenkins 地址格式为http://jenkins.example.com/project/micro-userSecret Token 填 Jenkins 生成的触发令牌在流水线任务的配置里可以找到。勾选 Push events保存。然后在 Jenkins 流水线任务的触发器配置里确认开启“Build when a change is pushed to GitLab”。之后再做一次测试本地改一行代码push 到 GitLab随后 Jenkins 自动开始构建。前几次构建可能比较慢因为 Maven 依赖需要下载但后面会逐步稳定下来。这个实测流程跑通之后整个 CI/CD 一体化才算真正落地了。8. 常见问题与排查技巧速查表问题现象可能原因解决方法Jenkins 无法连接 GitLab凭据配置错误、网络不通、Token 权限不足测试连接检查凭据类型和 GitLab API Token 范围Maven 构建下载依赖超时网络问题、Maven 中央仓库访问慢配置国内 Maven 镜像仓库在 settings.xml 中修改 mirrorDocker build 时找不到 Dockerfile路径错误、工作目录不对确认 stage 里的dir目录Dockerfile 放在项目根目录构建时报 Docker daemon 权限不足Jenkins 用户不在 docker 组执行usermod -aG docker jenkins并重启 Jenkins镜像推送到 Harbor 失败仓库不存在、认证失败、HTTP 或 HTTPS 策略问题确认 Harbor 项目存在用 docker login 测试检查 daemon.json 的 insecure-registries部署服务器拉取镜像失败目标服务器未登录 Harbor、网络不通在目标服务器执行 docker login确认访问链路正常容器启动后立即退出Nacos 连接失败、端口冲突、配置加载失败查看docker logs 容器名根据具体报错判断服务间调用报连接拒绝容器不在同一网络、服务名解析失败把所有服务放到同一个 docker-compose 工程或者同一网络里流水线构建成功但服务没更新镜像标签没变、compose 没有强制重建使用唯一的构建版本号作为标签用--force-recreate --no-depsJenkins 插件下载安装慢国内网络访问插件仓库慢更换 Update Site 为国内镜像站再重载插件列表Windows Docker Desktop 无法启动未开启虚拟化、WSL2 未启用检查 BIOS VT-x、启用 Windows 的 WSL2 或 Hyper-V 功能排查的思路最核心的一点就是先看日志再改配置。Jenkins 的构建日志、容器的启动日志、Nacos 的控制台日志这三个日志源能定位绝大多数问题。不要一上来就怀疑脚本写错了先顺着日志看一步走到哪了、卡在哪里。这里再多提一句如果你在某一次构建中看到docker: error response from daemon: get ...这类拉镜像时报错的日志先不要慌张。第一反应看网络通不通第二看仓库地址是否写错第三看仓库登录状态。如果三样都正常重启一下 Docker 守护进程通常能解决。9. 关于这套方案的几点体会最后说说我踩过一遍之后的感受。Jenkins Docker 这套体系最重要的不是某个单独的环节或者某个炫酷的技术而是把整个流程串起来的意识。从代码提交的那一刻起所有操作都应该有迹可循有日志可查有办法回滚。刚开始搭建的时候你可能觉得手动部署更简单——装包、拷代码、重启服务两步就完成了。但等微服务模块增长到五六个以上每次发版需要手动执行十几条命令、改好几处配置的时候你才会明白自动化部署的价值。它省下来的不只是敲命令的时间更重要的是避免了“人肉操作”带来的低级错误比如漏改了配置、忘了重启某个服务。我的建议是不管你现在团队有多少人、项目有多小先把这套链路搭起来。一开始可以只在测试环境跑等验证没问题了再逐步推广到生产环境。搭建过程中遇到任何问题对照上面这些排查思路和方法基本都能解决。如果你正准备搞微服务自动化部署希望这份安装和部署过程记录能帮你少走一些弯路。