# @haneinfo/rbac 中文文档

规范地址：https://npmcn.com/package/%40haneinfo/rbac/

版本：8\.3\.1
npm 元数据更新时间：2026-11-17T01:12:59.222Z
中文译文更新时间：2026-11-17T07:42:25.261Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40haneinfo/rbac
原文对照：https://npmcn.com/package/%40haneinfo/rbac/?lang=original

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

- 包体积（解压后）：173 kB，108 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：zod ^4\.4\.0，react ^19\.0\.0，react-dom ^19\.0\.0，@nestjs/core ^11\.0\.0 \|\| ^12\.0\.0，lucide-react ^1\.22\.0，@nestjs/common ^11\.0\.0 \|\| ^12\.0\.0，@prisma/client ^6\.19\.0 \|\| ^7\.10\.1，@haneinfo/common ^0\.6\.1 \|\| ^0\.7\.0，@haneinfo/frontend-shell ^1\.1\.0，@haneinfo/plugin-host-nest ^2\.0\.0
- 首次发布：2026-10-02T05:26:28.643Z
- 最新版本发布：2026-11-17T01:12:59.013Z
- 近 30 天下载量：5831（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：39（近 12 个月 39 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @haneinfo/rbac
```

也可以使用：`pnpm add @haneinfo/rbac`、`yarn add @haneinfo/rbac`、`bun add @haneinfo/rbac`

## README

# 角色权限

第8版仓库 `RolePermission.permission` 作为文本。 应用软件的Prisma `Permission` 语句 是可选的,仅作为App所有ID的目录。 独立商业身份证 也可以作为常数提供.

`RbacPermissionCatalog` 负载 `.haneinfo/generated/permissions.json` 相对于 `process.cwd()` 一次开始。 以其插件构建目录运行后端 工作目录(通常情况下) `backend/`将这款生成的工艺品与App一起部署. 只有活动 `desired` 可授予条目; `freshInstallPlan` 从未应用. ENOENT记录了绝对缺失的路径并只披露了App权限. 无效的 JSON, 不支持的计划、 重复的ID 或 I/O 出错失败启动 .

默认的 App 权限来自 耗用 App 生成的 `@prisma/client` `Permission` 导出,从工作目录中解析。 对于常数或不同的 从 App 拥有的全球模块导出此供应商 :

```ts
{
  provide: RBAC_PERMISSION_CATALOG_OPTIONS,
  useValue: {
    appPermissions: [...Object.values(Permission), 'equipment-loan:loan:return'],
    permissionsPath: '/app/backend/.haneinfo/generated/permissions.json',
  } satisfies PermissionCatalogOptions,
}
```

`GET /roles/permission-catalog` 只读并使用相同的交互式认证 并担任管理角色 它回来了 `{ permissions: [{ id, displayName, source, pluginId? }] }`。 。 。 . `RolesService` 在创建、更新和替换时拒绝未知的ID, 返回时 `unknownPermissionIds`。当前目录中未显示的现有身份证已退役 : 替换者保留了他们的赠款,他们不能被新授予另一个角色.

通过此回复为 `permissionCatalog` 改为 `RolesTable`启用 `permissionGroups()` 准备 `CreateRoleDialog` 选择。 仍在使用的 App 标签 `Permission.*` 翻译; 使用的插件标签 `displayName`。 。 。 . `permissionLabels` 自定义 App 标题并 已退役标记( 默认 ): `App 權限`, (中文(简体) ), `已停用`) (中文(简体) ). `frontend-admin` 获取目录本身 .

## 从7.x升级每个应用程序

1.  发布后,在每个工作空间安装rbac 8.0.0并安装匹配的前端-admin更新. 将可选的 m2m- api- key 端点更新为接受 rbac 8. 的版本 .
    
2.  运行 `haneinfo build` 用于再生插件文物和构成的图案。 如果应用 用途 `backend/prisma/schema/` 作为其有效的计划,同时抄录所审查的 `node_modules/@haneinfo/rbac/prisma/role.prisma` 在那里;构建不会覆盖该文件夹.
    
3.  在部署新后端前添加一个 App 自主迁移 :
    
    ```sql
    ALTER TABLE role_permissions ALTER COLUMN permission TYPE text USING permission::text;
    ```
    
4.  保留旧的enum,如果它仍然提供 App 分类值。 不放弃其 PostgreSQL 键,其他列则使用。 现有赠款价值保持不变.
    
5.  重新生成Prisma客户端,部署迁移,再种子并运行App集成测试. 部署 `permissions.json` ,并在运行时使用相同的后端工作目录.
    
6.  授予非ADMIN设计师 `<kind>:definition:write` 财务报告和审定财务报表 `:read` (或读取). 需要额外出版 `<kind>:definition:publish` 并且仍然是人性的.
    

### 种子赠款

种子绕过"角色服务",因此在写入前验证常数对应同一目录:

```ts
import { RbacPermissionCatalog } from '@haneinfo/rbac';
const catalog = new RbacPermissionCatalog(); // run from backend/, after haneinfo build
const grants: string[] = [Permission.USERS_READ, 'timer:definition:write'];
catalog.assertGrantable(grants);
await prisma.rolePermission.createMany({
  data: grants.map((permission) => ({ roleId, permission })),
  skipDuplicates: true,
});
```

不要输入混合目录为 `Permission[]`. 现有种子可以继续使用 应用enum常数,但应验证每项赠款并保留退休赠款,而不是 而不是在升级时删除所有角色权限.

## 实例访问列表

已根据第202610-c8e3号决定执行.

RbacPolicyPort.findRolesByNames(名称,交易?)是对现有角色的可选批次查询 机器名称和无效的显示标签。 它加入一个提供的交易并省略缺失的名字. 现有角色ForUser/Authorization OffUser已经提供当前的角色名;消费者通过这些名称 名字输入自己的查询中,绝不加入非洲区域局的表格。 国家机器清单宣布 新国家机器:内地:admin许可. 重新生成 App 权限 json 并授予它通过 RbacPermissionCatalog;一个受赠者的WRITE单靠它无法管理访问. API引擎地板为1.14.0.

应用App迁移后,将受影响的机制一起升级。 维持的模式, HTTP 路由,只读列表 instance 访问 MCP 工具,错误和权限合同都有文件记录 在@haneinfo/状态-机器/代理-guide.md中。 它的棱镜a/ intance- access. sql 迁移了现有的读者 在保留时间戳的同时,将表格移至用户/区域办事处、读取/写取和指定/指定/指定行. 选择的维护者(InstanceId,主Type,主Id,源)独有性. 人工补助金为: 默认限制为100;永久 READ 条目在人工删除后幸存. 见软件包寄存器 sQL、测试和应用程序恢复证据的验证/设备 -- -- 贷款/进入/报告.

## 经认证的角色标签查询

Get /rbac/roles/ lookup?q=未经行政许可使用InteractiveAuthGuard. q为 可选、可修饰和最多200个字符。 该响应最多为20个 {名称, 显示Name} 条目, 按机器名称排序, 然后 ID 。 譬如元相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 授权内容和成员从未包括在内。 现有行政/路线 保持他们的守卫。 不需要新的 MCP 工具或插件- api 合同 .

## 附加声明的默认角色

`defaultRoleIds()` 不会再回到 `SYSTEM_USER_ROLE` (单位:千美元)`USER`自动。 默认, 新创建的用户没有获得任何角色( e)`[]`) (中文(简体) ). 需要新用户的 Apps(通过手动创建,JIT,或 空 CSV 导入 `roles` 单元格)接收默认角色必须配置 `rbac` (单位:千美元)`configRef: "rbac"`:

```json
{
  "defaultRoleNames": ["EDITOR"]
}
```

保留先前的指派行为 `USER` 自动配置 `defaultRoleNames: ["USER"]`。 。 。 . 复制角色名称和 `ADMIN` (单位:千美元)`SYSTEM_ADMIN_ROLE`)在启动时被拒绝。 失踪申报 角色名称抛出 `NotFoundException` 列出失踪姓名时 `defaultRoleIds()` 运行.

`RbacPolicyService` 还执行 `RbacPolicyPort.resolveImportRoleIds(names, transaction?)` 页:1 CSV 用户导入: 机器名称被修剪并被复制, `ADMIN` 以 `system-admin`,并用 `unknown`。 。 。 .

## 常见问题

### 如何安装 @haneinfo/rbac？

在项目目录运行 npm install @haneinfo/rbac，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.4\.0）、@nestjs/core（^11\.0\.0 \|\| ^12\.0\.0）、@nestjs/common（^11\.0\.0 \|\| ^12\.0\.0）、@prisma/client（^6\.19\.0 \|\| ^7\.10\.1）、@haneinfo/common（^0\.6\.1 \|\| ^0\.7\.0）、@haneinfo/plugin-host-nest（^2\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @haneinfo/rbac 支持 TypeScript 吗？

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

### @haneinfo/rbac 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @haneinfo/rbac 可以商用吗？

@haneinfo/rbac 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @haneinfo/rbac 的下载量有多少？

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

### @haneinfo/rbac 还在维护吗？

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

