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），可实现金丝雀发布

更新策略配置：

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 部署

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

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

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

使用 kubectl 直接部署

# 按顺序部署
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，需要取消注释并修改：

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

# 查看 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 文件：

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

修改应用配置

编辑 configmap.yaml 文件：

data:
  EZ_LOG_RETENTION_DAYS: "60"
  EZ_BALANCER_STATS_FLUSH_ENABLED: "true"

扩容

水平扩展 ez-api / balancer

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（单实例模式）
• 如需高可用数据库，建议使用托管数据库服务或配置主从复制

监控和日志

# 查看 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

清理

# 删除所有资源（保留 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