ez-api/test/k8s/README.md

# EZ-API Kubernetes Deployment

## 目录结构

```
k8s/
├── namespace.yaml      # 命名空间定义
├── configmap.yaml      # 配置映射
├── secret.yaml         # 敏感信息（密码、Token等）
├── postgres.yaml       # 主数据库 StatefulSet + Headless Service
├── log-postgres.yaml   # 日志数据库 StatefulSet + Headless Service
├── redis.yaml          # Redis StatefulSet + Headless Service
├── ez-api.yaml         # ez-api Deployment + LoadBalancer Service
├── balancer.yaml       # balancer Deployment + LoadBalancer Service
├── kustomization.yaml  # Kustomize 配置文件
└── README.md           # 本文档
```

## 架构说明

### 有状态服务（StatefulSet）

**PostgreSQL 和 Redis 使用 StatefulSet 的原因：**

1. **稳定的网络标识**：Pod 名称固定（如 `postgres-0`），DNS 可预测
2. **有序部署和扩展**：Pod 按顺序创建和删除
3. **稳定的持久化存储**：每个 Pod 有自己的 PVC，Pod 重建后数据保留
4. **更新策略控制**：支持分区更新（Partition），可实现金丝雀发布

**更新策略配置：**

```yaml
updateStrategy:
  type: RollingUpdate
  rollingUpdate:
    partition: 0  # 0 表示全部更新，设置为 N 表示只更新 ordinal >= N 的 Pod
```

- `partition: 0` - 所有 Pod 都会更新（默认行为）
- `partition: 1` - 只有 ordinal >= 1 的 Pod 会更新，ordinal=0 保持不变（金丝雀发布）

### 无状态服务（Deployment）

**ez-api 和 balancer 使用 Deployment 的原因：**

1. 无需持久化存储（状态存储在数据库/Redis）
2. 可以快速水平扩展
3. 支持滚动更新和回滚

## 部署方式

### 使用 Kustomize 部署

```bash
# 预览生成的 YAML
kubectl kustomize ez-api/test/k8s/

# 部署到集群
kubectl apply -k ez-api/test/k8s/

# 查看部署状态
kubectl get all -n ez-api-test-dev
```

### 使用 kubectl 直接部署

```bash
# 按顺序部署
kubectl apply -f ez-api/test/k8s/namespace.yaml
kubectl apply -f ez-api/test/k8s/configmap.yaml
kubectl apply -f ez-api/test/k8s/secret.yaml
kubectl apply -f ez-api/test/k8s/postgres.yaml
kubectl apply -f ez-api/test/k8s/log-postgres.yaml
kubectl apply -f ez-api/test/k8s/redis.yaml
kubectl apply -f ez-api/test/k8s/ez-api.yaml
kubectl apply -f ez-api/test/k8s/balancer.yaml
```

## 存储配置

### PVC 持久化卷

| 服务 | 存储大小 | 用途 |
|------|---------|------|
| postgres | 50Gi | 主数据库数据 |
| log-postgres | 100Gi | 日志数据库（数据量较大） |
| redis | 10Gi | Redis AOF 持久化 |

### 修改 StorageClass

如果集群使用特定的 StorageClass，需要取消注释并修改：

```yaml
volumeClaimTemplates:
  - metadata:
      name: postgres-data
    spec:
      accessModes: ["ReadWriteOnce"]
      storageClassName: "your-storage-class"  # 取消注释并修改
      resources:
        requests:
          storage: 50Gi
```

## 服务访问

### LoadBalancer 服务

| 服务 | 端口 | 类型 |
|------|------|------|
| ez-api | 8080 | LoadBalancer |
| balancer | 8081 | LoadBalancer |

### 获取外部 IP

```bash
# 查看 Service 状态
kubectl get svc -n ez-api-test-dev

# 等待 LoadBalancer 分配 IP
kubectl get svc ez-api -n ez-api-test-dev -w
kubectl get svc balancer -n ez-api-test-dev -w
```

## 配置修改

### 修改密码和 Token

编辑 [`secret.yaml`](ez-api/test/k8s/secret.yaml) 文件：

```yaml
stringData:
  POSTGRES_PASSWORD: "your-secure-password"
  EZ_ADMIN_TOKEN: "your-secure-token"
```

### 修改应用配置

编辑 [`configmap.yaml`](ez-api/test/k8s/configmap.yaml) 文件：

```yaml
data:
  EZ_LOG_RETENTION_DAYS: "60"
  EZ_BALANCER_STATS_FLUSH_ENABLED: "true"
```

## 扩容

### 水平扩展 ez-api / balancer

```bash
kubectl scale deployment ez-api --replicas=3 -n ez-api-test-dev
kubectl scale deployment balancer --replicas=3 -n ez-api-test-dev
```

### 注意事项

- PostgreSQL 和 Redis 的 StatefulSet 副本数保持为 1（单实例模式）
- 如需高可用数据库，建议使用托管数据库服务或配置主从复制

## 监控和日志

```bash
# 查看 Pod 日志
kubectl logs -f deployment/ez-api -n ez-api-test-dev
kubectl logs -f deployment/balancer -n ez-api-test-dev

# 查看 StatefulSet 日志
kubectl logs -f statefulset/postgres -n ez-api-test-dev
kubectl logs -f statefulset/redis -n ez-api-test-dev

# 进入 Pod 调试
kubectl exec -it postgres-0 -n ez-api-test-dev -- psql -U postgres -d ezapi
kubectl exec -it redis-0 -n ez-api-test-dev -- redis-cli
```

## 清理

```bash
# 删除所有资源（保留 PVC）
kubectl delete -k ez-api/test/k8s/

# 删除 PVC（会删除数据！）
kubectl delete pvc -l app.kubernetes.io/name=ez-api-test-dev -n ez-api-test-dev

# 删除命名空间（会删除所有资源和数据！）
kubectl delete namespace ez-api-test-dev
```