从0到1部署fastapi-scaff项目：Docker容器化完整教程

【免费下载链接】fastapi-scaff This is a fastapi scaf. (fastapi脚手架，一键生成项目或api，让开发变得更简单) 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-scaff

fastapi-scaff是一款高效的FastAPI脚手架工具，能够一键生成项目或API，极大简化开发流程。本教程将带你完成从环境准备到容器化部署的全过程，让你快速掌握Docker容器化部署fastapi-scaff项目的核心方法。

📋 环境准备清单

在开始部署前，请确保你的系统已安装以下工具：

• Docker Engine（推荐20.10+版本）
• Docker Compose（v2+版本）
• Git

1️⃣ 克隆项目代码库

首先通过Git克隆项目源码到本地：

git clone https://gitcode.com/gh_mirrors/fa/fastapi-scaff
cd fastapi-scaff

2️⃣ 认识项目容器化配置

项目提供了完善的Docker化配置文件，主要包括：

Dockerfile基础镜像配置

项目根目录下提供两种Dockerfile配置：

• Dockerfile：基于Python 3.12-bullseye完整镜像，包含完整依赖环境
• Dockerfile-slim：基于Python 3.12-slim精简镜像，适合生产环境

核心配置示例：

FROM python:3.12-bullseye  # 基础镜像
WORKDIR /backend           # 工作目录设置
COPY requirements.txt .    # 复制依赖文件
RUN pip install --upgrade pip && pip install -r requirements.txt  # 安装依赖
COPY config ./config       # 复制配置文件
COPY app ./app             # 复制应用代码

Docker Compose编排文件

项目提供两种编排方案：

• docker-compose.yaml：基础单机部署配置
• docker-compose.swarm.yaml：Swarm集群部署配置

基础服务定义示例：

services:
  app:
    image: fastapi-scaff:v1.0.0  # 强烈建议不要用 :latest
    volumes:
      - ./config:/backend/config  # 配置文件挂载
    ports:
      - "8000:8000"              # 端口映射

3️⃣ 构建Docker镜像

使用项目提供的Dockerfile构建应用镜像：

# 使用标准镜像构建
docker build -t fastapi-scaff:v1.0.0 -f Dockerfile .

# 如需精简镜像，可使用slim版本
# docker build -t fastapi-scaff:v1.0.0 -f Dockerfile-slim .

4️⃣ 启动服务容器

通过Docker Compose快速启动服务：

# 基础部署
docker-compose up -d

# 如需Swarm集群部署
# docker stack deploy -c docker-compose.swarm.yaml fastapi-scaff

5️⃣ 验证部署结果

服务启动后，可通过以下方式验证：

1. 检查容器状态：

docker-compose ps

2. 访问API端点：

curl http://localhost:8000/api/ping

3. 查看应用日志：

docker-compose logs -f app

6️⃣ 生产环境优化建议

配置文件管理

项目配置文件位于config/目录，包含不同环境的配置：

• app_dev.yaml：开发环境配置
• app_prod.yaml：生产环境配置
• app_test.yaml：测试环境配置

建议生产环境使用环境变量注入敏感配置，避免硬编码。

数据持久化

通过Docker volumes实现数据持久化，关键挂载点：

• 配置文件：./config:/backend/config
• 日志目录：根据实际日志配置添加挂载

性能优化

1. 使用Dockerfile-slim减小镜像体积
2. 配置适当的资源限制：

services:
  app:
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 1G

🚀 部署常见问题解决

端口冲突

如遇"Bind for 0.0.0.0:8000 failed"错误，修改docker-compose.yaml中的端口映射：

ports:
  - "8001:8000"  # 将主机端口改为未占用端口

依赖安装失败

确保网络通畅，或修改requirements.txt使用国内镜像源：

-i https://pypi.tuna.tsinghua.edu.cn/simple

容器启动后立即退出

查看日志定位问题：

docker-compose logs app

总结

通过本教程，你已掌握使用Docker容器化部署fastapi-scaff项目的完整流程。从克隆代码、构建镜像到启动服务，Docker提供了一致的部署环境，极大降低了环境差异带来的问题。结合项目提供的docker-compose.yaml和Dockerfile配置文件，你可以快速实现开发、测试和生产环境的统一部署。

如需进一步扩展，可参考项目的docker-compose.swarm.yaml配置，实现多节点集群部署，满足更高的可用性需求。

【免费下载链接】fastapi-scaff This is a fastapi scaf. (fastapi脚手架，一键生成项目或api，让开发变得更简单) 项目地址: https://gitcode.com/gh_mirrors/fa/fastapi-scaff