ljwx-study/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

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

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

2. 创建 Harbor 项目

# 登录 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 和基础资源

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

验证基础设施

# 检查 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，需要注册一个：

# 下载 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 流程会自动触发：

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 状态
   • 验证服务可达性

手动部署

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

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 记录：

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

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

安装 Grafana Dashboard

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: 磁盘使用率

🔍 故障排查

查看日志

# 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

# 进入 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

解决方案:

# 检查 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

解决方案:

# 查看 Pod 事件
kubectl describe pod -l app=pager-backend -n learn

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

3. 数据库连接失败

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

解决方案:

# 检查 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 无法访问

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

解决方案:

# 检查 Ingress 状态
kubectl get ingress -n learn
kubectl describe ingress pager-ingress -n learn

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

回滚部署

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

# 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

🔄 更新部署

更新环境变量

# 编辑 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

更新镜像

# 手动更新镜像
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

📈 性能优化

水平扩容

# 扩容 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 中的资源限制：

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. 检查本文档的故障排查章节