# 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** | - | 共享配置管理 |

## 快速部署

```bash
# 部署所有资源
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

```yaml
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）：

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

### 2. 使用 Secret 管理敏感信息

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

在 Deployment 中引用：

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

### 3. 配置 HPA 自动扩缩容

```yaml
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 保证可用性

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

### 5. 使用 PVC 持久化 Redis 数据

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

## 监控集成

### Prometheus 抓取配置

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

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

### ServiceMonitor（如使用 Prometheus Operator）

```yaml
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
```

## 常用命令

```bash
# 查看所有资源
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 启动失败

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

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

### Redis 连接失败

```bash
# 检查 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 不消费任务

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

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

## 相关文档

- [快速入门](getting-started.md)
- [监控指南](monitoring.md)
- [并发控制](concurrency-control.md)
- [日志集成](loki-quick-reference.md)