pixi auth 完全指南：为私有频道与上传服务配置登录凭证

• 开发工具
• CLI
• 包管理器
• 任务调度

导读

pixi auth是 pixi 提供的认证命令族，用于向 prefix.dev、anaconda.org 等服务器登录，从而访问私有频道、向包仓库上传构建产物。通过本指南，你将掌握login、logout、token、status四个子命令的全部参数与典型用法，理解 pixi 凭证的底层存储机制（系统密钥环 /RATTLER_AUTH_FILE/ 配置覆盖文件），并能独立配置 OAuth/OIDC、Token、Basic Auth 与 S3 四类认证方式。

pixi auth 命令总览

pixi auth本身不执行任何认证操作，它是一个命令族入口，语法为：

pixi auth <COMMAND>

官方文档对其功能的定位是：Login to prefix.dev or anaconda.org servers to access private channels，即登录 prefix.dev 或 anaconda.org 服务器以访问私有频道。它共包含四个子命令：

从源码结构看，该命令族在 CLI 层由 crates/pixi_cli/src/lib.rs 中的Auth(rattler::cli::auth::Args)命令变体承载，并在 crates/pixi_cli/src/lib.rs 处通过rattler::cli::auth::execute(cmd)直接委托给 rattler 生态的 auth 实现，pixi 侧则通过pixi_authcrate 提供凭证存储的集中配置。

子命令一：pixi auth login

login是认证的核心入口，用于为给定主机存储认证信息，完整用法为：

pixi auth login [OPTIONS] <HOST>

其中<HOST>为必填参数，表示要认证的主机，例如prefix.dev。登录方式按大类可分为 OAuth/OIDC、S3、Token / Basic 三种，分别对应不同的选项组。

OAuth / OIDC 认证

OAuth/OIDC 是向 prefix.dev 这类自带身份提供方（IdP）的服务器登录的推荐方式，选项如下：

典型用法：

# 向 prefix.dev 发起 OAuth 登录 pixi auth login prefix.dev # 对接自建 OIDC 身份提供方 pixi auth login my.private.host \ --oauth \ --oauth-issuer-url https://idp.example.com \ --oauth-client-id my-cli-client # 无浏览器可用的无头机器（headless），使用 device-code 流程 pixi auth login prefix.dev --oauth-flow device-code

几点实战提示：

• --oauth-flow的三种取值中，device-code适用于无浏览器环境（在终端展示一次性验证码，用户在任意设备上完成授权）；auth-code适用于有浏览器的交互式环境；auto则让 pixi 自动选择。
• 默认--oauth-client-id为rattler，这意味着与标准的 rattler/pixi 客户端注册信息兼容；仅在对接自建 IdP 需要自定义客户端时覆盖它。
• 若 IdP 注册的回调地址是固定的，--oauth-redirect-uri必须与 IdP 侧配置严格一致，否则回调会失败。

S3 认证

pixi auth login支持以s3://协议形式存储对象存储（如 AWS S3 或兼容服务）的访问凭证，用于访问私有 bucket 频道或向 S3 上传：

示例：

pixi auth login s3://my-bucket \ --s3-access-key-id $AWS_ACCESS_KEY_ID \ --s3-secret-access-key $AWS_SECRET_ACCESS_KEY

需要说明的是，S3 凭证并不会明文保存在终端历史之外的位置，而是进入统一的凭证存储（详见下文“凭证存储机制”一节）。这一能力与pixi publish的 S3 上传深度绑定：在 crates/pixi_cli/src/publish/mod.rs 附近，发布流程会从ctx.auth_storage解析 S3 凭证，若未找到则会提示先执行pixi auth login s3://{bucket}存储凭证。

Token / Basic 认证

对于不支持 OAuth 的服务（或手动管理 token 的场景），可以使用以下选项：

示例：

# prefix.dev 的 token pixi auth login repo.prefix.dev --token pfx_JQEV-m_2bdz-D8NSyRSaAndHANx0qHjq7f2iD # anaconda.org 的 conda token pixi auth login anaconda.org --conda-token ABCDEFGHIJKLMNOP # 自建 quetz 服务的 Basic 认证 pixi auth login https://myquetz.server --username john --password xxxxxx

注意区分：--token面向 prefix.dev 的 token 体系，--conda-token面向 anaconda.org / quetz 的 token 体系，而--username/--password是通用的 HTTP Basic 认证。三种方式按服务类型选择其一即可。

其他选项

• --user-agent <USER_AGENT>：指定后续请求使用的 User-Agent 请求头，可用于自定义客户端标识。

