K3S实战：SpringBoot+Vue前后端分离项目容器化部署指南

1. 从单体到容器化：为什么选择K3S来部署前后端服务？

最近在折腾一个SpringBoot+Vue的前后端分离项目，从本地开发到最终上线，部署环节总是绕不开的一环。相信很多朋友都经历过：本地跑得好好的，一上服务器就各种环境问题，Node版本不对、JDK版本冲突、端口被占、依赖缺失…… 传统的部署方式，比如直接在物理机或虚拟机上安装Java、Nginx、MySQL，虽然直接，但环境隔离性差，迁移和扩展都相当麻烦。后来大家普遍转向了Docker，用容器把应用和它的运行环境打包在一起，确实解决了“在我这能跑”的问题。但当你需要管理多个容器，处理它们之间的网络、存储、调度时，单靠Docker Compose就显得力不从心了，这时候就需要一个容器编排平台。

Kubernetes（K8s）无疑是这个领域的王者，功能强大但同时也以“重”和“复杂”著称。对于中小型项目、个人开发者或者边缘计算场景，全套K8s的学习和维护成本有点过高。这正是轻量级Kubernetes发行版K3S的用武之地。K3S由Rancher Labs（现为SUSE）开发，它保留了K8s的核心API和功能，但通过移除旧的、非必须的代码和外部依赖，将二进制文件大小控制在100MB左右，内存占用极低。它默认使用containerd作为容器运行时，内置了SQLite作为默认的存储后端（也支持etcd），并且将所有的K8s组件打包进了一个单一的二进制文件中，安装和启动变得异常简单。对于部署我们这种典型的SpringBoot后端+Vue前端的前后端分离应用，K3S提供了一个近乎完美的平衡点：它具备了服务发现、负载均衡、配置管理、滚动更新等生产级能力，同时又足够轻巧，可以在从云端虚拟机到树莓派的任何地方快速拉起一个集群。

所以，这次我们就来实战一下，如何将一个标准的SpringBoot + Vue前后端分离项目，完整地部署到K3S集群中。整个过程会涵盖从应用容器化（Docker镜像制作）到K8s资源定义（Deployment, Service, Ingress），再到最终通过域名访问的完整链路。你会发现，借助K3S，部署和维护一个现代化应用可以如此清晰和高效。

2. 项目准备与容器化：构建可部署的Docker镜像

在将应用扔进K3S之前，我们必须先把它“装进盒子”，也就是制作成Docker镜像。这是至关重要的一步，镜像的质量直接决定了部署的稳定性和可重复性。我们的项目结构通常如下：

my-app/ ├── backend/ # SpringBoot项目目录 │ ├── src/ │ ├── pom.xml # 或 build.gradle │ └── Dockerfile ├── frontend/ # Vue项目目录 │ ├── src/ │ ├── package.json │ ├── vue.config.js │ └── Dockerfile └── k8s-manifests/ # K8s资源定义文件（后续使用）

2.1 SpringBoot后端镜像构建

SpringBoot应用的容器化已经非常成熟。关键在于构建一个分层（Layered）的镜像，以充分利用Docker的镜像缓存机制，加快构建和推送速度。这里以Maven项目为例，使用多阶段构建。

backend/Dockerfile:

# 第一阶段：构建 FROM maven:3.8.6-eclipse-temurin-17 AS builder WORKDIR /app COPY pom.xml . # 利用缓存提前下载依赖 RUN mvn dependency:go-offline -B COPY src ./src RUN mvn clean package -DskipTests # 第二阶段：运行 FROM eclipse-temurin:17-jre-jammy WORKDIR /app # 复制构建产物，使用分层JAR结构 COPY --from=builder /app/target/*.jar app.jar # 创建一个非root用户运行，增强安全性 RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app USER appuser EXPOSE 8080 ENTRYPOINT ["java", "-jar", "/app/app.jar"]

关键点解析：

1. 多阶段构建：第一阶段使用完整的JDK镜像进行编译打包，第二阶段只包含轻量的JRE运行环境，这能显著减小最终镜像的体积（通常能从600MB+降到200MB左右）。
2. 依赖缓存：先单独复制pom.xml并执行mvn dependency:go-offline，这样只要依赖不变，后续构建就可以复用这一层缓存，极大加速构建过程。
3. 非Root用户：在生产环境中，以root权限运行容器是高风险行为。我们创建一个名为appuser的普通用户来运行应用，这是安全最佳实践。
4. 分层JAR：Spring Boot 2.3+支持在打包时创建分层索引（spring-boot-maven-plugin配置<layers>true</layers>），可以进一步优化镜像层。上述Dockerfile是通用写法，如果项目启用了分层，可以更精细地复制spring-boot-loader、dependencies、snapshot-dependencies、application各层，最大化缓存利用率。

