devpi-docker

用于通过 Docker Compose 快速启动一个本地 devpi 服务。devpi 可作为 Python 包缓存、私有包索引和离线环境的包源入口。

功能

• 基于 python:3.12-slim 构建 devpi 镜像
• 默认安装 devpi-server、devpi-client 和 devpi-web
• 首次启动时自动初始化 devpi 数据目录
• 支持通过环境变量配置 root 密码、监听端口、上游 PyPI 镜像地址和请求超时
• 使用 Docker volume 持久化 /data/devpi

快速启动

docker compose up -d

默认服务地址：

http://localhost:3141

查看日志：

docker compose logs -f devpi

停止服务：

docker compose down

如果需要同时删除 devpi 数据卷：

docker compose down -v

配置

可以通过 .env 文件或启动命令中的环境变量覆盖默认配置。

变量	默认值	说明
DEVPI_IMAGE	ghcr.io/Lilembas/devpi-docker:latest	Compose 使用的镜像
DEVPI_PORT	3141	映射到宿主机的端口
DEVPI_ROOT_PASSWORD	change-me	devpi root 用户密码
DEVPI_MIRROR_URL	https://pypi.org/simple/	root/pypi 的上游镜像地址
DEVPI_REQUEST_TIMEOUT	5	devpi 请求超时时间，单位为秒

示例 .env：

DEVPI_PORT=3141
DEVPI_ROOT_PASSWORD=please-change-this
DEVPI_MIRROR_URL=https://pypi.org/simple/
DEVPI_REQUEST_TIMEOUT=10

生产或共享环境中请务必修改 DEVPI_ROOT_PASSWORD。如果服务已经初始化过，修改环境变量不会重置已有数据目录中的 root 密码。

使用 pip

将 pip 指向本地 devpi：

python -m pip install -i http://localhost:3141/root/pypi/+simple/ requests

也可以写入 pip 配置：

python -m pip config set global.index-url http://localhost:3141/root/pypi/+simple/

如果用于受控内网环境，可以按需增加 trusted host：

python -m pip config set global.trusted-host localhost

使用 devpi-client

登录 root 用户：

devpi use http://localhost:3141
devpi login root --password '<DEVPI_ROOT_PASSWORD>'

查看默认索引：

devpi index root/pypi

创建用户和私有索引示例：

devpi user -m alice password='<PASSWORD>'
devpi login alice --password '<PASSWORD>'
devpi user -m alice email=alice@example.com
devpi index -c dev bases=root/pypi
devpi use alice/dev

本地构建镜像

如果不使用远端镜像，可以在仓库根目录构建：

docker build -t devpi-docker:local docker/devpi

然后通过环境变量让 Compose 使用本地镜像：

DEVPI_IMAGE=devpi-docker:local docker compose up -d

数据持久化

Compose 使用名为 devpi-data 的 Docker volume 持久化 devpi 数据：

volumes:
  devpi-data:

容器内数据目录为：

/data/devpi

需要全量重建 devpi 数据时，可以先停止服务并删除 volume：

docker compose down -v
docker compose up -d

初始化行为

容器启动时会检查 DEVPI_SERVERDIR 中是否存在 .serverversion：

• 不存在时，执行 devpi-init 并使用 DEVPI_ROOT_PASSWORD 初始化 root 密码
• 存在时，复用已有数据目录
• 启动成功后，如果 DEVPI_MIRROR_URL 非空，会尝试更新 root/pypi 的 mirror_url

如果复用已有数据卷但提供了错误的 DEVPI_ROOT_PASSWORD，服务仍会启动，但镜像地址自动更新会被跳过并在日志中打印警告。