Docker容器化部署FastAPI项目：从开发到生产实践

基于YOLOv11无人机检测项目的实战经验总结

近期要离线部署python写的后端项目，容器化部署是最佳方案，可以避免环境不一致导致程序不能运行的问题，记录一下。以基于YOLOv11的VisDrone数据集目标检测API服务为例，展示从Dockerfile编写到镜像构建、运行的完整流程。

我的操作系统是ubuntu24.04，在amd64和arm64上都进行了尝试

1. 为什么选择Docker部署FastAPI？

在传统的应用部署中，环境配置差异常常导致"在我这里能运行，在服务器上就不行"的问题。Docker通过容器化技术解决了这一痛点，它将应用及其所有依赖项打包到一个标准化的单元中，确保环境一致性。

Docker的优势：

环境一致性：开发、测试、生产环境完全一致
快速部署：镜像构建完成后可一键部署
资源隔离：容器之间相互隔离，互不影响
易于扩展：结合编排工具可实现自动扩缩容

2. 项目结构与准备

以我们的YOLO检测API项目为例，典型结构如下：

复制代码

yolo-api/
├── main.py                 # FastAPI主应用文件
├── requirements.txt        # Python依赖列表
├── core/                   # 核心配置
├── services/               # 业务服务层
├── routers/                # API路由
├── models/                 # 机器学习模型文件
└── schemas/                # 数据模型定义

在开始Docker化前，需要确保项目在本地开发环境能够正常运行。

3. Dockerfile详细解析

下面是针对Python FastAPI项目优化的Dockerfile：

复制代码

# 使用官方Python运行时作为父镜像
FROM python:3.12.12-slim

# 设置镜像元数据
LABEL authors="huangg"
LABEL description="YOLOv11无人机检测API服务"
LABEL version="1.0"

# 设置环境变量
ENV PYTHONUNBUFFERED=1 

# 设置工作目录
WORKDIR /app

# 复制依赖文件（利用Docker缓存层）
COPY requirements.txt .