在backend目录下执行构建：

docker build -t my-springboot-app:latest .

2.2 Vue前端镜像构建

Vue项目是静态资源，我们需要一个Web服务器来托管它。Nginx是首选，因为它轻量、高效，并且配置灵活。同样采用多阶段构建：第一阶段用Node环境进行构建（npm run build），第二阶段将生成的dist目录复制到Nginx镜像中。

frontend/Dockerfile:

# 第一阶段：构建 FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build # 第二阶段：托管 FROM nginx:alpine # 将构建好的静态文件复制到Nginx的默认发布目录 COPY --from=builder /app/dist /usr/share/nginx/html # 复制自定义的Nginx配置文件（可选，用于处理Vue Router的history模式） COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80

关键点解析：

1. npm civsnpm install：在CI/CD环境中，推荐使用npm ci。它严格根据package-lock.json安装依赖，能确保依赖树的一致性，并且速度更快。
2. Nginx配置：默认配置可能无法正确处理Vue Router的history模式（访问非根路径返回404）。我们需要一个自定义配置来解决这个问题。frontend/nginx.conf:

   server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html index.htm; # 核心配置：当请求的文件不存在时，重定向到index.html，由前端路由处理 try_files $uri $uri/ /index.html; } # 可选：代理后端API请求，避免跨域。如果前后端通过K8s Service通信，则不需要此配置。 # location /api/ { # proxy_pass http://backend-service:8080/; # } }

   这个配置中的try_files指令是支持Vue Routerhistory模式的关键。它告诉Nginx，如果请求的URI对应的文件不存在，就返回index.html，让前端应用（Vue Router）去处理这个路由。

在frontend目录下执行构建：

docker build -t my-vue-app:latest .

实操心得：镜像标签（Tag）管理很重要。在生产实践中，不要总是使用:latest。建议使用Git提交哈希、构建编号或语义化版本作为标签的一部分（如my-app:git-${COMMIT_SHA}），这样可以实现精确的版本回滚和追踪。

3. K3S集群搭建与核心概念快速上手

有了镜像，接下来就需要一个K3S集群来运行它们。K3S的安装简单到令人发指。

3.1 单节点集群安装（All-in-One）

对于学习和测试，单节点模式足够了。在一台干净的Linux服务器（如Ubuntu 22.04）上，只需一行命令：

curl -sfL https://get.k3s.io | sh -

执行完成后，K3S服务会自动启动。你可以通过以下命令检查状态：

sudo systemctl status k3s

获取集群配置，以便用kubectl（K8s命令行工具）管理：

sudo cat /etc/rancher/k3s/k3s.yaml

将输出内容保存到本地~/.kube/config，并修改其中的server地址为你的服务器IP（如果从远程访问）。然后安装kubectl，就可以操作集群了。

3.2 多节点集群安装（可选）

如果需要多节点，首先在主节点上安装，并获取token：

sudo cat /var/lib/rancher/k3s/server/node-token

然后在工作节点上，使用以下命令加入集群（将<MASTER_IP>和<TOKEN>替换为实际值）：

curl -sfL https://get.k3s.io | K3S_URL=https://<MASTER_IP>:6443 K3S_TOKEN=<TOKEN> sh -

3.3 部署前必须理解的几个K8s资源对象

在编写部署文件之前，需要理解几个核心的K8s资源，它们是我们应用的“乐高积木”。

1. Pod：K8s中最小的可部署单元。一个Pod包含一个或多个容器（通常是一个），共享网络和存储空间。我们一般不直接创建Pod。
2. Deployment：这是管理Pod的“控制器”。你定义一个Deployment，它来确保指定数量的Pod副本（Replicas）始终运行。它负责滚动更新、回滚等。我们的应用（无论是前端还是后端）都会通过Deployment来部署。
3. Service：Pod是短暂的，IP会变。Service提供了一个稳定的网络端点（一个固定的集群内部IP和DNS名称）来访问一组Pod。后端服务需要被前端访问，所以后端需要一个Service。前端如果只需要被外部访问，可能不需要独立的Service（可通过Ingress直接指向Pod）。
4. Ingress：Service提供的是L4（TCP/UDP）访问。Ingress是L7（HTTP/HTTPS）流量管理器，它可以根据域名、路径将外部请求路由到集群内部不同的Service。我们需要一个Ingress来将公网流量路由到前端Nginx，并可能将/api路径的请求代理到后端Service。K3S默认安装了Traefik作为Ingress Controller。

