epicwink/proxpi

PyPI缓存镜像

镜像概述

PyPI缓存镜像是一个轻量级工具，用于在本地缓存Python Package Index (PyPI)资源，解决频繁下载PyPI包导致的网络带宽消耗大、下载速度慢等问题。通过将PyPI包缓存到本地服务器，团队成员或CI/CD流程可直接从本地获取依赖，显著提升依赖安装效率。

核心功能与特性

• 智能缓存机制：自动缓存首次请求的PyPI包，后续请求直接返回本地缓存，避免重复下载
• 索引同步：定期同步PyPI官方索引，确保缓存内容与上游源保持一致
• 轻量级部署：基于Docker容器化，部署简单，资源占用低
• 灵活配置：支持自定义缓存大小、同步频率、上游源等参数
• 兼容性：兼容标准pip客户端，无需修改现有项目依赖文件

使用场景

• 开发团队共享缓存：多成员开发环境共享一个缓存服务，减少团队整体网络消耗
• CI/CD流水线加速：在CI/CD流程中集成，避免每次构建重复下载依赖，缩短构建时间
• 网络受限环境：在网络带宽有限或PyPI访问不稳定的环境中保障依赖安装可靠性
• 离线环境支持：提前缓存所需依赖后，可在完全离线环境中使用

使用方法与配置说明

基本部署

Docker Run 命令

bash
docker run -d \
  --name pypi-mirror \
  -p 8080:8080 \
  -v /path/to/pypi-cache:/cache \
  -e SYNC_INTERVAL=86400 \
  -e CACHE_MAX_SIZE=10G \
  docker.xuanyuan.run/pypi-mirror:latest

Docker Compose 配置

yaml
version: '3'
services:
  pypi-mirror:
    image: docker.xuanyuan.run/pypi-mirror:latest
    container_name: pypi-mirror
    ports:
      - "8080:8080"
    volumes:
      - ./pypi-cache:/cache
    environment:
      - SYNC_INTERVAL=86400  # 同步间隔（秒），默认86400（24小时）
      - CACHE_MAX_SIZE=10G   # 最大缓存大小，默认10G
      - UPSTREAM_URL=https://pypi.org/simple  # 上游PyPI源，默认官方源
      - PORT=8080            # 服务端口，默认8080
    restart: unless-stopped

环境变量配置

持久化存储

为避免容器重启后缓存丢失，需将缓存目录挂载到宿主机或持久化卷：

bash
# 宿主机目录挂载示例
-v /data/pypi-cache:/cache

客户端配置（pip使用）

临时使用

安装包时指定镜像：

bash
pip install --extra-index-url http://<mirror-ip>:8080/simple <package-name>

全局配置

修改pip配置文件（pip.conf或pip.ini）：

ini
[global]
index-url = http://<mirror-ip>:8080/simple
trusted-host = <mirror-ip>  # 非HTTPS环境需添加信任

验证部署

1. 启动服务后，访问 http://<mirror-ip>:8080 应显示PyPI索引页面
2. 执行 pip install requests，检查服务日志是否有缓存命中记录
3. 再次执行相同安装命令，确认从缓存获取（日志显示"Cache hit"）

注意事项

• 首次使用时需同步索引，可能需要较长时间（取决于网络速度）
• 缓存大小应根据团队需求调整，避免空间不足导致缓存频繁清理
• 生产环境建议配置HTTPS（可通过反向代理如Nginx实现）
• 定期监控缓存命中率和存储空间使用情况，优化同步策略

通过以上配置，PyPI缓存镜像可有效提升Python依赖管理效率，特别适合中小型开发团队和CI/CD环境使用。