企业官网建设流程全解析

uv 如何用 uv auth 管理私有源凭据？login、logout、token 与 auth helper

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv

当项目依赖托管在私有包索引上时，uv 需要凭据才能拉取包内容。uv auth提供了高层的凭据管理接口：用uv auth login为某个主机存储凭据，之后 uv 在执行需要从该服务获取内容的打包操作时会自动使用它们。本文覆盖凭据的存入（login）、查看（token）、删除（logout）、提供给外部工具（auth helper）四个操作，以及凭据的存储位置与加密选项。

先说明几个文档中明确给出的边界：

• 目前只支持 HTTPS Basic 认证，凭据还不会用于 Git 请求；
• 凭据不会被验证，即错误的凭据在uv auth login时不会报错；
• uv 默认在发起未认证请求失败后才去查找凭据，个别索引（如 GitLab）会把未认证请求转发到公共索引，导致凭据不会被查找，此类情况需用authenticate配置调整（见文末）。

用 uv auth login 存储私有源凭据

为某个服务添加凭据的基本命令：

$ uv auth login example.com

执行后会交互式提示输入凭据。也可以用--username、--password选项直接提供，或使用--token选项——后者适用于使用__token__或任意用户名换取令牌的服务。

文档建议使用 stdin 传递密文：用-表示从 stdin 读取值，例如--password：

$ echo 'my-password' | uv auth login example.com --password -

同样的模式也可以用于--token。

把凭据加入存储后，uv 会在需要从该服务获取内容的打包操作中使用它们。文档明确说明凭据不会被验证，所以 login 成功不代表服务端认证能过，实际能否拉取包要在后续的操作中确认。

查看与删除凭据

查看某个 URL 存储的凭据，用uv auth token：

$ uv auth token example.com

如果登录时使用了用户名，则查看时也需要带上用户名：

$ uv auth token --username foo example.com

这是核对"凭据是否已为某主机存好"的直接方式。

删除某个服务的凭据用uv auth logout：

$ uv auth logout example.com

注意：logout 只是把凭据从本地存储中删除，不会通知远端服务器使其失效，远端的令牌或密码仍然可用。

凭据存放在哪里？是否加密？

凭据持久化到 uv 的凭据存储中。默认情况下凭据写入一个明文文件，位于 uv 的 state 目录下，例如 Unix 上的~/.local/share/uv/credentials/credentials.toml。文档说明该文件目前不打算被手动编辑。

如果想避免明文落盘，可以启用系统原生的加密存储后端：

export UV_PREVIEW_FEATURES=native-auth

启用后 uv 使用操作系统原生的密钥存储机制：macOS 上使用 Keychain Services，Windows 上使用 Windows Credential Manager，Linux 上使用基于 DBus 的 Secret Service API。两点限制需要注意：该机制目前处于 preview、仍在实验中，未来会成为默认存储机制；且 uv 只会在原生存储中查找它自己写入的凭据，不会读取其他应用持久化在那里的凭据。

uv 查找 HTTP 凭据的来源按优先级依次为：

1. URL 中嵌入的凭据，例如https://<user>:<password>@<hostname>/...；
2. .netrc配置文件（始终启用，路径从NETRC环境变量读取，未定义时回退到~/.netrc）；
3. uv 凭据存储（即uv auth写入的位置）；
4. keyring provider（默认关闭，可用--keyring-provider subprocess、UV_KEYRING_PROVIDER=subprocess或tool.uv.keyring-provider = "subprocess"启用，通过调用keyring命令获取凭据）。

凭据可作用于以下上下文中指定的主机：[index]、index-url、extra-index-url、find-links，以及package @ https://...形式的直接 URL。凭据缓存只持续单条命令的时长，不会跨 uv 调用缓存；uv add不会把索引凭据写入pyproject.toml或uv.lock，但会持久化直接 URL 中的凭据。

用 uv auth helper 向外部工具提供凭据

如果其他工具支持 credential helper 协议，可以让它向 uv 请求 HTTP 凭据。目前 uv 支持 Bazel credential helper 协议。uv auth helper由外部工具调用：从 stdin 读取 JSON 请求，向 stdout 写入 JSON 响应；当匹配到凭据时，响应包含Authorization头：

$ echo '{"uri": "https://example.com/path"}' | uv --preview-features auth-helper auth helper --protocol=bazel get {"headers":{"Authorization":["Basic ..."]}}

（以上为文档示例输出。）

如果找不到凭据，uv 返回空的头集合：

{ "headers": {} }

uv auth helper目前是实验性功能，需要加--preview-features auth-helper或使用环境变量UV_PREVIEW_FEATURES=auth-helper来消除警告。

在 Bazel 中使用的完整路径是：先用uv auth login https://packages.example.com为 Bazel 要拉取文件的主机认证，然后在.bazelrc中为匹配的主机配置 credential helper，并放置一个包装脚本（文档中给出的示例）：

#!/usr/bin/env bash exec uv --preview-features auth-helper auth helper --protocol=bazel "$@"

该脚本需要可执行：chmod +x bazel/uv-auth-helper。更完整的配置见 Bazel 集成指南。

凭据未被查找时的排查与限制

• 默认行为下，uv 先尝试未认证请求，失败后才查找凭据。如果索引会把未认证请求转发到公共索引（如 GitLab 的行为），uv 就不会去查找凭据。对此可对该索引设置authenticate = "always"，uv 会主动查找凭据，找不到时直接报错：

  [[tool.uv.index]] name = "example" url = "https://example.com/simple" authenticate = "always"

• 为防止泄露凭据，也可以对某个索引设置authenticate = "never"，uv 将永不为其查找凭据，且如果凭据被直接提供会报错。

• 在first-index搜索策略下，遇到 HTTP 401/403 时 uv 会停止跨索引搜索；如需忽略特定错误码，可用ignore-error-codes配置（例如ignore-error-codes = [403]）。

更多索引认证细节（环境变量方式UV_INDEX_<名称>_USERNAME/UV_INDEX_<名称>_PASSWORD、URL 内嵌凭据不会写入uv.lock等）见 索引认证文档，凭据存储与 netrc、keyring 的完整说明见 HTTP 认证文档，CLI 命令的完整说明见 uv auth CLI 文档。

【免费下载链接】uvAn extremely fast Python package and project manager, written in Rust.项目地址: https://gitcode.com/GitHub_Trending/uv/uv