企业官网建设流程全解析

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

pixi auth login是 pixi 包管理器中用于保存"某个主机（host）认证信息"的核心命令：无论是登录 prefix.dev 获取私有渠道访问权、为 anaconda.org / quetz 配置 conda token、为自建渠道配置 Basic HTTP 认证，还是为 S3 兼容存储桶配置密钥，都可以通过这一条命令完成。读完本文，你将掌握该命令的全部参数与四种认证方式的适用场景，理解凭据的底层存储机制（系统钥匙串 / 回退 JSON 文件），并能结合仓库源码看懂 pixi 与底层 rattler 生态如何消费这些凭据。

本文以仓库中的命令参考文档 docs/reference/cli/pixi/auth/login.md 为主体，并参考 docs/deployment/authentication.md 与相关 Rust 源码展开。

命令概览与基本语法

pixi auth login的作用一句话概括：为指定主机存储认证信息，供后续所有需要访问该主机的 pixi 操作（pixi install、pixi upload、pixi publish等）自动复用。其基本语法为：

pixi auth login [OPTIONS] <HOST>

必选参数：<HOST>

HOST 的写法随认证方式不同而变化：普通 HTTP 服务直接写域名（如prefix.dev、myserver.com），S3 存储桶则以s3://协议开头（如s3://my-bucket）。

通用选项：--user-agent

某些自建渠道或代理服务会校验 User-Agent，通过该选项可以覆盖默认值，用于满足服务端对客户端的识别要求。

四种认证方式与完整参数说明

pixi auth login将参数按认证方式划分为三组：OAuth/OIDC、S3、Token/Basic。不同服务器使用不同的认证方法，实际选择取决于目标主机支持哪种协议。

OAuth/OIDC 认证

OAuth/OIDC 是 pixi 向 prefix.dev 等现代渠道推荐的首选方式，适合交互式桌面环境：

关于--oauth-flow的默认值，命令参考文档 login.md 记录为device-code，而 docs/deployment/authentication.md 中的帮助输出显示默认值为auto（三选一：auto、auth-code、device-code）。从后者的说明看，auto会在运行时自动抉择：

• Authorization Code with PKCE：当处于带可用浏览器的桌面环境时，pixi 会打开浏览器标签页，你在服务端完成登录后由本地回调页完成令牌交换；
• Device Code：当 pixi 无法为你打开浏览器（SSH 会话、无头服务器、容器 shell 等）时，pixi 打印一个短用户码和 URL，你在任意设备上打开 URL 并输入该码即可完成认证。

如果auto的选择与你的环境不符，可以强制指定某一流程，例如无浏览器环境：

pixi auth login prefix.dev --oauth-flow device-code

最简登录方式（对 prefix.dev）：

pixi auth login prefix.dev

该命令会打开浏览器标签页，登录 prefix.dev 后 pixi 将凭据存入系统钥匙串。此登录授予的权限覆盖访问个人资料、读取渠道以及上传包，足以让pixi install、pixi upload、pixi publish开箱即用；令牌在过期前 pixi 会在后台自动刷新。

对于自带 OIDC 的自建主机（pixi 未内置默认参数），需要显式传入全部配置：

pixi auth login my.private.host \ --oauth \ --oauth-issuer-url https://idp.example.com \ --oauth-client-id my-cli-client \ --oauth-scope openid --oauth-scope channel:read

Token 认证（Bearer Token）

如果你希望自行管理令牌（例如 CI 场景无法进行浏览器登录），可以使用标准 Bearer Token 认证：

pixi auth login prefix.dev --token pfx_jj8WDzvnuTHEGdAhwRZMC1Ag8gSto8

Bearer Token 会以Authorization: Bearer <TOKEN>请求头随每次请求发送。token 认证适合在 CI、脚本等自动化环境中注入预先签发好的长期令牌。

anaconda.org / quetz 的 conda token

pixi auth login anaconda.org --conda-token xy-72b914cc-c105-4ec7-a969-ab21d23480ed

Conda token 的特别之处在于它被嵌入 URL 路径中：conda.anaconda.org/t/<TOKEN>/conda-forge/linux-64/...。quetz 服务器同样接受该 scheme，因此自建 quetz 实例也可以用--conda-token登录。

Basic HTTP 认证

pixi auth login myserver.com --username user --password password

这等价于http://user:password@myserver.com/...的访问方式，是自建渠道部署在 NGINX/Apache 反向代理之后并启用 HTTP Basic 认证时的典型选择。

S3 认证

pixi 支持对 S3 兼容存储桶进行认证（例如将包上传到 S3 或从 S3 渠道读取 repodata）：

pixi auth login s3://my-bucket --s3-access-key-id <access-key-id> --s3-secret-access-key <secret-access-key> # 若密钥包含会话令牌，还可以追加： pixi auth login s3://my-bucket --s3-access-key-id <access-key-id> --s3-secret-access-key <secret-access-key> --s3-session-token <session-token>

需要注意，登录 S3 时 HOST 要写成s3://my-bucket这样的 URI 形式。此外，S3 认证也支持通过 AWS 标准环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY）进行，详见 docs/deployment/s3.md。

完整示例速查

以下示例来自命令文档的示例扩展 login_extender，覆盖了全部认证方式的典型用法：

