bigscreen/DEVOPS_QUICKSTART.md

FastAPI Template DevOps 快速开始

目录

• 环境准备
• 本地开发
• Docker 部署
• Kubernetes 部署
• CI/CD 配置
• 常见问题

环境准备

1. 基础环境要求

• 操作系统: macOS (M2 Ultra) / Linux / Windows WSL2
• Python: 3.11+
• Node.js: 20+
• Docker: 最新版 (通过 OrbStack 运行)
• Kubernetes: 可选，用于生产部署

2. 本地镜像服务

确保以下服务正在运行：

# Gitea (代码仓库)
http://localhost:33000

# 业务镜像仓库
http://localhost:5000

# 基础镜像缓存
http://localhost:5001

3. 配置依赖镜像源

首次使用前，配置 pip 和 npm 镜像源以加速下载：

# 运行依赖缓存配置脚本
./scripts/setup-dependencies-cache.sh

这将配置：

• pip: 中科大 PyPI 镜像 (https://pypi.mirrors.ustc.edu.cn/simple/)
• npm: 淘宝镜像 (https://registry.npmmirror.com)

本地开发

方法 1: 一键启动脚本（推荐）

# 一键启动前后端服务
./start_app.sh

脚本功能：

• ✅ 自动创建/激活 Python 虚拟环境
• ✅ 智能安装/更新依赖（仅在文件变化时）
• ✅ 同时启动后端和前端
• ✅ 健康检查和错误处理
• ✅ 优雅关闭（Ctrl+C）

启动后访问：

• 前端: http://localhost:6115
• API 文档: http://localhost:5115/docs
• 健康检查: http://localhost:5115/api/v1/health/

方法 2: 手动启动

后端

cd backend

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 配置数据库等信息

# 启动服务
python run.py

前端

cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev

停止服务

如果使用 start_app.sh，直接按 Ctrl+C 停止所有服务。

手动启动的服务需要分别在各终端按 Ctrl+C 停止。

Docker 部署

1. 构建镜像

# 构建并推送到本地镜像仓库
./build-and-push.sh v1.0.0 --push

# 仅构建后端
./build-and-push.sh v1.0.0 --backend-only --push

# 不使用缓存构建
./build-and-push.sh v1.0.0 --no-cache --push

2. 使用 Docker Compose 部署

# 复制环境配置
cp .env.prod.example .env.prod

# 编辑配置文件（重要：修改数据库密码和 SECRET_KEY）
vim .env.prod

# 启动所有服务
docker-compose -f docker-compose.prod.yml --env-file .env.prod up -d

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

# 停止服务
docker-compose -f docker-compose.prod.yml down

服务包括：

• Backend (FastAPI)
• Frontend (Vue 3 + Nginx)
• PostgreSQL
• Redis
• Nginx (反向代理)

访问地址：

• 应用: http://localhost (Nginx)
• 后端 API: http://localhost:5115
• 前端: http://localhost:6115

3. 数据库初始化

# 进入后端容器
docker exec -it fastapi-backend bash

# 运行数据库迁移
alembic upgrade head

# 初始化数据
python scripts/init_data.py

Kubernetes 部署

1. 前置准备

确保 kubectl 已配置并能连接到集群：

kubectl cluster-info

2. 配置环境变量

开发环境：

# 创建开发环境配置
cp .env.k8s.dev.example .env.k8s.dev

# 编辑配置
vim .env.k8s.dev

生产环境：

# 创建生产环境配置
cp .env.k8s.prod.example .env.k8s.prod

# 编辑配置（务必修改所有密码和密钥）
vim .env.k8s.prod

3. 部署应用

开发环境：

./deploy_k8s.sh dev v1.0.0

生产环境：

./deploy_k8s.sh prod v1.0.0

4. 验证部署

# 查看 Pods 状态
kubectl get pods -n fastapi-template-dev

# 查看服务
kubectl get svc -n fastapi-template-dev

# 查看 Ingress
kubectl get ingress -n fastapi-template-dev

# 查看日志
kubectl logs -f deployment/backend -n fastapi-template-dev

5. 端口转发（本地访问）

# 转发后端服务
kubectl port-forward svc/backend-service 8000:8000 -n fastapi-template-dev

# 转发前端服务
kubectl port-forward svc/frontend-service 8080:80 -n fastapi-template-dev

6. 删除部署

# 删除整个命名空间（包括所有资源）
kubectl delete namespace fastapi-template-dev

CI/CD 配置

1. Gitea Actions 设置

安装 Gitea Actions Runner

# 下载 act_runner
wget https://dl.gitea.com/act_runner/latest/act_runner-latest-linux-amd64

# 赋予执行权限
chmod +x act_runner-latest-linux-amd64
mv act_runner-latest-linux-amd64 /usr/local/bin/act_runner

# 注册 runner
act_runner register --instance http://localhost:33000 --token YOUR_RUNNER_TOKEN

# 启动 runner
act_runner daemon

配置 Secrets

在 Gitea 项目设置中配置以下 Secrets：

开发环境:

• KUBECONFIG_DEV: K8s 开发环境配置
• DEV_DATABASE_NAME: 数据库名
• DEV_DATABASE_USER: 数据库用户
• DEV_DATABASE_PASSWORD: 数据库密码
• DEV_REDIS_PASSWORD: Redis 密码
• DEV_SECRET_KEY: JWT 密钥

生产环境:

• KUBECONFIG_PROD: K8s 生产环境配置
• PROD_DATABASE_NAME: 数据库名
• PROD_DATABASE_USER: 数据库用户
• PROD_DATABASE_PASSWORD: 数据库密码
• PROD_REDIS_PASSWORD: Redis 密码
• PROD_SECRET_KEY: JWT 密钥

邮件通知:

• SMTP_PASSWORD: QQ 邮箱授权码

2. 工作流说明

CI 工作流 (.gitea/workflows/ci.yaml)

触发条件：

• 推送到 main 或 develop 分支
• 创建 Pull Request

执行内容：

• Python 代码检查 (black, ruff, mypy)
• 单元测试 + 覆盖率报告
• Frontend 代码检查和构建测试

构建工作流 (.gitea/workflows/build-and-push.yaml)

触发条件：

• 推送到 main 分支
• 创建 tag (v*)

执行内容：

• 构建后端和前端 Docker 镜像
• 推送到本地镜像仓库 (localhost:5000)
• 可选：镜像安全扫描

部署工作流 (.gitea/workflows/deploy.yaml)

触发条件：

• 推送到 main 分支（自动部署到开发环境）
• 手动触发（可选择环境和版本）

执行内容：

• 部署到 K8s 集群
• 健康检查
• 发送部署通知

3. 配置邮件通知

# 复制邮件配置示例
cp .env.email.example .env.email

# 编辑邮件配置
vim .env.email

配置说明：

# QQ 邮箱配置
SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_USER=38455629@qq.com
SMTP_PASSWORD=your-qq-authorization-code  # QQ 邮箱授权码，非登录密码

FROM_EMAIL=38455629@qq.com
TO_EMAILS=38455629@qq.com

获取 QQ 邮箱授权码：

1. 登录 QQ 邮箱
2. 设置 → 账户 → POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务
3. 开启"POP3/SMTP服务"或"IMAP/SMTP服务"
4. 生成授权码（16位字符）
5. 将授权码填入 SMTP_PASSWORD

测试邮件发送：

# 设置环境变量
export $(grep -v '^#' .env.email | xargs)

# 测试发送
python scripts/send-test-report-email.py backend/reports/

4. 查看测试报告

测试报告会自动上传到 Gitea Actions Artifacts：

1. 进入 Actions 页面
2. 点击对应的 workflow run
3. 下载 backend-test-reports artifact
4. 解压查看 HTML 报告

常见问题

1. pip 安装依赖很慢

确认已配置中科大镜像源：

pip config get global.index-url
# 应该输出: https://pypi.mirrors.ustc.edu.cn/simple/

如果没有配置，运行：

./scripts/setup-dependencies-cache.sh

2. npm 安装依赖失败

使用淘宝镜像：

npm config set registry https://registry.npmmirror.com
npm install

3. Docker 构建镜像失败

检查镜像仓库是否运行：

curl http://localhost:5000/v2/_catalog
curl http://localhost:5001/v2/_catalog

4. K8s 部署后 Pod 无法启动

查看 Pod 事件：

kubectl describe pod <pod-name> -n fastapi-template-dev

常见原因：

• 镜像拉取失败：检查镜像仓库连接
• 配置错误：检查 ConfigMap 和 Secret
• 资源不足：检查节点资源

5. 数据库连接失败

检查数据库配置：

# 查看环境变量
kubectl get configmap fastapi-config -n fastapi-template-dev -o yaml
kubectl get secret fastapi-secret -n fastapi-template-dev -o yaml

6. Gitea Actions 不执行

检查：

1. Runner 是否在线（Gitea 管理界面）
2. 工作流文件语法是否正确
3. 查看 Actions 日志

7. 邮件发送失败

检查：

1. SMTP 配置是否正确
2. QQ 邮箱授权码是否有效
3. 网络是否可以访问 smtp.qq.com:587

调试命令：

telnet smtp.qq.com 587

8. 镜像缓存不生效

Docker 配置镜像代理：

OrbStack 用户：

1. 打开 OrbStack 设置
2. Docker → Registry Mirrors
3. 添加: http://localhost:5001

9. 虚拟环境激活失败

# 删除旧的虚拟环境
rm -rf backend/venv

# 重新创建
python3 -m venv backend/venv
source backend/venv/bin/activate

10. 端口被占用

查找并杀死占用端口的进程：

# 查找占用端口 5115 的进程
lsof -ti:5115

# 杀死进程
lsof -ti:5115 | xargs kill -9

进阶配置

1. 自定义域名

修改 K8s Ingress 配置：

# 编辑 .env.k8s.dev
DOMAIN=dev.myapp.com

# 重新部署
./deploy_k8s.sh dev

2. HTTPS 配置

使用 cert-manager 自动签发证书：

# 安装 cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# 编辑 k8s/ingress.yaml 启用 TLS 部分
# 重新部署

3. 监控和日志

推荐使用：

• Prometheus + Grafana: 监控指标
• ELK Stack: 日志收集和分析
• Jaeger: 分布式追踪

4. 数据库备份

自动备份脚本：

# 创建备份
kubectl exec -n fastapi-template-prod deployment/postgres -- \
    pg_dump -U postgres template_prod > backup-$(date +%Y%m%d).sql

# 恢复备份
kubectl exec -i -n fastapi-template-prod deployment/postgres -- \
    psql -U postgres template_prod < backup-20251201.sql

下一步

• 配置生产环境监控
• 设置自动化备份
• 实现蓝绿部署
• 配置告警系统
• 性能优化和压测

获取帮助

• 查看详细文档: DEVOPS_SOLUTION.md
• 项目架构: CLAUDE.md
• Issues: http://localhost:33000/your-org/fastapi-template/issues