怎么在局域网内部署私有Python软件包仓库

一、架构选型与工作机制

Python 的包安装工具 pip 在获取依赖时，通过查询符合 PEP 503 协议的简单 HTML 页面（即 /simple/ 路由）来检索软件包列表与下载链接。构建局域网私有仓库时，我们不需要复杂的数据库系统，核心需求在于稳定响应索引请求、控制包发布权限以及在内网未命中时回退转发到公共镜像源。

目前局域网私有仓库常见方案有三种：轻量级 pypiserver、功能完备但资源占用较大的 devpi，以及仅用 Nginx 做目录索引的静态站点。对于绝大多数团队与局域网环境，pypiserver 是最均衡的选择：单进程启动、以文件目录直接存储包、内存占用常年低于 50MB，且支持 htpasswd 格式的发布身份校验与上游官方源自动回退（Fallback）。

二、服务器环境与目录结构规划

为了保证服务安全与稳定性，建议在局域网专用的 Linux 主机（如 Ubuntu Server 22.04 或 Rocky Linux 9）上运行，并使用独立的非特权系统用户隔离运行进程。

1. 创建专用运行用户与数据目录

在服务器终端执行以下命令，创建名为 pypi 的系统用户，以及用于存放软件包、密码文件和虚拟环境的根目录：

# 创建不带登录 shell 的专用系统用户
sudo useradd -r -s /bin/false -d /data/pypi pypi

# 创建存储目录、配置目录及日志目录
sudo mkdir -p /data/pypi/packages
sudo mkdir -p /data/pypi/auth
sudo mkdir -p /data/pypi/logs

# 将目录所有权赋予 pypi 用户
sudo chown -R pypi:pypi /data/pypi
sudo chmod 750 /data/pypi

2. 部署独立 Python 虚拟环境与依赖

避免将软件包服务直接安装在系统全局 Python 环境中。使用 Python 内置的 venv 创建隔离环境，并安装 pypiserver 与 passlib：

# 进入服务根目录并初始化虚拟环境
cd /data/pypi
sudo -u pypi python3 -m venv venv

# 在虚拟环境中升级 pip 并安装核心组件
sudo -u pypi /data/pypi/venv/bin/pip install --upgrade pip
sudo -u pypi /data/pypi/venv/bin/pip install pypiserver passlib

其中 passlib 是 pypiserver 用于解析与校验密码哈希算法（如 bcrypt 或 apr1）的必要扩展模块。缺少该模块时，服务在校验用户登录时会报错回退。

三、配置权限凭证与启动服务

私有仓库在局域网内通常采用“匿名拉取、凭证推送”的权限策略。局域网内的所有开发机与测试节点都可以无需密码直接下载依赖，但只有持有凭据的开发者或 CI/CD 构建机才能上传新包。

1. 生成身份认证密码文件

我们使用 htpasswd 工具（位于 apache2-utils 或 httpd-tools 软件包中）生成符合 Apache 格式的加密凭据文件：

# Ubuntu / Debian 环境安装工具
sudo apt-get update && sudo apt-get install -y apache2-utils

# 创建用户名为 deployer 的凭证文件，使用安全的 SHA 散列加密
sudo htpasswd -sc /data/pypi/auth/.htpasswd deployer

# 修正权限，仅允许 pypi 用户读取密码文件
sudo chown pypi:pypi /data/pypi/auth/.htpasswd
sudo chmod 600 /data/pypi/auth/.htpasswd

2. 参数含义与前台启动校验

pypiserver 支持通过命令行参数精确控制认证策略与包存储路径。在注册系统服务之前，先在终端中手动前台启动一次，确保参数无误：

sudo -u pypi /data/pypi/venv/bin/pypi-server run \
  -p 8080 \
  -a update,upload \
  -P /data/pypi/auth/.htpasswd \
  --fallback-url https://pypi.tuna.tsinghua.edu.cn/simple/ \
  /data/pypi/packages

关键参数说明：

• -p 8080：指定局域网内监听的 TCP 端口。
• -a update,upload：指定只有更新和上传操作需要凭据校验。未列出 download 意味着局域网内部所有用户均可匿名免密拉取包。
• -P /data/pypi/auth/.htpasswd：指定密码散列文件路径。
• --fallback-url：指定公共镜像源。当内网客户端请求某个包，而本地仓库未找到时，服务会自动重定向到该上游镜像，确保基础第三方库依然能正常安装。
• /data/pypi/packages：最后的路径参数为实际存放 .whl 和 .tar.gz 文件的本地目录。