理解了这些，我们就可以像搭积木一样，用YAML文件描述出我们应用的完整运行蓝图。

4. 编写K8s部署清单：定义应用运行蓝图

现在，我们在项目根目录创建k8s-manifests文件夹，并开始编写YAML文件。这些文件描述了我们的应用在K3S集群中应该如何运行。

4.1 部署后端SpringBoot应用

首先定义后端的Deployment和Service。

k8s-manifests/backend-deployment.yaml:

apiVersion: apps/v1 kind: Deployment metadata: name: springboot-backend labels: app: springboot-backend spec: replicas: 2 # 运行2个副本，提高可用性 selector: matchLabels: app: springboot-backend template: # 这是Pod的模板 metadata: labels: app: springboot-backend spec: containers: - name: backend image: my-springboot-app:latest # 替换为你的实际镜像名 ports: - containerPort: 8080 resources: requests: # 容器启动所需的最小资源 memory: "512Mi" cpu: "250m" limits: # 容器所能使用的最大资源 memory: "1Gi" cpu: "500m" env: # 环境变量，可用于传递配置 - name: SPRING_PROFILES_ACTIVE value: "prod" - name: DB_HOST valueFrom: configMapKeyRef: name: app-config key: database.host # 健康检查探针，对Spring Boot Actuator应用非常有用 livenessProbe: httpGet: path: /actuator/health/liveness port: 8080 initialDelaySeconds: 60 # 容器启动后60秒开始探测 periodSeconds: 10 readinessProbe: httpGet: path: /actuator/health/readiness port: 8080 initialDelaySeconds: 30 periodSeconds: 5 --- apiVersion: v1 kind: Service metadata: name: backend-service spec: selector: app: springboot-backend ports: - port: 80 # Service对外暴露的端口 targetPort: 8080 # 容器内端口 type: ClusterIP # 默认类型，仅在集群内部可访问

关键配置解读：

• replicas: 2：启动两个相同的Pod实例。当一个实例故障时，另一个仍可提供服务，Deployment会自动创建新的Pod维持数量。
• resources：为容器设置资源请求和限制是生产环境必备操作。它防止某个应用耗尽节点资源，影响其他应用。250m代表0.25个CPU核心。
• env：将配置从代码中分离。这里演示了直接写死和引用ConfigMap两种方式。敏感信息（如密码）应使用Secret。
• livenessProbe&readinessProbe：
  • 就绪探针（Readiness）：告诉K8s什么时候Pod可以开始接收流量。如果检查失败，Pod会从Service的负载均衡池中移除。
  • 存活探针（Liveness）：告诉K8s什么时候Pod需要重启。如果检查失败，K8s会杀死并重启容器。
  • Spring Boot Actuator提供了现成的健康端点。这能确保流量只会被发送到真正准备好的应用实例，并在应用死锁时自动恢复。
• Service类型为ClusterIP：这意味着后端服务只能在K3S集群内部通过backend-service这个DNS名称访问（例如，前端应用可以通过http://backend-service/api/users来调用后端API）。这实现了前后端在网络层面的解耦和安全隔离。

4.2 部署前端Vue应用

前端是静态文件，我们同样用Deployment来管理Nginx Pod，并用一个Service暴露它。但前端的Service最终需要被外部访问，我们有两种选择：1) 使用NodePort类型的Service；2) 使用ClusterIP+Ingress。生产环境推荐第二种。

k8s-manifests/frontend-deployment.yaml:

apiVersion: apps/v1 kind: Deployment metadata: name: vue-frontend labels: app: vue-frontend spec: replicas: 2 selector: matchLabels: app: vue-frontend template: metadata: labels: app: vue-frontend spec: containers: - name: frontend image: my-vue-app:latest # 替换为你的实际镜像名 ports: - containerPort: 80 resources: requests: memory: "128Mi" cpu: "100m" limits: memory: "256Mi" cpu: "200m" # 前端通常不需要复杂的健康检查，一个简单的HTTP GET即可 livenessProbe: httpGet: path: / port: 80 initialDelaySeconds: 30 periodSeconds: 10 --- apiVersion: v1 kind: Service metadata: name: frontend-service spec: selector: app: vue-frontend ports: - port: 80 targetPort: 80 type: ClusterIP # 先使用ClusterIP，通过Ingress对外暴露

4.3 配置Ingress路由规则

这是将外部流量引入集群的关键。我们创建一个Ingress资源，定义路由规则。假设我们的域名是app.my-domain.com。

