在开发基于 FastAPI 的后端服务时本地运行一切正常但一到部署环节环境依赖、版本冲突、系统兼容性等问题就接踵而至让很多开发者头疼。Docker 的出现为应用部署提供了一套标准化的解决方案它能将应用及其所有依赖打包成一个轻量级、可移植的容器实现“一次构建处处运行”。本文将手把手带你完成一个 FastAPI 项目的 Docker 化部署全流程内容涵盖从基础镜像选择、Dockerfile 编写、多阶段构建优化到使用 Docker Compose 编排复杂服务如数据库最后探讨生产环境的最佳实践。无论你是刚接触 Docker 的新手还是希望优化现有部署流程的开发者都能从中获得可直接复用的代码和配置。1. FastAPI 与 Docker 部署核心概念在开始动手之前我们有必要厘清几个核心概念理解“为什么”要这么做这比单纯记住步骤更重要。1.1 为什么选择 FastAPIFastAPI 是一个现代、快速高性能的 Web 框架用于基于标准 Python 类型提示构建 API。它之所以成为 Python 后端开发的热门选择主要得益于其极高的性能基于 Starlette 和 Pydantic、直观的开发体验自动交互式 API 文档、以及强大的类型系统。对于需要快速迭代和清晰接口定义的微服务项目FastAPI 是一个绝佳的选择。1.2 Docker 解决了什么部署难题传统部署方式通常需要在服务器上手动安装 Python 解释器、项目依赖pip install、配置环境变量等。这种方式会带来诸多问题环境不一致开发、测试、生产环境稍有差异就可能导致程序行为异常即经典的“在我机器上能跑”问题。依赖冲突不同项目可能依赖同一库的不同版本全局安装会引起冲突。部署过程繁琐每次更新都需要在服务器上重复执行一系列安装和配置命令。系统污染直接在宿主机安装各种软件包可能导致系统环境混乱。Docker 通过容器化技术解决了这些问题。容器是一个标准的软件单元它将代码及其所有依赖运行时、系统工具、系统库、设置打包在一起。这保证了应用在任何环境中都能以相同的方式运行。对于 FastAPI 项目使用 Docker 意味着我们可以创建一个包含特定 Python 版本、项目依赖和应用程序代码的镜像这个镜像可以在任何安装了 Docker 的机器上瞬间启动为一个容器。1.3 核心组件Dockerfile 与 Docker ComposeDockerfile一个文本文件包含了一系列用于构建 Docker 镜像的指令如FROM,COPY,RUN,CMD。它是创建自定义镜像的“蓝图”。Docker ImageDockerfile 构建后产生的只读模板。它包含了运行应用所需的文件系统结构和元数据。Docker Container镜像的运行实例。你可以创建、启动、停止、移动或删除容器。容器是轻量级且可隔离的。Docker Compose一个用于定义和运行多容器 Docker 应用程序的工具。通过一个docker-compose.yml文件你可以配置应用的所有服务例如一个 FastAPI 应用服务和一个 PostgreSQL 数据库服务然后用一条命令启动所有服务。2. 环境准备与项目说明在开始构建之前请确保你的本地开发环境已经就绪。2.1 基础环境要求操作系统Windows 10/11需启用 WSL2 或 Hyper-V、macOS 或 Linux推荐 Ubuntu/Debian。本文示例命令在 Linux/macOS 的终端或 Windows 的 WSL2/PowerShell 中通用。Docker 引擎你需要安装 Docker。访问 Docker 官网下载并安装适合你操作系统的Docker DesktopWindows/macOS或Docker EngineLinux。验证安装打开终端运行docker --version和docker-compose --version对于 Docker Desktopdocker compose命令也已集成。应能看到版本号信息。Python 环境仅用于本地开发本地需要 Python 3.7 用于开发和测试 FastAPI 应用。建议使用venv或conda创建虚拟环境。2.2 示例 FastAPI 项目结构为了演示我们创建一个简单的 FastAPI 项目。在你的工作目录下创建如下结构的项目fastapi-docker-demo/ ├── app/ │ ├── __init__.py │ ├── main.py # FastAPI 应用主文件 │ └── dependencies.py # 可选的依赖项 ├── requirements.txt # Python 依赖列表 ├── Dockerfile # Docker 镜像构建文件 └── docker-compose.yml # Docker Compose 编排文件可选2.3 项目核心文件内容1.requirements.txt这个文件列出了项目运行所需的所有 Python 包及其版本。fastapi0.104.1 uvicorn[standard]0.24.0 # 如果需要连接数据库可以添加如下依赖 # sqlalchemy2.0.23 # psycopg2-binary2.9.9 # PostgreSQL 适配器 # pymysql1.1.0 # MySQL 适配器2.app/main.py这是一个最简单的 FastAPI 应用用于验证部署。from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware app FastAPI(titleFastAPI Docker Demo, version1.0.0) # 添加 CORS 中间件示例按需配置 app.add_middleware( CORSMiddleware, allow_origins[*], # 在生产环境中应指定具体域名 allow_credentialsTrue, allow_methods[*], allow_headers[*], ) app.get(/) async def root(): return {message: Hello from FastAPI running inside Docker!} app.get(/health) async def health_check(): return {status: healthy}3. 编写 Dockerfile构建 FastAPI 镜像Dockerfile 是构建镜像的核心。我们将采用多阶段构建策略以生成更小、更安全的生产镜像。3.1 基础单阶段 Dockerfile我们先从一个简单的版本开始理解。# Dockerfile # 第一阶段使用官方 Python 精简版作为基础镜像 FROM python:3.11-slim # 设置工作目录 WORKDIR /app # 设置环境变量确保 Python 输出不被缓冲便于日志实时查看 ENV PYTHONUNBUFFERED1 # 首先复制依赖文件利用 Docker 缓存层避免依赖未变时重复安装 COPY requirements.txt . # 安装 Python 依赖 RUN pip install --no-cache-dir --upgrade pip \ pip install --no-cache-dir -r requirements.txt # 将应用程序代码复制到容器中 COPY ./app ./app # 暴露容器监听的端口FastAPI 默认在 8000 端口运行 EXPOSE 8000 # 定义容器启动时执行的命令 # 使用 uvicorn 运行应用 --host 0.0.0.0 让服务监听所有网络接口 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]关键指令解析FROM: 指定基础镜像。python:3.11-slim比python:3.11体积更小更适合生产环境。WORKDIR: 设置容器内的工作目录后续的COPY、RUN、CMD等命令都会在此目录下执行。ENV PYTHONUNBUFFERED1: 防止 Python 缓冲 stdout 和 stderr使得日志能立即输出到容器日志流方便调试。COPY requirements.txt .: 先只复制依赖文件。Docker 构建是分层的如果requirements.txt没有变化Docker 会复用之前的RUN pip install...这一层缓存大大加快构建速度。RUN pip install: 安装依赖。--no-cache-dir避免 pip 缓存减小镜像体积。COPY ./app ./app: 复制应用代码。这行命令变化频繁所以放在依赖安装之后。EXPOSE 8000: 声明容器运行时监听的端口这是一个元数据实际映射需要在docker run或docker-compose中指定。CMD: 容器启动时的默认执行命令。这里使用列表格式[“executable”, “param1”, “param2”]这是推荐格式。3.2 优化版多阶段构建 Dockerfile多阶段构建可以在一个 Dockerfile 中使用多个FROM语句。前几个阶段用于构建和安装最后一个阶段仅包含运行应用所必需的最小内容从而生成非常小的最终镜像。# Dockerfile # 第一阶段构建阶段Builder FROM python:3.11-slim as builder WORKDIR /app ENV PYTHONUNBUFFERED1 # 复制依赖文件 COPY requirements.txt . # 安装依赖到 /usr/local 目录 RUN pip install --no-cache-dir --user -r requirements.txt # 第二阶段运行阶段Final FROM python:3.11-slim WORKDIR /app ENV PYTHONUNBUFFERED1 \ # 将 Python 用户安装目录添加到 PATH PATH/root/.local/bin:$PATH # 从构建阶段复制已安装的 Python 包 COPY --frombuilder /root/.local /root/.local # 从构建阶段复制依赖列表可选用于审计 COPY --frombuilder /app/requirements.txt . # 复制应用程序代码 COPY ./app ./app # 创建一个非 root 用户来运行应用增强安全性强烈推荐用于生产环境 RUN useradd -m -u 1000 appuser chown -R appuser:appuser /app USER appuser EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]优化点说明多阶段构建builder阶段负责安装依赖。最终的slim镜像只从builder复制安装好的包/root/.local而不包含构建工具和中间文件镜像体积更小。使用非 root 用户默认情况下容器内进程以 root 用户运行存在安全风险。我们创建了一个名为appuser的普通用户并使用USER指令切换至此用户运行应用。这是生产部署的重要安全实践。--user参数在builder阶段使用pip install --user将包安装到用户目录便于在第二阶段复制。4. 构建与运行 Docker 容器有了 Dockerfile我们就可以构建镜像并运行容器了。4.1 构建 Docker 镜像在项目根目录fastapi-docker-demo/下打开终端执行构建命令# -t 参数为镜像打标签格式通常为 名称:版本fastapi-app 是镜像名v1.0 是标签。 # 最后的 . 表示 Dockerfile 所在的当前目录为构建上下文。 docker build -t fastapi-app:v1.0 .构建过程会依次执行 Dockerfile 中的指令。首次构建时间稍长因为需要下载基础镜像和安装依赖。后续构建如果代码或依赖未变Docker 会利用缓存极大加速。4.2 运行 Docker 容器镜像构建成功后使用docker run命令启动一个容器# -d 表示在后台运行守护进程模式 # -p 将宿主机的 8000 端口映射到容器的 8000 端口 (宿主机端口:容器端口) # --name 为容器指定一个名称便于管理 docker run -d -p 8000:8000 --name fastapi-container fastapi-app:v1.0命令解析-d: 后台运行。-p 8000:8000: 端口映射。将本地机器宿主机的 8000 端口转发到容器内部的 8000 端口。这样访问http://localhost:8000就能访问到容器内的 FastAPI 应用。--name fastapi-container: 给容器起个名字否则 Docker 会随机分配一个。4.3 验证服务容器启动后可以通过以下方式验证查看容器状态docker ps应能看到名为fastapi-container的容器正在运行。查看容器日志docker logs fastapi-container可以查看应用启动日志应该能看到 Uvicorn 启动的信息。访问 API打开浏览器访问http://localhost:8000应该看到{message:Hello from FastAPI running inside Docker!}。访问http://localhost:8000/docs可以看到 FastAPI 自动生成的交互式 API 文档Swagger UI。访问http://localhost:8000/health应返回健康检查状态。4.4 常用容器管理命令# 停止容器 docker stop fastapi-container # 启动已停止的容器 docker start fastapi-container # 重启容器 docker restart fastapi-container # 进入容器内部的 shell用于调试 docker exec -it fastapi-container /bin/bash # 删除容器必须先停止 docker rm fastapi-container # 删除镜像 docker rmi fastapi-app:v1.05. 使用 Docker Compose 编排多服务应用实际项目往往不止一个 FastAPI 应用还需要数据库如 PostgreSQL、缓存如 Redis、消息队列等。Docker Compose 允许你用一个 YAML 文件定义和管理多个相关联的容器。5.1 编写 docker-compose.yml假设我们的应用需要连接一个 PostgreSQL 数据库。在项目根目录创建docker-compose.yml文件。# docker-compose.yml version: 3.8 # 指定 Compose 文件格式版本 services: # FastAPI 应用服务 web: build: . # 使用当前目录的 Dockerfile 构建镜像 container_name: fastapi-web ports: - 8000:8000 # 映射端口 environment: # 设置环境变量会被注入到容器中 - DATABASE_URLpostgresql://app_user:app_passworddb:5432/app_db depends_on: # 定义依赖关系确保 db 服务先启动 - db volumes: # 挂载代码目录实现开发时代码热重载仅开发环境使用 # - ./app:/app/app # 健康检查确保服务就绪 healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 3 start_period: 40s networks: - app-network # PostgreSQL 数据库服务 db: image: postgres:15-alpine # 使用官方的 PostgreSQL Alpine 镜像体积小 container_name: fastapi-db environment: - POSTGRES_USERapp_user - POSTGRES_PASSWORDapp_password - POSTGRES_DBapp_db volumes: # 将数据库数据持久化到宿主机避免容器删除后数据丢失 - postgres_data:/var/lib/postgresql/data networks: - app-network # 通常数据库不需要对外暴露端口只在内部网络访问 # ports: # - 5432:5432 # 如果需要从宿主机连接可以取消注释 # 定义命名数据卷用于持久化数据库数据 volumes: postgres_data: # 定义自定义网络方便服务间通过服务名通信 networks: app-network: driver: bridge5.2 更新 FastAPI 应用以连接数据库为了演示我们修改app/main.py添加一个简单的数据库连接和端点。# app/main.py (更新版) from fastapi import FastAPI, Depends from sqlalchemy import create_engine, Column, Integer, String from sqlalchemy.ext.declarative import declarative_base from sqlalchemy.orm import sessionmaker, Session import os # 从环境变量读取数据库连接字符串 DATABASE_URL os.getenv(DATABASE_URL, sqlite:///./test.db) # 创建 SQLAlchemy 引擎和会话 engine create_engine(DATABASE_URL) SessionLocal sessionmaker(autocommitFalse, autoflushFalse, bindengine) Base declarative_base() # 定义数据模型 class Item(Base): __tablename__ items id Column(Integer, primary_keyTrue, indexTrue) name Column(String, indexTrue) # 创建数据库表在实际项目中通常使用 Alembic 进行迁移 Base.metadata.create_all(bindengine) app FastAPI(titleFastAPI Docker Compose Demo, version1.0.0) # 依赖项获取数据库会话 def get_db(): db SessionLocal() try: yield db finally: db.close() app.get(/) async def root(): return {message: Hello from FastAPI with Docker Compose!} app.get(/items/) async def read_items(db: Session Depends(get_db)): # 这是一个简单的示例实际逻辑可能更复杂 items db.query(Item).all() return {items: items} app.get(/health) async def health_check(db: Session Depends(get_db)): # 简单的健康检查尝试执行一个简单的数据库查询 try: db.execute(SELECT 1) return {status: healthy, database: connected} except Exception as e: return {status: unhealthy, database: disconnected, error: str(e)}同时更新requirements.txt添加 SQLAlchemy 和 PostgreSQL 驱动。fastapi0.104.1 uvicorn[standard]0.24.0 sqlalchemy2.0.23 psycopg2-binary2.9.9 # 用于连接 PostgreSQL5.3 使用 Docker Compose 启动服务在包含docker-compose.yml的目录下运行以下命令# 构建镜像并启动所有服务-d 表示后台运行 docker-compose up -d # 查看所有服务的运行状态和日志 docker-compose ps docker-compose logs -f # -f 跟随日志输出 # 停止并移除所有服务同时会移除容器和网络但默认保留数据卷 docker-compose down # 停止并移除所有服务同时删除数据卷警告这会清除数据库数据 # docker-compose down -v启动后访问http://localhost:8000/items/应该能看到一个空的物品列表。访问/docs可以看到新增的端点。数据库数据会持久化在名为fastapi-docker-demo_postgres_data的 Docker 卷中。6. 生产环境部署最佳实践将容器化的 FastAPI 应用部署到生产环境如云服务器、Kubernetes时需要考虑更多因素。6.1 镜像优化与安全使用更小的基础镜像如python:3.11-alpine。Alpine Linux 体积极小但某些二进制依赖可能需要额外安装。多阶段构建如前文所示这是减小镜像体积的金标准。使用非 root 用户务必在 Dockerfile 中创建并使用非 root 用户运行进程。定期更新基础镜像定期重建镜像以获取基础镜像中的安全更新。扫描镜像漏洞使用docker scan或第三方工具如 Trivy、Clair扫描镜像中的已知漏洞。6.2 配置管理使用环境变量所有配置如数据库连接字符串、API密钥、日志级别都应通过环境变量注入而不是硬编码在代码或镜像中。Docker Compose 的environment或 Kubernetes 的ConfigMap/Secret是常用方式。区分环境配置为开发、测试、生产环境准备不同的docker-compose.override.yml或 Helm values 文件。6.3 日志与监控日志输出到标准流确保应用日志输出到stdout和stderrDocker 会自动捕获并可通过docker logs或日志驱动如json-file,journald, 或转发到 ELK/EFK 栈收集。添加健康检查如 Docker Compose 示例所示为服务定义healthcheck便于编排工具如 Docker Compose, Kubernetes判断服务是否就绪。集成监控在应用中集成 Prometheus 客户端库如prometheus-fastapi-instrumentator暴露 metrics 端点方便 Prometheus 抓取和 Grafana 展示。6.4 性能与可扩展性使用 Gunicorn 作为进程管理器对于生产环境通常使用 Uvicorn 的 Worker 类运行在 Gunicorn 后面以利用多核 CPU 和提供更强的进程管理。修改Dockerfile中的CMDCMD [gunicorn, -k, uvicorn.workers.UvicornWorker, -c, /app/gunicorn_conf.py, app.main:app]创建gunicorn_conf.py配置文件设置 worker 数量、超时时间等。设置资源限制在docker run或docker-compose.yml中使用--memory,--cpus或deploy.resources限制容器可用的 CPU 和内存防止单个容器耗尽主机资源。考虑无状态设计确保应用本身是无状态的会话数据应存储在外部服务如 Redis中。这样便于水平扩展。7. 常见问题与排查思路在 Docker 化部署 FastAPI 的过程中你可能会遇到一些典型问题。问题现象可能原因排查步骤与解决方案docker build失败提示pip install错误1. 网络问题无法访问 PyPI。2.requirements.txt中存在不兼容或错误的包版本。3. 基础镜像缺少编译依赖如gcc。1. 检查网络或为 pip 配置国内镜像源在 Dockerfile 的RUN pip install前添加RUN pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple。2. 在本地虚拟环境中测试pip install -r requirements.txt。3. 对于需要编译的包如psycopg2在slim镜像中可能需要先安装系统依赖RUN apt-get update apt-get install -y gcc python3-dev。docker run后访问localhost:8000连接被拒绝1. 容器没有成功启动。2. 端口映射错误。3. 应用在容器内监听的不是0.0.0.0。1. 运行docker ps查看容器状态docker logs 容器名查看启动日志。2. 检查docker run -p或docker-compose.yml中的端口映射配置确认宿主机端口是否被占用。3. 确保 FastAPI 应用通过 Uvicorn 启动时指定了--host 0.0.0.0在 Dockerfile 的 CMD 中。应用无法连接数据库在 Docker Compose 中1. 数据库服务未启动或启动失败。2. 环境变量DATABASE_URL配置错误。3. 网络配置问题应用容器无法通过服务名db解析到数据库容器。1. 运行docker-compose logs db查看数据库日志。2. 检查docker-compose.yml中web服务的environment配置确认主机名、端口、用户名、密码、数据库名正确。3. 确保web和db服务在同一个自定义网络如app-network下。可以进入应用容器docker-compose exec web bash尝试ping db。容器内应用代码修改后不生效Docker 镜像层是只读的。构建后代码被固化在镜像中。开发模式使用volumes挂载宿主机代码目录到容器见docker-compose.yml中注释掉的部分实现代码热重载。生产模式任何代码变更都需要重新构建镜像docker build并部署新容器。docker-compose up提示端口已被占用宿主机上已有其他进程占用了 Compose 文件中定义的端口如 8000, 5432。1. 修改docker-compose.yml中的端口映射例如将“8000:8000”改为“8080:8000”。2. 停止并移除占用端口的进程或其他容器。镜像体积过大1. 使用了完整版基础镜像如python:3.11。2. 构建过程中产生了大量缓存和中间文件。1. 换用slim或alpine变体。2. 采用多阶段构建。3. 在RUN命令中合并 apt-get 操作并清理缓存 apt-get clean rm -rf /var/lib/apt/lists/*。4. 使用.dockerignore文件排除构建上下文中的不必要的文件如__pycache__,.git,.venv。创建一个.dockerignore文件能有效减小构建上下文大小加速构建# .dockerignore __pycache__/ *.pyc *.pyo *.pyd .Python .env .venv venv/ ENV/ env/ .git/ .gitignore README.md Dockerfile* docker-compose* .vscode/ .idea/ *.log通过以上步骤你已经掌握了将 FastAPI 项目进行 Docker 化部署的核心技能。从编写高效的 Dockerfile 到使用 Docker Compose 管理多服务应用再到为生产环境做准备这套流程能显著提升你的应用部署效率和可靠性。记住容器化只是第一步结合 CI/CD 流水线如 GitHub Actions, GitLab CI实现自动化构建和部署才能真正发挥其威力。接下来你可以尝试将构建好的镜像推送到 Docker Hub 或私有镜像仓库并在云服务器或 Kubernetes 集群上进行部署实践。