# 安装系统依赖（如有需要）
RUN apt-get update && \
    rm -rf /var/lib/apt/lists/*

# 安装Python依赖（先安装PyTorch等复杂依赖）
RUN pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu124
RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 8002

# 定义健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/health || exit 1

# 启动应用
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8002"]

关键指令说明：

分层优化：将变动频繁的操作放在Dockerfile后面，充分利用缓存
多阶段构建：对于复杂项目可考虑多阶段构建减小镜像体积
依赖管理：先安装PyTorch等大型包，再安装其他依赖

需要说明的是，fastapi项目入口文件main.py中不一定是8002这个端口，在dockerfile里面配置好指定的端口就行了，不要再修改main.py中的端口了

另外需要说明的是，RUN pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu124可能会报错，比如在arm上执行这个，就报错：

bash 复制代码

ERROR: Could not find a version that satisfies the requirement torchvision==0.19.1 (from versions: 0.1.6, 0.2.0, 0.17.0, 0.20.0, 0.20.1)
ERROR: No matching distribution found for torchvision==0.19.1

可以尝试换成有的版本，比如0.20.1，经过几番尝试，在当前操作系统（Ubuntu24.04，arm64）下，下面的pip是可行的

bash 复制代码

pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 --index-url https://download.pytorch.org/whl/cu124

4. 关键配置文件

4.1 requirements.txt依赖管理

对于包含机器学习框架的项目，建议将PyTorch等框架单独安装（最好把那三个注释起来的依赖删掉，这个是我用pip freeze > requirements.txt生成的依赖）：

复制代码

annotated-doc==0.0.4
annotated-types==0.7.0
anyio==4.12.1
certifi==2026.1.4
charset-normalizer==3.4.4
click==8.3.1
colorama==0.4.6
contourpy==1.3.3
cycler==0.12.1
fastapi==0.128.0
filelock==3.20.0
fonttools==4.61.1
fsspec==2025.12.0
h11==0.16.0
idna==3.11
Jinja2==3.1.6
kiwisolver==1.4.9
MarkupSafe==2.1.5
matplotlib==3.10.8
mpmath==1.3.0
networkx==3.6.1
numpy==2.2.6
opencv-python==4.12.0.88
packaging==25.0
pillow==12.0.0
polars==1.37.1
polars-runtime-32==1.37.1
psutil==7.2.1
pydantic==2.12.5
pydantic-settings==2.12.0
pydantic_core==2.41.5
pyparsing==3.3.1
python-dateutil==2.9.0.post0
python-dotenv==1.2.1
python-multipart==0.0.21
PyYAML==6.0.3
requests==2.32.5
scipy==1.17.0
setuptools==80.9.0
six==1.17.0
starlette==0.50.0
sympy==1.14.0
# torch==2.4.1+cu124
# torchaudio==2.4.1+cu124
# torchvision==0.19.1+cu124
tqdm==4.67.1
typing-inspection==0.4.2
typing_extensions==4.15.0
ultralytics==8.3.252
ultralytics-thop==2.0.18
urllib3==2.6.3
uvicorn==0.40.0
wheel==0.45.1

4.2 .dockerignore文件

创建.dockerignore文件避免不必要的文件被复制到镜像中：

复制代码

__pycache__
*.pyc
*.pyo
*.pyd
.Python
env/
venv/
.venv/
.git/
.DS_Store
models/pretrained/  # 大型模型文件建议运行时下载

5. 镜像构建与运行

5.1 构建Docker镜像

复制代码

# 构建镜像
docker build -t yolo-fastapi:latest .

# 查看镜像
docker images

5.2 运行容器

复制代码

# 开发环境运行
docker run -d -p 8002:8002 --name yolo-api yolo-fastapi:latest

# 生产环境运行（添加资源限制）
docker run -d \
  -p 8000:8000 \
  --name yolo-api \
  --memory=4g \
  --cpus=2 \
  yolo-fastapi:latest

5.3 服务验证

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

复制代码

# 检查容器状态
docker ps

# 查看日志
docker logs yolo-api

# 测试健康检查接口
curl http://localhost:8000/health

# 访问API文档
# http://localhost:8000/docs

6. 常见问题与解决方案

6.1 pip依赖安装超时问题

问题：在构建过程中pip安装依赖超时

解决方案：使用国内镜像源并设置超时时间

复制代码

RUN pip install --timeout=300 -r requirements.txt \
    -i https://pypi.tuna.tsinghua.edu.cn/simple/

6.2 docker拉基础镜像失败

问题：国内环境拉docker基础镜像十次有9次不成功

解决方案：

修改docker的镜像源，修改/etc/docker/daemon.json

目前我可用的一个源列表如下：

bash 复制代码

(base) root@aipc:~# cat /etc/docker/daemon.json
{
  "exec-opts": ["native.cgroupdriver=cgroupfs"],
    "runtimes": {
      "nvidia": {
        "args": [],
        "path": "nvidia-container-runtime"
      }
    },
   "registry-mirrors": [
     "https://docker.registry.cyou",
     "https://docker-cf.registry.cyou",
     "https://dockercf.jsdelivr.fyi",
     "https://docker.jsdelivr.fyi",
     "https://dockertest.jsdelivr.fyi",
     "https://mirror.aliyuncs.com",
     "https://dockerproxy.com",
     "https://mirror.baidubce.com",
     "https://docker.m.daocloud.io",
     "https://docker.nju.edu.cn",
     "https://docker.mirrors.sjtug.sjtu.edu.cn",
     "https://docker.mirrors.ustc.edu.cn",
     "https://mirror.iscas.ac.cn",
     "https://docker.rainbond.cc"
   ]
}

7. 运行容器

命令：

bash 复制代码

docker run -d --restart=unless-stopped --name tmri-yolo-recognition-api -p 8002:8002 tmri-yolo-recognition-api

查看容器运行状态：

bash 复制代码

(base) root@aipc:/home/huangg/yolo-api# docker ps -a
CONTAINER ID   IMAGE                       COMMAND                  CREATED         STATUS         PORTS                                                                                                                                                                                                                    NAMES
cebab6effdb0   tmri-yolo-recognition-api   "uvicorn main:app --..."   9 seconds ago   Up 9 seconds   0.0.0.0:8002->8002/tcp, :::8002->8002/tcp                                                                                                                                                                                tmri-yolo-recognition-api

如果一切ok的话，应该是上面的输出，但是实际上我报错了很多次，有几次是因为pytorch安装失败，有一次是因为缺少opencv的C++库

我再上一遍我的dockerfile

dockerfile 复制代码

FROM python:3.12.12-slim
LABEL authors="huangg"

ENV PYTHONUNBUFFERED=1

RUN apt-get update && apt-get install -y \
    libgl1 \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

COPY requirements.txt .

RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/ --no-deps
RUN pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 --index-url https://download.pytorch.org/whl/cu124

COPY . .
RUN mkdir -p /app/logs

EXPOSE 8002

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

下面这段：

dockerfile 复制代码

RUN apt-get update && apt-get install -y \
    libgl1 \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    && rm -rf /var/lib/apt/lists/*

就是安装opencv基础库的命令

另外：

dockerfile 复制代码

RUN pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/ --no-deps
RUN pip install torch==2.5.0 torchvision==0.20.0 torchaudio==2.5.0 --index-url https://download.pytorch.org/whl/cu124

先安装python基础包，然后再安装pytorch，因为requirements.txt中涉及ultralytics会重复安装pytorch

可以查看这个容器的日志

可以看到，服务正常启动了，但是cuda却不可用，因为这个容器内我没有配置cuda的环境，由于运行yolo训练好的模型，gpu和cpu实际上没有太大区别，所以我暂时先不操作cuda了，后面再说

8. 接口测试

我用postman测了一下：

也都正常，至此，算是顺利打出了一个包

蛇年的最后一篇博客了，愿来年一切安好