k8s-manifests/ingress.yaml:

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: app-ingress annotations: # 以下注解针对Traefik（K3S默认Ingress Controller） traefik.ingress.kubernetes.io/router.entrypoints: web # 如果启用HTTPS，还需要配置websecure入口点和证书 spec: rules: - host: "app.my-domain.com" # 你的域名 http: paths: - path: / pathType: Prefix backend: service: name: frontend-service port: number: 80 - path: /api pathType: Prefix backend: service: name: backend-service port: number: 80

路由规则解读：

• 当用户访问http://app.my-domain.com/时，流量会被路由到frontend-service，即我们的Vue应用。
• 当Vue前端发起API请求到/api/users时，这个请求会被Ingress捕获，并路由到backend-service。注意，这里后端Service的端口是80（Service端口），它会转发到Pod的8080端口（targetPort）。
• 这样就实现了前后端在同一个域名下的统一访问入口，完美解决了前后端分离项目在部署时的跨域问题（CORS），因为现在它们在同源（相同域名、端口）下了。

踩坑提醒：如果你的SpringBoot后端有配置上下文路径（server.servlet.context-path），例如/api/v1，那么Ingress中的path应该与之匹配，比如设置为/api/v1。同时，前端调用后端API的基地址（Base URL）也应该是/api/v1，而不是简单的/api。路径不匹配是导致404错误的常见原因。

5. 部署实战与运维要点

编写好YAML文件后，就可以开始部署了。

5.1 应用部署与状态检查

1. 应用配置：首先，确保你的Docker镜像已经推送到一个K3S节点能够访问的镜像仓库（如Docker Hub、私有Harbor，或者直接构建在本地节点上）。如果镜像在本地，K3S可以直接使用。
2. 部署资源：在Master节点上，使用kubectl apply命令部署所有资源。

   kubectl apply -f k8s-manifests/

   这个命令会读取目录下所有.yaml文件并创建资源。
3. 检查部署状态：

   # 查看所有Pod的状态 kubectl get pods -o wide # 查看Deployment状态 kubectl get deployments # 查看Service kubectl get svc # 查看Ingress kubectl get ingress

   等待所有Pod的状态变为Running，并且READY列为2/2（表示2个副本都就绪）。

5.2 访问应用与问题排查

1. 获取访问地址：由于我们使用了Ingress，需要知道Traefik（Ingress Controller）的外部IP。在云服务器上，这个IP可能就是节点的公网IP。执行以下命令查看：

   kubectl get svc -n kube-system traefik

   如果EXTERNAL-IP是<pending>，在非云环境中，你可能需要将节点的IP地址作为访问地址。或者，你可以修改frontend-service的类型为NodePort，然后通过节点IP:NodePort直接访问前端。
2. 配置DNS/本地Hosts：将你的域名app.my-domain.com解析到上一步获得的IP地址。在测试环境，可以直接修改本地的hosts文件。
3. 访问：在浏览器中打开http://app.my-domain.com，应该能看到Vue前端页面。前端发起的API请求（如/api/users）应该能正确到达后端并返回数据。

5.3 常见问题与排查命令

• Pod一直处于Pending状态：通常是资源不足（CPU/内存）或节点选择问题。使用kubectl describe pod <pod-name>查看事件详情。
• Pod处于CrashLoopBackOff状态：容器反复启动失败。首先查看日志：kubectl logs <pod-name>。如果容器有多个，用-c <container-name>指定。查看前一次崩溃的日志：kubectl logs <pod-name> --previous。
• 服务无法访问：
  • 检查Service的Selector是否与Pod的Label匹配：kubectl describe svc <service-name>。
  • 进入一个Pod内部，尝试用Service的DNS名称（如curl http://backend-service/actuator/health）测试连通性。
  • 检查Ingress Controller日志：kubectl logs -n kube-system deployment/traefik。
• 应用配置问题：确保环境变量、ConfigMap、Secret等配置正确挂载到容器中。使用kubectl exec -it <pod-name> -- /bin/sh进入容器内部检查环境。

5.4 配置管理与敏感信息处理

在实际项目中，数据库连接字符串、API密钥等敏感信息绝不能硬编码在镜像或YAML文件中。K8s提供了ConfigMap和Secret来管理配置和敏感数据。

示例：使用ConfigMap管理应用配置

# k8s-manifests/configmap.yaml apiVersion: v1 kind: ConfigMap metadata: name: app-config data: application.properties: | spring.datasource.url=jdbc:mysql://${DB_HOST}:3306/mydb app.feature.enabled=true

示例：使用Secret管理数据库密码

# k8s-manifests/secret.yaml (密码需要base64编码) apiVersion: v1 kind: Secret metadata: name: db-secret type: Opaque data: password: c3VwZXJzZWNyZXQ= # "supersecret"的base64编码

