Python-Poetry 基础镜像文档

镜像概述

本镜像基于官方Python基础镜像构建，预集成了Poetry依赖管理工具，旨在为使用Poetry进行依赖管理的Python项目提供开箱即用的运行环境。通过省去手动安装Poetry的步骤，降低Docker化配置复杂度，提升开发与部署效率。

核心功能与特性

• 官方兼容基础：基于Docker Official Images中的Python镜像构建，确保与官方Python运行环境的兼容性和安全性
• Poetry预安装：内置最新稳定版Poetry工具，支持poetry install、poetry run等核心命令
• 环境优化配置：默认启用Poetry虚拟环境集成，支持项目依赖隔离
• 多版本支持：提供多个标签对应不同Python版本（如3.9-slim、3.10-alpine等），适配不同项目需求
• 轻量级设计：基于slim或alpine变体构建（依标签而定），减少镜像体积

使用场景与适用范围

• 开发环境：快速搭建本地开发容器，无需手动配置Poetry环境
• CI/CD流程：在持续集成/部署管道中作为构建基础，简化依赖安装步骤
• 生产部署：直接作为应用运行环境，支持通过Poetry管理生产依赖
• 教学演示：用于Poetry使用教程或Python项目示例，降低环境配置门槛

使用方法与配置说明

获取镜像

通过Docker Hub拉取镜像（假设镜像名为username/python-poetry，实际使用时替换为具体镜像名称）：

# 拉取特定Python版本（如3.11-slim）
docker pull username/python-poetry:3.11-slim

# 拉取最新版本
docker pull username/python-poetry:latest

基础使用示例

交互式环境测试

启动容器并进入交互式shell，验证Poetry安装状态：

docker run -it --rm username/python-poetry:3.11-slim /bin/bash

# 验证Poetry版本
poetry --version
# 输出示例：Poetry (version 1.8.2)

项目依赖安装与运行

挂载本地Poetry项目目录，安装依赖并运行应用：

# 假设项目目录为./my-python-project
docker run -it --rm -v $(pwd)/my-python-project:/app -w /app username/python-poetry:3.11-slim \
  sh -c "poetry install && poetry run python main.py"

Dockerfile集成示例

在项目中使用本镜像构建应用镜像：

# 指定基础镜像（选择对应Python版本）
FROM username/python-poetry:3.11-slim

# 设置工作目录
WORKDIR /app

# 复制项目依赖文件
COPY pyproject.toml poetry.lock ./

# 安装项目依赖（生产环境模式，不包含开发依赖）
RUN poetry install --no-dev

# 复制项目源代码
COPY . .

# 运行应用
CMD ["poetry", "run", "python", "main.py"]

构建并运行自定义镜像：

docker build -t my-poetry-app .
docker run -it --rm my-poetry-app

Docker Compose配置示例

创建docker-compose.yml管理多服务环境：

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile  # 引用上述Dockerfile
    volumes:
      - ./:/app  # 开发环境挂载本地代码（生产环境可移除）
    environment:
      - POETRY_VIRTUALENVS_IN_PROJECT=true  # 在项目内创建虚拟环境
    command: poetry run python main.py

启动服务：

docker-compose up --build

环境变量配置

支持通过环境变量调整Poetry行为，常用配置：

示例：禁用虚拟环境创建（直接使用系统Python环境）

docker run -e POETRY_VIRTUALENVS_CREATE=false -it --rm username/python-poetry:3.11-slim