RubyGems 导航菜单
指南

RubyGems.org API 密钥、其范围和 CLI 使用

您可以根据您的需求创建多个 API 密钥。API 密钥具有不同的范围，授予特定权限。使用权限最少的 API 密钥可以提高您的 RubyGems.org 帐户的安全性，因为它可以限制受损密钥的影响。

创建新的 API 密钥

访问您的 RubyGems.org 帐户 设置页面 并点击 **API 密钥**。系统会提示您输入帐户密码以确认您的身份。

Settings API key

如果您以前从未访问过此页面，您应该看到至少一个名为 *legacy-key* 的密钥。*legacy-key* 是 RubyGems.org 曾经使用每个帐户只有一个具有完全访问权限的 API 密钥的时代的遗留物。我们建议您尽快 从 *legacy-key* 迁移。

点击 **新的 API 密钥** 为您的帐户创建一个新的 API 密钥。

Settings API key

输入一个名称来帮助您识别 API 密钥可能使用的环境（例如：ci-push-key、mirror-webhook-key 等）。选中您可能想要启用的所有范围，然后点击创建。

**注意：** *显示仪表板* 是一个独占范围，它不能与任何其他范围一起启用。

New API key

在下一页，您应该会看到新的 API 密钥。

API key created

年龄列显示密钥的年龄。最后访问列显示密钥上次成功身份验证的时间（UTC）。您可以使用编辑按钮更新密钥的范围。您可以使用最后一行中的重置按钮删除与您的帐户关联的所有 API 密钥。

与 gem CLI 一起使用

如上所述创建的 API 密钥可以直接在 gem CLI 中使用，方法是在名为 GEM_HOST_API_KEY 的环境变量中设置它，例如：

$ GEM_HOST_API_KEY=rubygems_123456 gem push example-1.2.3.gem

这种方法适用于非交互式情况，例如基于 CI/CD 的 gem 发布流程。在您可以直接访问的个人开发机器上，通常更倾向于使用 gem signin 进行交互式登录（见下文）。

从 gem CLI 创建

注意：如果您想使用 gem CLI 创建具有范围的 API 密钥，则需要 rubygems 3.2.0 或更高版本。

运行 gem signin 将提示您输入 RubyGems.org 凭据、密钥名称和要为密钥启用的范围。所有范围的默认选择是不启用它们。

$ gem signin
Enter your RubyGems.org credentials.
Don't have an account yet? Create one at https://rubygems.org.cn/sign_up
   Email:   [email protected]
Password:

API Key name [4458ffe32b0c-unknown-user-20201231104303]:   docker-push-key
Please select scopes you want to enable for the API key (y/n)
index_rubygems [y/N]:
push_rubygem [y/N]:   Y
yank_rubygem [y/N]:
add_owner [y/N]:
remove_owner [y/N]:
access_webhooks [y/N]:
show_dashboard [y/N]:

Signed in with API key: docker-push-key.

当我们在您的主机上找不到任何 API 密钥时，将自动创建一个 API 密钥（默认密钥名称：hostname-whoami-timestamp），并具有所需的范围。类似地，如果密钥没有正确的范围，则主机上现有 API 密钥的范围将更新为所需的范围。

$ gem yank begone -v 4.1.48
Yanking gem from https://rubygems.org.cn...
The existing key doesn't have access of yank_rubygem on https://rubygems.org.cn. Please sign in to update access.
   Email:   [email protected]
Password:
Added yank_rubygem scope to the existing API key
Successfully deleted gem: begone (4.1.48)

API 密钥范围

  • 索引 rubygems：列出您帐户的所有 RubyGems
  • 推送 rubygems：创建一个新的 RubyGem 或发布您拥有的任何 RubyGem 的新版本
  • 撤回 rubygems：删除您拥有的任何 RubyGem 的已发布版本
  • 添加所有者：将用户添加到您拥有的任何 RubyGem 的所有者
  • 删除所有者：从您拥有的任何 RubyGem 的所有者中删除用户
  • 访问 Webhook：列出、创建、删除或触发与您的帐户关联的 Webhook
  • 显示仪表板：访问 RubyGems.org 仪表板的 Atom Feed。这是一个独占范围，不能与任何其他范围一起启用。

在特定 API 密钥上启用 MFA

如果您的帐户在仅 UI 或UI 和 gem signin 身份验证级别上启用了 MFA，则可以选择在特定 API 密钥上启用 MFA。这将需要一个 OTP 代码用于 gem push、yank、owner --add/--remove 命令。

您可以在 UI 上创建或编辑 API 密钥时切换此选项。 启用 MFA 的新 API 密钥

从旧版 API 密钥迁移

您的帐户的旧版 API 密钥已迁移到一个启用了所有范围的密钥。我们强烈建议您删除此密钥，并将其替换为一个启用了最小范围的新 API 密钥。

  • 访问您的帐户的 API 密钥页面，然后单击名为 legacy-key 的密钥的 删除 按钮。
  • 在您使用过旧版 API 密钥的所有主机上运行 gem signout
  • 确保您已安装 rubygems 3.2.0 或更高版本。运行 gem update --system 将您的 rubygem 更新到最新版本。
  • 运行 gem signin 创建一个新的 API 密钥。

如果您无法更新 rubygems，您仍然可以使用新的 API 密钥，方法是使用 Web UI 创建一个新的密钥，并将密钥替换为 ~/.gem/credentials 或 ~/.local/share/gem/credentials 文件中的密钥。

$ cat ~/.local/share/gem/credentials
:rubygems_api_key: rubygems_cec9db9373ea171daaaa0bf2337edce187f09558cb19c1b2

注意：用于获取 API 密钥的旧版端点 GET /api/v1/keys 已更新，以便在每次请求时创建新的 API 密钥。作为安全预防措施，新的 API 密钥在单向加密后存储在我们的数据库中。我们不再能够以明文形式获取相同的 API 密钥。

上一页 下一页