第16章 故障排查:PyPI 可信发布常见问题
故障排查 GitHub 上禁止的触发器
注意 禁止触发器的列表可能会随时间变化。
GitHub Actions 中的某些工作流触发器从根本上来说是危险的,攻击者历史上曾利用它们来破坏软件包注册表的上传安全。因此,即使其他方面都有效,PyPI 目前也禁止来自某些触发器的可信发布(Trusted Publishing)流程。当前禁止的触发器集合包括:
pull_request_target issue_comment
GitHub 上的可复用工作流
目前,可复用工作流(Reusable workflows)不能用作可信发布者(Trusted Publisher)的工作流。这是一个实际限制,正在 warehouse#11096 中跟踪。
速率限制
PyPI 目前对可信发布者注册实施速率限制:单个用户或 IP 地址在 24 小时窗口内注册的发布者可不超过 100 个。
这对大多数用户来说应该足够了(因为相对于发布者的使用频率,发布者注册应该是很少发生的),但拥有大量项目或通过共享 IP 地址访问 PyPI 的维护者可能会遇到速率限制错误。如果发生这种情况,请等待 24 小时,重试,如果问题持续存在,请联系 PyPI 管理员。
令牌铸造
以下是 mint-token 端点可能返回的错误列表的快速枚举:
not-enabled:这表明 PyPI 后端完全禁用了 OIDC。除非 PyPI 管理员决定禁用 OIDC 支持,否则在正常运行期间你不应该看到此消息。 invalid-payload:提交给 mint-token 端点的 OIDC 令牌负载格式不正确。负载必须是一个 JSON 序列化对象,具有以下布局:
{ "token": "oidc-token-here" }
不支持其他布局。
invalid-payload 并附带未知可信发布发行者错误:生成令牌的 OIDC 提供程序不受支持。这可能发生在自托管 GitLab 实例上,因为目前仅支持托管在 https://gitlab.com 上的项目。 invalid-token:OIDC 令牌本身格式不正确、签名无效、已过期等。这涵盖了 OIDC 令牌(即 JWT)在与发布者匹配之前可能发生的几乎任何故障模式。 invalid-pending-publisher 和 invalid-publisher:OIDC 令牌本身格式良好(且签名有效),但不匹配任何已知(待处理)的 OIDC 发布者。这可能表示用户/项目设置中指定的 OIDC 发布者与实际 OIDC 令牌中表示的声明之间存在不匹配。请检查是否有拼写错误!如果你正在使用 GitHub Actions,请检查工作流是否使用了与在 PyPI 上配置发布者时相同的环境。 对于之前工作正常的项目出现 invalid-publisher:这通常表示拼写错误,或双方都有变更。我们见过的一个例子是当源仓库被重命名时,PyPI 上的配置仍继续使用旧仓库名。对于 GitHub,请检查 repository_owner、repository 和工作流文件名值在两边是否一致。
上传错误
在使用待处理发布者创建新项目时,你可能会遇到如下错误: 非用户身份不能创建新项目。这可能是因为成功使用了待处理发布者,但项目名称指定不正确(无论是在发布者中还是在项目元数据中)。 请确保两者匹配。
这意味着待处理发布者成功创建了项目,但上传元数据中提供的项目名称与其不匹配。如果待处理发布者的项目名称或元数据中的名称拼写错误或以其他方式错误输入,都可能发生这种情况。 例如,一个在元数据中指定 python-example 但在待处理发布者中注册为 example 的项目会导致此错误。 要解决此问题,你必须确定这两个名称中哪一个是正确的:
如果待处理发布者中使用的名称是正确的,则你必须更新项目元数据以反映该名称。后续使用可信发布者的上传将自动正常工作,无需进一步操作。
如果项目元数据中使用的名称是正确的,则你必须:
进入你的项目并删除错误创建的项目。 这也将删除错误注册的可信发布者。
使用更正后的项目名称创建新的待处理发布者。
下一次上传将创建具有预期名称的项目,后续上传也将按预期工作。