这次我们来看一个 FastAPI 课程更新 Docker 部署内容的项目。对于正在学习或使用 FastAPI 构建 Web API 的开发者来说如何将开发好的应用稳定、高效地部署到生产环境是一个绕不开的实战环节。传统的部署方式依赖复杂的服务器环境配置而 Docker 容器化技术则提供了一套标准化的解决方案能极大简化部署流程提升应用的可移植性和一致性。这个课程更新的核心就是将 FastAPI 应用与 Docker 深度结合让你从“本地能跑”快速进阶到“随处可部署”。它不只是一个概念讲解而是聚焦于实操如何编写 Dockerfile、如何管理依赖、如何构建镜像、如何运行容器以及如何通过 Docker Compose 编排多服务应用比如搭配数据库。对于个人项目测试、团队协作交付或是需要快速搭建演示环境掌握这套流程都至关重要。本文会带你完整走通 FastAPI 应用的 Docker 化部署全流程。我们将从零开始准备一个简单的 FastAPI 应用然后为其编写 Dockerfile接着构建镜像并运行容器最后还会扩展到使用 Docker Compose 管理应用与数据库。无论你是想了解 Docker 部署的基本步骤还是希望优化现有的部署脚本这篇文章都能提供直接的参考。1. 核心能力速览在深入细节之前我们先通过下表快速了解本次课程内容覆盖的核心能力与要点能力项说明技术栈FastAPI (Python Web 框架) Docker (容器化平台)主要目标将 FastAPI 应用打包为 Docker 镜像实现一键部署与环境隔离环境门槛支持 Windows, macOS, Linux。需预先安装 Docker Desktop 或 Docker Engine。资源占用极小。基础镜像体积通常在 100MB ~ 300MB运行时内存占用主要取决于应用本身。启动方式命令行通过docker run启动或使用docker-compose up编排启动。核心功能1. 应用容器化打包2. 依赖隔离与环境固化3. 服务端口映射4. 多服务编排 (如 App DB)是否支持 API是。容器内运行的 FastAPI 应用自动提供 Swagger UI 和 ReDoc 接口文档。是否支持“批量任务”间接支持。可通过启动多个容器实例实现水平扩展或使用容器内后台任务。适合场景开发测试环境搭建、CI/CD 流水线、生产环境部署、微服务演示、避免“在我机器上能跑”问题。2. 适用场景与使用边界这个课程内容适合谁FastAPI 初学者在学会编写接口后迫切想知道如何把应用分享给别人或放到服务器上。全栈开发者希望用标准化方式部署后端 API前端通过固定地址调用。运维或 DevOps 工程师需要为团队提供可复现的、隔离的测试环境。项目管理者关注应用交付物是否独立于开发环境便于迁移和升级。能解决什么问题环境一致性问题解决因 Python 版本、系统库、依赖包版本不同导致的“开发环境正常测试/生产环境报错”。简化部署流程将复杂的安装配置步骤简化为一条docker run命令。快速搭建与清理秒级启动一个包含所有依赖的完整服务环境测试完毕后可彻底删除不留残留。微服务架构支撑为每个微服务如用户服务、订单服务构建独立镜像便于组合与扩展。不适合什么场景超轻量级单脚本如果一个 FastAPI 应用只有几个文件且无复杂依赖直接使用 Python 运行可能更简单。对容器技术有严格限制的环境某些受监管的或旧有体系可能不允许使用容器。追求极致性能的底层系统开发容器化带来的轻微开销可忽略不计在极端性能场景下可能需要考量。安全与合规边界镜像安全应使用官方或可信的基础镜像定期更新以修补安全漏洞。避免在镜像中硬编码密码、密钥等敏感信息应使用环境变量或 Docker 密文管理。网络与端口合理配置容器网络避免将内部服务端口无必要地暴露给公网。在生产环境中通常会在容器前放置 Nginx 等反向代理。数据持久化容器内产生的数据如上传的文件、数据库文件默认随容器删除而丢失。重要数据必须通过“卷Volume”挂载到宿主机。3. 环境准备与前置条件开始之前请确保你的本地开发环境满足以下条件。这是后续所有操作的基础。1. 操作系统Windows 10/11 专业版、企业版或教育版64位家庭版需要额外配置。macOS 10.15 或更高版本。Linux (Ubuntu, CentOS, Debian 等主流发行版)。2. Docker 环境这是最核心的依赖。你需要安装并成功运行 Docker。Windows/macOS推荐安装 Docker Desktop 。安装后在终端PowerShell, CMD 或 Terminal运行docker --version验证。Linux根据发行版使用包管理器安装 Docker Engine例如 Ubuntu 可使用apt-get install docker.io。安装后可能需要将当前用户加入docker组以避免使用sudo。验证 Docker 安装打开终端输入以下命令docker --version docker run hello-world如果能看到 Docker 版本号并且hello-world镜像成功运行并输出欢迎信息说明 Docker 安装正确。3. Python 环境仅用于本地开发虽然最终应用运行在容器内但本地开发、编写代码和测试仍需 Python。Python 版本建议 Python 3.8 及以上FastAPI 对高版本支持良好。包管理工具使用pip即可。建议使用虚拟环境venv 或 conda隔离项目依赖。4. 代码编辑器任何你熟悉的编辑器即可如 VS Code, PyCharm, Sublime Text 等。5. 网络连接首次构建 Docker 镜像时需要从 Docker Hub 拉取基础镜像如python:3.11-slim请确保网络通畅。4. 安装部署与启动方式我们将从一个最简单的 FastAPI 应用开始逐步完成 Docker 化。整个过程分为三步准备应用、编写 Dockerfile、构建与运行。4.1 准备 FastAPI 应用首先创建一个项目目录例如fastapi-docker-demo并在其中创建应用文件。项目结构fastapi-docker-demo/ ├── app/ │ ├── __init__.py │ └── main.py ├── requirements.txt └── Dockerfile1. 创建主应用文件 (app/main.py)这是一个标准的 FastAPI 应用包含两个简单的端点。from fastapi import FastAPI from pydantic import BaseModel app FastAPI(titleFastAPI Docker Demo, version1.0.0) class Item(BaseModel): name: str price: float app.get(/) def read_root(): return {message: Hello from FastAPI inside Docker!} app.get(/items/{item_id}) def read_item(item_id: int, q: str None): return {item_id: item_id, q: q} app.post(/items/) def create_item(item: Item): return {item_name: item.name, item_price: item.price}2. 创建依赖文件 (requirements.txt)列出项目运行所需的所有 Python 包。fastapi0.104.1 uvicorn[standard]0.24.0这里我们使用 Uvicorn 作为 ASGI 服务器来运行 FastAPI。4.2 编写 DockerfileDockerfile 是构建镜像的蓝图。在项目根目录创建Dockerfile无后缀名。# 使用官方 Python 轻量级镜像作为基础 FROM python:3.11-slim # 设置工作目录后续命令都在此目录下执行 WORKDIR /app # 将依赖文件复制到工作目录 COPY requirements.txt . # 安装 Python 依赖使用清华镜像加速可选 RUN pip install --no-cache-dir -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt # 将应用代码复制到工作目录 COPY ./app ./app # 声明容器运行时监听的端口FastAPI 默认在 8000 端口运行 EXPOSE 8000 # 定义容器启动时执行的命令 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]Dockerfile 关键指令解析FROM指定基础镜像我们选择了包含 Python 3.11 的轻量级slim版本。WORKDIR设置容器内的工作目录相当于cd /app。COPY将本地文件复制到镜像中。先复制requirements.txt是为了利用 Docker 的缓存层依赖未变更时无需重复安装。RUN在构建镜像时执行的命令这里用于安装依赖。EXPOSE声明容器打算使用的端口这是一个文档性质的指令实际映射在docker run时指定。CMD指定容器启动后默认运行的命令。这里启动 Uvicorn 服务器监听所有网络接口 (0.0.0.0)。4.3 构建 Docker 镜像在包含Dockerfile的目录项目根目录打开终端执行构建命令。# -t 参数给镜像打标签格式为 名称:版本这里使用 latest 表示最新版本 docker build -t fastapi-demo:latest .命令最后的.表示构建上下文是当前目录。构建过程观察Docker 会逐行执行 Dockerfile 中的指令每一层都会缓存。首次构建需要下载基础镜像和安装依赖耗时稍长。后续如果只修改了应用代码 (app/main.py)由于依赖层缓存存在重建速度会非常快。4.4 运行 Docker 容器镜像构建成功后就可以基于它运行一个容器实例。# 最基本的运行命令 docker run -d --name my-fastapi-app -p 8000:8000 fastapi-demo:latest命令参数解析-d后台运行容器detached mode。--name给容器起一个名字便于后续管理启动、停止、查看日志。-p端口映射格式为宿主机端口:容器端口。这里将宿主机的 8000 端口映射到容器的 8000 端口。fastapi-demo:latest指定要运行的镜像名称和标签。验证服务运行查看容器状态docker ps应能看到名为my-fastapi-app的容器正在运行。访问应用打开浏览器访问http://localhost:8000。你应该看到{message:Hello from FastAPI inside Docker!}的 JSON 响应。访问交互式文档FastAPI 自动生成了 API 文档。访问http://localhost:8000/docs(Swagger UI) 或http://localhost:8000/redoc(ReDoc)可以查看和测试所有接口。至此一个最简单的 FastAPI Docker 部署就完成了。你的应用现在运行在一个与宿主机环境隔离的容器中。5. 功能测试与效果验证部署完成后我们需要验证应用功能是否完整以及 Docker 部署带来的特性。5.1 基础 API 端点测试我们可以使用curl命令或直接在浏览器的 Swagger UI 中进行测试。1. 测试根路径 (GET /):curl http://localhost:8000/预期返回{message:Hello from FastAPI inside Docker!}2. 测试路径参数与查询参数 (GET /items/{item_id}):curl http://localhost:8000/items/123?qtestquery预期返回{item_id:123,q:testquery}3. 测试请求体 (POST /items/):curl -X POST http://localhost:8000/items/ \ -H Content-Type: application/json \ -d {name:Laptop,price:999.99}预期返回{item_name:Laptop,item_price:999.99}判断成功标准所有接口均返回正确的 HTTP 状态码200和符合预期的 JSON 数据。5.2 容器化特性验证1. 环境隔离验证在宿主机上尝试运行python --version或pip list其版本和包列表与容器内是独立的。进入容器内部查看# 进入正在运行的容器内部 docker exec -it my-fastapi-app /bin/bash # 容器内执行 python --version pip list exit你会发现容器内只有我们在requirements.txt中定义的fastapi和uvicorn环境非常纯净。2. 服务停止与重启# 停止容器 docker stop my-fastapi-app # 此时访问 http://localhost:8000 会失败 # 重新启动容器 docker start my-fastapi-app # 服务恢复可再次访问这模拟了服务器重启或服务进程异常退出的恢复场景。3. 容器删除与重建# 停止并删除容器 docker stop my-fastapi-app docker rm my-fastapi-app # 基于已有的镜像重新运行一个新容器可以换一个名字和端口 docker run -d --name my-fastapi-app-v2 -p 8080:8000 fastapi-demo:latest现在应用运行在宿主机的 8080 端口 (http://localhost:8080)。这证明了镜像作为“不可变基础设施”的价值无论容器如何销毁重建只要镜像不变运行起来的环境就是完全一致的。5.3 常见失败原因与排查问题现象可能原因排查方式docker build失败提示pip install错误1. 网络问题无法访问 PyPI。2.requirements.txt中包名或版本不存在。1. 检查网络或更换 pip 源如 Dockerfile 中已使用清华源。2. 在本地虚拟环境中手动pip install -r requirements.txt测试。docker run失败提示port is already allocated宿主机 8000 端口被其他程序占用。1. 使用netstat -ano | findstr :8000(Win) 或lsof -i :8000(Mac/Linux) 查找占用进程。2. 更改-p参数如-p 8001:8000。访问localhost:8000连接被拒绝1. 容器未成功启动。2. 防火墙或安全组阻止。1. 运行docker ps查看容器状态docker logs my-fastapi-app查看启动日志。2. 检查宿主机防火墙设置。应用启动报错ModuleNotFoundError1.requirements.txt未包含某些隐式依赖。2. Dockerfile 中COPY命令路径错误代码未复制进去。1. 检查完整错误日志将缺失的包加入requirements.txt。2. 检查 Dockerfile 中COPY ./app ./app的路径是否正确。6. 接口 API 与批量任务FastAPI 应用本身就是一个 API 服务。Docker 化之后这个服务变得更加标准化和易于集成。6.1 标准化 API 访问容器化后API 的访问地址变得固定由宿主机 IP 和映射端口决定。其他服务如前端应用、移动端、或其他微服务可以通过这个固定地址调用 API。Python 客户端调用示例import requests import time BASE_URL http://localhost:8000 # 如果部署在服务器替换为服务器IP:端口 # 1. 测试健康检查或根路径 def test_health(): try: resp requests.get(f{BASE_URL}/, timeout5) resp.raise_for_status() print(f服务健康: {resp.json()}) return True except requests.exceptions.RequestException as e: print(f服务不可达: {e}) return False # 2. 批量创建项目模拟批量任务 def batch_create_items(item_list): created_items [] for item_data in item_list: # 可以加入延时避免请求过快 # time.sleep(0.1) try: resp requests.post( f{BASE_URL}/items/, jsonitem_data, timeout10 ) if resp.status_code 200: created_items.append(resp.json()) print(f创建成功: {item_data[name]}) else: print(f创建失败 {resp.status_code}: {item_data[name]}) except Exception as e: print(f请求异常: {e}) return created_items if __name__ __main__: if test_health(): items_to_create [ {name: Item_A, price: 10.5}, {name: Item_B, price: 25.0}, {name: Item_C, price: 99.99}, ] results batch_create_items(items_to_create) print(f批量创建完成成功 {len(results)} 项)6.2 容器内的“批量任务”与后台处理有时应用本身需要执行一些后台或批量任务如数据处理、报告生成。在 Docker 中有几种模式1. 作为主进程的一部分在 FastAPI 应用启动时使用BackgroundTasks或像Celery这样的异步任务队列。任务逻辑在同一个容器内执行。这种方式简单但任务失败可能导致主应用受影响。2. 作为独立的“工作容器”为批量任务单独创建一个 Docker 镜像和容器。这个“工作容器”可以从消息队列如 Redis/RabbitMQ中获取任务处理完毕后写入数据库或存储。它与主 API 容器通过网络和共享存储Volume通信。这是更解耦、更健壮的生产级做法。3. 使用 Docker Compose 编排这是管理多容器应用API Worker DB Redis的标准方式我们将在下一节详细展开。7. 资源占用与性能观察将 FastAPI 应用 Docker 化后我们需要关注其运行时资源消耗。7.1 观察容器资源占用使用 Docker 自带的命令可以方便地监控容器状态。# 查看所有容器的实时资源占用类似 top 命令 docker stats # 查看指定容器的详细信息包括资源限制、网络配置等 docker inspect my-fastapi-app # 查看容器的进程列表 docker top my-fastapi-app运行docker stats你会看到类似下面的输出包含了 CPU、内存、网络 I/O、块 I/O 的实时数据CONTAINER ID NAME CPU % MEM USAGE / LIMIT MEM % NET I/O BLOCK I/O PIDS a1b2c3d4e5f6 my-fastapi-app 0.05% 45.32MiB / 1.94GiB 2.28% 1.12kB / 0B 0B / 0B 3对于一个简单的 FastAPI 应用内存占用通常在 50MB - 150MB 之间CPU 在空闲时接近 0%。性能开销主要来自应用逻辑和网络吞吐容器化本身带来的损耗极小通常 1%-3%。7.2 性能调优与配置1. 镜像体积优化我们之前使用的python:3.11-slim镜像已经比较小。还可以使用更极致的python:3.11-alpine镜像基于 Alpine Linux但需注意 Alpine 使用 musl libc某些依赖可能需要额外编译。优化后的 Dockerfile 示例# 使用多阶段构建进一步减小最终镜像体积 FROM python:3.11-slim as builder WORKDIR /app COPY requirements.txt . RUN pip install --user --no-cache-dir -r requirements.txt FROM python:3.11-slim WORKDIR /app # 从构建阶段只复制安装好的包 COPY --frombuilder /root/.local /root/.local # 确保 pip 安装的包在 PATH 中 ENV PATH/root/.local/bin:$PATH COPY ./app ./app EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]2. 容器资源限制在生产环境中应为容器设置资源上限防止单个容器耗尽主机资源。# 运行容器时限制 CPU 和内存 docker run -d --name my-app-limited \ --cpus0.5 \ # 最多使用 0.5 个 CPU 核心 --memory256m \ # 内存限制为 256 MB -p 8000:8000 \ fastapi-demo:latest3. 端口冲突处理如果默认的 8000 端口被占用在docker run时映射到其他端口即可例如-p 8080:8000。应用本身监听的容器内端口8000在 Dockerfile 的CMD中定义一般无需修改。8. 使用 Docker Compose 编排多服务应用实际项目往往不止一个 FastAPI 应用还需要数据库如 PostgreSQL、MySQL、缓存如 Redis、消息队列等。Docker Compose 允许你使用一个 YAML 文件来定义和运行多个相关联的容器。8.1 编写 docker-compose.yml在项目根目录创建docker-compose.yml文件。version: 3.8 services: # FastAPI 应用服务 web: build: . # 使用当前目录的 Dockerfile 构建镜像 container_name: fastapi-web ports: - 8000:8000 environment: - DATABASE_URLpostgresql://user:passworddb:5432/mydb depends_on: - db # 设置卷将本地代码目录挂载到容器便于开发时热重载 volumes: - ./app:/app/app # 开发时使用 --reload 参数代码修改后自动重启 command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload # PostgreSQL 数据库服务 db: image: postgres:15-alpine container_name: fastapi-db environment: POSTGRES_USER: user POSTGRES_PASSWORD: password POSTGRES_DB: mydb volumes: # 将数据库数据持久化到宿主机避免容器删除后数据丢失 - postgres_data:/var/lib/postgresql/data ports: - 5432:5432 # 暴露端口便于本地连接工具访问 # Redis 缓存服务可选 redis: image: redis:7-alpine container_name: fastapi-redis ports: - 6379:6379 # 定义命名卷用于数据持久化 volumes: postgres_data:8.2 启动与管理多服务# 在 docker-compose.yml 所在目录执行 # 启动所有服务后台运行 docker-compose up -d # 查看运行状态 docker-compose ps # 查看所有服务的日志 docker-compose logs # 查看特定服务如 web的日志 docker-compose logs -f web # 停止所有服务 docker-compose down # 停止服务并删除数据卷谨慎使用会清除数据库数据 docker-compose down -v使用 Docker Compose 后你只需一个命令就能拉起一个包含应用、数据库、缓存等的完整开发环境并且服务间可以通过服务名如db,redis进行网络通信无需关心 IP 地址。9. 常见问题与排查方法在 Docker 化 FastAPI 应用的过程中你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案构建失败pip install超时或错误网络连接 Docker Hub 或 PyPI 不稳定。查看构建日志错误信息通常包含Could not fetch URL或Timeout。1. 在 Dockerfile 的RUN pip install命令中更换国内镜像源如清华源、阿里云源。2. 使用公司或个人的私有镜像仓库。运行失败Address already in use宿主机端口已被其他进程占用。使用netstat -ano | findstr :端口号或lsof -i :端口号查找占用进程。1. 停止占用端口的进程。2. 修改docker run -p或docker-compose.yml中的宿主机端口映射。容器启动后立即退出1. 应用启动命令CMD执行错误。2. 应用本身启动失败如依赖缺失。docker logs 容器名查看容器日志通常会有具体的错误堆栈。1. 检查 Dockerfile 中的CMD或ENTRYPOINT命令是否正确。2. 根据日志错误修复代码或依赖问题。3. 可以尝试用docker run -it 镜像名 /bin/sh进入交互模式手动调试。应用代码修改后容器内未更新未使用卷挂载Volume或未启用热重载。容器内的代码是构建镜像时复制的后续本地修改不会自动同步。开发模式在docker-compose.yml中使用volumes挂载代码目录并在启动命令中添加--reload参数。生产模式需要重新构建镜像并运行新容器。容器内应用无法连接localhost上的数据库容器有独立的网络命名空间localhost指向容器自身。理解 Docker 网络模型。使用 Docker Compose 时通过服务名如db访问。直接使用docker run时需使用 Docker 网络或宿主机特殊域名host.docker.internal(Mac/Windows) 或172.17.0.1(Linux Docker 网桥网关) 来访问宿主机服务。docker-compose命令未找到Docker Desktop 默认包含 Compose。Linux 可能需要单独安装。在终端运行docker-compose --version。Windows/Mac确保 Docker Desktop 已安装并运行。Linux根据发行版安装docker-compose插件或独立版本。磁盘空间不足频繁构建镜像会产生大量中间层和悬虚镜像。运行docker system df查看 Docker 磁盘使用情况。定期清理docker image prune删除悬虚镜像。docker system prune -a清理所有未使用的资源谨慎会删除未运行的容器和未使用的镜像。10. 最佳实践与使用建议遵循以下实践能让你的 FastAPI Docker 部署更加稳健、高效。分层构建与缓存利用像我们之前的 Dockerfile 那样先复制requirements.txt并安装依赖再复制应用代码。这样当代码变更而依赖未变时Docker 可以利用缓存跳过耗时的依赖安装步骤极大加速构建。使用.dockerignore文件在项目根目录创建.dockerignore排除不需要复制到镜像中的文件如__pycache__,.git,.venv,*.log,*.pyc可以减小镜像体积提高构建速度。__pycache__/ *.pyc .git .venv .env *.log Dockerfile docker-compose.yml README.md环境变量管理切勿将敏感信息数据库密码、API密钥硬编码在代码或 Dockerfile 中。应通过environment在docker run或docker-compose.yml中注入或使用 Docker Secrets、专门的配置管理服务。生产环境优化镜像使用多阶段构建并选择-alpine或-slim等小体积基础镜像。服务器关闭 Uvicorn 的--reload选项使用更高效的 ASGI 服务器如 Gunicorn 搭配 Uvicorn Worker。日志确保应用日志输出到标准输出stdout和标准错误stderr这样 Docker 可以捕获并可通过docker logs查看。健康检查在 Dockerfile 或 Compose 文件中配置HEALTHCHECK指令让容器编排工具能感知应用健康状态。开发与生产配置分离准备两套 Compose 文件如docker-compose.yml(开发) 和docker-compose.prod.yml(生产)。开发配置注重热重载和调试便利生产配置注重性能、安全性和资源限制。版本化与标签为镜像打上有意义的标签而不仅仅是latest。例如使用 Git 提交哈希或语义化版本号myapp:v1.2.3,myapp:git-abc1234。这便于回滚和追踪。将 FastAPI 应用 Docker 化是迈向现代化应用部署和运维的关键一步。它带来的环境一致性、隔离性和可移植性能显著提升开发体验和部署可靠性。从最简单的单容器部署到使用 Docker Compose 管理复杂应用栈这套流程已经成为云原生时代的通用技能。建议你从手头的一个小项目开始实践先跑通整个流程再逐步探索镜像仓库、CI/CD 集成等更进阶的主题。当你能够熟练地将任何 Python 应用打包成 Docker 镜像时你就拥有了在任何地方快速交付服务的能力。