522 lines
13 KiB
Markdown
522 lines
13 KiB
Markdown
# 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
|