配置 pip 与 uv 的 PyPI 代理缓存

之前https://pypi.org/simple

之后http://localhost:23333/pypi/simple/

pip、uv、Poetry、Pipenv 和 PDM 都使用 Depsilo 的 /pypi/simple/ 端点。

Portal 只生成配置

在 Depsilo Portal 中选择 Python 与对应客户端，可以得到按当前实例地址生成的配置。Portal 只展示和复制内容，不会修改你的机器或项目文件。

配置客户端

优先使用本次命令、项目或项目虚拟环境的配置。修改前记录原 index，合并需要的字段，不要覆盖现有配置文件。

pip

先用命令参数接入，只影响本次安装，不写入用户配置。将 requirements.txt 换成项目实际使用的依赖文件：

python -m pip install -r requirements.txt \
  --index-url http://localhost:23333/pypi/simple/ \
  --trusted-host localhost:23333

使用有效 HTTPS 证书时，省略 --trusted-host。

需要持久化时，先激活项目的虚拟环境，再将以下设置合并到该环境的配置文件。Unix/macOS 为 $VIRTUAL_ENV/pip.conf，Windows 为 %VIRTUAL_ENV%\pip.ini；可用 python -m pip config debug 查看位置。pip 不会自动读取仓库根目录的 pip.conf。

项目虚拟环境的 pip 配置

[global]
index-url = http://localhost:23333/pypi/simple/
# 仅明文 HTTP 需要：
trusted-host =
    localhost:23333

若已有 trusted-host 列表，把 Depsilo 的主机与端口加入原列表，保留其他条目。这里的 [global] 表示对 pip 的所有子命令生效，配置文件位置才决定影响范围。

可选：用户级配置。 只有希望当前用户的其他项目也使用 Depsilo 时，才执行：

python -m pip config --user set global.index-url http://localhost:23333/pypi/simple/

先备份用户配置；HTTP 实例还需在同一用户配置中合并 trusted-host，不要覆盖已有列表。虚拟环境中也可以用 python -m pip config --site set global.index-url URL 明确修改当前环境。范围与优先级见 pip 官方文档；裸 pip config set 不保证写入项目虚拟环境。

uv

pyproject.toml

[[tool.uv.index]]
name = "depsilo"
url = "http://localhost:23333/pypi/simple/"
default = true

设置 default = true，让 uv 默认通过 Depsilo 解析包，而不是并行使用公网索引。

Poetry

poetry source add --priority=primary depsilo \
  http://localhost:23333/pypi/simple/

等价的项目配置如下：

pyproject.toml

[[tool.poetry.source]]
name = "depsilo"
url = "http://localhost:23333/pypi/simple/"
priority = "primary"

不要用 extra-index-url 作为公网回退

pip 会把多个索引中的候选版本放在一起选择。将公网 PyPI 配为 extra-index-url 可能绕过 Depsilo 的策略决定。需要强制所有请求经过 Depsilo 时，应只保留受控入口，并配合网络出口控制。

验证请求

1. 检查实例就绪状态

   curl -fsS http://localhost:23333/ready

2. 发出一次不修改环境的请求

   python -m pip install --dry-run --ignore-installed --no-cache-dir --no-deps \
     --index-url http://localhost:23333/pypi/simple/ \
     --trusted-host localhost:23333 six

   这是本次命令的连接测试，不会安装包；使用 HTTPS 时省略 --trusted-host。pip 可能只读取索引与包元数据，不能假设这一步已下载完整的 wheel 或源码包。

3. 在 Admin 中确认流量

   打开 Admin 的 Access logs（/admin/logs），按时间确认 PyPI 请求、包名与响应状态，区分索引、元数据与实际包文件。客户端成功退出或命中本地缓存，都不能单独证明 Depsilo 的制品缓存命中。

4. 单独验证制品缓存

   验证缓存提供了绕过包管理器本地缓存、独立下载同一制品并核对日志的方法，使用 npm tarball 作为示例。验证 Python 下载时，应核对实际 wheel 或源码包的请求记录，不能用索引日志代替。缓存已预热时，第一次下载也可能命中。

在 CI 中使用

通过 CI 环境变量覆盖索引，无需改写 requirements 文件。把示例主机名替换为 Runner 实际可达的 Depsilo 地址：

export PIP_INDEX_URL=http://depsilo.internal:23333/pypi/simple/
# 仅明文 HTTP 需要：
export PIP_TRUSTED_HOST=depsilo.internal:23333

python -m pip install -r requirements.txt

如果 CI 在容器中运行，localhost 指向容器自身，不能代表宿主机上的 Depsilo。

常见问题

HTTPS 还需要 trusted-host 吗？

有效 HTTPS 证书不需要这个例外。trusted-host 会让 pip 信任没有有效 HTTPS 的主机；本页只在明文 HTTP 示例中使用它。切换到 HTTPS 后，仅移除 Depsilo 对应的旧例外，保留其他源已有的设置。

如何回滚？

命令参数只对那次调用生效。持久化配置需在原来修改的虚拟环境或用户文件中恢复旧 index，并移除本次新增的 Depsilo 信任例外，保留其他字段。不要通过新增一个并行公网 fallback 来“回滚”。

其他 Python 客户端使用哪个端点？

Pipenv 与 PDM 也使用 /pypi/simple/。在 Portal 中选择对应客户端，复制它提供的项目级配置。

请求异常或策略拒绝时，见故障排查。