kodemore/python

Python-Alpine-Poetry 镜像文档

镜像概述

该镜像基于轻量级的Python:alpine基础镜像，集成了Poetry包管理器，专门用于加速Python项目的Docker构建流程。通过预配置Poetry环境并优化依赖安装机制，解决传统Python项目Docker构建中依赖解析慢、镜像体积大等问题，提升开发和部署效率。

核心功能与特性

• 轻量级基础：采用Alpine Linux作为基础，镜像体积远小于基于Debian的Python镜像，减少存储和传输成本
• Poetry集成：预装Poetry包管理器，支持Python依赖的声明式管理、虚拟环境隔离和项目打包
• 构建优化：通过Poetry的依赖缓存机制和分层构建支持，减少重复依赖安装步骤，显著缩短构建时间
• 兼容性：兼容Python官方alpine镜像的所有版本标签，可灵活选择Python版本（如3.9-alpine、3.10-alpine等）

使用场景

• Python项目Docker化：快速将Poetry管理的Python项目容器化
• CI/CD流水线：在持续集成/部署流程中加速构建环节，提高迭代效率
• 开发环境标准化：为团队提供统一的Python+Poetry开发环境，减少"环境不一致"问题
• 微服务部署：适合构建轻量级Python微服务镜像，降低容器资源占用

使用方法与配置说明

基本使用

直接运行镜像进入交互式环境：

bash
docker run -it --rm docker.xuanyuan.run/python-alpine-poetry:latest sh

Dockerfile示例

以下是使用该镜像构建Python项目的典型Dockerfile：

dockerfile
# 选择基础镜像（可指定Python版本，如3.11-alpine）
FROM docker.xuanyuan.run/python-alpine-poetry:3.11-alpine

# 设置工作目录
WORKDIR /app

# 复制依赖文件（优先复制以利用Docker缓存）
COPY pyproject.toml poetry.lock ./

# 安装项目依赖（不创建虚拟环境，直接安装到系统Python）
RUN poetry config virtualenvs.create false && \
    poetry install --no-interaction --no-ansi --without dev

# 复制项目代码
COPY . .

# 暴露应用端口（根据实际情况修改）
EXPOSE 8000

# 启动命令
CMD ["python", "app.py"]

环境变量配置

docker-compose示例

yaml
version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
    image: docker.xuanyuan.run/python-alpine-poetry-app:latest
    ports:
      - "8000:8000"
    environment:
      - POETRY_VIRTUALENVS_CREATE=false
      - PYTHONUNBUFFERED=1
    volumes:
      - ./app:/app

构建优化建议

1. 依赖文件优先复制：始终先复制pyproject.toml和poetry.lock，再复制代码文件，利用Docker层缓存机制减少重复安装依赖
2. 禁用虚拟环境：在Docker环境中建议通过poetry config virtualenvs.create false禁用虚拟环境，直接将依赖安装到系统Python，减少镜像层数和体积
3. 安装生产依赖：使用poetry install --without dev仅安装生产环境依赖，避免包含开发工具
4. 多阶段构建：如需进一步减小镜像体积，可结合多阶段构建，仅保留运行时必要文件

dockerfile
# 构建阶段
FROM python-alpine-poetry:3.11-alpine as builder
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN poetry config virtualenvs.create false && \
    poetry install --without dev

# 运行阶段
FROM python:3.11-alpine
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY --from=builder /app .
EXPOSE 8000
CMD ["python", "app.py"]