# @frogbotai/plugin-api-keys 中文文档

规范地址：https://npmcn.com/package/%40frogbotai/plugin-api-keys/

版本：0\.42\.0
npm 元数据更新时间：2026-11-15T07:38:52.230Z
中文译文更新时间：2026-11-15T16:29:49.878Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40frogbotai/plugin-api-keys
原文对照：https://npmcn.com/package/%40frogbotai/plugin-api-keys/?lang=original
项目主页：https://github.com/frogbotai/frogbot#readme
源码仓库：https://github.com/frogbotai/frogbot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：127 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.22\.3
- 运行依赖：0 个
- peer 依赖：react ^19\.0\.1 \|\| ^19\.1\.2 \|\| ^19\.2\.1，frogbot 0\.42\.0，react-dom ^19\.0\.1 \|\| ^19\.1\.2 \|\| ^19\.2\.1，@frogbotai/ui 0\.42\.0，@frogbotai/gateway 0\.42\.0
- 首次发布：2026-07-24T14:20:30.645Z
- 最新版本发布：2026-11-15T07:38:52.031Z
- 近 30 天下载量：2309（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

FrogBot 的多个命名 API 密钥 .

## 安装

```sh
npm install @frogbotai/plugin-api-keys
```

也可以使用：`pnpm add @frogbotai/plugin-api-keys`、`yarn add @frogbotai/plugin-api-keys`、`bun add @frogbotai/plugin-api-keys`

## README

# @frogbotai/plugin-api-键

在 FrogBot 应用程序中添加多个命名,独立可撤销的 API 密钥 .

```ts
import { apiKeysPlugin } from '@frogbotai/plugin-api-keys';
import { buildConfig } from 'frogbot';

export default buildConfig({
  secret: process.env.FROGBOT_SECRET!,
  db: databaseAdapter,
  collections: [{ slug: 'users', auth: true, fields: [] }],
  plugins: [apiKeysPlugin()],
});
```

插件添加一个 `api-keys` 收集,所有者范围管理端点,API-key认证,以及默认管理员控制. `frogbot dev` 在开始前生成管理员导入地图,因此在第一个负载上会出现密钥创建控制。 在 API 密钥管理收藏中创建密钥, 然后用两个标题认证请求 :

```http
Authorization: Bearer fb_...
X-API-Key: fb_...
```

纯文本密钥只在创建时返回 。 收藏库存储了SHA-256散列,并支持每个用户有多个独立吊销的密钥. 嵌入和旋转需要签名会话或密钥 `canMint`: 由任何其他密钥认证的请求获得 `403`,所以一个被泄露的密钥不能留下新的密钥. 钥匙有 `canMint` 关闭,除非一个会话 薄荷他们与 `data: { canMint: true }`。一个密钥被密钥记录为 `mintedBy`,可以拥有 `canMint` 仅通过它,取其对其他插件添加的字段的值,加上AI政策插件留在其模型列表和月上限内,其支出会以该上限计. 吊销一个密钥 吊销它下面的每个密钥 除非呼叫通过 `cascade: false` (单位:千美元)`revokeApiKey({ ..., cascade: false })`,或 `{ "cascade": false }` 作为 `revoke` 端点的正体),它只撤销了那个键并留下了它使键起作用. 管理员的撤销对话框询问, 默认检查, 当密钥实现时 。 密钥只旋转自身和所刻出的密钥; 旋转保留 `mintedBy`被拒绝的人不会撤销任何东西 一个密钥仍然可以列出并重命名其所有者的密钥,并撤销自己和它所制作的密钥.

钥匙工作到被吊销为止,除非用 `expiresAt`,未来ISO日期,发布于 `mint` 旁边 `name` 或转至 `mintApiKey`发送一天,例如 `2027-02-07` (协调世界时午夜)或与 `Z` 或一个不在未来的日期 `400`。一旦它通过, 键停止认证。 以后不能更改,旋转保留,旋转过期的密钥 `400`。由密钥铸造的密钥最迟于其父母过期。 创建对话框有一个过期日取取器,默认为空取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.

插件没有添加预算或模型限制;请求使用所有者的AI政策. 与 `@frogbotai/plugin-ai-policy` 在同一认证收藏上,每个密钥也会得到一个模型列表和其所有者内部的月封顶,设置在创建对话框中一个已崩溃的Lindept段. 其他插件在密钥收藏中添加此字段 : `mint` 接受为 `data`, (中文(简体) ), `rotate` 从旧密钥复制它们, 由密钥刻制的密钥会占用其父的值, 服务器组件注册于 `admin.custom['plugin-api-keys'].createFields` 在对话框的限值部分中渲染,读取和设置值 `useCreateKeyData()` 从 `@frogbotai/plugin-api-keys/client`。在配置AI后,使用行包括可选 `apiKey` 关系。 Cookie - 认证请求省略, 关系随之而来 `collectionSlug`。 。 。 .

构建和启动工作流程必须运行 `frogbot generate:importmap` 在添加插件后。 添加成一个 `prebuild` cI 引用时的分步 `next build` 直接说 如果服务器控制台报告导入地图中缺少一个组件, 请运行 `frogbot generate:importmap` 重建,或重新启动 `frogbot dev`。 。 。 .

```ts
apiKeysPlugin({
  authCollection: 'accounts',
  collectionSlug: 'credentials',
  tokenPrefix: 'acme',
  headerNames: ['x-service-key'],
  collection: {
    admin: { group: 'Security' },
    fields: [{ name: 'environment', type: 'text' }],
  },
});
```

收藏会与生成的字段,访问,端点,钩子,管理员组件相合并,并被其他插件所应用的变换. 管理器使用默认的管理员组件,而令牌对话框则传送一个基于管理员主题变量所构建的小样式表.

插件本身没有角色系统. 钥匙是所有者范围。 要在顶部分层角色, 安装 `@frogbotai/plugin-roles` 通过 `canRevokeAnyKey` 和收藏访问 :

```ts
import { allow, hasRole } from '@frogbotai/plugin-roles';

apiKeysPlugin({
  canRevokeAnyKey: (req) => hasRole(req, 'admin', 'support'),
  collection: {
    access: {
      read: allow('auditor', 'support', { role: 'member', own: 'owner' }),
      update: allow('support', { role: 'member', own: 'owner' }),
    },
  },
});
```

## 常见问题

### @frogbotai/plugin-api-keys 是什么？

FrogBot 的多个命名 API 密钥 \.

### 如何安装 @frogbotai/plugin-api-keys？

在项目目录运行 npm install @frogbotai/plugin-api-keys，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.0\.1 \|\| ^19\.1\.2 \|\| ^19\.2\.1）、frogbot（0\.42\.0）、react-dom（^19\.0\.1 \|\| ^19\.1\.2 \|\| ^19\.2\.1）、@frogbotai/ui（0\.42\.0）、@frogbotai/gateway（0\.42\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @frogbotai/plugin-api-keys 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @frogbotai/plugin-api-keys 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @frogbotai/plugin-api-keys 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.22\.3。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @frogbotai/plugin-api-keys 可以商用吗？

@frogbotai/plugin-api-keys 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @frogbotai/plugin-api-keys 的下载量有多少？

根据 npm 官方下载统计，@frogbotai/plugin-api-keys 在 2026/10/16 – 2026/11/14 这 30 天内被下载 2,309 次，日均约 77 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @frogbotai/plugin-api-keys 还在维护吗？

最新版本 0\.42\.0 发布于 2026/11/15（今天）；至今共发布 39 个版本，其中过去 12 个月发布了 39 个；首次发布于 2026/07/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。