Full-Stack FastAPI 项目部署指南：从零到生产环境

武朵欢Nerissa

于 2025-05-30 09:18:04 发布

阅读量274

点赞数 4

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00670/article/details/148328066

Full-Stack FastAPI 项目部署指南：从零到生产环境

full-stack-fastapi-template 项目地址: https://gitcode.com/gh_mirrors/fu/full-stack-fastapi-template

项目概述

Full-Stack FastAPI 模板项目是一个现代化的全栈应用开发框架，集成了前端(Vue.js)、后端(FastAPI)和数据库(PostgreSQL)等组件。本文将详细介绍如何将这个项目从本地开发环境部署到生产服务器，涵盖从基础设施准备到自动化部署的全过程。

部署架构设计

该项目的部署架构采用以下核心组件：

Traefik反向代理：作为入口网关，处理HTTPS证书和请求路由
Docker容器化：所有服务组件都运行在Docker容器中
多环境支持：支持staging和生产环境独立部署
CI/CD流程：通过自动化工作流实现持续集成和部署

部署前准备

服务器基础配置

服务器选择：准备一台具有公网IP的Linux服务器(推荐Ubuntu 20.04+)
域名配置：
- 将域名A记录指向服务器IP
- 配置通配符子域名(如*.yourdomain.com)
Docker安装：在服务器上安装Docker Engine和Docker Compose

网络规划

建议为不同环境使用不同的子域名：

生产环境：app.yourdomain.com, api.yourdomain.com
测试环境：staging.yourdomain.com, staging-api.yourdomain.com

Traefik代理部署

为什么需要Traefik？

Traefik作为现代反向代理和负载均衡器，具有以下优势：

自动发现服务并配置路由
自动管理Let's Encrypt证书
提供可视化仪表板
支持多种后端服务

部署步骤

mkdir -p /opt/traefik
docker network create traefik-public

准备环境变量：

export USERNAME=admin
export PASSWORD=your_secure_password
export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)
export DOMAIN=yourdomain.com
export EMAIL=your@email.com

启动Traefik服务：

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

应用部署配置

环境变量管理

项目依赖多个环境变量，建议通过.env文件管理：

# 基础配置
ENVIRONMENT=production
DOMAIN=yourdomain.com
PROJECT_NAME=MyFastAPIApp

# 数据库配置
POSTGRES_SERVER=db
POSTGRES_USER=appuser
POSTGRES_PASSWORD=your_db_password
POSTGRES_DB=app

# 安全配置
SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
FIRST_SUPERUSER=admin@example.com
FIRST_SUPERUSER_PASSWORD=your_admin_password

# 邮件配置
SMTP_HOST=smtp.provider.com
SMTP_USER=your_smtp_user
SMTP_PASSWORD=your_smtp_password
EMAILS_FROM_EMAIL=noreply@yourdomain.com

安全建议

所有密码类配置都应使用强密码
使用secrets.token_urlsafe(32)生成安全的随机密钥
限制数据库和其他服务的网络访问权限

多环境部署策略

生产环境部署

export ENVIRONMENT=production
export DOMAIN=yourdomain.com
export STACK_NAME=production-stack
docker compose -f docker-compose.yml up -d

预发布环境部署

export ENVIRONMENT=staging
export DOMAIN=staging.yourdomain.com
export STACK_NAME=staging-stack
docker compose -f docker-compose.yml up -d

自动化部署实现

自托管Runner配置

创建专用用户：

adduser deployer
usermod -aG docker deployer

安装并注册Runner：

# 切换到deployer用户
su - deployer

# 下载并配置Runner
mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64-2.285.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.285.1/actions-runner-linux-x64-2.285.1.tar.gz
tar xzf ./actions-runner-linux-x64-2.285.1.tar.gz
./config.sh --url https://your-repo-url --token YOUR_RUNNER_TOKEN

配置为系统服务：

sudo ./svc.sh install
sudo ./svc.sh start

工作流配置

项目已预置两种工作流：

Staging环境：在推送到master分支时自动部署
Production环境：在创建GitHub Release时触发部署

部署后验证

服务健康检查

Traefik仪表板：访问https://traefik.yourdomain.com
API文档：访问https://api.yourdomain.com/docs
前端应用：访问https://app.yourdomain.com
数据库管理：访问https://adminer.yourdomain.com

监控建议

配置日志收集系统(如ELK)
设置基础资源监控(CPU、内存、磁盘)
配置应用性能监控(如Sentry)

常见问题解决

证书获取失败：
- 检查域名解析是否正确
- 确认服务器80/443端口开放
- 检查Traefik日志获取详细错误
服务无法启动：
- 检查Docker日志：docker logs <container_name>
- 验证环境变量是否正确设置
- 检查网络连接：docker network inspect traefik-public
数据库连接问题：
- 验证PostgreSQL容器是否正常运行
- 检查连接字符串配置
- 确认网络连通性