
用 nginx 约 40 行配置为 Forgejo runner 搭建 PyPI 缓存
来源标题:A PyPI cache for your Forgejo runners
一篇技术文章介绍如何用约 40 行 nginx 配置搭建 PyPI 缓存,让 Forgejo runner 上的 Python 任务不再重复下载 numpy、pandas、FastAPI 等包。缓存需分两部分:索引页和 files.pythonhosted.org 上的包文件,且 pip 和 uv 会用 sha256 校验每个文件。作者在 nginx 1.26.3、uv 0.13.9、forgejo-runner v13.2.1 上做了验证。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
每个跑在全新 runner 上的 Python 任务都要重新下载同样的包:numpy、pandas、FastAPI 以及其余那些。在 runner 旁边放一个包缓存就能省掉这一步,用 nginx 大约 40 行就能搭起来。下面讲讲我们的这个缓存是怎么工作的、过程中踩了哪些坑,以及它省下了多少。
以下细节在 nginx 1.26.3、pip、uv 0.13.9 和 forgejo-runner v13.2.1 上验证过,环境是 Ubuntu 26.04 加 Python 3.14。耗时数据来自我们自己的环境,你的结果会不一样。
我们之前在 Forgejo Actions 上缓存 Python 构建里写过这个,效果不错。网络上的缓存做的是另一件事。它被所有 runner 共享,所以第一个需要某个包的任务会替所有人把它填进缓存;而且即使你的 lock 文件变了它照样有用,因为只需要下载新增的包。两者可以一起用。
pip 安装一个包时,会先向索引(PyPI)请求一个页面,页面上列出文件以及从哪里下载。这些文件放在另一台服务器 files.pythonhosted.org 上。每个条目还带一个 sha256 哈希,pip 和 uv 都会拿每个文件去核对。
所以缓存需要两部分:一部分存索引页,一部分存文件。而且索引页在转发过程中必须被改写。如果页面上写的还是 files.pythonhosted.org,你的 runner 就会绕过缓存,直接去 PyPI 下载。
nginx 两件事都能做。sub_filter 会改写索引页里的文件地址,这样下载也会走缓存回来。PyPI 声明其索引页可以缓存 10 分钟,nginx 照此执行。包文件永远不会变,所以保留 30 天。
proxy_cache_path /srv/cache/pypi levels=1:2 keys_zone=pypi:20m max_size=10g inactive=90d use_temp_path=off; server { listen 8081; add_header X-Cache-Status $upstream_cache_status always;
运行时解析域名,而不是只在启动时解析一次,这样 PyPI 地址变化
也能跟上。这里用你自己的 DNS 服务器。
resolver 127.0.0.53 valid=300s ipv6=off; proxy_http_version 1.1; proxy_ssl_server_name on; proxy_ssl_verify on; proxy_ssl_trusted_certificate /etc/ssl/certs/ca-certificates.crt; proxy_cache pypi; proxy_cache_lock on; proxy_cache_revalidate on; proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504; proxy_cache_valid 404 1m;
索引页。Accept 头是缓存键的一部分,因为客户端可能在同一地址
请求 HTML 或 JSON。
location /simple/ { set $pypi_host pypi.org; proxy_pass https://$pypi_host$request_uri; proxy_set_header Host pypi.org; proxy_set_header Accept-Encoding ""; proxy_cache_key "$request_uri|$http_accept"; sub_filter_types application/vnd.pypi.simple.v1+json application/vnd.pypi.simple.v1+html application/vnd.pypi.simple.latest+json application/vnd.pypi.simple.latest+html; sub_filter 'https://files.pythonhosted.org/' 'http://cache.example.internal:8081/files/'; sub_filter_once off;
包文件。
location /files/ { set $files_host files.pythonhosted.org; rewrite ^/files/(.*)$ /$1 break; proxy_pass https://$files_host; proxy_set_header Host files.pythonhosted.org; proxy_cache_valid 200 30d; location / { return 404;
把 cache.example.internal 换成你的 runner 访问缓存时用的名字或地址。X-Cache-Status 头会告诉你响应是 MISS 还是 HIT,搭建的时候很方便。
通过它只能访问这两个 PyPI 主机,而且缓存的文件仍会被 pip 和 uv 拿索引里的哈希去核对。我们把缓存里的一个文件和索引里的哈希做了对比,确认一致。
pip 从 /etc/pip.conf 读取设置:
[global] index-url = http://cache.example.internal:8081/simple/ trusted-host = cache.example.internal
trusted-host 这一行是必需的,因为缓存用的是明文 HTTP。没有它,pip 会提示该主机“不是受信任或安全的主机,已被忽略”,然后什么都找不到。把缓存放在私有网络里,因为明文 HTTP 意味着链路上的任何人都能读到流量。
如果把地址写进一个始终存在的配置里,那么缓存一出故障,所有 Python 任务都会失败。我们不想要这个。所以配置是在任务启动时写入的,而且只在缓存有响应时才写:
#!/bin/sh M=http://cache.example.internal:8081 if curl -fsS -m 5 -o /dev/null "$M/simple/pip/"; then printf '[global]\nindex-url = %s/simple/\ntrusted-host = cache.example.internal\n' "$M" > /etc/pip.conf else rm -f /etc/pip.conf fi
我们在每个任务启动前运行它。如果缓存在 5 秒内没有响应,就没有配置文件,pip 会直接去 PyPI。我们通过在一台任务机器上切断缓存来测试过:pip 跳过了缓存,直接从 PyPI 安装了包。
我们没有动 uv,原因有两个,都是测试中发现的。
所以如果你想让 uv 使用缓存,就在使用 uv pip install 的任务里自己设置 UV_DEFAULT_INDEX,而不要在 uv lock 会运行的任何地方设置它。
这些是 2026 年 11 月 19 日在 2 核 CPU 上跑的单个任务,安装 27 个包,包括 numpy、pandas、scipy 和 FastAPI。
我们的网络链路和其他任务共用,所以每次运行的时间会有波动,这也是 uv 的区间这么宽的原因。把这些数字理解成“快得多”,而不是精确值。
所以第一个任务会多花一点时间,之后每个任务都快得多。每个任务结束后就被删除的 runner 自己不会保留任何包,所以必须有 runner 之外的东西来记住它们。
这正是 Stoke CI 为你做的事。runner 的任务机器默认就为 pip 使用这个缓存,并在任务启动时做上面说的检查,所以缓存出问题不会让任务失败。你接上你的 Forgejo,把 runs-on: 改成 stoke-2cpu,pip 就已经指向它了。beta 期间免费。
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。