使用Devpi与Nginx构建高可用PyPI镜像源
Published in：2025-09-17 |
Words: 2k | Reading time: 8min | reading：

使用Devpi与Nginx构建高可用PyPI镜像源

前言：为什么你的pip install又超时了？

对于每一位Python开发者来说，pip install 无疑是最常用的命令之一。然而，团队开发中，我们常常会遇到这些痛点：

  • 速度瓶颈：团队几十号人，CI/CD流水线上百个任务，全都从国外的官方PyPI源拉取包，下载速度慢得令人抓狂，严重影响开发和部署效率。
  • 单点故障：官方PyPI偶尔会抖动，或者公司出口网络出现问题，导致所有依赖安装失败，研发流程瞬间停摆。
  • 安全与合规：无法对团队使用的第三方包进行统一管理和安全审计。
  • 私有包托管：团队内部开发的公共库无处安放，只能通过Git仓库等原始方式共享。

为了彻底解决这些问题，我们需要一个私有的、高速的、且永不宕机的Python包仓库。今天，我将手把手带你使用业界最强大的开源工具 devpi 和 Nginx，构建一个具备自动故障转移能力的高可用PyPI镜像源。

最终目标：无论清华源、阿里源还是其他任何一个镜像挂了，我们的 pip install 依然能丝滑流畅地运行，对开发者完全透明！

1
2
3
4
5
6
7
8
9
10
11
12
+-----------+     +-------------------+     +-------------------------+     +--------------------------+
|           |     |                   |     |                         |     |   Tsinghua Mirror       |
|  开发者   | --> |  devpi 服务器      | --> |  Nginx 反向代理          | --> |  (Upstream 1)            |
| (pip)     |     | (缓存/私有包)      |     | (处理上游故障转移)       |     +--------------------------+
|           |     |                   |     |                         |     |  Aliyun Mirror         |
+-----------+     +-------------------+     +-------------------------+ --> |  (Upstream 2)            |
                                                                            +--------------------------+
                                                                            |  USTC Mirror             |
                                                                          ->|  (Upstream 3)            |
                                                                            +--------------------------+
                                                                            |  ... and so on           |
                                                                            +--------------------------+

第一章：核心武器介绍 - Devpi 与 Nginx

在开始之前，我们先了解一下两位主角：

  1. Devpi: 一个功能完备的Python包服务器。它不仅仅是 pypi.org 的一个缓存代理，更是一个强大的私有包仓库和版本发布管理工具。我们将主要利用它的缓存镜像功能。

  2. Nginx: 一款高性能的HTTP和反向代理服务器。在这里，它将扮演我们镜像源的“智能调度员”和“故障哨兵”，负责监测上游镜像源的健康状况，并在某个源出现问题时，自动将流量切换到健康的备用源上。

第二章：基础建设 - 搭建Devpi缓存服务器

首先，我们需要一个能稳定运行的devpi服务。

步骤 1: 准备服务器与安装Devpi

在一台Linux服务器（本教程以Ubuntu为例）上，确保已安装Python和pip。

1
2
3
4
5
6
7
8
9
# 更新并安装依赖
sudo apt update
sudo apt install -y python3 python3-pip

# 安装 devpi-server
pip3 install devpi-server

devpi-init

步骤 2: 初始化Devpi

这个一次性操作会为你创建数据目录和 root 超级管理员。

1
devpi-init

在提示中，为 root 用户设置一个安全的密码，并牢牢记住它。

步骤 3: 让Devpi在后台稳定运行

为了生产环境的稳定，我们将 devpi 配置成一个 systemd 系统服务，实现开机自启和后台运行。

  1. 创建服务文件:

    1
    sudo nano /etc/systemd/system/devpi.service

  2. 粘贴以下配置 (注意修改 User 和 ExecStart 中的路径为你自己的):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
(venv) czq2@czq2:~/clip-video$ sudo cat /etc/systemd/system/devpi.service
[Unit]
Description=devpi-server daemon
After=network.target

[Service]
Type=simple
User=czq2
Group=czq2
ExecStart=/home/czq2/clip-video/venv/bin/devpi-server --host=0.0.0.0 --port=3141
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target
  • --host=0.0.0.0 确保局域网内的其他机器可以访问。
  1. 启动并验证服务:
    1
    2
    3
    4
    sudo systemctl daemon-reload
    sudo systemctl enable devpi  # 开机自启
    sudo systemctl start devpi   # 启动
    sudo systemctl status devpi  # 检查状态
    看到绿色的 active (running)，恭喜你，基础的 devpi 镜像服务已经成功运行在 http://<你的服务器IP>:3141 上了！
  • 成功输出
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
(venv) czq2@czq2:~/clip-video$ sudo systemctl start devpi
(venv) czq2@czq2:~/clip-video$ sudo systemctl status devpi
● devpi.service - devpi-server daemon
     Loaded: loaded (/etc/systemd/system/devpi.service; enabled; preset: enabled)
     Active: active (running) since Wed 2025-09-17 07:19:23 UTC; 3s ago
   Main PID: 1619813 (devpi-server)
      Tasks: 54 (limit: 309293)
     Memory: 41.4M (peak: 553.5M)
        CPU: 15.733s
     CGroup: /system.slice/devpi.service
             └─1619813 /home/czq2/clip-video/venv/bin/python3 /home/czq2/clip-video/venv/bin/devpi-server --host=0.0.0.0 --p>

