企业官网建设流程全解析

NocoBase API 密钥（API Keys）配置与使用全指南：编程访问认证、APP_KEY 与角色权限绑定

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase

导读

本文聚焦 NocoBase 的 API 密钥（API Keys）能力，讲解如何为当前用户创建 API 密钥、如何通过Authorization: Bearer <token>请求头编程访问 NocoBase 全部 API，以及为什么必须配置APP_KEY环境变量（Docker 与源码安装的差异）。读完本文，你将掌握 API 密钥的完整生命周期：创建、绑定角色、设置有效期、使用、删除与失效机制，并了解其底层基于 JWT 签名的实现原理。

一、什么是 NocoBase API 密钥

API 密钥（API Key）是 NocoBase 提供的一种编程访问凭据。官方插件文档（插件说明）明确指出：该插件允许你创建和管理 API keys，生成的 API key 可以用于访问 NocoBase 所有 API。

与用户在浏览器中登录后使用 Cookie/Session 会话不同，API 密钥面向的是脚本、外部服务、CI/CD 流水线等非交互式场景。你只需在 HTTP 请求头中携带该密钥，即可完成身份认证并调用任意 API 资源。

二、安装与启用插件

API 密钥功能由内置插件plugin-api-keys提供，其包名为@nocobase/plugin-api-keys（源码位于 packages/plugins/@nocobase/plugin-api-keys）。该插件包含：

• 服务端：src/server/plugin.ts定义资源与 ACL 权限片段，src/server/actions/api-keys.ts实现创建与销毁动作，src/server/commands/generate.ts提供 CLI 生成命令；
• 客户端：src/client/Configuration与src/client-v2/pages/ApiKeysPage.tsx提供配置页面；
• 数据集合：src/collections/apiKeys.ts定义存储表结构。

启用插件后，在插件管理页面启用api-keys插件即可。插件在beforeLoad阶段注册了apiKeys资源，并开放list、create、destroy三个动作（见 plugin.ts），同时注册了pm.api-keys.configuration权限片段，只有具备该权限的用户才能管理 API 密钥。

三、在管理界面添加 API 密钥

3.1 操作路径

启用插件后，进入系统设置页的「API 密钥」页面（界面路径为admin/settings/api-keys），点击添加 API 密钥按钮，填写相关信息后保存即可生成一个 API 密钥。

3.2 可配置项

根据数据集合定义（apiKeys.ts），创建密钥时涉及以下字段：

3.3 注意事项

• 密钥归属当前用户：添加的 API 密钥属于当前登录用户，角色为当前用户所属的角色，密钥权限完全继承该角色的权限（plugin.ts 中list、destroy动作会自动过滤createdById为当前用户，确保用户只能看到和管理自己的密钥）；
• 必须配置APP_KEY：请确保已经配置了APP_KEY环境变量并保证不泄漏；一旦APP_KEY变更，所有已添加的 API 密钥都会失效。

四、如何配置 APP_KEY

4.1 为什么需要 APP_KEY

API 密钥本质上是 NocoBase 认证管理器（authManager.jwt）使用APP_KEY作为签名密钥签发的 JWT。在 api-keys.ts 的动作实现 中可以看到：

const token = ctx.app.authManager.jwt.sign( { userId: ctx.auth.user.id, roleName: role.name }, { expiresIn: values.expiresIn }, );

APP_KEY就是 JWT 的签名密钥。如果未配置或每次启动随机生成，重启后旧密钥将无法通过验签而全部失效。

4.2 Docker 版本配置方式

Docker 部署时，修改docker-compose.yml，在服务环境的environment下添加APP_KEY：

services: app: image: nocobase/nocobase:main environment: - APP_KEY=4jAokvLKTJgM0v_JseUkJ

修改完成后需要重启容器使环境变量生效。注意：请务必使用足够随机、长度足够的强密钥，并妥善保管，切勿提交到公开仓库。

4.3 源码或 create-nocobase-app 安装配置方式

使用源码运行或通过create-nocobase-app创建的项目，直接修改项目根目录下的.env文件，添加或修改APP_KEY行：

APP_KEY=4jAokvLKTJgM0v_JseUkJ

修改后需重启 NocoBase 服务。同样地，修改APP_KEY会使此前签发的所有 API 密钥立即失效。

4.4 配置原则小结

• APP_KEY一经使用即成为系统级签名密钥，变更代价是所有 API 密钥作废，因此上线后应保持稳定；
• 不同环境（开发/测试/生产）应使用不同的APP_KEY；
• 不要泄漏APP_KEY，它等同于签发任意 API 密钥的能力。

五、使用 API 密钥调用 API

5.1 请求头格式

在 HTTP 请求头中添加Authorization字段，值为Bearer ${API_KEY}，即可访问 NocoBase 所有 API：

Authorization: Bearer <你的 API 密钥>

5.2 cURL 示例

插件官方使用文档（usage.md）给出的例子如下：

curl '{domain}/api/roles:check' -H 'Authorization: Bearer {API key}'

