Docker 容器化部署 FastAPI 应用

简介

Docker 是一种流行的容器化技术，它允许将应用及其依赖打包成独立、可移植的容器。对于 FastAPI 应用来说，使用 Docker 可以简化部署流程，确保环境一致性，并提高可扩展性。本教程将带你从零开始，学习如何将 FastAPI 应用容器化并部署。

为什么选择 Docker 部署 FastAPI？

• 环境一致性：容器内运行的应用与宿主机环境隔离，避免了依赖冲突。
• 可移植性：镜像可在任何支持 Docker 的系统上运行，便于跨平台部署。
• 高效部署：简化了部署和运维过程，支持快速迭代和微服务架构。

准备工作

在开始之前，请确保已安装以下工具：

• Docker（建议使用最新稳定版）

• FastAPI 项目：可以是一个简单的示例应用。如果还没有，可以创建一个。

  快速创建一个简单的 FastAPI 应用：

  mkdir fastapi-docker-demo
  cd fastapi-docker-demo
  pip install fastapi uvicorn
  

  创建一个 main.py 文件：

  from fastapi import FastAPI
  
  app = FastAPI()
  
  @app.get("/")
  def read_root():
      return {"Hello": "World from FastAPI in Docker"}
  

步骤 1：创建 Dockerfile

Dockerfile 是定义容器构建过程的配置文件。在项目根目录下创建一个名为 Dockerfile 的文件（无扩展名）。

Dockerfile 示例

# 使用官方 Python 镜像作为基础
FROM python:3.9-slim

# 设置工作目录
WORKDIR /app

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口（FastAPI 默认运行在 8000 端口）
EXPOSE 8000

# 启动命令
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

解释：

• FROM python:3.9-slim：基于轻量级 Python 3.9 镜像。
• WORKDIR /app：设置容器内的工作目录为 /app。
• COPY requirements.txt .：将本地的依赖文件复制到容器中。
• RUN pip install ...：安装依赖项。
• COPY . .：复制所有项目文件。
• EXPOSE 8000：声明容器运行时监听的端口。
• CMD [...]：启动 FastAPI 应用，使用 uvicorn 服务器。

注意：如果没有 requirements.txt 文件，可以创建一个，列出依赖（如 fastapi 和 uvicorn）。

步骤 2：构建 Docker 镜像

在包含 Dockerfile 的目录下，运行以下命令构建镜像。镜像名可以自定义，例如 fastapi-app。

docker build -t fastapi-app .

• -t fastapi-app：给镜像打上标签（名称）。
• .：表示当前目录是构建上下文。

构建过程可能需要几分钟，特别是首次构建时。完成后，可以使用 docker images 命令查看所有镜像，确认 fastapi-app 已存在。

步骤 3：运行 Docker 容器

构建成功后，运行容器来启动 FastAPI 应用。

docker run -d -p 8000:8000 --name fastapi-container fastapi-app

参数说明：

• -d：在后台运行容器（detached 模式）。
• -p 8000:8000：将宿主机的 8000 端口映射到容器的 8000 端口。
• --name fastapi-container：为容器指定一个名称。
• fastapi-app：要运行的镜像名称。

运行后，使用 docker ps 命令查看容器是否正在运行。然后在浏览器中访问 http://localhost:8000/，应该看到 {"Hello": "World from FastAPI in Docker"} 的响应。

步骤 4：测试与调试

• 查看日志：如果应用未正常启动，使用 docker logs fastapi-container 查看容器的日志输出。
• 进入容器：调试时可以进入容器内部，例如：

  docker exec -it fastapi-container /bin/bash
  

  在容器内部，可以检查文件或运行命令。

步骤 5：部署优化与高级技巧

使用多阶段构建

对于生产环境，可以使用多阶段构建来减小镜像大小。例如：

# 构建阶段
FROM python:3.9 AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --user -r requirements.txt

# 运行阶段
FROM python:3.9-slim
WORKDIR /app
COPY --from=builder /root/.local /root/.local
COPY . .
ENV PATH=/root/.local/bin:$PATH
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

配置环境变量

Docker 支持通过环境变量配置应用。在 Dockerfile 中：

ENV APP_NAME="FastAPI Docker App"

在运行时覆盖：docker run -e APP_NAME="New Name" ...

使用 Docker Compose

对于复杂应用，可以使用 Docker Compose 管理多个容器。创建一个 docker-compose.yml 文件：

version: '3.8'
services:
  fastapi:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ENV_VAR=value

运行：docker-compose up -d

常见问题解答

1. 端口冲突：确保宿主机端口未被占用，或更改映射端口（如 -p 8080:8000）。
2. 依赖安装失败：检查 requirements.txt 文件是否正确，或尝试使用 --no-cache-dir 选项。
3. 容器启动慢：确保基础镜像是最新，或使用 alpine 版本以减小大小。

总结

通过本教程，你已学会了使用 Docker 容器化部署 FastAPI 应用的基础步骤。Docker 使得 FastAPI 应用的部署更加灵活和可靠。推荐继续学习 Docker 网络、存储卷等高级主题，以应对更复杂的生产环境需求。实践是学习的关键——尝试部署自己的 FastAPI 项目，并在社区中分享经验！

Happy Coding！