huojin
/
Cpte-Boot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Cpte-Boot/K8S_DEPLOYMENT.md

522 lines
13 KiB
Markdown
Raw Normal View History

no message
2026-03-06 15:19:25 +08:00
# WMS 微服务 K8s 部署文档
## 📋 目录
- [架构概述](#架构概述)
- [技术栈](#技术栈)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [详细部署步骤](#详细部署步骤)
- [服务间调用](#服务间调用)
- [监控与运维](#监控与运维)
- [常见问题](#常见问题)
---
## 🏗️ 架构概述
### 微服务架构
```
┌─────────────────────────────────────────────────────────┐
│ Kubernetes Cluster │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Nginx Ingress Controller │ │
│ └────────────────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────┼────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Service │ │ Service │ │ Service │ │
│ │ Basic │ │ Inbound │ │ Outbound │ │
│ │ :80 │ │ :80 │ │ :80 │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ │ │ │ │
│ ┌──────┴──────┐ ┌──────┴──────┐ ┌──────┴──────┐ │
│ │ Pod ×2 │ │ Pod ×2 │ │ Pod ×2 │ │
│ │ (HPA 2-10) │ │ (HPA 2-10) │ │ (HPA 2-10) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │ Service │ │ Service │ │
│ │ Inventory │ │ Schedule │ │
│ │ :80 │ │ :80 │ │
│ └────────────┘ └────────────┘ │
│ │ │ │
│ ┌──────┴──────┐ ┌──────┴──────┐ │
│ │ Pod ×2 │ │ Pod ×2 │ │
│ │ (HPA 2-10) │ │ (HPA 2-10) │ │
│ └─────────────┘ └─────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ MySQL + Redis (StatefulSet) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```
### 服务列表
| 服务名称 | 端口 | 副本数 | HPA | 说明 |
|---------|------|--------|-----|------|
| wms-basic-service | 80 | 2 | 2-10 | 基础数据服务 |
| wms-inbound-service | 80 | 2 | 2-10 | 入库服务 |
| wms-outbound-service | 80 | 2 | 2-10 | 出库服务 |
| wms-inventory-service | 80 | 2 | 2-10 | 库存服务 |
| wms-schedule-service | 80 | 2 | 2-10 | 调度服务（AGV） |
---
## 🛠️ 技术栈
### 核心技术
- **微服务框架**: Spring Boot 3.5.5
- **服务调用**: OpenFeign 4.1.3
- **HTTP 客户端**: OkHttp
- **容器编排**: Kubernetes 1.24+
- **Ingress**: Nginx Ingress Controller
- **数据库**: MySQL 8.0+
- **缓存**: Redis 5.0+
### 监控与日志
- **健康检查**: Spring Boot Actuator
- **指标收集**: Prometheus
- **日志**: ELK Stack（可选）
- **链路追踪**: SkyWalking（可选）
---
## 📦 环境要求
### 硬件要求
- **CPU**: 至少 8 核（推荐 16 核+）
- **内存**: 至少 16GB（推荐 32GB+）
- **磁盘**: 至少 100GB 可用空间
### 软件要求
- **Kubernetes**: 1.24+
- **Docker**: 20.10+
- **kubectl**: 1.24+
- **Maven**: 3.6+（用于构建）
- **Helm**: 3.0+（可选）
---
## 🚀 快速开始
### 1. 克隆项目
```bash
git clone <repository-url>
cd Cpte-Boot
```
### 2. 一键部署
```bash
# 设置镜像标签
export IMAGE_TAG=v1.0.0
# 执行一键部署
chmod +x deploy.sh
./deploy.sh deploy
```
### 3. 验证部署
```bash
# 查看 Pods 状态
kubectl get pods -n wms-system
# 查看 Services 状态
kubectl get svc -n wms-system
# 查看 Ingress 状态
kubectl get ingress -n wms-system
```
### 4. 访问服务
```bash
# 获取 Ingress 地址
INGRESS_HOST=$(kubectl get ingress wms-ingress -n wms-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
# 访问 API 文档
echo "http://${INGRESS_HOST}/doc.html"
```
---
## 📝 详细部署步骤
### 步骤 1: 准备 K8s 集群
```bash
# 检查 kubectl 连接
kubectl cluster-info
# 检查节点状态
kubectl get nodes
```
### 步骤 2: 配置镜像仓库
修改 `deploy.sh` 中的镜像仓库地址：
```bash
REGISTRY_URL="registry.cn-beijing.aliyuncs.com/cpte-wms"
```
### 步骤 3: 构建 Docker 镜像
```bash
# 单独构建镜像
./deploy.sh build
# 或构建特定服务
cd cpte-wms-service/cpte-wms-inbound-service
docker build -t registry.cn-beijing.aliyuncs.com/cpte-wms/wms-inbound-service:latest .
```
### 步骤 4: 推送镜像
```bash
# 推送所有镜像
./deploy.sh push
# 或推送特定服务
docker push registry.cn-beijing.aliyuncs.com/cpte-wms/wms-inbound-service:latest
```
### 步骤 5: 部署到 K8s
```bash
# 如果已构建和推送镜像，可直接部署
./deploy.sh k8s
```
### 步骤 6: 验证部署
```bash
# 查看所有资源
kubectl get all -n wms-system
# 查看 Pods 状态
kubectl get pods -n wms-system -o wide
# 查看服务日志
kubectl logs -f deployment/wms-inbound-service -n wms-system
```
---
## 🔌 服务间调用
### Feign Client 使用
#### 1. 添加依赖
已在所有服务的 `pom.xml` 中添加：
```xml
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-starter-openfeign</artifactId>
<version>4.1.3</version>
</dependency>
```
#### 2. 创建 Feign Client
```java
@FeignClient(
name = "wms-basic-service",
url = "${feign.client.wms-basic.url:http://wms-basic-service:80}",
configuration = FeignClientConfiguration.class,
fallbackFactory = BasicServiceFallbackFactory.class
)
public interface BasicServiceClient {
@GetMapping("/api/wms/basic/item/{id}")
Result<Map<String, Object>> getItemById(@PathVariable("id") String id);
}
```
#### 3. 使用 Feign Client
```java
@Service
public class InboundService {
@Autowired
private BasicServiceClient basicServiceClient;
@Autowired
private InventoryServiceClient inventoryServiceClient;
public Result<String> inbound(String itemId, Integer quantity) {
// 调用基础服务验证物品
Result<Map<String, Object>> itemResult = basicServiceClient.getItemById(itemId);
if (!itemResult.isSuccess()) {
return Result.error("物品不存在");
}
// 调用库存服务增加库存
Map<String, Object> params = new HashMap<>();
params.put("itemId", itemId);
params.put("quantity", quantity);
Result<Boolean> increaseResult = inventoryServiceClient.increaseInventory(params);
return Result.OK("入库成功");
}
}
```
### 服务调用关系
```
入库服务 → 基础服务（验证物品/库位）
入库服务 → 库存服务（增加库存）
入库服务 → 调度服务（创建上架任务）
出库服务 → 基础服务（验证物品/库位）
出库服务 → 库存服务（扣减库存）
出库服务 → 调度服务（创建下架任务）
调度服务 → 基础服务（获取库位信息）
调度服务 → 库存服务（获取库存信息）
```
---
## 📊 监控与运维
### 健康检查
每个服务都配置了健康检查端点：
```bash
# 检查服务健康状态
curl http://<service-ip>/actuator/health
# 检查存活探针
curl http://<service-ip>/actuator/health/liveness
# 检查就绪探针
curl http://<service-ip>/actuator/health/readiness
```
### 查看日志
```bash
# 查看实时日志
kubectl logs -f deployment/wms-inbound-service -n wms-system
# 查看最近 100 行日志
kubectl logs --tail=100 deployment/wms-inbound-service -n wms-system
# 查看特定 Pod 日志
kubectl logs <pod-name> -n wms-system
```
### 扩缩容
```bash
# 手动扩容到 5 个副本
kubectl scale deployment wms-inbound-service --replicas=5 -n wms-system
# 查看 HPA 状态
kubectl get hpa -n wms-system
# HPA 会自动根据 CPU/内存使用率扩缩容
```
### 滚动更新
```bash
# 重启服务（滚动更新）
kubectl rollout restart deployment/wms-inbound-service -n wms-system
# 查看更新状态
kubectl rollout status deployment/wms-inbound-service -n wms-system
# 回滚到上一个版本
kubectl rollout undo deployment/wms-inbound-service -n wms-system
```
### 监控指标
```bash
# 查看 Pod 资源使用
kubectl top pods -n wms-system
# 查看节点资源使用
kubectl top nodes
```
---
## ❓ 常见问题
### Q1: Pod 无法启动
**问题**: Pod 一直处于 `Pending` 或 `CrashLoopBackOff` 状态
**解决**:
```bash
# 查看 Pod 详情
kubectl describe pod <pod-name> -n wms-system
# 查看日志
kubectl logs <pod-name> -n wms-system
# 常见原因:
# 1. 资源不足：检查节点资源
# 2. 镜像拉取失败：检查镜像地址和凭证
# 3. 配置错误：检查 ConfigMap 和 Secret
# 4. 数据库连接失败：检查数据库服务
```
### Q2: 服务间调用失败
**问题**: Feign Client 调用超时或返回错误
**解决**:
```bash
# 1. 检查服务是否正常
kubectl get pods -n wms-system
# 2. 检查 Service 是否正确
kubectl get svc -n wms-system
# 3. 测试服务连通性
kubectl run test --rm -it --image=busybox --namespace=wms-system --restart=Never -- wget -qO- http://wms-basic-service/actuator/health
# 4. 查看调用日志
kubectl logs deployment/wms-inbound-service -n wms-system | grep Feign
```
### Q3: Ingress 无法访问
**问题**: 通过 Ingress 无法访问服务
**解决**:
```bash
# 1. 检查 Ingress Controller 是否运行
kubectl get pods -n ingress-nginx
# 2. 检查 Ingress 配置
kubectl describe ingress wms-ingress -n wms-system
# 3. 检查 DNS 解析
nslookup wms.yourcompany.com
# 4. 直接通过 Service IP 访问
kubectl get svc -n wms-system
curl http://<service-ip>/doc.html
```
### Q4: HPA 不工作
**问题**: HPA 无法自动扩缩容
**解决**:
```bash
# 1. 检查 metrics-server 是否运行
kubectl get pods -n kube-system | grep metrics-server
# 2. 查看 HPA 详情
kubectl describe hpa wms-inbound-hpa -n wms-system
# 3. 检查 Pod 资源请求配置
kubectl get deployment wms-inbound-service -n wms-system -o yaml
# 确保配置了 resources.requests.cpu 和 resources.requests.memory
```
### Q5: 数据库连接失败
**问题**: 服务无法连接数据库
**解决**:
```bash
# 1. 检查 MySQL 服务
kubectl get svc mysql-service -n wms-system
# 2. 测试数据库连接
kubectl run mysql-test --rm -it --image=mysql:8.0 --namespace=wms-system --restart=Never -- mysql -h mysql-service -u root -p
# 3. 检查 Secret 配置
kubectl get secret wms-secret -n wms-system -o yaml
# 4. 查看服务日志中的数据库连接信息
kubectl logs deployment/wms-inbound-service -n wms-system | grep -i datasource
```
---
## 🔧 高级配置
### 配置中心
使用 ConfigMap 管理配置：
```bash
# 更新配置
kubectl create configmap wms-app-config --from-file=application.yml --namespace=wms-system --dry-run=client -o yaml | kubectl apply -f -
# 重启服务使配置生效
kubectl rollout restart deployment/wms-inbound-service -n wms-system
```
### 密钥管理
使用 Secret 管理敏感信息：
```bash
# 创建 Secret
kubectl create secret generic wms-db-secret --from-literal=username=root --from-literal=password=YourPassword --namespace=wms-system
```
### 持久化存储
```yaml
# 创建 PersistentVolumeClaim
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
name: wms-data-pvc
namespace: wms-system
spec:
accessModes:
- ReadWriteMany
resources:
requests:
storage: 10Gi
storageClassName: nfs-storage
```
---
## 📖 相关文档
- [Feign 使用指南](cpte-wms-service/FEIGN_USAGE.md)
- [K8s 配置说明](k8s/)
- [Dockerfile 说明](cpte-wms-service/*/Dockerfile)
---
## 📞 技术支持
如有问题，请联系：
- **邮箱**: cpte@163.com
- **文档**: http://wms.yourcompany.com/doc.html