# OAuth 登录 prefix.dev pixi auth login prefix.dev # OAuth 登录自建 OIDC 提供商 pixi auth login my.private.host \ --oauth \ --oauth-issuer-url https://idp.example.com \ --oauth-client-id my-cli-client # 无浏览器机器（强制 device-code 流程） pixi auth login prefix.dev --oauth-flow device-code # 手动 token、conda token、basic auth、S3 凭据 pixi auth login repo.prefix.dev --token pfx_JQEV-m_2bdz-D8NSyRSaAndHANx0qHjq7f2iD pixi auth login anaconda.org --conda-token ABCDEFGHIJKLMNOP pixi auth login https://myquetz.server --username john --password xxxxxx pixi auth login s3://my-bucket --s3-access-key-id $AWS_ACCESS_KEY_ID --s3-secret-access-key $AWS_SECRET_ACCESS_KEY

凭据存储在哪里？

认证信息由 pixi 底层使用的 rattler 网络库负责持久化，存储位置随操作系统不同而不同（来自 docs/deployment/authentication.md）：

• Windows：存储在"凭据管理器"（Credentials Manager）中，搜索rattler即可找到 pixi（或其他基于 rattler 的程序）保存的凭据；
• macOS：存储在钥匙串（Keychain）中，可用系统自带的Keychain Access程序访问，同样搜索rattler；
• Linux：使用GNOME Keyring（或 Keyring）经由libsecret安全存储，搜索rattler可列出全部相关凭据。

回退存储：JSON 文件

如果运行环境没有任何上述钥匙串可用（例如精简服务器），pixi 会回退到不加密的 JSON 文件存储凭据，该文件位于~/.rattler/credentials.json。虽然不加密，但它保证在无钥匙串环境下认证功能依然可用。

覆盖存储位置

你可以通过RATTLER_AUTH_FILE环境变量覆盖默认凭据文件位置。设置后，该文件将成为 pixi 唯一使用的认证数据来源：

export RATTLER_AUTH_FILE=$HOME/credentials.json # 也可以在命令行指定 pixi global install --auth-file $HOME/credentials.json ...

注意：RATTLER_AUTH_FILE的优先级高于命令行参数。该文件的 JSON 格式如下：

{ "*.prefix.dev": { "BearerToken": "your_token" }, "otherhost.com": { "BasicHTTP": { "username": "your_username", "password": "your_password" } }, "conda.anaconda.org": { "CondaToken": "your_token" }, "s3://my-bucket": { "S3Credentials": { "access_key_id": "my-access-key-id", "secret_access_key": "my-secret-access-key", "session_token": null } } }

JSON 中的主机名支持通配符：若使用*.prefix.dev，则任何子域都会匹配（例如repo.prefix.dev也匹配）。此外，还可以在全局配置文件中设置认证覆盖文件，详见 docs/reference/pixi_configuration.md。

源码视角：pixi 如何组织与消费认证

pixi auth这一组命令（login / logout / token / status）在 pixi CLI 中通过 rattler 生态的 CLI 实现接入。在 crates/pixi_cli/src/lib.rs 中可以看到Auth(rattler::cli::auth::Args)的声明，并在命令分发处（crates/pixi_cli/src/lib.rs）直接调用rattler::cli::auth::execute执行——这正是pixi auth login各项参数与 OAuth/S3 流程的底层实现来源。

而 pixi 自身负责的，是依据配置构造统一的认证存储（AuthenticationStorage）。这一逻辑集中在 crates/pixi_auth/src/lib.rs：

• get_auth_store（crates/pixi_auth/src/lib.rs）：首先从环境变量与默认后端构造存储（AuthenticationStorage::from_env_and_defaults()），随后检查 pixi 配置中的authentication_override_file设置，将文件型存储按优先级插入后端列表（排在RATTLER_AUTH_FILE之后、钥匙串之前）；
• get_auth_middleware（crates/pixi_auth/src/lib.rs）：将认证存储包装为AuthenticationMiddleware，供 HTTP 请求中间件链直接使用。

该存储被多个上层命令消费：

• 上传：crates/pixi_cli/src/upload.rs 中pixi upload通过get_auth_store获得认证存储，并传递给 rattler 的上传选项，从而复用pixi auth login保存的凭据；
• 发布：crates/pixi_cli/src/publish/mod.rs 在发布流程的上下文（PublishContext）中持有auth_storage，用于上传到 prefix、anaconda、cloudsmith、quetz、artifactory 等目标；其中 S3 场景会从认证存储解析凭据，若未找到会提示用户运行pixi auth login s3://{bucket}来保存凭据（见 crates/pixi_cli/src/publish/mod.rs）；
• 状态查看：crates/pixi_cli/src/info.rs 的pixi info会显示认证存储位置，其优先级为：RATTLER_AUTH_FILE环境变量 → 全局配置的authentication_override_file→ 默认文件型存储。

与其他 auth 子命令配合使用

pixi auth login是 pixi auth 子命令组的一员，与之配套的还有：

• pixi auth logout：移除指定主机的认证信息；
• pixi auth token：打印指定主机已存储的认证令牌；
• pixi auth status：显示已存储的认证条目及非机密令牌元数据。

典型工作流是：先用pixi auth login写入凭据，日常使用pixi install/pixi upload/pixi publish自动复用；需要排查或清理时用pixi auth status/pixi auth logout管理；在 CI 等无钥匙串环境，则通过RATTLER_AUTH_FILE或--token直接注入预先准备的凭据文件，实现完全非交互的认证。

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