Cpte-Boot/k8s/README.md

# CPTE WMS KubeSphere 部署指南

本文档详细说明如何将 CPTE WMS 系统部署到 KubeSphere/Kubernetes 环境。

## 目录

- [环境要求](#环境要求)
- [架构概览](#架构概览)
- [部署步骤](#部署步骤)
- [配置说明](#配置说明)
- [常见问题](#常见问题)

---

## 环境要求

### 服务器要求

| 组件 | 最低配置 | 推荐配置 |
|------|---------|---------|
| CPU | 4核 | 8核+ |
| 内存 | 16GB | 32GB+ |
| 存储 | 100GB | 500GB+ SSD |

### 软件要求

- Kubernetes 1.20+
- KubeSphere 3.3+
- Docker 20.10+
- kubectl 命令行工具
- Helm 3.0+ (可选)

### 存储类要求

确保 Kubernetes 集群有可用的 StorageClass，用于持久化存储：

```bash
kubectl get storageclass
```

如果没有默认存储类，需要先创建。KubeSphere 默认提供 `local` 存储类。

---

## 架构概览

### 服务架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        Ingress (Nginx)                          │
│                    wms.yourdomain.com                           │
└─────────────────────────────────────────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
        ▼                       ▼                       ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│ cpte-wms-     │     │ cpte-wms-     │     │ cpte-wms-     │
│ system        │     │ basic         │     │ inbound       │
│ (8000)        │     │ (8001)        │     │ (8002)        │
│ 系统主服务     │     │ 基础服务       │     │ 入库服务       │
└───────────────┘     └───────────────┘     └───────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
        ▼                       ▼                       ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│ cpte-wms-     │     │ cpte-wms-     │     │ cpte-wms-     │
│ outbound      │     │ inventory     │     │ schedule      │
│ (8003)        │     │ (8004)        │     │ (8005)        │
│ 出库服务       │     │ 库存服务       │     │ 调度服务       │
└───────────────┘     └───────────────┘     └───────────────┘
        │                       │                       │
        └───────────────────────┼───────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    │                       │
                    ▼                       ▼
            ┌───────────────┐     ┌───────────────┐
            │ mysql-service │     │ redis-service │
            │ (3306)        │     │ (6379)        │
            │ NodePort:30926│     │ NodePort:30899│
            └───────────────┘     └───────────────┘
                    │
                    ▼
            ┌───────────────┐
            │ nginx-service │
            │ (80)          │
            │ NodePort:30575│
            └───────────────┘
```

### 文件结构

```
k8s/
├── namespace.yaml                    # 命名空间定义
├── configmap/
│   └── application-config.yaml       # 应用配置
├── secrets/
│   └── application-secrets.yaml      # 敏感信息配置
├── manifests/
│   ├── mysql.yaml                    # MySQL 部署
│   ├── redis.yaml                    # Redis 部署 (Service: redis-service, NodePort: 30899)
│   └── nginx.yaml                    # Nginx 部署 (Service: nginx-service, NodePort: 30575)
├── services/
│   ├── system-service.yaml           # 系统主服务
│   ├── basic-service.yaml            # 基础服务
│   ├── inbound-service.yaml          # 入库服务
│   ├── outbound-service.yaml         # 出库服务
│   ├── inventory-service.yaml        # 库存服务
│   └── schedule-service.yaml         # 调度服务
├── ingress/
│   └── ingress.yaml                  # Ingress 路由配置
└── scripts/
    ├── build-images.sh               # Linux 构建脚本
    ├── build-images.bat              # Windows 构建脚本
    ├── deploy.sh                     # Linux 部署脚本
    └── deploy.bat                    # Windows 部署脚本
```

---

## 部署步骤

### 第一步：准备工作

#### 1.1 克隆项目到服务器

```bash
# 在服务器上
git clone <your-repo-url>
cd Cpte-Boot
```

#### 1.2 配置域名和密钥

编辑 `k8s/secrets/application-secrets.yaml`，修改以下敏感信息：

```yaml
stringData:
  DB_USERNAME: "root"
  DB_PASSWORD: "your_secure_password"      # 修改为安全密码
  REDIS_PASSWORD: ""                        # 如需密码认证
  SIGNATURE_SECRET: "your_signature_key"   # 修改签名密钥
```

编辑 `k8s/ingress/ingress.yaml`，修改域名：

```yaml
spec:
  rules:
  - host: wms.yourdomain.com  # 修改为你的域名
```

#### 1.3 配置 DNS 解析

在域名服务商处配置 DNS 解析，将域名指向 Kubernetes 集群的 Ingress IP：

```bash
# 获取 Ingress IP
kubectl get svc -n ingress-nginx
```

### 第二步：构建 Docker 镜像

#### 方式一：在开发机构建后推送

```bash
# Windows
k8s\scripts\build-images.bat 3.8.3 your-registry.com

# Linux/Mac
chmod +x k8s/scripts/build-images.sh
./k8s/scripts/build-images.sh 3.8.3 your-registry.com

# 推送镜像
docker push your-registry.com/cpte-wms-system:3.8.3
docker push your-registry.com/cpte-wms-basic:3.8.3
docker push your-registry.com/cpte-wms-inbound:3.8.3
docker push your-registry.com/cpte-wms-outbound:3.8.3
docker push your-registry.com/cpte-wms-inventory:3.8.3
docker push your-registry.com/cpte-wms-schedule:3.8.3
```

#### 方式二：在服务器本地构建

```bash
# 在服务器上执行
cd Cpte-Boot
./k8s/scripts/build-images.sh
```

### 第三步：部署到 Kubernetes

#### 方式一：使用部署脚本

```bash
# Linux/Mac
chmod +x k8s/scripts/deploy.sh
./k8s/scripts/deploy.sh cpte-wms

# Windows
k8s\scripts\deploy.bat cpte-wms
```

#### 方式二：手动部署

```bash
# 1. 创建命名空间
kubectl apply -f k8s/namespace.yaml

# 2. 创建 Secrets 和 ConfigMaps
kubectl apply -f k8s/secrets/application-secrets.yaml
kubectl apply -f k8s/configmap/application-config.yaml

# 3. 部署中间件
kubectl apply -f k8s/manifests/mysql.yaml
kubectl apply -f k8s/manifests/redis.yaml
kubectl apply -f k8s/manifests/nginx.yaml

# 4. 等待中间件就绪
kubectl wait --for=condition=ready pod -l app=cpte-wms-mysql -n cpte-wms --timeout=300s
kubectl wait --for=condition=ready pod -l app=redis -n cpte-wms --timeout=300s
kubectl wait --for=condition=ready pod -l app=nginx -n cpte-wms --timeout=300s

# 5. 部署应用服务
kubectl apply -f k8s/services/system-service.yaml
kubectl apply -f k8s/services/basic-service.yaml
kubectl apply -f k8s/services/inbound-service.yaml
kubectl apply -f k8s/services/outbound-service.yaml
kubectl apply -f k8s/services/inventory-service.yaml
kubectl apply -f k8s/services/schedule-service.yaml

# 6. 创建 Ingress
kubectl apply -f k8s/ingress/ingress.yaml
```

### 第四步：验证部署

```bash
# 查看所有 Pod 状态
kubectl get pods -n cpte-wms

# 查看服务状态
kubectl get svc -n cpte-wms

# 查看 Ingress
kubectl get ingress -n cpte-wms

# 查看日志
kubectl logs -f deployment/cpte-wms-system -n cpte-wms
```

### 第五步：初始化数据库

首次部署需要初始化数据库：

```bash
# 进入 MySQL Pod
kubectl exec -it -n cpte-wms $(kubectl get pod -n cpte-wms -l app=cpte-wms-mysql -o jsonpath='{.items[0].metadata.name}') -- mysql -uroot -p

# 或者使用 port-forward
kubectl port-forward svc/cpte-wms-mysql 3306:3306 -n cpte-wms

# 使用数据库客户端连接并执行 SQL 脚本
# SQL 脚本位于项目的 db 目录
```

---

## KubeSphere 控制台操作

### 通过 KubeSphere 控制台部署

#### 1. 创建项目

1. 登录 KubeSphere 控制台
2. 进入「应用负载」→「项目」
3. 点击「创建」，输入项目名称 `cpte-wms`

#### 2. 创建配置

1. 进入项目 `cpte-wms`
2. 点击「配置」→「配置字典」→「创建」
3. 上传 `k8s/configmap/application-config.yaml`

#### 3. 创建密钥

1. 点击「配置」→「密钥」→「创建」
2. 上传 `k8s/secrets/application-secrets.yaml`

#### 4. 创建应用负载

1. 点击「应用负载」→「工作负载」→「创建」
2. 选择「部署」，依次创建各服务

#### 5. 创建服务

1. 点击「应用负载」→「服务」→「创建」
2. 配置服务端口映射

#### 6. 创建应用路由

1. 点击「应用负载」→「应用路由」→「创建」
2. 配置域名和路由规则

### 使用 KubeSphere 应用商店

如果配置了应用商店，可以直接使用 Helm Chart 部署。

---

## 配置说明

### 环境变量说明

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| SPRING_PROFILES_ACTIVE | Spring 配置环境 | k8s |
| DB_HOST | 数据库主机 | cpte-wms-mysql |
| DB_PORT | 数据库端口 | 3306 |
| DB_NAME | 数据库名称 | cpte-wms |
| DB_USERNAME | 数据库用户名 | root |
| DB_PASSWORD | 数据库密码 | - |
| REDIS_HOST | Redis 主机 | redis-service |
| REDIS_PORT | Redis 端口 | 6379 |
| REDIS_PASSWORD | Redis 密码 | - |

### 资源配置调整

根据实际负载调整各服务的资源配置：

```yaml
resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "1Gi"
    cpu: "1000m"
```

### 副本数调整

修改 `replicas` 字段调整副本数：

```yaml
spec:
  replicas: 2  # 调整副本数
```

---

## 常见问题

### Q1: Pod 一直处于 Pending 状态

**原因**：可能是存储类不存在或资源不足

**解决**：
```bash
# 检查存储类
kubectl get storageclass

# 检查事件
kubectl describe pod <pod-name> -n cpte-wms
```

### Q2: 服务无法启动

**原因**：可能是数据库未就绪或配置错误

**解决**：
```bash
# 查看日志
kubectl logs <pod-name> -n cpte-wms

# 检查数据库连接
kubectl exec -it <mysql-pod> -n cpte-wms -- mysql -uroot -p
```

### Q3: Ingress 无法访问

**原因**：可能是 Ingress Controller 未安装或域名解析问题

**解决**：
```bash
# 检查 Ingress Controller
kubectl get svc -n ingress-nginx

# 检查 Ingress 状态
kubectl describe ingress -n cpte-wms
```

### Q4: 镜像拉取失败

**原因**：镜像不存在或仓库认证问题

**解决**：
```bash
# 创建镜像拉取密钥
kubectl create secret docker-registry regcred \
  --docker-server=<your-registry> \
  --docker-username=<username> \
  --docker-password=<password> \
  -n cpte-wms

# 在 Deployment 中添加 imagePullSecrets
```

### Q5: 数据库连接超时

**原因**：MySQL 未完全启动

**解决**：检查 initContainers 是否正常等待 MySQL 就绪

---

## 运维命令

### 日常运维

```bash
# 查看所有资源状态
kubectl get all -n cpte-wms

# 重启服务
kubectl rollout restart deployment/cpte-wms-system -n cpte-wms

# 扩缩容
kubectl scale deployment/cpte-wms-system --replicas=3 -n cpte-wms

# 查看资源使用
kubectl top pods -n cpte-wms

# 进入容器
kubectl exec -it <pod-name> -n cpte-wms -- /bin/sh
```

### 备份与恢复

```bash
# 备份 MySQL
kubectl exec -n cpte-wms <mysql-pod> -- mysqldump -uroot -p cpte-wms > backup.sql

# 备份 PVC
kubectl get pvc -n cpte-wms -o yaml > pvc-backup.yaml
```

### 日志查看

```bash
# 查看服务日志
kubectl logs -f deployment/cpte-wms-system -n cpte-wms

# 查看最近 100 行日志
kubectl logs --tail=100 deployment/cpte-wms-system -n cpte-wms

# 查看所有容器日志
kubectl logs -f deployment/cpte-wms-system -n cpte-wms --all-containers
```

---

## 联系支持

如有问题，请联系：
- 邮箱：cpte@163.com
- 网站：http://www.cpte.com