一、项目环境说明

本教程基于 Windows开发机 + Linux K8s虚拟机 架构，实现CADS前后端项目容器化部署，适配企业级轻量化容器部署场景。

环境架构

• 开发环境：Windows

• 部署环境：Linux虚拟机（Kubernetes集群）

• 数据库：Windows宿主机 MySQL（192.168.86.1:3306）

• 容器技术：Docker、Nginx

• 编排工具：Kubernetes

项目结构

• cads-backend：SpringBoot后端项目

• cads-frontend：Vue/静态页面前端项目

二、部署前置准备（Windows端）

1. 环境依赖安装

提前安装并配置环境变量：JDK22、Maven3.6+、Node.js20+、Docker Desktop

2. 前端项目编译构建

进入前端项目目录，打包生成静态资源文件

cd C:\cad-system\cads\cads-frontend
npm run build

作用：生成 dist 目录，包含编译完成的HTML、JS、CSS静态文件，为Nginx部署提供资源。

3. 后端项目Maven打包

进入后端项目目录，清理并打包Jar包

cd C:\cad-system\cads\cads-backend
mvn clean package

作用：清理旧编译文件，编译生成可执行文件 cads-backend-1.0.0.jar，用于后端容器镜像构建。

三、Docker镜像构建与推送（Windows端）

前后端均采用Docker容器化打包，构建标准化镜像，推送至镜像仓库供K8s集群拉取部署。

1. 后端镜像构建

（1）后端Dockerfile

路径：cads-backend/Dockerfile

FROM openjdk:22-jre-slim
WORKDIR /app
COPY cads-backend-1.0.0.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

（2）构建&推送命令

cd C:\cad-system\cads\cads-backend
docker build -t 项目镜像仓库/cads:v1 .
docker push 项目镜像仓库/cads:v1

2. 前端镜像构建（Nginx多阶段构建）

（1）前端Dockerfile

路径：cads-frontend/Dockerfile，采用多阶段构建，精简镜像体积

FROM node:20-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
​
FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/templates/default.conf.template
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

（2）前端Nginx核心配置

路径：cads-frontend/nginx.conf，处理前端路由转发、后端API反向代理

