FunctionalScaffold/docs/kubernetes-deployment.md

Kubernetes 部署指南

本文档介绍如何在 Kubernetes 集群中部署 FunctionalScaffold 服务。

架构概览

                    ┌─────────────────┐
                    │   Ingress/LB    │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   API Service   │
                    │   (ClusterIP)   │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
       ┌──────▼──────┐ ┌─────▼─────┐ ┌─────▼─────┐
       │  API Pod 1  │ │ API Pod 2 │ │ API Pod 3 │
       └─────────────┘ └───────────┘ └───────────┘
                             │
                    ┌────────▼────────┐
                    │  Redis Service  │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
       ┌──────▼──────┐ ┌─────▼─────┐        │
       │ Worker Pod 1│ │Worker Pod2│        │
       └─────────────┘ └───────────┘        │
                                     ┌──────▼──────┐
                                     │  Redis Pod  │
                                     └─────────────┘

组件说明

组件	副本数	说明
API Deployment	3	HTTP 服务，处理同步请求和任务创建
Worker Deployment	2	异步任务处理，从 Redis 队列消费任务
Redis Deployment	1	任务队列和状态存储
ConfigMap	-	共享配置管理

快速部署

# 部署所有资源
kubectl apply -f deployment/kubernetes/deployment.yaml
kubectl apply -f deployment/kubernetes/service.yaml

# 查看部署状态
kubectl get pods -l app=functional-scaffold
kubectl get svc -l app=functional-scaffold

配置文件说明

deployment.yaml

包含以下资源：

ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: functional-scaffold-config
data:
  APP_ENV: "production"
  LOG_LEVEL: "INFO"
  REDIS_HOST: "functional-scaffold-redis"
  # ... 更多配置

主要配置项：

配置项	默认值	说明
APP_ENV	production	运行环境
LOG_LEVEL	INFO	日志级别
REDIS_HOST	functional-scaffold-redis	Redis 服务地址
MAX_CONCURRENT_JOBS	10	最大并发任务数
JOB_EXECUTION_TIMEOUT	300	任务执行超时（秒）

API Deployment

• 副本数: 3
• 资源限制: 256Mi-512Mi 内存，250m-500m CPU
• 健康检查: /healthz（存活）、/readyz（就绪）
• 环境变量: RUN_MODE=api

Worker Deployment

• 副本数: 2
• 资源限制: 256Mi-512Mi 内存，250m-500m CPU
• 健康检查: exec 探针检查 Redis 连接
• 环境变量: RUN_MODE=worker

Redis Deployment

• 副本数: 1
• 资源限制: 128Mi-256Mi 内存，100m-200m CPU
• 持久化: AOF 模式（appendonly yes）
• 存储: emptyDir（开发环境）

service.yaml

Service	类型	端口	说明
functional-scaffold-api	ClusterIP	80 → 8000	API 服务
functional-scaffold-metrics	ClusterIP	8000	Prometheus 指标
functional-scaffold-redis	ClusterIP	6379	Redis 服务

生产环境建议

1. 使用外部 Redis

生产环境建议使用托管 Redis 服务（如阿里云 Redis、AWS ElastiCache）：

# 修改 ConfigMap
data:
  REDIS_HOST: "r-xxxxx.redis.rds.aliyuncs.com"
  REDIS_PORT: "6379"
  REDIS_PASSWORD: ""  # 使用 Secret 管理

2. 使用 Secret 管理敏感信息

apiVersion: v1
kind: Secret
metadata:
  name: functional-scaffold-secrets
type: Opaque
stringData:
  REDIS_PASSWORD: "your-password"
  DATABASE_URL: "postgresql://..."

在 Deployment 中引用：

envFrom:
- configMapRef:
    name: functional-scaffold-config
- secretRef:
    name: functional-scaffold-secrets

3. 配置 HPA 自动扩缩容

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: functional-scaffold-api-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: functional-scaffold-api
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

4. 配置 PDB 保证可用性

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: functional-scaffold-api-pdb
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: functional-scaffold
      component: api

5. 使用 PVC 持久化 Redis 数据

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: redis-data-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi

监控集成

Prometheus 抓取配置

functional-scaffold-metrics Service 已添加 Prometheus 注解：

annotations:
  prometheus.io/scrape: "true"
  prometheus.io/port: "8000"
  prometheus.io/path: "/metrics"

ServiceMonitor（如使用 Prometheus Operator）

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: functional-scaffold
spec:
  selector:
    matchLabels:
      app: functional-scaffold
      component: api
  endpoints:
  - port: metrics
    path: /metrics
    interval: 30s

常用命令

# 查看所有资源
kubectl get all -l app=functional-scaffold

# 查看 Pod 日志
kubectl logs -l app=functional-scaffold,component=api -f
kubectl logs -l app=functional-scaffold,component=worker -f

# 扩缩容
kubectl scale deployment functional-scaffold-api --replicas=5
kubectl scale deployment functional-scaffold-worker --replicas=3

# 滚动更新
kubectl set image deployment/functional-scaffold-api \
  api=functional-scaffold:v2.0.0

# 回滚
kubectl rollout undo deployment/functional-scaffold-api

# 查看部署历史
kubectl rollout history deployment/functional-scaffold-api

# 进入 Pod 调试
kubectl exec -it <pod-name> -- /bin/sh

# 端口转发（本地调试）
kubectl port-forward svc/functional-scaffold-api 8000:80

故障排查

Pod 启动失败

# 查看 Pod 事件
kubectl describe pod <pod-name>

# 查看 Pod 日志
kubectl logs <pod-name> --previous

Redis 连接失败

# 检查 Redis Service
kubectl get svc functional-scaffold-redis

# 测试 Redis 连接
kubectl run redis-test --rm -it --image=redis:7-alpine -- \
  redis-cli -h functional-scaffold-redis ping

Worker 不消费任务

# 检查 Worker 日志
kubectl logs -l component=worker -f

# 检查 Redis 队列
kubectl exec -it <redis-pod> -- redis-cli LLEN job:queue

相关文档

• 快速入门
• 监控指南
• 并发控制
• 日志集成