main:新增 Kubernetes 部署配置及文档
变更内容： - 添加 Kubernetes 部署配置文件，包括 API Deployment、Worker Deployment 和 Redis Deployment。 - 新增 Service 定义，支持 API、Metrics 和 Redis 的集群访问。 - 配置 ConfigMap，用于全局共享环境变量。 - 编写 Kubernetes 部署指南文档，包含快速部署步骤、建议配置及故障排查方法。 - 提升系统的可扩展性和容器编排能力，适配生产环境使用。
This commit is contained in:
307
docs/kubernetes-deployment.md
Normal file
307
docs/kubernetes-deployment.md
Normal file
@@ -0,0 +1,307 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user