Sep 17 07:19:23 czq2 devpi-server[1619813]: 2025-09-17 07:19:23,634 WARNI NOCTX No secret file provided, creating a new rand>
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,757 INFO  [ASYN] Starting asyncio event loop
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX devpi-server version: 6.17.0
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX serverdir: /home/czq2/.devpi/server
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX uuid: 0c7aa3d0d1874fd596c8936cd007d305
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX serving at url: http://0.0.0.0:3141 (might b>
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX using 50 threads
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX bug tracker: https://github.com/devpi/devpi/>
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,777 INFO  NOCTX Hit Ctrl-C to quit.
Sep 17 07:19:25 czq2 devpi-server[1619813]: 2025-09-17 07:19:25,785 INFO  Serving on http://0.0.0.0:3141
  • 错误分析
1
sudo journalctl -u devpi.service -n 50 --no-pager

第三章：构建护城河 - Nginx高可用反向代理

现在，我们要为 devpi 构建一个坚固的前哨站，让它不再直接依赖任何单一的上游源。

步骤 1: 安装 Nginx

1
2
sudo apt update
sudo apt install -y nginx

步骤 2: 编写Nginx高可用配置

这是实现自动故障转移的核心。

  1. 创建Nginx配置文件:

    1
    sudo nano /etc/nginx/sites-available/pypi-proxy

  2. 粘贴以下魔法配置:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    # /etc/nginx/sites-available/pypi-proxy

    # 定义一个上游服务器组，这次全部使用 HTTPS
    upstream pypi_mirrors_https {
        # 【核心修改】直接指向 HTTPS 域名，端口 443 是默认的，可以不写
        server pypi.tuna.tsinghua.edu.cn:443;
        server mirrors.aliyun.com:443;
        server pypi.mirrors.ustc.edu.cn:443;
        server mirrors.cloud.tencent.com:443;
        server repo.huaweicloud.com:443;
    }

    server {
        listen 8888;
        server_name localhost;

        location / {
            # 【核心修改】将请求代理到我们新的 HTTPS 服务器组
            proxy_pass https://pypi_mirrors_https;

            # 故障转移的配置保持不变
            proxy_next_upstream error timeout http_500 http_502 http_503 http_504;

            proxy_connect_timeout 10s;

            # 【重要】当代理到 HTTPS 上游时，必须正确设置 Host 头
            # 这里的 $host 会是上游服务器组的名称，为了正确性，我们应该传递原始请求的Host
            # 或者直接硬编码为 pypi.tuna.tsinghua.edu.cn 等，但传递原始Host更灵活
            proxy_set_header Host $proxy_host; # 使用 $proxy_host 变量
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;

            # （可选，但推荐）增加 SSL 相关的代理设置
            proxy_ssl_server_name on; # 这会让Nginx在TLS握手中发送正确的服务器名称(SNI)
            proxy_ssl_session_reuse on; # 启用SSL会话复用以提高性能
        }
    }

  3. 启用配置并重启Nginx:

    1
    2
    3
    sudo ln -s /etc/nginx/sites-available/pypi-proxy /etc/nginx/sites-enabled/
    sudo nginx -t          # 测试配置语法
    sudo systemctl restart nginx # 重启Nginx

    现在，一个强大的、能自动切换源的反向代理已经在 http://192.168.10.158:8088 上为你待命。

第四章：合体！将Devpi接入Nginx代理

万事俱备，只差最后一步：让 devpi 通过我们的 Nginx “护城河”去访问世界。

  1. 停止Devpi服务:

    1
    sudo systemctl stop devpi

  2. 修改Devpi的启动参数:

    1
    sudo nano /etc/systemd/system/devpi.service

  3. 在 ExecStart 行的末尾，添加 --mirror-url 参数，指向我们的Nginx代理：

    1
    2
    3
    # ...
    ExecStart=/home/your_username/.local/bin/devpi-server --host=0.0.0.0 --port=3141 --mirror-url http://192.168.10.158:8088/pypi
    # ...

  4. 重新加载并启动Devpi:

    1
    2
    sudo systemctl daemon-reload
    sudo systemctl start devpi

第五章：享受成果 - 配置客户端

现在，让团队的所有开发者和CI/CD服务器都享受到这个稳定高速的镜像源吧！

在每一台客户端机器上，创建或修改 ~/.pip/pip.conf (macOS/Linux) 或 %APPDATA%\pip\pip.ini (Windows) 文件：

1
2
3
[global]
index-url = http://192.168.10.158:3141/root/pypi/
trusted-host = 192.168.10.158
  • index-url 指向我们搭建的 devpi 服务。
  • trusted-host 告诉 pip 这是一个可信任的HTTP源。

See

python
Next:
使用 Docker Compose 快速部署 Shadowsocks 代理服务教程

    • Copyright © 2023 - Now Zhaoqi.Cao | Powered by Hexo | Theme Bamboo

    Total visits： times |