# 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