零基础也能上手：Docker部署FastAPI项目全教程

FastAPI 是当下很受欢迎的高性能 Python Web 框架，搭配 Docker 打包部署能极大简化环境迁移问题。
本文从头演示 Docker部署FastAPI项目 的完整流程，每一步都给出可执行的命令和配置，即使是刚接触服务器的小白也能照着完成。

一、准备工作：你需要什么

在开始之前，确认以下条件已满足：

• 一台安装了 Linux 或 macOS 的服务器（Windows 也可以用 Docker Desktop，但命令略有差异）。
• Docker 已安装并启动。验证命令：docker --version 和 docker compose version（新版本推荐用 docker compose 而非 docker-compose）。
• 一个简单的 FastAPI 项目。如果你还没有，可以在本地创建如下文件结构。

my_fastapi_app/
├── main.py
├── requirements.txt
└── Dockerfile

main.py 示例：

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

requirements.txt：

fastapi
uvicorn[standard]

二、编写 Dockerfile：把项目打包成镜像

在项目根目录创建 Dockerfile，内容如下：

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

# 设置工作目录
WORKDIR /app

# 先把依赖文件复制进来，利用 Docker 缓存减少构建时间
COPY requirements.txt .

# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制项目代码
COPY . .

# 暴露容器端口（与 FastAPI 监听端口一致）
EXPOSE 8000

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

关键点说明：

• WORKDIR /app 切换工作目录，后续操作都在此目录中。
• 先复制 requirements.txt 再安装，这样在不修改依赖时能利用 Docker 层缓存。
• EXPOSE 8000 只是文档作用，真正映射端口在运行时通过 -p 参数指定。
• CMD 使用 uvicorn 启动，0.0.0.0 允许外部访问。

三、编写 docker-compose.yml（推荐方式）

虽然可以直接用 docker run，但用 docker compose 管理容器更方便。
在项目根目录创建 docker-compose.yml：

version: '3.8'

services:
  fastapi:
    build: .
    container_name: my_fastapi
    ports:
      - "8000:8000"
    volumes:
      - .:/app
    environment:
      - PYTHONDONTWRITEBYTECODE=1
      - PYTHONUNBUFFERED=1

配置解释：

• build: . 表示用当前目录下的 Dockerfile 构建镜像。
• container_name 自定义容器名称，方便识别。
• ports 把宿主机 8000 端口映射到容器内 8000。
• volumes 将本地代码挂载到容器内，方便开发时热重载（记得在 CMD 中加上 --reload）。但生产环境建议去掉 volumes，改用 COPY 构建镜像。
• environment 设置两个环境变量：禁止生成 .pyc 文件，以及禁止 Python 缓冲输出。

四、构建并运行容器

打开终端，进入项目目录，执行以下命令：

# 构建镜像并启动容器（后台运行）
docker compose up -d --build

首次构建会下载基础镜像、安装依赖，需要一点时间。
看到类似 Creating my_fastapi ... done 的消息说明启动成功。

验证服务是否运行：

docker ps

输出中应该能看到名为 my_fastapi 的容器，状态为 Up。

访问接口：
在浏览器打开 http://你的服务器IP:8000 ，或者用 curl：

curl http://localhost:8000

返回 {"Hello":"World"} 就说明 Docker部署FastAPI项目 成功了。

五、常见问题与避坑指南

5.1 端口被占用

如果宿主机 8000 端口已被其他程序占用，运行时会报错 port is already allocated。
解决：修改 docker-compose.yml 中的映射端口，例如 "8001:8000"，然后重新 docker compose up -d。

5.2 依赖安装失败

国内网络问题导致 pip install 超时。
可以在 Dockerfile 的 RUN 中添加国内镜像源：

RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

如果你用了 requirements.txt 以外的系统包，记得一并加入。

5.3 代码修改后不生效

开发阶段使用了 volumes 挂载，但 CMD 没有加 --reload。
修改 CMD 为：

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

然后重建容器：docker compose up -d --build。
注意 --reload 只推荐开发用，生产环境去掉。

5.4 容器启动后立即退出

用 docker logs my_fastapi 查看错误日志。
常见原因：main:app 导入出错，检查 main.py 中的 app 实例名称是否写对。
另外，确认 requirements.txt 路径正确。

六、生产环境优化建议

• 去掉 volumes 挂载，使用 COPY 构建镜像，避免源码泄露。
• 使用多阶段构建缩小镜像体积。
• 加一层反向代理（如 Nginx）处理 SSL 和静态文件。
• 设置容器重启策略：restart: always（在 docker-compose.yml 的 services 下添加）。

总结

通过以上步骤，你已经完成了从零开始的 Docker部署FastAPI项目 实践。
核心思路是：准备项目文件 → 编写 Dockerfile → 用 docker compose 管理 → 构建运行 → 验证接口。
遇到问题时先回看第五节的避坑点，基本都能解决。
掌握这个流程后，你可以轻松把自己的 FastAPI 应用容器化，并部署到任意支持 Docker 的服务器上。