pypiserver/pypiserver

pypiserver Docker镜像文档

镜像概述

pypiserver是一个轻量级的PyPI兼容服务器，专为pip或easy_install设计，基于bottle框架开发，可从普通目录提供软件包服务。该Docker镜像封装了pypiserver的核心功能，支持上传/下载wheels、bdists、eggs及PGP签名文件，兼容pip、setuptools、twine等标准Python工具，无需复杂配置即可快速搭建私有PyPI仓库。

核心功能与特性

• PyPI兼容性：实现PyPI相同接口，无缝对接pip、twine等标准Python工具
• 多包格式支持：处理wheels、bdists、eggs及PGP签名文件
• 灵活认证：通过Apache htpasswd文件支持用户认证，保护上传/下载权限
• 包目录管理：从本地目录递归扫描并提供包服务，支持多目录配置
• PyPI fallback：本地仓库缺失的包自动重定向至PyPI（可禁用）
• 轻量级部署：基于Docker容器化部署，简化环境依赖管理
• 可扩展性：支持自定义健康检查端点、URL前缀、缓存控制等高级配置

使用场景

• 企业内部Python包管理与分发
• 团队私有Python组件仓库
• 开发/测试环境的包依赖隔离
• 无法直接访问公共PyPI环境的离线部署

Docker镜像使用方法

基本部署（Docker Run）

bash
# 创建本地包目录
mkdir -p ~/pypi_packages

# 启动基础pypiserver容器
docker run -d -p 8080:8080 -v ~/pypi_packages:/data/packages docker.xuanyuan.run/pypiserver/pypiserver:latest run -p 8080 /data/packages

带认证的部署

1. 创建htpasswd文件（需安装passlib）：

   bash
   pip install passlib
   htpasswd -sc ~/pypi_htpasswd.txt admin  # 按提示输入密码
   

2. 启动带认证的容器：

   bash
   docker run -d -p 8080:8080 \
     -v ~/pypi_packages:/data/packages \
     -v ~/pypi_htpasswd.txt:/data/htpasswd.txt \
     docker.xuanyuan.run/pypiserver/pypiserver:latest \
     run -p 8080 -P /data/htpasswd.txt -a update /data/packages
   

Docker Compose配置

yaml
version: '3'
services:
  pypiserver:
    image: docker.xuanyuan.run/pypiserver/pypiserver:latest
    ports:
      - "8080:8080"
    volumes:
      - ./packages:/data/packages
      - ./htpasswd.txt:/data/htpasswd.txt
    command: run -p 8080 -P /data/htpasswd.txt -a update,download /data/packages
    restart: always

核心配置参数

客户端配置

pip配置

临时使用

bash
pip install --extra-index-url http://localhost:8080/simple/ 包名

永久配置（~/.pip/pip.conf）

ini
[global]
extra-index-url = http://localhost:8080/simple/
trusted-host = localhost  # 非HTTPS时需要

easy_install配置（~/.pydistutils.cfg）

ini
[easy_install]
index_url = http://localhost:8080/simple/

上传包（twine）

1. 配置~/.pypirc：

   ini
   [distutils]
   index-servers = local
   
   [local]
   repository: http://localhost:8080
   username: admin  # htpasswd中的用户名
   password: 密码    # htpasswd中的密码
   

2. 上传命令：

   bash
   twine upload --repository local dist/*
   

高级配置

健康检查

bash
docker run -d -p 8080:8080 \
  -v ~/pypi_packages:/data/packages \
  docker.xuanyuan.run/pypiserver/pypiserver:latest \
  run --health-endpoint /health /data/packages

访问http://localhost:8080/health返回200 OK表示服务正常。

自定义URL前缀

bash
docker run -d -p 8080:8080 \
  -v ~/pypi_packages:/data/packages \
  docker.xuanyuan.run/pypiserver/pypiserver:latest \
  run --server-base-url /pypi /data/packages

此时访问地址为http://localhost:8080/pypi/simple/。

反向代理配置（Nginx示例）

nginx
server {
    listen 80;
    server_name pypi.example.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

镜像信息

• 版本：2.4.0
• 基础镜像：Python 3.8+
• 源码：https://github.com/pypiserver/pypiserver
• 维护者：https://github.com/ankostis, https://github.com/mplanchard, https://github.com/dee-me-tree-or-love, https://github.com/pawamoy
• 许可证：MIT + zlib/libpng

注意事项

• 生产环境建议使用HTTPS加密（可配合Nginx/Traefik等反向代理）
• 定期备份~/pypi_packages目录以防止数据丢失
• 高并发场景可考虑使用--backend cached-dir启用缓存
• 私有包名建议使用独特前缀（如公司名），避免与PyPI公共包冲突

更多详细信息请参考https://github.com/pypiserver/pypiserver%E3%80%82