Docker 容器化部署 Python Flask 应用的实践日志

一、场景描述 在最近的个人项目开发中，我遇到了一个典型的 "环境一致性" 难题：本地 macOS 系统开发的 Flask 应用（依赖 Python 3.9、SQLite 数据库及特定版本的 Pillow 库），部署到云服务器（Ubuntu 20.04）时频繁出现 "ImportError: cannot import name 'Image' from 'PIL'" 和数据库路径权限错误。反复调试依赖版本后发现，问题根源在于本地与服务器的系统库差异（如 libjpeg 库版本）及文件系统权限模型不同。为彻底解决这类 "在我电脑上能运行" 的问题，我决定采用 Docker 容器化方案，将应用及依赖环境完整封装，确保跨环境一致运行。 二、解决方案概述 通过 Docker 实现 Flask 应用容器化部署，核心步骤包括： 搭建 Docker 开发环境 编写多阶段构建 Dockerfile 使用 docker-compose 管理应用服务 实现数据持久化与日志收集 优化镜像体积与运行性能 整个过程需确保：代码可复现、配置可版本化、问题可追溯，最终形成一套标准化的容器化部署流程。 三、详细操作步骤 3.1 环境准备：安装 Docker 与依赖工具 在 Ubuntu 服务器上执行以下命令安装 Docker 及 compose 插件： bash # 更新apt索引并安装依赖包 sudo apt-get update && sudo apt-get install -y \ apt-transport-https \ ca-certificates \ curl \ software-properties-common # 添加Docker官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # 设置stable仓库 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker Engine与compose插件 sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 验证安装结果（出现版本号即成功） docker --version && docker compose version 3.2 项目结构设计 为便于容器化，调整项目目录结构如下： plaintext flask-docker-demo/ ├── app/ # 应用代码目录 │ ├── __init__.py # Flask应用入口 │ ├── routes.py # 业务路由 │ └── static/ # 静态资源 ├── data/ # 数据库存储目录（需持久化） ├── logs/ # 日志目录 ├── Dockerfile # 镜像构建文件 ├── docker-compose.yml # 服务编排配置 ├── requirements.txt # 依赖清单 └── .dockerignore # 排除无需打包的文件 3.3 编写核心配置文件 3.3.1 应用依赖清单（requirements.txt） txt Flask==2.3.3 gunicorn==21.2.0 # 生产环境WSGI服务器 SQLAlchemy==2.0.23 # ORM工具（适配SQLite） Pillow==10.1.0 # 图像处理依赖 3.3.2 Dockerfile（多阶段构建优化） dockerfile # 第一阶段：构建依赖（减小最终镜像体积） FROM python:3.9-slim AS builder WORKDIR /app COPY requirements.txt . # 生成依赖 wheel包 RUN pip wheel --no-cache-dir --wheel-dir /app/wheels -r requirements.txt # 第二阶段：生产环境 FROM python:3.9-slim WORKDIR /app # 设置时区（解决日志时间错乱问题） ENV TZ=Asia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone # 复制构建阶段的依赖包并安装 COPY --from=builder /app/wheels /wheels RUN pip install --no-cache /wheels/* && rm -rf /wheels # 复制应用代码 COPY . . # 创建非root用户并授权（增强安全性） RUN useradd -m appuser && chown -R appuser:appuser /app USER appuser # 暴露应用端口 EXPOSE 5000 # 启动命令（使用gunicorn，支持多进程） CMD ["gunicorn", "--workers", "4", "--bind", "0.0.0.0:5000", "app:create_app()"] 3.3.3 docker-compose.yml（服务编排） yaml version: '3.8' services: web: build: . # 基于当前目录Dockerfile构建 restart: always # 异常退出自动重启 ports: - "5000:5000" # 端口映射（宿主机:容器） volumes: - ./data:/app/data # 数据库持久化（宿主机目录挂载） - ./logs:/app/logs # 日志持久化 environment: - FLASK_ENV=production # 生产环境模式 - DATABASE_URI=sqlite:///data/app.db # 数据库路径 healthcheck: # 健康检查（自动恢复异常实例） test: ["CMD", "curl", "-f", "http://localhost:5000/health"] interval: 30s timeout: 10s retries: 3 3.4 构建与运行容器化应用 3.4.1 构建镜像并启动服务 bash # 构建镜像（首次运行较慢，后续有缓存） docker compose build # 后台启动服务 docker compose up -d # 查看服务状态（确保web服务状态为"Up (healthy)"） docker compose ps # 查看应用日志（验证启动是否正常） docker compose logs -f --tail=100 3.4.2 验证应用可用性 bash # 访问健康检查接口 curl http://localhost:5000/health # 预期响应：{"status":"healthy","timestamp":"2025-09-25T15:30:00Z"} 四、核心思路与原理四 4.1 Docker 解决环境一致性的底层逻辑 镜像分层存储：Dockerfile 中的每个指令对应一层镜像，基于 UnionFS 实现增量构建，如COPY、RUN指令会生成新层，未修改的层可复用，减少重复构建时间。 隔离机制：通过 Linux Namespace 实现容器与宿主机的资源隔离（PID、网络、挂载等），如容器内的/app目录与宿主机完全独立，避免路径冲突。 资源限制：通过 Cgroup 限制容器 CPU / 内存使用（可在 docker-compose.yml 中配置deploy.resources），防止单个应用占用过多服务器资源。 配置代码化：Dockerfile 与 docker-compose.yml 将环境依赖、启动参数等写入代码，纳入版本控制，避免 "口头配置" 导致的偏差。 4.2 多阶段构建的优势 对比传统单阶段构建，多阶段构建通过分离 "构建环境" 与 "运行环境"，使最终镜像体积从 1.2GB 减小至 380MB（减少约 68%），具体优化点： 仅保留运行时必要依赖，剔除编译器、构建工具等临时依赖 清理缓存文件（如pip cache、apt list） 合并冗余指令（如RUN指令用&&串联，减少镜像层数） 五、实践中的问题与解决方案 5.1 问题 1：SQLite 数据库文件权限错误 现象：容器启动后日志报 "sqlite3.OperationalError: unable to open database file" 原因：容器内非 root 用户（appuser）对挂载的宿主机./data目录无写入权限 解决：宿主机执行chmod 775 ./data并设置属主 ID 与容器内一致： bash # 查看容器内appuser的UID/GID docker compose exec web id appuser # 输出如：uid=1000(appuser) gid=1000(appuser) # 宿主机目录授权 sudo chown -R 1000:1000 ./data 5.2 问题 2：Pillow 库依赖系统库缺失 现象：构建镜像时pip install Pillow失败，提示 "libjpeg.so.8: cannot open shared object file" 原因：slim 基础镜像缺少图像处理依赖的系统库 解决：Dockerfile 中添加系统库安装指令： dockerfile # 在builder阶段添加 RUN apt-get update && apt-get install -y --no-install-recommends \ libjpeg-dev zlib1g-dev \ # Pillow依赖的系统库 && rm -rf /var/lib/apt/lists/* # 清理apt缓存 5.3 问题 3：容器时区与本地不一致 现象：日志时间比实际时间早 8 小时（UTC 与 CST 时差） 解决：Dockerfile 中通过环境变量与软链接统一时区（已在 3.3.2 中体现），验证： bash docker compose exec web date # 输出应与宿主机一致