muccg/python-base

Python 基础镜像文档

1. 镜像概述和主要用途

Python 基础镜像是基于官方 Python 版本构建的标准化基础镜像，旨在为 Python 应用开发、测试和部署提供稳定、精简的运行环境。该镜像作为上层应用镜像的构建基础，包含 Python 解释器、标准库及基础依赖管理工具（如 pip），支持多版本和多操作系统变体，适用于从简单脚本到复杂微服务的各类 Python 应用场景。

2. 核心功能和特性

• 官方版本支持：基于 Python 官方源码构建，覆盖 3.7+ 全系列版本，版本标签与官方 Python 版本严格对应（如 3.11、3.12）。
• 多系统变体：提供多种操作系统底层支持，包括：
  • 标准变体（基于 Debian，完整系统依赖）；
  • slim 变体（精简 Debian，减少非必要依赖，平衡体积与兼容性）；
  • alpine 变体（基于 Alpine Linux，最小化体积，适合资源受限场景）。
• 工具预装：内置 pip、setuptools 等依赖管理工具，支持快速安装 Python 包。
• 多架构兼容：支持 amd64、arm64、ppc64le 等主流架构，满足跨平台部署需求。
• 安全更新：定期同步官方 Python 安全补丁，确保基础环境安全性。

3. 使用场景和适用范围

• Python 应用开发环境：作为本地开发容器，提供一致的 Python 版本和依赖环境。
• 微服务构建基础：作为 Python 微服务的底层镜像，简化多服务统一依赖管理。
• CI/CD 流程节点：在持续集成/部署流程中作为构建、测试或运行节点，确保环境一致性。
• 轻量级工具部署：用于部署单文件 Python 脚本或轻量级工具（如数据处理脚本、定时任务）。
• 教学与实验环境：快速搭建隔离的 Python 学习或实验环境，避免本地环境污染。

4. 详细使用方法和配置说明

4.1 获取镜像

通过 Docker Hub 直接拉取，格式为 docker pull docker.xuanyuan.run/python:<tag>，其中 <tag> 需指定 Python 版本及系统变体（未指定变体时默认使用 Debian 标准变体）。

常用标签示例：

• python:3.11（Python 3.11 + Debian 标准变体）
• python:3.12-slim（Python 3.12 + Debian slim 变体）
• python:3.10-alpine（Python 3.10 + Alpine 变体）

4.2 基本使用

4.2.1 交互式运行

启动 Python 解释器交互终端：

bash
docker run -it --rm docker.xuanyuan.run/python:3.11 python

• -it：启用交互式终端；
• --rm：退出后自动删除容器；
• python:3.11：指定镜像及版本；
• python：容器启动命令（运行 Python 解释器）。

4.2.2 运行本地 Python 脚本

挂载本地目录并运行脚本（假设当前目录存在 script.py）：

bash
docker run --rm -v $(pwd):/app -w /app docker.xuanyuan.run/python:3.11 python script.py

• -v $(pwd):/app：将本地当前目录挂载到容器内 /app 目录；
• -w /app：设置工作目录为 /app。

4.3 自定义配置

4.3.1 环境变量

通过 -e 指定环境变量，常用配置如下：

示例：

bash
docker run --rm -e PYTHONUNBUFFERED=1 -e PYTHONPATH=/app docker.xuanyuan.run/python:3.11 python /app/main.py

4.3.2 工作目录与用户

• 指定工作目录：通过 -w 或 --workdir 设置容器内工作目录，避免路径依赖问题。
• 非 root 用户运行：默认使用 root 用户，生产环境建议通过 -u 指定低权限用户（需镜像支持）：

  bash
  docker run -it --rm -u 1000:1000 docker.xuanyuan.run/python:3.11-slim bash
  

4.4 结合 Dockerfile 构建应用

以 Python 基础镜像为基础，通过 Dockerfile 构建自定义应用镜像：

示例 Dockerfile（基于 slim 变体）：

dockerfile
# 基础镜像
FROM docker.xuanyuan.run/python:3.11-slim

# 设置工作目录
WORKDIR /app

# 复制依赖文件并安装
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt  # 禁用缓存减少体积

# 复制应用代码
COPY . .

# 运行命令
CMD ["python", "app.py"]

构建并运行：

bash
docker build -t my-python-app .
docker run --rm docker.xuanyuan.run/my-python-app

5. Docker 部署方案示例

5.1 docker run 命令示例

5.1.1 运行带依赖的 Python 应用

bash
# 假设当前目录有 requirements.txt 和 app.py
docker run --rm -v $(pwd):/app -w /app -e PYTHONUNBUFFERED=1 docker.xuanyuan.run/python:3.11 \
  sh -c "pip install -r requirements.txt && python app.py"

5.1.2 后台运行 Python 服务

bash
docker run -d --name python-service -v $(pwd):/app -p 8080:8080 docker.xuanyuan.run/python:3.11 \
  python /app/server.py

• -d：后台运行；
• --name：指定容器名称；
• -p 8080:8080：端口映射（宿主端口:容器端口）。

5.2 docker-compose 配置示例

创建 docker-compose.yml，定义 Python 应用服务：

yaml
version: '3.8'

services:
  python-app:
    image: docker.xuanyuan.run/python:3.11-slim  # 使用 slim 变体减少体积
    volumes:
      - ./src:/app  # 挂载应用代码目录
    working_dir: /app
    environment:
      - PYTHONUNBUFFERED=1
      - PYTHONPATH=/app/lib
    ports:
      - "8080:8080"  # 暴露服务端口
    command: >
      sh -c "pip install --no-cache-dir -r requirements.txt &&
             python main.py"

启动服务：

bash
docker-compose up -d  # -d 后台运行

6. 注意事项

• 变体选择：

  • alpine 变体体积最小（约 50MB），但需额外安装系统库（如 libc6-compat）以支持部分 Python 包；
  • slim 变体（约 200MB）平衡体积与兼容性，推荐生产环境使用；
  • 标准变体（约 900MB）包含完整系统工具，适合需要调试或依赖复杂系统库的场景。

• 版本锁定：生产环境建议指定具体版本标签（如 3.11.6）而非模糊版本（如 3.11），避免镜像自动更新导致兼容性问题。

• 安全加固：默认使用 root 用户运行，生产环境需通过 Dockerfile 创建低权限用户（如 RUN useradd -m appuser && USER appuser）。

• 依赖管理：通过 requirements.txt 或 pyproject.toml 固化依赖版本，避免 pip install <package> 导致版本漂移。