fastapi-template/README_DEVOPS.md

FastAPI Template - DevOps 完整解决方案

概述

本项目是一个企业级 FastAPI + Vue3 模板，提供完整的 DevOps 解决方案，支持本地开发、Docker 部署和 Kubernetes 生产环境部署。

核心特性

✅ 三种部署方式

• 本地一键启动 (start_app.sh)
• Docker Compose 容器化部署
• Kubernetes 生产环境部署

✅ 完整的 CI/CD

• Gitea Actions 自动化流程
• 代码质量检查 (lint, format, type check)
• 自动化测试 + 覆盖率报告
• 自动构建和推送镜像
• 自动部署到 K8s

✅ 依赖缓存优化

• pip 使用中科大镜像源
• npm 使用淘宝镜像
• Docker 基础镜像缓存

✅ 测试和通知

• HTML 格式测试报告
• 代码覆盖率报告
• QQ 邮箱自动通知

快速开始

1. 配置依赖镜像源

./scripts/setup-dependencies-cache.sh

2. 本地开发

# 一键启动
./start_app.sh

# 访问
# 前端: http://localhost:6115
# API: http://localhost:5115/docs

3. Docker 部署

# 构建镜像
./build-and-push.sh v1.0.0 --push

# 启动服务
docker-compose -f docker-compose.prod.yml up -d

4. Kubernetes 部署

# 配置环境
cp .env.k8s.dev.example .env.k8s.dev
vim .env.k8s.dev

# 部署
./deploy_k8s.sh dev v1.0.0

项目结构

fastapi-template/
├── .gitea/
│   └── workflows/              # Gitea Actions CI/CD 配置
│       ├── ci.yaml             # 代码检查和测试
│       ├── build-and-push.yaml # 构建并推送镜像
│       └── deploy.yaml         # 自动部署
│
├── backend/                    # 后端代码
│   ├── Dockerfile.prod         # 生产环境 Dockerfile
│   ├── app/                    # 应用代码
│   ├── tests/                  # 测试代码
│   └── requirements.txt        # Python 依赖
│
├── frontend/                   # 前端代码
│   ├── Dockerfile              # 前端 Dockerfile
│   ├── nginx.conf              # Nginx 配置
│   ├── src/                    # Vue 源码
│   └── package.json            # npm 依赖
│
├── k8s/                        # Kubernetes 配置
│   ├── namespace.yaml          # 命名空间
│   ├── configmap.yaml          # 配置项
│   ├── secret.yaml             # 密钥
│   ├── postgres.yaml           # 数据库
│   ├── redis.yaml              # 缓存
│   ├── backend.yaml            # 后端服务
│   ├── frontend.yaml           # 前端服务
│   └── ingress.yaml            # 入口配置
│
├── nginx/                      # Nginx 反向代理
│   ├── nginx.conf              # 主配置
│   └── conf.d/
│       └── default.conf        # 站点配置
│
├── scripts/                    # 工具脚本
│   ├── setup-dependencies-cache.sh  # 配置镜像源
│   └── send-test-report-email.py    # 发送测试报告邮件
│
├── start_app.sh                # 本地一键启动
├── build-and-push.sh           # 构建并推送镜像
├── deploy_k8s.sh               # K8s 部署脚本
│
├── docker-compose.prod.yml     # 生产环境 Docker Compose
├── .env.prod.example           # Docker Compose 配置示例
├── .env.k8s.dev.example        # K8s 开发环境配置示例
├── .env.k8s.prod.example       # K8s 生产环境配置示例
├── .env.email.example          # 邮件通知配置示例
│
├── .pip/pip.conf               # pip 镜像源配置
├── .npmrc                      # npm 镜像源配置
│
├── DEVOPS_SOLUTION.md          # DevOps 方案详细说明
├── DEVOPS_QUICKSTART.md        # 快速开始指南
└── README_DEVOPS.md            # 本文件

核心脚本说明

start_app.sh

本地一键启动脚本

功能：

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

使用：

./start_app.sh

build-and-push.sh

镜像构建和推送脚本

功能：

• 多阶段 Docker 构建
• 利用 BuildKit 缓存加速
• 支持多架构 (amd64/arm64)
• 自动版本标记
• 推送到本地镜像仓库

使用：

# 构建并推送
./build-and-push.sh v1.0.0 --push

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

# 不使用缓存
./build-and-push.sh --no-cache --push

deploy_k8s.sh

Kubernetes 部署脚本