然后在Deployment中通过环境变量引用：

env: - name: DB_PASSWORD valueFrom: secretKeyRef: name: db-secret key: password

6. 进阶：持久化存储、滚动更新与监控初探

6.1 为SpringBoot应用添加数据库持久化

我们的SpringBoot应用通常需要数据库。在K8s中，数据库（如MySQL）也建议以有状态工作负载（StatefulSet）部署，并需要持久化存储（PersistentVolume, PV）来保存数据。

简化示例：使用K3S内置的Local Path ProvisionerK3S默认安装了一个本地路径存储类（StorageClass），可以动态创建PV。我们可以为MySQL创建一个PersistentVolumeClaim（PVC）。

# k8s-manifests/mysql-pvc.yaml apiVersion: v1 kind: PersistentVolumeClaim metadata: name: mysql-pvc spec: accessModes: - ReadWriteOnce storageClassName: local-path # K3S默认的存储类 resources: requests: storage: 5Gi

然后在MySQL的Deployment中挂载这个PVC到容器内的数据目录（如/var/lib/mysql）。这样即使Pod重启或迁移，数据也不会丢失。

6.2 实现零停机滚动更新

当我们发布新版本的镜像时，Deployment的滚动更新策略可以确保服务不中断。这是我们在Deployment定义中spec.strategy字段控制的，默认就是RollingUpdate。

触发更新：只需修改Deployment YAML文件中的镜像标签，然后重新apply。

kubectl set image deployment/springboot-backend backend=my-springboot-app:v2.0 # 或者 kubectl apply -f k8s-manifests/backend-deployment.yaml # 如果文件里镜像tag已改

K8s会逐步用新Pod替换旧Pod，期间始终有Pod在提供服务。你可以通过kubectl rollout status deployment/springboot-backend来观察更新状态。如果新版本有问题，可以快速回滚：kubectl rollout undo deployment/springboot-backend。

6.3 基础监控与日志收集

对于生产环境，监控和日志必不可少。

• K3S集群监控：可以部署Prometheus + Grafana。社区有成熟的Helm Chart可以一键部署，用于监控节点、Pod的资源使用情况（CPU、内存、网络）。
• 应用日志：所有容器的标准输出和错误输出都可以通过kubectl logs查看。对于集中式日志收集，可以考虑部署EFK（Elasticsearch, Fluentd, Kibana）或Loki栈。在K3S上，由于资源限制，Loki是更轻量级的选择。
• 应用性能监控（APM）：对于Java应用，可以集成SkyWalking、Pinpoint等APM工具，通过Sidecar模式或Java Agent注入到应用容器中，来监控接口性能、调用链路和JVM状态。

7. 总结与个人实践建议

走完这一整套流程，你会发现用K3S部署SpringBoot+Vue项目，虽然前期需要学习一些K8s的概念和YAML语法，但一旦流程固化下来，其带来的收益是巨大的：环境标准化、一键部署、弹性伸缩、故障自愈。整个过程就像是为你的应用编写了一份详细的“运行说明书”（YAML文件），集群会严格按照说明书来执行和维护。

从我个人的实践经验来看，有几点建议值得分享：

第一，基础设施即代码（IaC）。把你所有的K8s YAML文件、Dockerfile、甚至安装脚本都纳入Git版本控制。这能保证部署过程的可重复性和可审计性。你可以使用Kustomize或Helm来管理更复杂的配置和多个环境（开发、测试、生产）。

第二，重视健康检查。为你的SpringBoot应用集成Actuator，并配置好livenessProbe和readinessProbe。这是K8s管理你应用生命周期的“眼睛”，没有它，K8s就不知道你的应用是死是活，滚动更新和自愈能力会大打折扣。

第三，镜像标签策略。永远不要依赖:latest标签进行生产部署。使用有意义的标签，如${gitTag}-${buildNumber}。这能让你在出问题时，精确地知道线上运行的是哪个版本的代码，并快速回滚。

第四，从小处着手。如果你和你的团队是K8s新手，不要试图一次性把所有微服务、所有中间件都搬上去。可以从一个简单的、无状态的应用（就像我们这个前后端项目）开始，熟悉整个流程和排查问题的方法。等有了信心，再逐步迁移更复杂的组件。

最后，K3S的轻量化特性使得它成为个人项目、初创公司或边缘场景拥抱K8s生态的绝佳跳板。它降低了你学习和试错的硬件和心智门槛。当你用几行命令就搭建起一个具备完整容器编排能力的集群，并看着你的应用在其中稳定运行时，那种一切尽在掌控的感觉，正是DevOps文化的魅力所在。