避坑指南：使用 Docker 部署 Python Flask 项目的完整实战记录

在将 Python Flask 项目容器化部署的过程中，往往会遇到各种网络限制、依赖冲突和配置遗漏等“坑”。本文以一次真实的部署经历为线索，详细记录了从拉取镜像、编写 Dockerfile、解决依赖冲突到最终映射端口暴露服务的全过程，希望能为大家提供一份避坑参考。

一、 解决 Docker 镜像拉取超时问题

在国内网络环境下，直接使用docker pull拉取官方镜像时，经常会遇到Client.Timeout exceeded while awaiting headers的报错。这通常是因为 Docker 默认访问境外的registry-1.docker.io服务器，由于跨境网络延迟或限制导致连接超时。

1. 配置镜像加速器

解决此问题的首选方案是配置国内镜像加速器。编辑或创建/etc/docker/daemon.json文件，写入稳定的加速源地址：

json

编辑

{ "registry-mirrors": [ "https://docker.xuanyuan.me", "https://docker.1ms.run", "https://docker.m.daocloud.io" ] }

2. 修改 Hosts 文件（关键）

有时即使配置了加速器，Docker 仍会尝试回退到官方源并卡死。这可能是因为 DNS 解析到了不支持的 IPv6 地址。可以通过强制指定 IPv4 地址来彻底解决：

bash

编辑

sudo tee -a /etc/hosts <<-'EOF' 185.243.192.104 auth.docker.io 185.243.192.104 registry-1.docker.io 185.243.192.104 production.cloudflare.docker.com EOF

配置完成后，执行sudo systemctl daemon-reload && sudo systemctl restart docker重启服务即可生效。

二、 编写 Dockerfile 与解决依赖安装问题

python:3.11-slim等精简镜像虽然体积小，但不包含任何第三方库。在构建镜像时，需要规范地安装项目依赖。

1. 规范使用 requirements.txt

在开发过程中，如果每次遇到ModuleNotFoundError都去修改 Dockerfile 单独安装某个包，效率极低。最佳实践是在项目根目录生成requirements.txt文件，并在 Dockerfile 中统一安装。

2. 配置国内 pip 镜像源

由于默认的 PyPI 源在国外，容器内安装依赖同样会非常缓慢。在 Dockerfile 中可以通过-i参数指定国内镜像源（如阿里云）：

dockerfile

编辑

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt COPY . . CMD ["python", "tcmai_heart_server.py"]

三、 解决 PyTorch GPU 版本的安装冲突

当requirements.txt中包含带有 CUDA 标识的 PyTorch 版本（如torch==2.11.0+cu130）时，使用常规的 pip 镜像源会报错No matching distribution found。这是因为阿里云等通用镜像源只同步了 CPU 版本的 PyTorch。

解决方案：指定 PyTorch 官方源

需要在 Dockerfile 中为 PyTorch 单独指定官方的 CUDA 包索引地址。可以将安装命令修改为：

dockerfile

编辑

RUN pip install --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt \ && pip install --no-cache-dir torch==2.11.0+cu130 -f https://download.pytorch.org/whl/cu130/torch_stable.html

通过-f参数强制 pip 从 PyTorch 官方源下载指定的 GPU 版本，而其他普通依赖依然走阿里云源，既保证了兼容性，又兼顾了下载速度。

四、 容器启动与端口映射

镜像构建成功后，为了让外部网络能够访问到容器内的 Flask 服务，需要进行端口映射。

1. 核心运行命令

使用-p参数将宿主机的端口映射到容器内的端口，并使用-d参数让容器在后台运行：

bash

编辑

docker run -d \ -p 8080:5000 \ -v /app/heart_ecg:/app \ --name heart-ecg-server \ heart-ecg-app

• -p 8080:5000：将宿主机的 8080 端口映射到容器内的 Flask 默认端口 5000。
• -v /app/heart_ecg:/app：将本地代码目录挂载到容器内，方便后续修改代码后直接重启容器生效，无需重新 build。

2. 常用管理命令

• 查看运行中的容器：docker ps
• 查看实时日志：docker logs -f heart-ecg-server
• 停止/重启容器：docker stop/restart heart-ecg-server

总结

将 Python 项目容器化部署时，网络环境和依赖管理是两大核心痛点。通过配置 Docker 加速器、规范使用 requirements.txt、区分通用包与特殊包（如 PyTorch GPU 版）的安装源，可以大幅提高构建效率并避免各种报错。希望这篇实战记录能帮助大家少走弯路，顺利完成项目的 Docker 化部署。