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

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创建密钥时涉及以下字段字段说明可选值 / 默认值name密钥名称用于标识用途任意字符串role绑定角色密钥的权限即该角色的权限当前用户拥有的角色expiresIn有效期1d/7d/30d/90d/custom自定义/never永不过期token生成的密钥字符串服务端自动生成前端不可见hidden: true3.3 注意事项密钥归属当前用户添加的 API 密钥属于当前登录用户角色为当前用户所属的角色密钥权限完全继承该角色的权限plugin.ts 中list、destroy动作会自动过滤createdById为当前用户确保用户只能看到和管理自己的密钥必须配置APP_KEY请确保已经配置了APP_KEY环境变量并保证不泄漏一旦APP_KEY变更所有已添加的 API 密钥都会失效。四、如何配置 APP_KEY4.1 为什么需要 APP_KEYAPI 密钥本质上是 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_KEYservices: app: image: nocobase/nocobase:main environment: - APP_KEY4jAokvLKTJgM0v_JseUkJ修改完成后需要重启容器使环境变量生效。注意请务必使用足够随机、长度足够的强密钥并妥善保管切勿提交到公开仓库。4.3 源码或 create-nocobase-app 安装配置方式使用源码运行或通过create-nocobase-app创建的项目直接修改项目根目录下的.env文件添加或修改APP_KEY行APP_KEY4jAokvLKTJgM0v_JseUkJ修改后需重启 NocoBase 服务。同样地修改APP_KEY会使此前签发的所有 API 密钥立即失效。4.4 配置原则小结APP_KEY一经使用即成为系统级签名密钥变更代价是所有 API 密钥作废因此上线后应保持稳定不同环境开发/测试/生产应使用不同的APP_KEY不要泄漏APP_KEY它等同于签发任意 API 密钥的能力。五、使用 API 密钥调用 API5.1 请求头格式在 HTTP 请求头中添加Authorization字段值为Bearer ${API_KEY}即可访问 NocoBase 所有 APIAuthorization: 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字段该角色的权限即密钥的权限。其底层实现链路如下创建时校验角色在 create 动作 中服务端通过users.roles仓库查询当前用户是否拥有该角色不存在则抛出Role not foundHTTP 400JWT 携带角色签发的 token 载荷payload包含{ userId, roleName }即用户 ID 与角色名认证后按角色鉴权请求携带 Bearer token 时认证中间件解出userId与roleNameACL 据此判定权限。因此为密钥选择高权限角色等同于把该角色的能力授权给持有密钥的一方务必按最小权限原则分配。七、删除与失效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参数说明参数必填说明默认值-n, --name name是密钥名称--u, --username username是密钥所属的用户名--r, --role roleName是绑定的角色名--e, --expires-in [expiresIn]否有效期如30d30d命令执行后会输出-----BEGIN API KEY----- token 字符串 -----END API KEY-----该命令走的是服务端generateAPIKey方法plugin.ts会校验用户名存在、角色属于该用户再通过authManager.jwt.sign签发 token 并写入apiKeys集合。它绕过了界面适合初始化系统或自动化运维场景。九、数据存储结构API 密钥存储在名为apiKeys的共享集合中shared: true定义见 collections/apiKeys.ts关键字段id自增主键name密钥名称字符串rolebelongsTo 关联roles集合外键为roleNameexpiresIn有效期枚举1d/7d/30d/90d/custom/nevertoken密钥字符串隐藏字段仅服务端写入。集合启用createdBy记录创建者与logging操作日志并按用户分组参与数据导出dumpRules.group: usermigrationRules: [schema-only]表示仅迁移表结构。这些设计保证了密钥数据随用户数据一起备份、迁移且每次创建/删除都有审计记录。十、常见问题FAQQ1为什么重启容器后 API 密钥失效A未配置APP_KEY时部分部署方式会在启动时生成随机签名密钥重启即更换导致旧 token 无法验签。按本文第四节配置固定的APP_KEY即可解决。插件使用文档对此有明确警告使用 Docker 镜像时必须配置APP_KEY否则 API key 将在每次重启后失效。Q2API 密钥和登录 Session 有什么区别AAPI 密钥是无状态的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考