Dockerfile中从Gitlab私有PyPI源pip安装包失败求助

问题背景 #

本地执行以下命令可正常从GitLab私有源安装依赖：

pip install -r requirements.txt --index-url https://username:password@private.gitlab.internal --cert /usr/local/share/ca-certificates/cert.crt

但将该操作迁移到基于python:3.12的Dockerfile中，通过GitLab流水线构建时失败。构建命令为：

docker build -t image_name --build-arg "PRIVATE_PYPI_USERNAME=username" --build-arg "PRIVATE_PYPI_PASSWORD=password" --build-arg "CA_CERTIFICATE_LOCATION=cert.crt" --progress=plain .

Dockerfile中生成的${INDEX_URL}正确，但pip安装时提示找不到black==24.4.0（该包在私有PyPI中存在且本地可正常安装），错误日志如下：

#20 [16/19] RUN pip install -r requirements.txt --index-url "https://username:password@private.gitlab.internal/api/v4/projects/9/packages/pypi/simple/" --cert /usr/local/share/ca-certificates/cert.crt --trusted-host private.gitlab.internal
#20 0.678 Using pip 24.0 from /usr/local/lib/python3.12/site-packages/pip (python 3.12)
#20 0.728 Looking in indexes: https://username:****@private.gitlab.internal/api/v4/projects/9/packages/pypi/simple/
#20 1.034 ERROR: Could not find a version that satisfies the requirement black==24.4.0 (from versions: none)
#20 1.035 ERROR: No matching distribution found for black==24.4.0
#20 ERROR: process "/bin/sh -c pip install -r requirements.txt --index-url \"${INDEX_URL}\" --cert /usr/local/share/ca-certificates/cert.crt --trusted-host private.gitlab.internal" did not complete successfully: exit code: 1
------
 > [16/19] RUN pip install -v -r requirements.txt --index-url "https://username:password@private.gitlab.internal/api/v4/projects/9/packages/pypi/simple/" --cert /usr/local/share/ca-certificates/cert.crt --trusted-host private.gitlab.internal:
0.678 Using pip 24.0 from /usr/local/lib/python3.12/site-packages/pip (python 3.12)
0.728 Looking in indexes: https://username:****@private.gitlab.internal/api/v4/projects/9/packages/pypi/simple/
1.034 ERROR: Could not find a version that satisfies the requirement black==24.4.0 (from versions: none)
1.035 ERROR: No matching distribution found for black==24.4.0
------
Dockerfile:31
--------------------
 29 |     # Install
 30 |     RUN pip install --upgrade pip
 31 | >>> RUN pip install -v -r requirements.txt --index-url "${INDEX_URL}" --cert /usr/local/share/ca-certificates/cert.crt --trusted-host private.gitlab.internal
 32 |
 33 |     # Make sure environment variables can be read
--------------------
ERROR: failed to solve: process "/bin/sh -c pip install -v -r requirements.txt --index-url \"${INDEX_URL}\" --cert /usr/local/share/ca-certificates/cert.crt --trusted-host private.gitlab.internal" did not complete successfully: exit code: 1

已尝试的无效操作 #

• 本地执行Docker构建日志中输出的相同命令，可正常运行
• 在容器内用curl加--cacert参数访问black的wheel文件URL，可正常访问
• 尝试--no-cache-dir、--trusted-host参数组合，给${INDEX_URL}加引号，均无效果

可能的原因及排查点 #

1. 流水线账号的权限不足 #

本地使用的账号可能拥有GitLab项目9的包读取权限，但流水线运行时使用的账号（比如GitLab Runner的服务账号）没有访问该私有PyPI源的权限。

• 检查GitLab项目9的包仓库权限设置，确认流水线所属的账号/群组/项目角色具备读取包的权限
• 在流水线的Docker构建步骤中临时添加验证命令：

  RUN curl -u ${PRIVATE_PYPI_USERNAME}:${PRIVATE_PYPI_PASSWORD} --cert /usr/local/share/ca-certificates/cert.crt https://private.gitlab.internal/api/v4/projects/9/packages/pypi/simple/black/
  

  查看返回内容是否包含black==24.4.0的下载链接，以此验证权限是否正常。

2. pip隐式访问公共PyPI导致的混淆 #

虽然指定了--index-url，但如果私有源中没有适配当前环境的包格式（比如只有Windows版本的wheel，或者缺少python3.12兼容的包），pip可能会尝试去公共PyPI查找，若网络受限或参数阻止了公共源访问，就会提示找不到包。

• 检查私有源中black==24.4.0的包格式，确认存在适配linux/amd64、python3.12的版本
• 添加--no-index参数强制pip只从指定私有源查找，避免访问公共PyPI：

  pip install -v -r requirements.txt --no-index --index-url "${INDEX_URL}" --cert /usr/local/share/ca-certificates/cert.crt --trusted-host private.gitlab.internal
  

3. 系统证书未正确加载 #

虽然把证书复制到了/usr/local/share/ca-certificates/，但如果没有执行update-ca-certificates命令，系统信任链不会更新，pip依赖系统证书池时会无法识别该证书（而curl是手动指定证书所以能访问）。

• 在Dockerfile的证书复制步骤后添加更新命令：

  COPY ${CA_CERTIFICATE_LOCATION} /usr/local/share/ca-certificates/
  RUN update-ca-certificates
  

• 也可以在pip命令前添加验证：RUN ls -l /usr/local/share/ca-certificates/cert.crt，确认证书文件存在且路径正确。

4. 构建参数的特殊字符转义问题 #

如果密码包含@、:、%等特殊字符，在构建参数传递时可能被shell转义，导致INDEX_URL中的密码失真，虽然日志显示username:****，但实际认证信息不正确。

• 在Dockerfile中用ENV变量直接拼接URL，避免shell转义：

  ARG PRIVATE_PYPI_USERNAME
  ARG PRIVATE_PYPI_PASSWORD
  ENV INDEX_URL=https://${PRIVATE_PYPI_USERNAME}:${PRIVATE_PYPI_PASSWORD}@private.gitlab.internal/api/v4/projects/9/packages/pypi/simple/
  

• 可临时添加RUN echo "${INDEX_URL}"查看实际生成的URL（注意不要泄露密码，测试后删除该命令）。

5. GitLab Runner的网络限制 #

流水线所在的GitLab Runner可能处于受限网络环境，无法正常访问私有GitLab源的HTTPS端口，或者代理配置未同步到Docker构建环境。

• 检查Runner的网络连通性，确认能访问private.gitlab.internal:443
• 如果使用代理，在Dockerfile中添加代理环境变量：

  ENV HTTP_PROXY=http://proxy.example.com:8080
  ENV HTTPS_PROXY=http://proxy.example.com:8080
  

内容的提问来源于stack exchange，提问作者Lewistrick