Back to Details

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:
  • 在进行权限操作前，必须已完成NocoBase MCP的身份验证。
  • 如果MCP工具返回
    Auth required
    等身份验证错误，请勿尝试临时登录流程。
  • 请停止操作并要求用户先恢复MCP身份验证。
有用参考资料：

ACL Model

ACL模型

Think in layers. Configure from identity to business access:
  1. Role identity
  2. System role mode
  3. System permissions
  4. Route permissions
  5. Global table permissions
  6. Table independent permissions
  7. 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".
按层级思考。从身份到业务访问进行配置：
  1. 角色身份
  2. 系统角色模式
  3. 系统权限
  4. 路由权限
  5. 全局表格权限
  6. 表格独立权限
  7. 行与字段限制
在明确系统、路由和全局表格的配置意图之前，不要直接配置表格独立权限。 当用户需要配置真实业务角色时，不要仅停留在仅包含操作的框架上。一个真实的角色通常需要对每个相关层级做出明确决策，即使决策是"留空"。

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:*
    or 
    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

推荐操作顺序

  1. Inspect current state first.
    • List roles.
    • Check current role context and system role mode.
    • Inspect current system snippets if system capability matters.
    • Inspect current route permissions if menu access matters.
    • List available ACL actions.
    • Read data-source global strategy if table access matters.
    • List collections visible in role permissions.
    • Inspect existing scopes if the task mentions own-record or custom data ranges.
  2. Change one layer at a time.
    • Role or default role first.
    • Then system role mode if needed.
    • Then system permissions.
    • Then route permissions.
    • Then global table permissions.
    • Then table independent permissions.
    • Then scopes and field restrictions.
  3. Verify with real ACL metadata after every write.
    • Re-read the updated role, route binding, or resource permission record.
    • Re-check the current role context when union mode or default role is involved.
  4. Prefer a complete permission matrix before writing.
    • For each role, decide system snippets, route bindings, global table strategy, independent collection actions, field lists, and row scopes.
    • If a layer is intentionally left empty, record why it is empty instead of silently skipping it.
  1. 先检查当前状态。
    • 列出所有角色。
    • 检查当前角色上下文和系统角色模式。
    • 如果系统能力相关，检查当前系统权限片段。
    • 如果菜单访问相关，检查当前路由权限。
    • 列出可用的ACL操作。
    • 如果表格访问相关，读取数据源全局策略。
    • 列出角色权限中可见的集合。
    • 如果任务涉及自有记录或自定义数据范围，检查现有范围。
  2. 每次仅修改一个层级。
    • 先修改角色或默认角色。
    • 如有需要，再修改系统角色模式。
    • 然后修改系统权限。
    • 接着修改路由权限。
    • 之后修改全局表格权限。
    • 再修改表格独立权限。
    • 最后修改范围和字段限制。
  3. 每次写入后，使用真实的ACL元数据进行验证。
    • 重新读取更新后的角色、路由绑定或资源权限记录。
    • 当涉及联合模式或默认角色时，重新检查当前角色上下文。
  4. 建议在写入前先完成完整的权限矩阵。
    • 针对每个角色，确定系统权限片段、路由绑定、全局表格策略、独立集合操作、字段列表和行范围。
    • 如果某一层级有意留空，请记录留空原因，而非直接跳过。

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
    中。
  • 使用自有记录语义的集合具有必要的所有权字段。
  • 关联修改权限在需要的地方被明确覆盖。
  • 对于真实业务角色，最终配置包含对系统权限、路由权限、全局权限、独立权限、字段权限和范围的明确决策。
  • 空全局策略是有意为之且有合理理由，而非疏忽。
  • 空范围意味着"设计上允许全行访问"，而非"忘记配置范围"。
  • 在字段可见性或修改边界重要的地方配置字段列表，尤其是在更新/创建/查看/导出操作上。
  • 至少在一个允许案例和一个拒绝案例上测试实际访问权限。