在微服务这条路上走得越久越会明白一个道理代码写得再漂亮部署环节一团糟整个团队的效率都会被拖垮。我接手Spring Cloud项目初期服务拆了十几个每次发版靠人肉脚本登录服务器改配置靠记事本逐个通知一次发布折腾大半天回滚更是凭记忆操作。后来下决心把GitLab、Jenkins、Docker、K8s这套CI/CD流水线完整搭起来配合Nacos做注册中心和配置中心整个部署过程才算真正自动化。这篇文章就是把这套微服务CI/CD架构从设计思路、组件选型到落地步骤和踩坑记录完整讲一遍适合正在搭建或者准备搭建自动化部署体系的团队参考也适合想搞懂这些技术如何串联的开发者。1. 整套流水线的设计思路与选型逻辑1.1 这套技术栈解决的核心痛点先不急着谈安装配置聊聊为什么非要用这套组合。微服务架构最大的问题不是服务多而是服务之间的依赖关系和部署复杂度呈指数级上涨。单体应用部署就是打一个jar包扔到服务器微服务呢订单、用户、商品、支付、网关每个服务有独立的配置、独立的内存占用、独立的启动顺序有的服务之间还要互相调用。如果停留在人工部署阶段典型场景是这样的开发本地跑通了把代码推到GitLab然后告诉运维“帮我发布一下订单服务”。运维手动拉代码、手动编译、手动传包、手动启停期间还要确认Nacos里配置有没有改、数据库连的对不对。一次两个服务上线就要折腾一小时出了问题还不知道是哪个环节错了。等服务的数量超过十个这套流程基本就走不动了。所以这套架构的核心目标很明确让代码从提交到线上运行的全过程自动化同时把环境差异、依赖管理、服务发现这些原本靠人肉协调的事情交给工具链解决。Spring Cloud负责微服务本身的开发框架Nacos管服务注册和配置下发GitLab管代码版本和变更记录Jenkins负责从拉代码到构建镜像的自动化编排Docker保证应用打包后在任何环境行为一致K8s则接管容器在集群里的调度和运行。1.2 为什么是Nacos、Jenkins、K8s这几个组件选型这件事没有绝对的正确但每个选择背后都有充分的理由。Nacos和Eureka、Consul相比最大的优势是把注册中心和配置中心合并成了一个组件。Spring Cloud早期项目里很多团队用Eureka做服务发现再用Spring Cloud Config搭一套配置中心两套系统都要维护用起来也繁琐。Nacos一个进程搞定两件事还支持配置的动态刷新改完配置不需要重启服务就能生效这对微服务集群来说太重要了。而且Nacos支持命名空间和分组可以很方便地把开发、测试、生产三个环境的配置隔离。Jenkins在这个架构里承担的是调度中枢的角色。现在GitLab CI也可以做自动化构建但Jenkins的插件生态实在太成熟了从Maven构建到Docker镜像打包再到调用K8s的API全都有现成的插件支持。还有一个重要的原因是Jenkins的Pipeline语法非常适合表达一条完整的发布流水线哪个阶段失败、失败在哪一步打开界面看得清清楚楚团队成员上手门槛很低。K8s和Docker的关系用个生活化的类比就很好理解。Docker是生产标准集装箱的工厂保证每个应用被打包成统一的镜像格式K8s是港口调度系统知道哪个集装箱该放哪艘船、哪个坏了该换新的、哪个港口忙哪个港口闲。你直接用Docker跑几个容器没问题但生产环境几十上百个容器谁挂了要自动拉起流量要分发到多个副本发布要平滑滚动不中断这些诉求Docker本身管不了必须靠K8s。1.3 分支策略与发布模型的确定流水线设计里最容易忽略但最影响体验的是分支策略。我见过很多团队把这个问题抛给git管理员结果分支建了一堆谁也不知道哪个分支对应哪个环境。我们的做法是收敛成三段dev分支对应开发环境satge分支对应测试环境main/master分支加tag对应生产环境。开发者的代码通过Merge Request合入合并到dev分支会自动触发Jenkins构建并部署到开发环境合入stage分支触发测试环境部署打tag则触发生产环境的发布流水线。这样设计的好处是开发、测试、生产三条流水线共用一套Jenkins模板只是参数不同谁触发了构建、构建的是哪个分支、要部署到哪个环境全都有记录可查。生产环境还额外加了一道手动审批的步骤避免误触发生成环境发布。2. 基础设施搭建GitLab、Jenkins、Docker与K8s环境准备2.1 用Docker快速部署GitLab并配置SSH免密GitLab的安装最简单的方式就是用Docker直接跑起来一条命令就能完成部署docker run --detach \ --hostname gitlab.example.com \ --publish 443:443 --publish 80:80 --publish 22:2222 \ --name gitlab \ --restart always \ --volume /srv/gitlab/config:/etc/gitlab \ --volume /srv/gitlab/logs:/var/log/gitlab \ --volume /srv/gitlab/data:/var/opt/gitlab \ gitlab/gitlab-ce:latest注意几点。这里的--publish 22:2222是因为宿主机22端口可能已经被SSH占用了所以把GitLab的SSH端口映射到2222克隆代码的时候地址要写成ssh://gitgitlab.example.com:2222/group/project.git。GitLab容器对内存的要求不低实测下来至少给4G内存如果只有2G内存启动会非常慢而且容易中途挂掉。部署完GitLab之后要做两件事创建项目分组和配置SSH密钥。开发机和Jenkins服务器都需要生成SSH密钥并添加到GitLab的SSH Keys里这样Jenkins拉代码的时候就是免密的不用每次构建都输入密码。密钥生成和添加的过程相对简单ssh-keygen -t ed25519生成密钥对把公钥内容粘贴到GitLab用户设置里的SSH Keys即可。2.2 Jenkins安装、插件源与基础环境配置Jenkins的部署同样推荐用Docker方式但有个重要的额外挂载——必须把Docker的socket挂进容器里否则Jenkins无法调用宿主机的Docker来构建镜像。我的启动命令是这样docker run -d \ --name jenkins \ -p 8080:8080 -p 50000:50000 \ -v /home/jenkins_home:/var/jenkins_home \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /usr/bin/docker:/usr/bin/docker \ -v /etc/docker/daemon.json:/etc/docker/daemon.json \ jenkins/jenkins:lts-jdk17这里把宿主机的Docker二进制文件和socket都挂进了容器Jenkins容器内执行docker命令时实际调用的是宿主机的Docker引擎。宿主机上还要先装好Maven和JDK再通过Jenkins系统设置里的Global Tool Configuration配置JDK和Maven的路径。插件源一定要换成国内镜像不然装插件等到怀疑人生。进入/var/jenkins_home/updates/目录编辑default.json把https://updates.jenkins.io/download替换成清华镜像地址sed -i s#https://updates.jenkins.io/download#https://mirrors.tuna.tsinghua.edu.cn/jenkins#g /var/jenkins_home/updates/default.json替换完记得重启Jenkins再打开插件管理页面速度就快多了。必装的插件是Git、Pipeline、Docker Pipeline、Kubernetes CLI以及用于凭据管理的Credentials Binding。2.3 Jenkins连接DockerHost URI与权限问题处理Jenkins要调用Docker构建镜像需要在Manage Jenkins - Manage Nodes and Clouds - New Cloud里添加一个Docker类型的云节点。里面有一个关键的配置项Docker Host URI。网上很多教程写tcp://localhost:2375我实测下来这个填法经常出问题因为Docker默认没有开启2375端口监听连接直接失败。正确做法是填unix:///var/run/docker.sock因为我们前面已经把socket挂进Jenkins容器了这样通信走的是本地socket安全又稳定。但这里有一个非常隐蔽的坑Jenkins容器内默认是jenkins用户这个用户的ID是1000对挂载进去的/var/run/docker.sock可能没有读写权限。表现为构建时执行docker build报错Got permission denied while trying to connect to the Docker daemon socket解决办法有两种。第一种简单粗暴启动Jenkins容器时加--user root让它以root身份运行权限问题直接消失缺点是有一定安全隐患。第二种更规范进入运行中的Jenkins容器把jenkins用户加入docker组docker exec -u root -it jenkins usermod -aG docker jenkins docker restart jenkins我倾向于第二种既解决了权限问题又不至于让Jenkins全程跑在root下。2.4 K8s集群初始化和经典报错处理K8s集群的搭建推荐用kubeadm虽然手动步骤多一点但网络上的文档成熟遇到问题也好排查。控制节点初始化时我踩过一个几乎所有人都会碰到的坑报错信息是[kubelet-check] The HTTP call equal to http://127.0.0.1:10248/healthz failed with error: Get http://127.0.0.1:10248/healthz: dial tcp 127.0.0.1:10248: connect: connection refused ... The API server is not healthy after 4m0.00747357s这个报错看着吓人其实就是kube-apiserver这个静态Pod没能正常运行。排查思路按照下面几条逐一确认第一确认镜像拉取。国内网络环境下kubeadm默认从k8s.gcr.io拉镜像几乎必然超时。初始化时一定要指定国内镜像仓库kubeadm init \ --apiserver-advertise-address10.0.0.10 \ --image-repository registry.aliyuncs.com/google_containers \ --kubernetes-version v1.28.2 \ --pod-network-cidr192.168.0.0/16第二关闭swap。k8s要求控制节点必须关掉swap否则kubelet起不来。执行swapoff -a后还要确认/etc/fstab里挂载swap的配置被注释掉不然重启机器后又回来了。第三检查cgroup驱动。如果用的是containerd作为容器运行时必须保证kubelet和containerd的cgroup驱动都是systemd不一致的话apiserver也会反复崩溃。检查方式是在控制节点执行kubectl get pods -n kube-system看容器状态然后通过journalctl -u kubelet查看具体报错。初始化失败后重新来之前一定要执行kubeadm reset清理残留状态否则第二次初始化会遇到端口占用、etcd数据残留等一系列莫名其妙的问题。3. Spring Cloud应用容器化与Nacos联动3.1 多阶段Dockerfile与JVM参数设计Spring Cloud服务打包成镜像的Dockerfile我强烈推荐用多阶段构建。用一个带Maven的JDK镜像完成编译再用一个精简的JRE镜像运行这样最终推送到镜像仓库的体积能小一半以上。FROM maven:3.8.7-eclipse-temurin-17 AS builder WORKDIR /build COPY pom.xml . RUN mvn dependency:go-offline -B COPY src ./src RUN mvn clean package -DskipTests -B FROM eclipse-temurin:17-jre-alpine WORKDIR /app COPY --frombuilder /build/target/*.jar app.jar EXPOSE 8080 ENTRYPOINT [java,-jar,-Xms256m,-Xmx512m,/app/app.jar]有几个细节要注意。mvn dependency:go-offline这一步是为了在COPY源码之前先把所有依赖下载好这样源码有改动时Maven只需要增量打包构建速度会快很多。JVM参数里我固定了堆内存上下限防止容器内存被撑爆。生产环境更建议把-Xms和-Xmx配置成通过环境变量传入这样不同服务调整内存不需要重新构建镜像。基础镜像的选取也值得多说一句。Alpine版本的JRE镜像体积小但有些依赖了glibc的原生库的组件可能会出问题。如果遇到启动报错找不到动态链接库直接换回eclipse-temurin:17-jre这个基于Ubuntu的镜像就好体积大几十兆但兼容性稳妥得多。3.2 Nacos配置中心与服务的启动联动Nacos在微服务体系里管两件事服务注册和配置管理。服务启动时需要知道Nacos的地址、命名空间、分组这些信息不应该写死在配置文件里而是通过环境变量注入。Spring Cloud Alibaba项目的配置文件里通过spring.config.import导入Nacos上的共享配置spring: cloud: nacos: discovery: server-addr: ${NACOS_ADDR:nacos-service.default.svc.cluster.local:8848} namespace: ${NACOS_NAMESPACE:public} config: server-addr: ${NACOS_ADDR:nacos-service.default.svc.cluster.local:8848} namespace: ${NACOS_NAMESPACE:public} file-extension: yml config: import: - nacos:common-data.yml?groupDEFAULT_GROUP这里的${NACOS_ADDR:默认值}是环境变量占位符容器运行时再通过K8s的Deployment配置传入具体的Nacos地址。测试环境用测试的Nacos生产环境用生产的Nacos同一套镜像直接切换环境变量就能部署到不同环境这是微服务配置管理最核心的思路。有一点必须强调编写Dockerfile时不要执行任何需要Nacos连接的步骤比如在构建阶段跑集成测试。Nacos的地址在构建时往往是未知的而且构建环境也不一定能连通生产环境的Nacos。连接Nacos这步全部留到容器启动时完成。3.3 镜像仓库与镜像Tag规范构建好的镜像要有一个私有的镜像仓库来承接生产环境推荐用Harbor功能全、界面友好。镜像tag的规范直接影响发布和回滚的效率我这里用的是两级tag测试环境镜像服务名-feature-分支名-构建序号例如order-service-feature-dev-128生产环境镜像服务名-release-版本号例如order-service-release-1.4.0这样从Jenkins的构建记录里一眼就能看出这个镜像是什么服务、哪个分支、哪次构建产生的。生产环境发布时只把release版本号的镜像推到Harbor的prod项目下平时开发构建的镜像都放在dev项目下天然形成了环境隔离。回滚的时候也不需要重新构建直接在K8s的Deployment里把镜像tag改回上一个release版本就行秒级回滚。4. Jenkins Pipeline流水线完整实现4.1 Pipeline语法与Stage设计Jenkins的Pipeline我推荐用声明式语法结构清晰团队成员看着也好理解。一条标准的流水线划分为四个Stage拉取代码、Maven构建、构建并推送Docker镜像、部署到K8s。每个Stage职责单一任何一个环节失败后面的阶段都不会执行。pipeline { agent any environment { DOCKER_REGISTRY registry.example.com REGISTRY_CREDENTIALS credentials(harbor-credentials) KUBECONFIG_CREDENTIALS credentials(kubeconfig) } stages { stage(拉取代码) { steps { checkout scm } } stage(Maven构建) { steps { sh mvn clean package -DskipTests -pl ${SERVICE_NAME} -am } } stage(构建并推送Docker镜像) { steps { script { def image ${DOCKER_REGISTRY}/demo/${SERVICE_NAME}:${ENV_NAME}-${BUILD_NUMBER} sh docker build -f ${SERVICE_NAME}/Dockerfile -t ${image} ${SERVICE_NAME}/ echo ${REGISTRY_CREDENTIALS_PSW} | docker login ${DOCKER_REGISTRY} -u ${REGISTRY_CREDENTIALS_USR} --password-stdin docker push ${image} } } } } }Pipeline里的environment块用来定义全局变量注意credentials关键字是Jenkins专门用来管理敏感信息的用户名和密码会被转换成变量名_USR和变量名_PSW两个环境变量。不要直接在Pipeline里写明文密码这是新手最容易犯的错误一旦Pipeline脚本被提交到Git仓库等于把服务器密码公之于众。4.2 多模块Maven项目的按需构建Spring Cloud项目通常是一个多模块的Maven工程聚合了gateway、common、各个业务服务。如果每次都全量编译随着模块越来越多构建时间会从几分钟膨胀到几十分钟非常浪费时间。按需构建的关键是用了-pl和-am参数-pl指定要构建的模块-am表示同时构建它依赖的模块。Jenkins的Pipeline里把这个目标服务名做成参数构建时手动选择或者由分支触发逻辑自动带上服务名。这里有一个很常见的问题如果common模块的代码改了只编一个order-service会不会用上最新的common代码答案是会的-am参数会自动把order-service依赖的common模块也一起编译。但如果common模块自身的版本号没有更新Maven的SNAPSHOT机制可能拉到的是本地仓库的旧版本所以公共模块的版本管理要单独规范不能依赖Jenkins的偶然成功。4.3 部署到K8s与滚动发布部署阶段核心动作只有两个替换Deployment里的镜像版本然后kubectl apply。我采用的做法是在Jenkins服务器上保存一份K8s的Deployment模板Pipeline通过sed命令直接替换其中的镜像tagsed -i s#image:.*#image: ${IMAGE_TAG}#g k8s/order-service-deployment.yaml kubectl apply -f k8s/order-service-deployment.yaml这份Deployment模板包含两个关键配置探针和滚动更新策略。spec: replicas: 2 strategy: type: RollingUpdate rollingUpdate: maxUnavailable: 0 maxSurge: 1 template: spec: containers: - name: order-service image: registry.example.com/demo/order-service:latest ports: - containerPort: 8080 readinessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 15 periodSeconds: 10 livenessProbe: httpGet: path: /actuator/health port: 8080 initialDelaySeconds: 30 periodSeconds: 20 resources: requests: memory: 256Mi cpu: 250m limits: memory: 512MimaxUnavailable: 0意味着发布过程中旧实例不会一次性全部停止maxSurge: 1允许先多启动一个新实例等新实例就绪后再摘掉旧实例这样发布期间服务完全不会中断。readinessProbe会在流量进入前检查服务的/actuator/health如果新实例启动失败K8s会阻止流量进入并保留旧实例发布自动失败而不是把故障引入线上。Spring Boot应用需要引入spring-boot-starter-actuator依赖健康检查路径才能生效。这一步忘了的话K8s的探针永远请求不到健康接口新实例永远不健康发布会被卡住。5. 常见问题与排查技巧实录5.1 K8s初始化与节点问题的排查顺序K8s的报错排查我的经验是先看日志再动手改配置。控制节点初始化失败后第一条命令永远是journalctl -u kubelet -n 100日志里会明确告诉你卡在哪一步。The API server is not healthy这个报错绝大多数情况下是kube-apiserver容器本身起不来。再用crictl ps -a看所有容器的状态就能看到apiserver容器反复启动失败的原因无外乎镜像没拉下来、cgroup驱动不一致、静态Pod配置错误这几个方向。另外注意kubeadm初始化命令里有一个--timeout参数默认是4分钟。如果服务器性能弱apiserver启动慢可以适当调大比如--timeout 10m避免出现上面的超时报错。但如果你发现apiserver容器一直处于ImagePullBackOff状态再多的超时时间也救不回来先把镜像源换好再初始化。5.2 Docker Desktop自动化和Windows环境问题很多开发者的本地环境是Windows装Docker Desktop时最经典的一个报错是Docker Desktop failed to start because virtualisation support wasnt detected这个问题的根源在于Windows的虚拟化功能没打开或者BIOS里的虚拟化开关是关闭的。排查步骤很简单但一定要按顺序来首先确认Windows功能中“虚拟机平台”和“适用于Linux的Windows子系统”两项是勾选状态然后重启电脑接着进BIOS检查Intel VT-x或AMD-V是否开启。如果重启后还是报错多半是BIOS虚拟化开关没生效。开发环境的Docker Desktop配好之后本地调试Spring Cloud服务直接连容器里的中间件非常方便。很多团队搭测试库都是这样两个MySQL容器分别映射3306和3307端口一个Redis主从一个Nacos单节点用Docker Compose编排version: 3 services: mysql: image: mysql:8.0 ports: [3306:3306] environment: MYSQL_ROOT_PASSWORD: rootpass TZ: Asia/Shanghai volumes: - ./mysql-data:/var/lib/mysql nacos: image: nacos/nacos-server:v2.2.0 ports: [8848:8848, 9848:9848] environment: MODE: standalone访问容器内的MySQL有一个高频坑宿主机上用localhost:3306连是通的但服务部署在Docker容器里时localhost指向的是容器自身必须改成宿主机IP或者直接通过Docker网络访问。如果在同一个Compsoe定义里服务名就可以直接当主机名用jdbc:mysql://mysql:3306/xxx是对的写法。5.3 镜像构建相关的权限与时区问题docker build阶段出现permission denied优先检查执行用户是不是在docker组里。我推荐的方式是把当前用户加入docker组然后重新登录会话sudo usermod -aG docker $USER newgrp docker镜像里运行的Java应用默认时区是UTC打印的日志时间会比北京时间早八个小时。排查线上问题时时间对不上非常痛苦。Dockerfile里提前设置好时区RUN apk add --no-cache tzdata \ cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \ echo Asia/Shanghai /etc/timezoneK8s的Deployment里也可以通过env传入TZ环境变量来设置时区但Dockerfile里设好是更根本的解法因为这样无论部署到哪个环境镜像内的时区都是一致的。5.4 CI流水线调优的几点心得整套流水线跑通之后我的体会是从GitLab推代码到镜像构建完成一个服务通常需要3到5分钟其中Maven依赖下载和上传镜像消耗的时间占比最大。Maven依赖可以通过在Jenkins服务器上挂载一个本地的.m2仓库缓存来避免每次都全量下载镜像推送速度则取决于Harbor和Jenkins之间的网络条件这个环节很难再优化。生产环境发布的流程里我强烈建议加一道人工审批。Pipeline里用input步骤实现非常方便构建完成并推送镜像之后由负责人在Jenkins界面点一下“继续”才会执行后面的K8s部署避免自动化流程误触发生成环境的更新。最后再补充一个容易被忽略的配置Jenkins的可用环境变量。Pipeline阶段里需要用到工作目录、构建号、Git提交号等记得先查一下Jenkins自带的全局环境变量列表比如BUILD_NUMBER、GIT_COMMIT、WORKSPACE这些都是开箱即用的不要自己定义同名的变量去覆盖很容易踩坑。我见过有人把BUILD_NUMBER重新赋值结果导致镜像tag全乱掉的案例。整条流水线落地后最直观的改变是发布效率以前发一个服务要半小时现在从代码推送到线上运行只需要几分钟而且过程是可复现、可审计的。如果你所在的团队还在人肉部署微服务我建议从最薄弱的一个环节开始改造先把Docker镜像构建跑通再把Nacos接上然后逐步引入Jenkins和K8s每一步都能看到实际的收益推进起来也会顺得多。