fastapi-template/DEVOPS_FILES.md

DevOps 相关文件清单

本文件列出了所有 DevOps 相关的配置文件和脚本，方便快速查找和理解。

📁 文件分类

🚀 部署脚本

文件	用途	使用场景
start_app.sh	本地一键启动前后端	开发环境
build-and-push.sh	构建并推送 Docker 镜像	镜像构建
deploy_k8s.sh	K8s 部署脚本	K8s 部署
scripts/setup-dependencies-cache.sh	配置依赖镜像源	环境初始化
scripts/send-test-report-email.py	发送测试报告邮件	CI/CD 通知

🐳 Docker 配置

文件	用途	说明
backend/Dockerfile.prod	后端生产镜像	多阶段构建
frontend/Dockerfile	前端生产镜像	Nginx + Vue
frontend/nginx.conf	Nginx 配置	前端服务器
docker-compose.prod.yml	生产环境编排	完整服务栈
nginx/nginx.conf	Nginx 主配置	反向代理
nginx/conf.d/default.conf	Nginx 站点配置	路由规则

☸️ Kubernetes 配置

文件	用途	资源类型
k8s/namespace.yaml	命名空间	Namespace
k8s/configmap.yaml	配置项	ConfigMap
k8s/secret.yaml	敏感信息	Secret
k8s/postgres.yaml	PostgreSQL	Deployment + Service + PVC
k8s/redis.yaml	Redis	Deployment + Service + PVC
k8s/backend.yaml	后端服务	Deployment + Service + HPA
k8s/frontend.yaml	前端服务	Deployment + Service
k8s/ingress.yaml	入口控制器	Ingress

🔄 CI/CD 配置

文件	用途	触发条件
.gitea/workflows/ci.yaml	代码检查和测试	Push/PR
.gitea/workflows/build-and-push.yaml	构建镜像	Push to main/tags
.gitea/workflows/deploy.yaml	自动部署	Push to main/手动

⚙️ 环境配置

文件	用途	环境
.env.prod.example	Docker Compose 配置	生产环境
.env.k8s.dev.example	K8s 开发环境配置	K8s Dev
.env.k8s.prod.example	K8s 生产环境配置	K8s Prod
.env.email.example	邮件通知配置	CI/CD
.pip/pip.conf	pip 镜像源配置	Python
.npmrc	npm 镜像源配置	Node.js

📚 文档

文件	内容
DEVOPS_SOLUTION.md	完整 DevOps 方案设计
DEVOPS_QUICKSTART.md	快速开始指南
README_DEVOPS.md	DevOps 总览
DEVOPS_FILES.md	本文件
CLAUDE.md	项目架构和开发指南

🎯 使用场景

场景 1: 首次设置开发环境

1. scripts/setup-dependencies-cache.sh - 配置镜像源
2. start_app.sh - 启动开发服务

场景 2: 构建和推送镜像

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

场景 3: Docker Compose 部署

1. cp .env.prod.example .env.prod - 复制配置
2. docker-compose -f docker-compose.prod.yml up -d - 启动

场景 4: K8s 部署

1. cp .env.k8s.dev.example .env.k8s.dev - 复制配置
2. deploy_k8s.sh dev v1.0.0 - 部署

场景 5: 配置 CI/CD

1. 配置 Gitea Secrets
2. 推送代码触发 Workflows

🔧 配置优先级

Docker Compose

docker-compose.prod.yml → .env.prod → 默认值

Kubernetes

deploy_k8s.sh → .env.k8s.{env} → k8s/*.yaml → 默认值

CI/CD

Gitea Secrets → .gitea/workflows/*.yaml → 默认值

📝 注意事项

⚠️ 不要提交到 Git 的文件

• .env.prod
• .env.k8s.dev
• .env.k8s.prod
• .env.email
• 任何包含真实密码的文件

这些文件已在 .gitignore 中，但仍需注意。

✅ 可以提交的文件

• *.example 配置示例
• 所有脚本文件
• Dockerfile 和 docker-compose.yml
• K8s YAML 配置（使用变量替换）
• CI/CD workflow 文件

🔐 密钥管理

本地开发

使用 .env 文件（不提交到 Git）

Docker 部署

使用 .env.prod 文件或环境变量

K8s 部署

1. 开发环境: .env.k8s.dev → K8s Secret
2. 生产环境: .env.k8s.prod → K8s Secret
3. 推荐: 使用 Sealed Secrets 或 Vault

CI/CD

使用 Gitea Repository Secrets

🎨 目录结构建议

fastapi-template/
├── 根目录脚本/          # 一键操作脚本
├── .gitea/workflows/    # CI/CD 配置
├── backend/             # 后端代码和 Dockerfile
├── frontend/            # 前端代码和 Dockerfile
├── k8s/                 # K8s 配置
├── nginx/               # Nginx 配置
├── scripts/             # 工具脚本
├── *.example            # 配置示例
└── *.md                 # 文档

📊 文件大小参考

start_app.sh              ~8KB    (启动脚本)
build-and-push.sh         ~8KB    (构建脚本)
deploy_k8s.sh             ~10KB   (部署脚本)
docker-compose.prod.yml   ~3KB    (编排配置)
backend/Dockerfile.prod   ~2KB    (后端镜像)
frontend/Dockerfile       ~2KB    (前端镜像)
k8s/*.yaml                ~15KB   (K8s 配置总计)
.gitea/workflows/*.yaml   ~10KB   (CI/CD 配置总计)

🔄 更新记录

日期	更新内容
2025-12-01	初始版本，完整 DevOps 方案
2025-12-01	配置 pip 使用中科大镜像源
2025-12-01	配置 QQ 邮箱通知 (38455629@qq.com)

📞 获取帮助

遇到问题时：

1. 查看对应文档 (DEVOPS_*.md)
2. 检查配置文件是否正确
3. 查看脚本输出的错误信息
4. 提交 Issue 到 Gitea