2.7.11 与 Google Artifact Registry 配合使用

  2 分钟阅读  

原文链接: https://docs.astral.sh/uv/guides/integration/google/

2.7.11 与 Google Artifact Registry 配合使用

uv 可以从 Google Artifact Registry 安装包，既可以使用访问令牌，也可以使用 keyring 包。

注意

本指南假设 gcloud CLI 已安装并完成身份验证。

要使用 Google Artifact Registry，请把索引添加到你的项目：

1
2
3
4

# pyproject.toml
[[tool.uv.index]]
name = "private-registry"
url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"

使用 Google 访问令牌进行身份验证

凭据可以通过 “Basic” HTTP 身份验证方案提供。把访问令牌放在 URL 的密码字段中。用户名必须是 oauth2accesstoken，否则身份验证会失败。

用 gcloud 生成令牌：

1
2
3

export ARTIFACT_REGISTRY_TOKEN=$(
    gcloud auth application-default print-access-token
)

注意

你可能需要传入额外参数才能正确生成令牌（例如 --project），这里只是一个基本示例。

然后这样为该索引设置凭据：

1
2

export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken
export UV_INDEX_PRIVATE_REGISTRY_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"

注意

PRIVATE_REGISTRY 应与你在 pyproject.toml 中定义的索引名称一致。

使用 keyring 和 keyrings.google-artifactregistry-auth 进行身份验证

你也可以使用 keyring 包配合 keyrings.google-artifactregistry-auth 插件向 Artifact Registry 进行身份验证。由于这两个包是向 Artifact Registry 进行身份验证所必需的，它们必须先从 Artifact Registry 之外的来源预安装。

keyrings.google-artifactregistry-auth 插件封装了 gcloud CLI，用于生成短期访问令牌、把它们安全地存入系统 keyring，并在过期时刷新。

uv 仅支持以子进程模式使用 keyring 包。keyring 可执行文件必须在 PATH 中，也就是全局安装或在当前激活环境中安装。keyring CLI 要求 URL 中包含用户名，且必须是 oauth2accesstoken。

1
2
3
4
5
6
7
8

# 从公共 PyPI 预安装 keyring 与 Artifact Registry 插件
uv tool install keyring --with keyrings.google-artifactregistry-auth

# 启用 keyring 身份验证
export UV_KEYRING_PROVIDER=subprocess

# 设置该索引的用户名
export UV_INDEX_PRIVATE_REGISTRY_USERNAME=oauth2accesstoken

注意

可以使用 tool.uv.keyring-provider 设置在 uv.toml 或 pyproject.toml 中启用 keyring。

同样，索引的用户名也可以直接写在索引 URL 中。

发布包

如果你还想把自己的包发布到 Google Artifact Registry，可以按构建和发布指南中所述使用 uv publish。

首先，为目标索引添加 publish-url。例如：

1
2
3
4
5

# pyproject.toml
[[tool.uv.index]]
name = "private-registry"
url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/simple/"
publish-url = "https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/"

然后配置凭据（如果未使用 keyring）：

1
2

$ export UV_PUBLISH_USERNAME=oauth2accesstoken
$ export UV_PUBLISH_PASSWORD="$ARTIFACT_REGISTRY_TOKEN"

并发布包：

1

$ uv publish --index private-registry

如果不想把 publish-url 添加到项目，也可以设置 UV_PUBLISH_URL 后使用 uv publish：

1
2

$ export UV_PUBLISH_URL=https://<REGION>-python.pkg.dev/<PROJECT>/<REPOSITORY>/
$ uv publish

注意这种方式并不理想，因为 uv 在上传产物之前无法检查该包是否已经发布。

最后修改 September 25, 2026: 更新 (221c74c33)