青蛙小白
博客 / 2025/09

uv 认证指南：全面掌握私有包索引仓库的访问

2025/09/08 · — 字 · 阅读约 — 分钟 ·
#uv
目录

在现代 Python 项目开发中，访问私有包索引和仓库是比较常见的需求。uv 作为新一代的 Python 包管理工具，提供了灵活且安全的认证机制来处理这些场景。

uv v0.8.15中新增了uv auth认证管理 , 全新的认证命令集，用于管理 Python 包仓库的登录凭证。解决了私有包仓库访问的痛点，提供统一的凭证管理方式，让企业用户能够更安全地使用内部包仓库。

认证概述

uv 支持多种认证方式来访问私有仓库或包索引：

  1. CLI 认证：通过 uv auth 命令管理凭据
  2. HTTP 认证：支持多种凭据存储方式
  3. Git 认证：处理 Git 仓库访问
  4. TLS 证书认证：处理证书验证和客户端证书
  5. 第三方服务认证：如 Hugging Face 等

CLI 认证

基本用法

uv 提供了简洁的命令行接口来管理认证凭据：

# 登录到服务
uv auth login example.com

# 交互式登录
uv auth login example.com --username myuser

# 使用 token 登录
uv auth login example.com --token my-secret-token

# 查看已存储的凭据
uv auth token example.com

# 登出
uv auth logout example.com

安全最佳实践

为了提高安全性，建议通过 stdin 传递敏感信息：

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

凭据存储

  • 默认情况下，凭据以明文形式存储在文件中
  • 可以启用加密存储（预览功能）：UV_PREVIEW_FEATURES=native-auth
  • 目前仅支持 HTTPS Basic 认证

HTTP 认证

认证优先级

uv 按以下优先级查找认证凭据：

  1. URL 内嵌凭据：https://<user>:<password>@<hostname>/...
  2. .netrc 配置文件
  3. uv 凭据存储
  4. keyring provider（默认关闭）

.netrc 文件

传统的 .netrc 文件仍然受支持：

machine pypi.example.com
login myuser
password mypass

原生密钥存储

启用系统原生密钥管理（预览功能）：

export UV_PREVIEW_FEATURES=native-auth

这将使用操作系统的原生密钥管理系统，如 macOS 的 Keychain 或 Windows 的 Credential Manager。

Git 认证

uv 允许通过 SSH 或 HTTP 认证，从私有 Git 仓库中安装软件包。

SSH 认证

使用 SSH 协议访问 Git 仓库：

# 在 pyproject.toml 中
[dependency-groups]
dev = ["my-package @ git+ssh://[email protected]/user/repo.git"]

HTTPS 认证

支持多种 HTTPS 认证格式：

# 用户名和 token
git+https://user:[email protected]/user/repo.git

# 仅 token
git+https://[email protected]/user/repo.git

# 仅用户名（需要后续认证）
git+https://[email protected]/user/repo.git

GitHub 集成

推荐使用 GitHub CLI 进行认证：

gh auth login
重要提示 使用 GitHub Personal Access Token 时，用户名是任意的，GitHub 不允许在 URL 中使用账户名和密码。

TLS 证书认证

系统证书

使用系统证书存储：

uv --native-tls install package
# 或
export UV_NATIVE_TLS=true

自定义证书

# 证书包路径
export SSL_CERT_FILE=/path/to/cert-bundle.pem

# 客户端证书（mTLS）
export SSL_CLIENT_CERT=/path/to/client-cert.pem

允许不安全连接

在 pyproject.toml 中配置：

[tool.uv]
allow-insecure-host = ["internal.company.com"]
警告 仅在受信任的环境中使用此选项。

第三方服务认证

Hugging Face

uv 自动支持 Hugging Face 认证：

export HF_TOKEN=hf_your_token_here
uv run https://huggingface.co/datasets/<user>/<name>/resolve/<branch>/main.py

可以通过设置环境变量UV_NO_HF_TOKEN=1来禁用 Hugging Face 的自动认证。

实战场景

场景 1：企业私有 PyPI

# 1. 配置私有索引
echo '[[tool.uv.index]]
name = "company-pypi"
url = "https://pypi.company.com/simple/"' >> pyproject.toml

# 2. 登录认证
uv auth login pypi.company.com --username employee-id

除了使用uv auth cli的方式进行认证，还可以使用环境变量的形式，这在CI/CD场景中十分常见。

[[tool.uv.index]]
name = "private-pypi"
# url = "https://mirrors.aliyun.com/pypi/simple/"
url = "https://pypi.example.com/repository/pypi-public/simple"
default = true

下面INDEX_PRIVATE是配置文件中索引名称private-pypi的大写版本，非字母数字字符被替换为下划线：

export UV_INDEX_PRIVATE_PYPI_USERNAME=username
export UV_INDEX_PRIVATE_PYPI_PASSWORD=password

场景 2：GitHub 私有仓库依赖

# 1. 使用 GitHub CLI 认证
gh auth login

# 2. 在 pyproject.toml 中添加依赖
dependencies = [
    "internal-lib @ git+https://github.com/company/internal-lib.git"
]

安全考虑

  1. 凭据隔离：uv 不会将认证信息持久化到 pyproject.toml 或 uv.lock
  2. 临时缓存：凭据仅在命令执行期间缓存
  3. 加密存储：考虑启用原生密钥存储功能
  4. 最小权限：为不同服务使用专门的访问令牌
  5. 定期轮换：定期更新访问凭据

总结

uv 的认证系统设计灵活且安全，能够满足从个人开发到企业级部署的各种需求。通过合理选择认证方法和遵循安全最佳实践，可以安全高效地管理 Python 项目的依赖访问。但还需注意，安全性和便利性需要平衡，选择最适合项目需求的认证策略才是关键。

随着 uv 的持续发展，更多认证功能（如原生密钥存储）正在不断完善。后续将继续关注 uv 的更新，以便及时了解最新的安全特性。

参考链接

TAGS # uv
评论