将{domain}替换为你的 NocoBase 服务地址，将{API key}替换为实际密钥。例如：

curl 'https://your-nocobase.example.com/api/roles:check' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIs...'

5.3 在代码中调用

任意支持自定义请求头的 HTTP 客户端均可使用 API 密钥。以 Node.js 的 fetch 为例：

const res = await fetch('https://your-nocobase.example.com/api/roles:check', { headers: { Authorization: `Bearer ${API_KEY}`, }, });

由于密钥绑定了角色，服务端在认证后会以该角色的权限执行 ACL 校验，因此密钥能访问的范围完全由所绑定角色的权限决定（见权限控制）。

六、权限控制原理

创建 API 密钥时必须选择角色（role字段），该角色的权限即密钥的权限。其底层实现链路如下：

1. 创建时校验角色：在 create 动作 中，服务端通过users.roles仓库查询当前用户是否拥有该角色，不存在则抛出Role not found（HTTP 400）；
2. JWT 携带角色：签发的 token 载荷（payload）包含{ userId, roleName }，即用户 ID 与角色名；
3. 认证后按角色鉴权：请求携带 Bearer token 时，认证中间件解出userId与roleName，ACL 据此判定权限。

因此，为密钥选择高权限角色等同于把该角色的能力授权给持有密钥的一方，务必按最小权限原则分配。

七、删除与失效

7.1 界面删除

在 API 密钥页面删除密钥后，该密钥将无法继续使用。

7.2 底层实现

删除动作（destroy）在删除记录前会调用ctx.app.authManager.jwt.block(token)将 token 加入黑名单：

export async function destroy(ctx: Context, next: Next) { const repo = ctx.db.getRepository(ctx.action.resourceName); const { filterByTk } = ctx.action.params; const data = await repo.findById(filterByTk); const token = data?.get('token'); if (token) { await ctx.app.authManager.jwt.block(token); } return actions.destroy(ctx, next); }

即删除操作做了「先封禁 token、再删记录」的双重处理，保证密钥立即失效，即使 token 仍处于有效期也无法再通过认证。

7.3 其他失效场景

• 到期失效：JWT 携带expiresIn过期时间，到期后自动无法通过验签；
• APP_KEY 变更：签名密钥更换后，旧 token 验签失败，全部密钥失效；
• 用户/角色删除：token 中绑定的用户或角色不存在时，相关鉴权无法通过。

八、进阶：命令行生成 API 密钥

除了管理界面，插件还提供 CLI 命令generate-api-key（实现见 generate.ts），便于在部署环境或脚本中批量生成：

yarn nocobase generate-api-key \ --name "my-service" \ --username "admin" \ --role "admin" \ --expires-in 30d

参数说明：

命令执行后会输出：

-----BEGIN API KEY----- <token 字符串> -----END API KEY-----

该命令走的是服务端generateAPIKey方法（plugin.ts），会校验用户名存在、角色属于该用户，再通过authManager.jwt.sign签发 token 并写入apiKeys集合。它绕过了界面，适合初始化系统或自动化运维场景。

九、数据存储结构

API 密钥存储在名为apiKeys的共享集合中（shared: true，定义见 collections/apiKeys.ts），关键字段：

• id：自增主键；
• name：密钥名称（字符串）；
• role：belongsTo 关联roles集合，外键为roleName；
• expiresIn：有效期枚举（1d/7d/30d/90d/custom/never）；
• token：密钥字符串，隐藏字段，仅服务端写入。

集合启用createdBy（记录创建者）与logging（操作日志），并按用户分组参与数据导出（dumpRules.group: 'user'），migrationRules: ['schema-only']表示仅迁移表结构。这些设计保证了密钥数据随用户数据一起备份、迁移，且每次创建/删除都有审计记录。

十、常见问题（FAQ）

Q1：为什么重启容器后 API 密钥失效？A：未配置APP_KEY时，部分部署方式会在启动时生成随机签名密钥，重启即更换，导致旧 token 无法验签。按本文第四节配置固定的APP_KEY即可解决。插件使用文档对此有明确警告：使用 Docker 镜像时必须配置APP_KEY，否则 API key 将在每次重启后失效。

Q2：API 密钥和登录 Session 有什么区别？A：API 密钥是无状态的 Bearer token，适合脚本与第三方服务；Session 依赖浏览器 Cookie。密钥权限由绑定的角色决定，且可以单独设置过期时间。

Q3：如何让某个密钥立即失效？A：在界面删除该密钥（会同时封禁 token），或修改APP_KEY（会让全部密钥失效）。

Q4：密钥能跨用户使用吗？A：不能。密钥创建后归属当前用户，list/destroy均按createdById过滤，其他用户无法查看或管理该密钥。

Q5：有效期可以设置多长？A：界面提供1d/7d/30d/90d/custom/never六档；CLI 命令可通过--expires-in指定任意时长（默认30d）。

【免费下载链接】nocobaseNocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase