bigscreen/DEVOPS_SOLUTION.md

FastAPI Template DevOps 解决方案

环境信息

• 硬件: Mac Studio M2 Ultra 192G (ARM64 架构)
• 容器运行时: OrbStack
• 代码仓库: Gitea (localhost:33000)
• 业务镜像仓库: localhost:5000
• 基础镜像缓存: localhost:5001

整体架构

┌─────────────────────────────────────────────────────────────────┐
│                         开发部署方式                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. 本地开发模式 (start_app.sh)                                   │
│     ├── 自动创建/复用虚拟环境                                      │
│     ├── 智能依赖安装 (增量更新)                                    │
│     ├── 同时启动前后端服务                                        │
│     └── 进程管理 (优雅启停)                                       │
│                                                                 │
│  2. Docker Compose 部署 (docker-compose.prod.yml)               │
│     ├── 从 localhost:5000 拉取业务镜像                           │
│     ├── 从 localhost:5001 拉取基础镜像                           │
│     ├── 完整服务编排 (app + db + redis + nginx)                 │
│     └── 持久化数据卷                                             │
│                                                                 │
│  3. Kubernetes 部署 (deploy_k8s.sh)                             │
│     ├── 从 localhost:5000 拉取业务镜像                           │
│     ├── ConfigMap/Secret 配置管理                                │
│     ├── Service + Ingress 网络配置                               │
│     └── HPA 自动扩缩容                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      CI/CD 流程 (Gitea Actions)                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  代码推送 → Gitea                                                │
│      ↓                                                          │
│  触发 Actions                                                    │
│      ├── 代码质量检查 (lint, format)                              │
│      ├── 单元测试 + 覆盖率报告                                     │
│      ├── 集成测试                                                │
│      ├── 构建 Docker 镜像                                        │
│      ├── 推送到 localhost:5000                                   │
│      ├── 生成测试报告 (HTML + JSON)                              │
│      ├── 上传报告到 Artifacts                                    │
│      └── 邮件通知 (成功/失败 summary)                             │
│                                                                 │
│  主分支推送 → 自动部署                                            │
│      ├── 开发环境: 自动部署到 K8s dev namespace                   │
│      └── 生产环境: 手动审批后部署                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                        依赖缓存策略                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Python (pip)                                                   │
│    ├── 镜像源: 阿里云/清华 TUNA                                  │
│    ├── 本地缓存: ~/.cache/pip                                   │
│    └── Dockerfile: pip cache mount                              │
│                                                                 │
│  Node.js (npm)                                                  │
│    ├── 镜像源: 淘宝镜像                                          │
│    ├── 本地缓存: ~/.npm                                         │
│    └── Dockerfile: npm cache mount                              │
│                                                                 │
│  Docker 基础镜像                                                 │
│    ├── Pull-through cache: localhost:5001                       │
│    ├── 支持: Docker Hub, ghcr.io, gcr.io                        │
│    └── 缓存策略: 永久缓存常用镜像                                 │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│                      测试报告与通知                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  测试报告生成                                                     │
│    ├── Pytest HTML Report (测试结果详情)                         │
│    ├── Coverage HTML Report (代码覆盖率)                         │
│    ├── JUnit XML (CI 集成)                                      │
│    └── JSON Summary (邮件摘要)                                   │
│                                                                 │
│  报告存储                                                        │
│    ├── Gitea Actions Artifacts (下载查看)                       │
│    ├── 静态文件服务 (Nginx)                                      │
│    └── 保留最近 30 次构建                                        │
│                                                                 │
│  邮件通知                                                        │
│    ├── 触发条件: 构建失败 / 主分支构建成功                         │
│    ├── 内容: Summary + 测试统计 + 报告链接                       │
│    └── 收件人: 配置在 .env 中                                    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

核心脚本说明

1. start_app.sh - 本地一键启动

功能:

• 自动检测并创建/激活 Python 虚拟环境
• 智能安装/更新依赖 (仅在 requirements.txt 变化时)
• 自动检测并安装 Node.js 依赖
• 同时启动后端 (FastAPI) 和前端 (Vite)
• 优雅关闭 (Ctrl+C 同时停止前后端)
• 健康检查和错误处理

使用:

./start_app.sh

2. build-and-push.sh - 构建并推送镜像

功能:

• 多架构构建 (amd64 + arm64)
• 多阶段构建优化镜像大小
• 利用 BuildKit 缓存加速构建
• 推送到本地镜像仓库 (localhost:5000)
• 自动打标签 (latest, git-sha, semantic version)
• 构建验证 (镜像扫描)

使用:

./build-and-push.sh [version]
# 例如: ./build-and-push.sh v1.0.0

3. docker-compose.prod.yml - 生产环境编排

功能:

• 从 localhost:5000 拉取业务镜像
• 从 localhost:5001 拉取基础镜像
• 完整服务栈: Backend + Frontend + PostgreSQL + Redis + Nginx
• 健康检查和自动重启
• 持久化数据卷
• 网络隔离

使用:

docker-compose -f docker-compose.prod.yml up -d

4. deploy_k8s.sh - K8s 部署脚本

功能:

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

使用:

./deploy_k8s.sh [environment]
# 例如: ./deploy_k8s.sh dev
# 例如: ./deploy_k8s.sh prod

CI/CD Workflow

Gitea Actions 工作流

1. 代码检查流程 (on: push, pull_request)

   • Lint (black, ruff)
   • Type check (mypy)
   • Security scan

2. 测试流程 (on: push, pull_request)

   • 单元测试
   • 集成测试
   • 生成覆盖率报告
   • 上传测试报告 Artifacts

3. 构建流程 (on: push to main/tags)

   • 构建 Docker 镜像
   • 推送到 localhost:5000
   • 生成 SBOM

4. 部署流程 (on: push to main)

   • 开发环境: 自动部署
   • 生产环境: 手动审批

5. 通知流程 (on: workflow completion)

   • 发送邮件通知
   • 包含测试报告 summary
   • 提供报告下载链接

依赖管理最佳实践

Python 依赖缓存

# Dockerfile 中使用缓存挂载
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

# pip 配置文件 ~/.pip/pip.conf
[global]
index-url = https://mirrors.aliyun.com/pypi/simple/
trusted-host = mirrors.aliyun.com

Node.js 依赖缓存

# Dockerfile 中使用缓存挂载
RUN --mount=type=cache,target=/root/.npm \
    npm ci --registry=https://registry.npmmirror.com

# npm 配置
npm config set registry https://registry.npmmirror.com

Docker 镜像缓存 (localhost:5001)

在 Dockerfile 中使用镜像缓存:

# 从缓存拉取基础镜像
FROM localhost:5001/python:3.11-slim
FROM localhost:5001/node:20-alpine
FROM localhost:5001/nginx:alpine

配置 Docker daemon 使用 pull-through cache:

{
  "registry-mirrors": ["http://localhost:5001"]
}

测试报告系统

报告生成

# 在 CI 中执行
pytest tests/ \
  --cov=app \
  --cov-report=html:reports/coverage \
  --cov-report=json:reports/coverage.json \
  --html=reports/test-results.html \
  --junitxml=reports/junit.xml

报告查看

1. Gitea Artifacts: 每次构建后下载 artifacts.zip
2. 静态服务: 通过 Nginx 访问 http://reports.local/{build-id}/
3. 邮件链接: 点击邮件中的链接直接查看

邮件模板

主题: [FastAPI Template] Build #123 - ✅ Success / ❌ Failed

构建信息:
- 分支: main
- Commit: a1b2c3d
- 作者: Bruno Gao
- 时间: 2025-12-01 10:30:00

测试结果:
✅ 45 passed
❌ 2 failed
⏭️  3 skipped
📊 Coverage: 85%

详细报告:
- 测试报告: http://reports.local/123/test-results.html
- 覆盖率: http://reports.local/123/coverage/index.html

失败的测试:
1. test_user_login - AssertionError
2. test_data_export - TimeoutError

查看完整日志:
http://gitea.local:33000/fastapi-template/actions/runs/123

快速开始

首次设置

# 1. 克隆项目
git clone http://localhost:33000/your-org/fastapi-template.git
cd fastapi-template

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

# 3. 本地开发
./start_app.sh

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

# 5. Docker 部署
docker-compose -f docker-compose.prod.yml up -d

# 6. K8s 部署
./deploy_k8s.sh dev

模板复用

当需要创建新项目时:

# 1. 复制模板
cp -r fastapi-template my-new-project
cd my-new-project

# 2. 修改项目配置
# - backend/.env: 修改 APP_NAME, DATABASE_NAME 等
# - frontend/package.json: 修改 name
# - CLAUDE.md: 更新项目说明

# 3. 初始化 Git
git init
git remote add origin http://localhost:33000/your-org/my-new-project.git

# 4. 启动开发
./start_app.sh

所有脚本和配置都是通用的，只需修改环境变量即可复用。

监控和维护

镜像仓库管理

# 查看本地镜像仓库内容
curl http://localhost:5000/v2/_catalog

# 查看镜像标签
curl http://localhost:5000/v2/fastapi-template-backend/tags/list

# 清理旧镜像 (保留最近 10 个版本)
# 可以配置定时任务

日志管理

# Docker Compose 日志
docker-compose -f docker-compose.prod.yml logs -f

# K8s 日志
kubectl logs -f deployment/fastapi-backend -n dev

# 日志收集 (可选: ELK Stack)

备份策略

# 数据库备份
docker exec ljwx-postgres pg_dump -U postgres template > backup.sql

# K8s 配置备份
kubectl get all -n dev -o yaml > k8s-backup.yaml

故障排查

常见问题

1. 镜像拉取失败

   • 检查 localhost:5000 和 localhost:5001 是否运行
   • 确认网络连接
   • 查看 Docker daemon 配置

2. 依赖安装慢

   • 确认镜像源配置正确
   • 检查缓存目录权限
   • 考虑使用本地 PyPI/npm 镜像服务

3. CI/CD 构建失败

   • 查看 Gitea Actions 日志
   • 检查 runner 容器状态
   • 验证镜像仓库可访问性

4. K8s 部署问题

   • 检查 namespace 和资源配置
   • 查看 Pod 事件: kubectl describe pod xxx
   • 检查 PVC 绑定状态

安全建议

1. 镜像仓库安全

   • 配置 HTTPS (自签名证书或 Let's Encrypt)
   • 启用基本认证或 Token 认证
   • 限制访问 IP 范围

2. 密钥管理

   • 敏感信息使用 K8s Secret
   • 不要将 .env 文件提交到 Git
   • 使用 Vault 管理生产密钥

3. 网络隔离

   • 使用 Docker 网络隔离服务
   • K8s NetworkPolicy 限制 Pod 通信
   • 配置防火墙规则

4. 镜像扫描

   • 使用 Trivy 或 Clair 扫描镜像漏洞
   • 定期更新基础镜像
   • 使用最小化镜像 (alpine, slim)

下一步

• 配置 Prometheus + Grafana 监控
• 集成 ELK Stack 日志收集
• 配置自动化备份
• 实现蓝绿部署/金丝雀发布
• 添加性能测试
• 配置告警系统 (AlertManager)