功能：

• 自动应用所有 K8s 配置
• 创建命名空间
• 部署 ConfigMap 和 Secret
• 部署应用和依赖服务
• 健康检查和状态显示

使用：

# 部署到开发环境
./deploy_k8s.sh dev v1.0.0

# 部署到生产环境
./deploy_k8s.sh prod v1.0.0

CI/CD 流程

代码检查 (ci.yaml)

触发：Push 或 PR

• Python 代码格式检查 (black)
• 代码质量检查 (ruff)
• 类型检查 (mypy)
• 单元测试 + 覆盖率
• Frontend 构建测试

构建镜像 (build-and-push.yaml)

触发：Push to main 或 创建 tag

• 构建 Docker 镜像
• 推送到 localhost:5000
• 可选镜像扫描

自动部署 (deploy.yaml)

触发：Push to main 或手动

• 部署到 K8s 开发环境（自动）
• 部署到生产环境（手动审批）
• 健康检查
• 邮件通知

配置说明

依赖镜像源

pip (中科大)

[global]
index-url = https://pypi.mirrors.ustc.edu.cn/simple/
trusted-host = pypi.mirrors.ustc.edu.cn

npm (淘宝)

registry=https://registry.npmmirror.com

邮件通知 (QQ 邮箱)

SMTP_HOST=smtp.qq.com
SMTP_PORT=587
SMTP_USER=38455629@qq.com
SMTP_PASSWORD=your-qq-authorization-code

获取 QQ 邮箱授权码：

1. 登录 QQ 邮箱 → 设置 → 账户
2. 开启 POP3/SMTP 服务
3. 生成授权码（16位）

环境要求

开发环境

• Python 3.11+
• Node.js 20+
• Docker (OrbStack)
• PostgreSQL 15+
• Redis 7+

生产环境

• Kubernetes 集群
• 持久化存储 (PVC)
• Ingress Controller
• 镜像仓库 (localhost:5000)

本地服务

• Gitea: http://localhost:33000
• 业务镜像仓库: http://localhost:5000
• 基础镜像缓存: http://localhost:5001

最佳实践

1. 安全

• ✅ 使用强密码和随机 SECRET_KEY
• ✅ 不要将 .env 文件提交到 Git
• ✅ 使用 K8s Secret 管理敏感信息
• ✅ 定期更新基础镜像和依赖
• ✅ 启用镜像扫描

2. 性能

• ✅ 使用依赖缓存加速构建
• ✅ 多阶段 Docker 构建减小镜像体积
• ✅ 配置 HPA 自动扩缩容
• ✅ 使用 Redis 缓存热点数据
• ✅ 启用 Gzip 压缩

3. 可维护性

• ✅ 统一的配置管理
• ✅ 完整的测试覆盖
• ✅ 详细的日志记录
• ✅ 健康检查和监控
• ✅ 自动化部署流程

常见问题

Q: pip 安装依赖很慢？

A: 运行 ./scripts/setup-dependencies-cache.sh 配置中科大镜像源

Q: Docker 构建失败？

A: 检查镜像仓库是否运行：curl http://localhost:5000/v2/_catalog

Q: K8s Pod 无法启动？

A: 使用 kubectl describe pod <pod-name> 查看详细错误

Q: 邮件发送失败？

A: 确认 QQ 邮箱授权码配置正确，不是登录密码

Q: 如何清理旧镜像？

A: 定期清理镜像仓库，保留最近 N 个版本

文档

• 完整 DevOps 方案 - 架构设计和详细说明
• 快速开始指南 - 分步操作指南
• 项目架构 - 代码架构和开发指南
• 后端文档 - FastAPI 后端说明
• 前端文档 - Vue3 前端说明

技术栈

后端

• FastAPI 0.115+
• PostgreSQL 15
• Redis 7
• SQLAlchemy 2.0
• Alembic (数据库迁移)
• Pytest (测试)

前端

• Vue 3
• Vite
• Tailwind CSS
• ECharts
• Vue Router
• Vue I18n

DevOps

• Docker + Docker Compose
• Kubernetes
• Gitea Actions
• Nginx
• OrbStack

路线图

• 本地开发环境
• Docker 部署
• Kubernetes 部署
• CI/CD 流程
• 测试和报告
• 邮件通知
• Prometheus + Grafana 监控
• ELK 日志收集
• 蓝绿部署/金丝雀发布
• 自动化备份
• 性能测试

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

作者

灵境万象 © 2025