子命令二：pixi auth logout

logout用于移除指定主机的认证信息，用法为：

pixi auth logout [OPTIONS] [HOST]

参数与选项：

示例：

pixi auth logout repo.prefix.dev pixi auth logout anaconda.org pixi auth logout s3://my-bucket

两个细节值得注意：

• 注销时支持与登录时对应的s3://协议主机形式，说明 S3 凭证与普通主机凭证存放在同一套存储中。
• --all会主动吊销（revoke）OAuth token，而不仅是删除本地记录，这对已泄露或不再需要的 token 是更彻底的处理方式。
• 交互式选择依赖配置项auth-interactive，这是 pixi 全局配置的一部分。

子命令三：pixi auth token

token用于打印指定主机已存储的认证 token，用法为：

pixi auth token <HOST>

其中<HOST>为必填参数（如prefix.dev）。该命令适合在脚本或 CI 流水线中取出 token 供其他工具复用。由于 token 是敏感信息，建议仅在受控环境中使用，并注意避免将输出写入日志。

子命令四：pixi auth status

status用于查看已存储的认证条目及其非机密元数据，用法为：

pixi auth status [OPTIONS]

选项：

与token不同，status刻意只展示“非机密”信息：它能列出当前存储了哪些主机的认证，但不会泄露 token 本体；仅在需要排查 OAuth 配置问题时（如 issuer 地址、client ID 是否匹配），才使用--details展开调试字段。

凭证存储机制：token 存在哪里

pixi auth的凭证存储由pixi_authcrate 集中管理。查看 crates/pixi_auth/src/lib.rs 的get_auth_store实现可以发现，存储层的优先级与构成如下：

1. 环境变量RATTLER_AUTH_FILE：若设置，则优先使用该文件作为凭证文件（file storage）。
2. pixi 全局配置的authentication_override_file：若配置了该选项，其指定的文件会被插入存储链，位置紧随RATTLER_AUTH_FILE之后；若文件不存在，会输出 warning 日志（crates/pixi_auth/src/lib.rs）。
3. 系统密钥环 / 默认凭证存储：作为兜底后端，凭证默认写入系统 keyring。

对应关系也可以在文档中交叉验证：

• 环境变量清单见 docs/reference/environment_variables.md：RATTLER_AUTH_FILE未设置时使用系统密钥环。
• 全局配置项authentication_override_file见 docs/reference/pixi_configuration.md；该配置项与default_channels等一样保留了snake_case写法兼容（authentication_override_file等价于 kebab-case 形式），因此既可以在config.toml中写authentication_override_file = "..."，也可以写 kebab-case 版本。

实际使用中，pixi auth login写入的凭证会被这些存储后端按上述优先级读取，所有需要访问私有频道的网络请求都会携带这些凭证。例如在pixi publish中，crates/pixi_cli/src/publish/mod.rs 通过pixi_auth::get_auth_store(config)构建认证存储，随后用于向 prefix.dev、anaconda.org、cloudsmith、quetz、artifactory 以及 S3 上传包（对应 pixi publish 的多个后端）。更详细的多服务认证配置说明可参考 docs/deployment/authentication.md。

使用场景串讲

综合以上内容，pixi auth的典型工作流是：

1. 访问私有频道：使用 conda-forge 之外的私有源时，先pixi auth login写入凭证，后续pixi install、pixi run等解析依赖时即可通过认证访问私有 repodata 与包文件。
2. 发布包：pixi publish向 prefix.dev / anaconda.org / quetz / artifactory / cloudsmith 上传时复用 auth 存储；S3 场景先执行pixi auth login s3://<bucket>再发布。
3. 管理与排障：pixi auth status检查已登录主机，pixi auth token取用 token 给外部工具，pixi auth logout --all一键清理并吊销 OAuth token。

小结

• pixi auth提供login/logout/token/status四个子命令，覆盖凭证的写入、删除、读取与巡检全生命周期；
• login支持 OAuth/OIDC（含 device-code 无头流程）、S3 凭证、prefix.dev token、anaconda.org/quetz conda-token 以及 HTTP Basic 认证五类方式；
• 凭证默认存放于系统密钥环，可被RATTLER_AUTH_FILE环境变量或全局配置authentication_override_file覆盖，存储逻辑集中在 crates/pixi_auth/src/lib.rs；
• CLI 层将auth命令委托给 rattler 的 auth 实现（见 crates/pixi_cli/src/lib.rs），pixi 侧主要承担存储配置与 publish 等命令的集成。

• 开发工具
• CLI
• 包管理器
• 任务调度