在将 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 版本如torch2.11.0cu130时使用常规的 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 torch2.11.0cu130 -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 化部署。