python-template/CICD_DEPLOY.md

# CI/CD 部署指南

本文档介绍如何配置和使用 CI/CD 流程将 Pager 应用部署到 Kubernetes 集群，并使用 Grafana 监控。

## 📋 目录

- [环境要求](#环境要求)
- [配置步骤](#配置步骤)
- [部署流程](#部署流程)
- [监控配置](#监控配置)
- [故障排查](#故障排查)

## 🔧 环境要求

### 基础设施

- **Kubernetes 集群**: v1.24+
- **Harbor 镜像仓库**: http://192.168.1.83:8080 (admin/admin123)
- **Gitea**: http://192.168.1.83:33000
- **Namespace**: learn
- **Grafana**: 用于应用监控
- **Prometheus**: 用于指标采集

### 工具

- kubectl v1.24+
- docker 或 podman
- git

## 🚀 配置步骤

### 1. 配置 Gitea Secrets

在 Gitea 仓库中配置以下 secrets：

**路径**: http://192.168.1.83:33000/gao/pager/settings/secrets

| Secret 名称 | 说明 | 值 |
|------------|------|-----|
| `HARBOR_PASSWORD` | Harbor 密码 | `admin123` |
| `KUBECONFIG` | K8s 配置文件 (base64 编码) | 见下方说明 |

#### 生成 KUBECONFIG Secret

```bash
# 将 kubeconfig 文件编码为 base64
cat ~/.kube/config | base64 -w 0
```

将输出的 base64 字符串设置为 `KUBECONFIG` secret。

### 2. 创建 Harbor 项目

```bash
# 登录 Harbor
docker login 192.168.1.83:8080 -u admin -p admin123

# Harbor 已经自动创建 pager 项目（通过 UI 或 API）
```

或通过 Harbor UI 创建：
- 访问 http://192.168.1.83:8080
- 登录 (admin/admin123)
- 创建项目 `pager`

### 3. 配置 Kubernetes

#### 创建 Namespace 和基础资源

```bash
cd /Users/brunogao/work/codes/pingan/pager

# 创建 namespace
kubectl apply -f k8s/namespace.yaml

# 创建 secrets 和 configmap
kubectl apply -f k8s/secret.yaml
kubectl apply -f k8s/configmap.yaml

# 部署 PostgreSQL
kubectl apply -f k8s/postgres.yaml

# 等待 PostgreSQL 就绪
kubectl wait --for=condition=ready pod -l app=pager-postgres -n learn --timeout=300s
```

#### 验证基础设施

```bash
# 检查 namespace
kubectl get namespace learn

# 检查 secrets
kubectl get secret -n learn

# 检查 PostgreSQL
kubectl get pods -n learn
kubectl logs -l app=pager-postgres -n learn
```

### 4. 配置 Gitea Actions Runner

确保 Gitea Actions Runner 已配置并运行：

**查看 Runners**: http://192.168.1.83:33000/gao/pager/settings/actions/runners

如果没有 runner，需要注册一个：

```bash
# 下载 act_runner
wget https://dl.gitea.com/act_runner/0.2.6/act_runner-0.2.6-linux-amd64

# 注册 runner
./act_runner register --instance http://192.168.1.83:33000 --token YOUR_REGISTRATION_TOKEN

# 运行 runner
./act_runner daemon
```

## 📦 部署流程

### 自动部署（推荐）

当代码推送到 `master` 或 `main` 分支时，CI/CD 流程会自动触发：

```bash
git add .
git commit -m "feat: your changes"
git push origin master
```

CI/CD 流程包括：

1. **构建阶段**:
   - 构建 Backend Docker 镜像
   - 构建 Frontend Docker 镜像
   - 推送镜像到 Harbor

2. **部署阶段**:
   - 更新 K8s Deployment
   - 滚动更新应用
   - 健康检查

3. **验证阶段**:
   - 检查 Pod 状态
   - 验证服务可达性

### 手动部署

如需手动部署，可以执行：

```bash
cd k8s

# 部署应用
kubectl apply -f deployment.yaml -n learn
kubectl apply -f service.yaml -n learn
kubectl apply -f ingress.yaml -n learn

# 检查部署状态
kubectl rollout status deployment/pager-backend -n learn
kubectl rollout status deployment/pager-frontend -n learn

# 查看 Pod
kubectl get pods -n learn -l app=pager-backend
kubectl get pods -n learn -l app=pager-frontend
```

### 访问应用

添加 hosts 记录：

```bash
echo "192.168.1.83 pager.learn.local" | sudo tee -a /etc/hosts
```

访问应用：
- **前端**: http://pager.learn.local
- **后端 API**: http://pager.learn.local/api
- **API 文档**: http://pager.learn.local/api/docs

## 📊 监控配置

### 安装 ServiceMonitor

```bash
# 部署 ServiceMonitor (需要 Prometheus Operator)
kubectl apply -f k8s/monitoring/servicemonitor.yaml
```

### 安装 Grafana Dashboard

```bash
cd k8s/monitoring

# 设置 Grafana 访问信息
export GRAFANA_URL="http://grafana.your-domain.com"
export GRAFANA_USER="admin"
export GRAFANA_PASSWORD="admin"

# 安装 Dashboard
./install-dashboard.sh
```

### 监控指标

Dashboard 包含以下监控面板：

- **Backend HTTP Requests**: API 请求速率
- **Backend Response Time**: P95/P99 响应时间
- **Pod CPU Usage**: 容器 CPU 使用率
- **Pod Memory Usage**: 容器内存使用
- **Database Connections**: 数据库连接数
- **Error Rate**: 4xx/5xx 错误率
- **Pod Restart Count**: Pod 重启次数
- **Disk Usage**: 磁盘使用率

## 🔍 故障排查

### 查看日志

```bash
# Backend 日志
kubectl logs -l app=pager-backend -n learn --tail=100 -f

# Frontend 日志
kubectl logs -l app=pager-frontend -n learn --tail=100 -f

# PostgreSQL 日志
kubectl logs -l app=pager-postgres -n learn --tail=100 -f
```

### 调试 Pod

```bash
# 进入 Backend Pod
kubectl exec -it deployment/pager-backend -n learn -- /bin/bash

# 进入 PostgreSQL Pod
kubectl exec -it deployment/pager-postgres -n learn -- psql -U postgres -d wordmaster
```

### 常见问题

#### 1. 镜像拉取失败

**症状**: `ImagePullBackOff` 或 `ErrImagePull`

**解决方案**:
```bash
# 检查 secret
kubectl get secret harbor-registry -n learn -o yaml

# 重新创建 secret
kubectl delete secret harbor-registry -n learn
kubectl create secret docker-registry harbor-registry \
  --docker-server=192.168.1.83:8080 \
  --docker-username=admin \
  --docker-password=admin123 \
  --namespace=learn
```

#### 2. Pod 启动失败

**症状**: `CrashLoopBackOff`

**解决方案**:
```bash
# 查看 Pod 事件
kubectl describe pod -l app=pager-backend -n learn

# 查看日志
kubectl logs -l app=pager-backend -n learn --previous
```

#### 3. 数据库连接失败

**症状**: Backend 日志显示数据库连接错误

**解决方案**:
```bash
# 检查 PostgreSQL 是否运行
kubectl get pods -l app=pager-postgres -n learn

# 测试数据库连接
kubectl run -it --rm debug --image=postgres:15-alpine --restart=Never -n learn -- \
  psql -h pager-postgres -U postgres -d wordmaster
```

#### 4. Ingress 无法访问

**症状**: 无法通过域名访问应用

**解决方案**:
```bash
# 检查 Ingress 状态
kubectl get ingress -n learn
kubectl describe ingress pager-ingress -n learn

# 检查 Ingress Controller
kubectl get pods -n ingress-nginx
```

### 回滚部署

如果部署出现问题，可以回滚到上一个版本：

```bash
# Backend 回滚
kubectl rollout undo deployment/pager-backend -n learn

# Frontend 回滚
kubectl rollout undo deployment/pager-frontend -n learn

# 查看回滚历史
kubectl rollout history deployment/pager-backend -n learn
```

## 🔄 更新部署

### 更新环境变量

```bash
# 编辑 ConfigMap
kubectl edit configmap pager-config -n learn

# 编辑 Secret
kubectl edit secret pager-secrets -n learn

# 重启 Pod 使配置生效
kubectl rollout restart deployment/pager-backend -n learn
```

### 更新镜像

```bash
# 手动更新镜像
kubectl set image deployment/pager-backend \
  backend=192.168.1.83:8080/pager/pager-backend:new-tag \
  -n learn

# 查看更新状态
kubectl rollout status deployment/pager-backend -n learn
```

## 📈 性能优化

### 水平扩容

```bash
# 扩容 Backend
kubectl scale deployment pager-backend --replicas=3 -n learn

# 扩容 Frontend
kubectl scale deployment pager-frontend --replicas=3 -n learn

# 配置自动扩容 (HPA)
kubectl autoscale deployment pager-backend \
  --cpu-percent=70 \
  --min=2 \
  --max=10 \
  -n learn
```

### 资源调整

编辑 `k8s/deployment.yaml` 中的资源限制：

```yaml
resources:
  requests:
    memory: "512Mi"
    cpu: "500m"
  limits:
    memory: "1Gi"
    cpu: "1000m"
```

## 📝 最佳实践

1. **使用版本标签**: 避免使用 `latest` 标签，使用具体的版本号或 Git SHA
2. **健康检查**: 配置 `livenessProbe` 和 `readinessProbe`
3. **资源限制**: 设置合理的 CPU 和内存限制
4. **日志管理**: 配置日志收集和轮转
5. **备份数据库**: 定期备份 PostgreSQL 数据
6. **监控告警**: 配置 Grafana 告警规则
7. **安全加固**: 使用非 root 用户运行容器，扫描镜像漏洞

## 🆘 支持

如遇问题，请：

1. 查看 Gitea Actions 日志：http://192.168.1.83:33000/gao/pager/actions
2. 查看 Pod 日志：`kubectl logs -n learn`
3. 查看 Grafana 监控面板
4. 检查本文档的故障排查章节