nocobase-acl-manage

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Goal

目标

Configure and diagnose NocoBase ACL safely through MCP: roles, default role, role union mode, system permission snippets, route permissions, data-source-level global table strategy, collection-level independent permissions, field permissions, and row scopes.

通过MCP安全地配置和诊断NocoBase ACL：角色、默认角色、角色联合模式、系统权限片段、路由权限、数据源级全局表格策略、集合级独立权限、字段权限以及行范围。

Prerequisite

前提条件

NocoBase MCP must already be authenticated before permission operations.
If MCP tools return authentication errors such as
```
Auth required
```
, do not attempt ad hoc sign-in flows.
Stop and ask the user to restore MCP authentication first.

Useful references:

MCP setup:
```
nocobase-mcp-setup
```
Roles and permissions handbook: https://docs.nocobase.com/handbook/acl
Data modeling handbook: https://docs.nocobase.com/data-sources/data-modeling
Full docs index used for ACL terminology: https://docs.nocobase.com/llms-full.txt

在进行权限操作前，必须已完成NocoBase MCP的身份验证。
如果MCP工具返回
```
Auth required
```
等身份验证错误，请勿尝试临时登录流程。
请停止操作并要求用户先恢复MCP身份验证。

有用参考资料：

MCP设置：
```
nocobase-mcp-setup
```
角色与权限手册：https://docs.nocobase.com/handbook/acl
数据建模手册：https://docs.nocobase.com/data-sources/data-modeling
ACL术语完整文档索引：https://docs.nocobase.com/llms-full.txt

ACL Model

ACL模型

Think in layers. Configure from identity to business access:

Role identity
System role mode
System permissions
Route permissions
Global table permissions
Table independent permissions
Row and field restrictions

Do not jump into table independent permissions until system, route, and global table intent are clear. Do not stop at action-only skeletons when the user asks for a realistic business role. A realistic role usually needs an explicit decision for every relevant layer, even when that decision is "leave empty".

按层级思考。从身份到业务访问进行配置：

角色身份
系统角色模式
系统权限
路由权限
全局表格权限
表格独立权限
行与字段限制

在明确系统、路由和全局表格的配置意图之前，不要直接配置表格独立权限。当用户需要配置真实业务角色时，不要仅停留在仅包含操作的框架上。一个真实的角色通常需要对每个相关层级做出明确决策，即使决策是"留空"。

What To Read

需阅读内容

For normal permission configuration, read the dimension-specific references you actually need:
- references/system-permissions.md
- references/route-permissions.md
- references/global-table-permissions.md
- references/independent-permissions.md
- references/field-permissions.md
- references/scopes.md
For debugging access mismatches or understanding middleware/security behavior, read references/safety-and-debug.md.

对于常规权限配置，阅读实际所需的特定维度参考资料：
- references/system-permissions.md
- references/route-permissions.md
- references/global-table-permissions.md
- references/independent-permissions.md
- references/field-permissions.md
- references/scopes.md
对于调试访问不匹配问题或了解中间件/安全行为，请阅读references/safety-and-debug.md。

Mandatory MCP Gate

强制MCP检查

Before mutation, confirm the ACL-related MCP tools are reachable:

```
roles:*
```

route permission tools such as

roles.desktopRoutes:*

roles.mobileRoutes:*

```
availableActions:list
```
role collection/resource permission tools
scope tools

If the swagger-generated tools are incomplete, fall back to the generic CRUD tool only after inspecting the relevant collection/resource metadata first.

在进行修改前，确认可访问以下与ACL相关的MCP工具：

```
roles:*
```

路由权限工具，如

roles.desktopRoutes:*

或

roles.mobileRoutes:*

```
availableActions:list
```
角色集合/资源权限工具
范围工具

如果Swagger生成的工具不完整，需先查看相关集合/资源元数据，再使用通用CRUD工具作为备选。

Preferred Order

Verification Checklist

验证清单

The target role exists and has the expected metadata.
The system role mode matches the intended multi-role behavior.
System snippets match the intended system capability boundary.
Route permissions match the intended menu/page boundary.
The global role strategy matches the broad table-level business rules.
Only the collections that need exceptions use
```
usingActionsConfig: true
```
.
Action names come from
```
availableActions:list
```
, not guesswork.
Field restrictions are only configured on actions that support field configuration.
Scoped actions carry the expected
```
scopeId
```
.
Scope definitions are re-read separately and their filters reference real fields and real relation paths.
Business scopes are created under the target data source, not in global
```
rolesResourcesScopes
```
.
Collections using own-record semantics have the necessary ownership fields.
Association mutation permissions are explicitly covered where needed.
For realistic business roles, the final config includes an explicit decision for system permissions, route permissions, global permissions, independent permissions, field permissions, and scopes.
Empty global strategy is intentional and justified, not accidental.
Empty scope means "full-row access by design", not "scope was forgotten".
Field lists are configured where field visibility or mutation boundaries matter, especially on update/create/view/export.
Effective access is tested on at least one allowed case and one denied case.

目标角色存在且具有预期的元数据。
系统角色模式符合预期的多角色行为。
系统权限片段符合预期的系统能力边界。
路由权限符合预期的菜单/页面边界。
全局角色策略符合宽泛的表格级业务规则。
仅需要例外的集合使用
```
usingActionsConfig: true
```
。
操作名称来自
```
availableActions:list
```
，而非猜测。
仅在支持字段配置的操作上设置字段限制。
带范围的操作包含预期的
```
scopeId
```
。
单独重新读取范围定义，确认其过滤器引用真实字段和真实关联路径。
业务范围创建在目标数据源下，而非全局
```
rolesResourcesScopes
```
中。
使用自有记录语义的集合具有必要的所有权字段。
关联修改权限在需要的地方被明确覆盖。
对于真实业务角色，最终配置包含对系统权限、路由权限、全局权限、独立权限、字段权限和范围的明确决策。
空全局策略是有意为之且有合理理由，而非疏忽。
空范围意味着"设计上允许全行访问"，而非"忘记配置范围"。
在字段可见性或修改边界重要的地方配置字段列表，尤其是在更新/创建/查看/导出操作上。
至少在一个允许案例和一个拒绝案例上测试实际访问权限。