Roog (顾新培)
73bd66813c
变更内容： - 添加 Kubernetes 部署配置文件，包括 API Deployment、Worker Deployment 和 Redis Deployment。 - 新增 Service 定义，支持 API、Metrics 和 Redis 的集群访问。 - 配置 ConfigMap，用于全局共享环境变量。 - 编写 Kubernetes 部署指南文档，包含快速部署步骤、建议配置及故障排查方法。 - 提升系统的可扩展性和容器编排能力，适配生产环境使用。
307 lines
7.6 KiB
Markdown
307 lines
7.6 KiB
Markdown
# 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) |