server {
    listen 80;
    server_name localhost;
    root /usr/share/nginx/html;
    index index.html;
​
    # 前端路由适配（解决SPA刷新404）
    location / {
        try_files $uri $uri/ /index.html;
    }
​
    # 后端API反向代理
    location /cads/api/ {
        proxy_pass http://cads:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

（3）构建&推送命令

cd C:\cad-system\cads\cads-frontend
docker build -t 项目镜像仓库/cads-frontend:v1 .
docker push 项目镜像仓库/cads-frontend:v1

四、Kubernetes集群部署（Linux虚拟机端）

所有操作均在K8s集群节点执行，依次部署后端、前端服务，配置端口映射、数据库环境变量与网络策略。

1. 后端服务部署

（1）创建Deployment工作负载

kubectl create deployment cads --image=项目镜像仓库/cads:v1

（2）创建NodePort类型Service（外部访问）

kubectl expose deployment cads --type=NodePort --port=8080 --target-port=8080 --name=cads

（3）配置数据库连接环境变量

# 数据库连接地址、账号密码
kubectl set env deployment/cads SPRING_DATASOURCE_URL="jdbc:mysql://192.168.86.1:3306/cads_db?useSSL=false&allowPublicKeyRetrieval=true"
kubectl set env deployment/cads SPRING_DATASOURCE_USERNAME=root
kubectl set env deployment/cads SPRING_DATASOURCE_PASSWORD=123456

（4）解决宿主机数据库网络访问问题

开启Pod主机网络，规避Calico网络隔离导致的数据库连接超时、拒绝连接问题

kubectl patch deployment cads -p '{"spec":{"template":{"spec":{"hostNetwork":true}}}}'

2. 前端服务部署

（1）创建Deployment工作负载

kubectl create deployment cads-front --image=项目镜像仓库/cads-frontend:v1

（2）创建前端Service并修复端口映射

核心问题：容器监听端口与Service映射端口不匹配，需统一端口配置

# 创建基础Service
kubectl expose deployment cads-front --type=NodePort --port=80 --target-port=80 --name=cads-front
​
# 一键修复端口映射（适配容器监听端口）
kubectl patch svc cads-front -p '{"spec":{"ports":[{"port":8080,"targetPort":80,"nodePort":32295}]}}'

（3）重启前端服务生效配置

kubectl rollout restart deployment cads-front

五、服务验证与访问测试

1. 查看集群服务与Pod状态

# 查看所有Service端口
kubectl get svc
​
# 查看Pod运行状态
kubectl get pods -o wide
​
# 查看端点关联状态（验证端口映射）
kubectl get endpoints

2. 本地访问地址

• 前端页面：http://192.168.86.130:32295/

• 后端API接口：http://192.168.86.130:31617/cads/api/

• 后端容器直连地址：http://192.168.86.130:8080/cads/api/

3. 网络连通性测试

# 虚拟机内部测试
curl http://192.168.86.130:32295/
curl http://192.168.86.130:31617/cads/api/
​
# 端口连通性检测
nc -zv 192.168.86.130 32295

六、核心问题报错排查与解决方案

1. 数据库连接异常

报错信息：Communications link failure、Connection refused、Connect timed out

根因：K8s Calico网络隔离，Pod无法访问Windows宿主机MySQL服务

解决方案：开启Pod主机网络模式

kubectl patch deployment cads -p '{"spec":{"template":{"spec":{"hostNetwork":true}}}}'

2. Nginx代理异常（502/404）

报错信息：502 Bad Gateway、404 Not Found

根因：Nginx反向代理路径拼接错误、后端服务域名无法解析

解决方案：固定代理地址，修正Nginx配置

# 进入Pod修改配置并重启Nginx
kubectl exec -it [前端Pod名称] -- sed -i 's|错误代理路径|proxy_pass http://cads:8080;|' /etc/nginx/conf.d/default.conf
kubectl exec -it [前端Pod名称] -- nginx -s reload

3. Service端口映射不匹配

报错信息：Empty reply from server、Connection refused

根因：Service targetPort 与容器实际监听端口不一致

解决方案：通过patch命令一键修正端口映射

kubectl patch svc cads-front -p '{"spec":{"ports":[{"port":8080,"targetPort":80,"nodePort":32295}]}}'

4. Pod CrashLoopBackOff崩溃重启

根因：数据库配置错误、端口冲突、配置文件异常

排错方案：优先查看日志定位问题，修复后重启服务

# 查看Pod运行日志
kubectl logs [Pod名称] --tail=100
​
# 重启工作负载
kubectl rollout restart deployment cads
kubectl rollout restart deployment cads-front

5. Docker镜像构建报错

报错信息：invalid reference format、no such file or directory

根因：镜像标签含非法字符、Dockerfile路径错误

解决方案：使用简洁合法镜像标签，确保构建目录存在Dockerfile

6. 网络代理超时错误

根因：Linux虚拟机残留无效代理配置，阻断网络请求

解决方案：清空所有代理环境变量

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
unset all_proxy ALL_PROXY no_proxy NO_PROXY

七、K8s常用排查命令汇总

# 查看资源状态
kubectl get pods -o wide
kubectl get svc
kubectl get all
​
# 查看详细报错信息
kubectl describe pod [Pod名称]
kubectl describe deployment [部署名称]
​
# 日志排查
kubectl logs [Pod名称] --tail=100
kubectl logs [Pod名称] --previous
​
# 进入Pod内部调试
kubectl exec -it [Pod名称] -- bash
​
# 重启/更新服务
kubectl rollout restart deployment [部署名称]
kubectl set image deployment/[部署名称] [容器名]=[新镜像地址]

八、项目部署经验总结

1. 网络优先级最高：容器访问宿主机服务优先开启 hostNetwork，规避集群网络隔离问题，本项目80%连接报错均由网络隔离导致。

2. 端口必须双向统一：容器监听端口、Service targetPort、NodePort 三者必须匹配，是外部访问服务的核心关键。

3. Nginx配置标准化：前端SPA项目必须配置 try_files 解决刷新404问题，API代理禁止随意拼接后缀，避免路径404/502报错。

4. 排错优先看日志：Pod崩溃、服务访问异常，优先通过 kubectl logs 定位根源，而非盲目重启服务。

5. 镜像轻量化：前端采用多阶段构建，分离编译环境与运行环境，大幅缩减镜像体积，提升部署效率。