3. 配置 systemd 系统服务实现持久守护

确认手动启动无误后，按 Ctrl+C 停止前台进程。编写 systemd 服务配置文件 /etc/systemd/system/pypiserver.service，实现开机自启与异常退出自动恢复：

[Unit]
Description=Private PyPI Server for Local Network
After=network.target

[Service]
Type=simple
User=pypi
Group=pypi
WorkingDirectory=/data/pypi
ExecStart=/data/pypi/venv/bin/pypi-server run -p 8080 -a update,upload -P /data/pypi/auth/.htpasswd --fallback-url https://pypi.tuna.tsinghua.edu.cn/simple/ /data/pypi/packages
Restart=always
RestartSec=5
StandardOutput=append:/data/pypi/logs/pypiserver.log
StandardError=append:/data/pypi/logs/pypiserver_err.log

[Install]
WantedBy=multi-user.target

加载并启动该服务：

sudo systemctl daemon-reload
sudo systemctl enable --now pypiserver.service
sudo systemctl status pypiserver.service

四、打包内部组件与推送发布

私有仓库就绪后，开发团队需要将自研的 Python 模块打包并推送至仓库。标准发布遵循基于 pyproject.toml 的构建规范。

1. 构建项目

在开发机上的项目工程根目录下，执行标准构建命令：

# 安装官方构建与上传依赖
pip install build twine

# 执行打包，生成 wheel 和 sdist 文件
python -m build

构建完成后，工程目录下将生成 dist/ 文件夹，包含形如 my_internal_pkg-0.1.0-py3-none-any.whl 的二进制分发包。

2. 配置上传认证文件

为了避免每次执行上传时重复手动输入服务器地址、用户名及密码，可以在开发机当前用户的家目录下创建 ~/.pypirc 配置文件（假设私有仓库服务器内网 IP 为 192.168.1.100）：

[distutils]
index-servers =
    internal

[internal]
repository = http://192.168.1.100:8080/
username = deployer
password = 刚才设置的明文密码

注意保持该文件私有权限，避免明文密码泄露：

chmod 600 ~/.pypirc

3. 上传软件包

调用 twine 将 dist/ 目录下的所有文件推送至局域网私有源：

twine upload -r internal dist/*

五、局域网客户端配置与依赖安装

在局域网内的其它开发机或生产服务器上，需要让 pip 能够识别并优先拉取私有仓库中的包，同时保证公共第三方包正常通过官方或镜像站下载。

1. 临时测试安装

可以通过命令行参数直接验证内网安装（注意：由于内网默认使用 HTTP 协议，pip 会拒绝非安全传输，必须显式附加 --trusted-host 参数）：

pip install my_internal_pkg \
  --index-url http://192.168.1.100:8080/simple/ \
  --trusted-host 192.168.1.100

2. 持久化全局配置

为避免每次安装都要输入长参数，推荐修改客户端全局 pip.conf 文件：

• Linux / macOS 配置文件位置：~/.config/pip/pip.conf 或 ~/.pip/pip.conf
• Windows 配置文件位置：%APPDATA%\pip\pip.ini

写入以下内容：

[global]
# 将局域网私有仓库设为主索引源（若开启了 fallback，可直接代理解析公共包）
index-url = http://192.168.1.100:8080/simple/

# 或者保留公共源为主源，将私有源作为附加源（extra-index-url）
# extra-index-url = http://192.168.1.100:8080/simple/

# 信任未启用 HTTPS 的局域网主机 IP
trusted-host = 192.168.1.100

# 延长局域网超时时间限制
timeout = 15

六、日常运维规范与疑难排查

部署上线后，仓库管理员需要关注磁盘容量、权限审计以及网络安全规范。

常见问题排查

通过以上部署与配置，局域网内部署的私有 Python 仓库即可稳定支撑起日常自研依赖管理与高速安装，且完全不依赖外网环境。在未来业务规模扩大时，可以直接挂载企业已有存储卷或通过 Nginx 增加 HTTPS 加密，平滑满足更严格的企业安全合规要求。