权限控制

CloudBase 提供两套权限模型，分别对应不同的环境模式，两者解决的核心问题相同——"用户能访问哪些资源"，但实现机制完全不同：

环境模式	权限模型	配置方式
传统模式	角色 + 策略（RBAC）	控制台可视化配置
PG 模式	三种数据库角色（anon / authenticated / service_role） + GRANT + 行级安全策略（RLS）	SQL 语句（同时支持控制台辅助配置）

模式选择

• PG 模式用户：完整的权限模型说明请阅读 PG：身份认证（含三角色、GRANT、RLS、典型场景），本页不适用
• 传统模式用户：继续阅读下文

角色 + 策略（传统模式）

CloudBase 权限控制通过角色体系实现精细化的权限管理，解决"用户能访问哪些资源"的问题。

前往 云开发平台/身份认证/权限控制 查看权限控制。

权限模型

CloudBase 权限控制基于 角色-策略 模型：

用户 → 角色 → 网关权限 + 资源权限 + 数据权限 

• 角色：权限的载体，将用户分配到不同角色
• 网关权限：在用户尝试访问资源时的第一道防线，鉴权时间早于资源健全，查看网关权限控制
• 资源权限：该角色可以访问哪些资源（数据模型、云函数、云存储等）
• 数据权限：可以访问哪些数据（全部数据、仅自己创建的数据、特定条件数据）

角色体系

系统角色

CloudBase 提供五种内置系统角色，满足常见的权限场景：

角色类型	说明	典型使用场景
管理员	拥有所有权限，可管理环境、成员、资源	项目负责人、技术主管
所有用户	包含所有已登录和未登录用户	公开内容访问控制
组织成员	添加到组织架构的用户	企业内部应用访问
注册用户	除组织成员外的非匿名登录用户，在用户管理中查看	C 端应用用户（如电商应用、社交应用）
匿名用户	使用匿名登录的访客	公开页面、营销落地页

⚠️ 安全警告：管理员角色拥有系统最高权限（删除数据、修改配置、管理成员等），请谨慎使用。建议为日常操作创建权限受限的自定义角色，仅在必要时使用管理员账号。

自定义角色

当系统角色无法满足业务需求时，可以创建自定义角色以实现更精细的权限控制。

创建步骤：

1. 访问 云开发平台/身份认证/权限控制 页面
2. 点击「创建角色」
3. 设置角色标识和描述（标识用于代码中引用）
4. 配置该角色的资源访问权限

常见自定义角色示例：

角色标识	角色名称	适用场景
content_editor	内容编辑	管理文章、商品等内容数据
data_analyst	数据分析	查看统计数据和分析报表
finance_admin	财务管理	管理订单、交易等财务数据
customer_support	客服人员	处理用户反馈和工单

多角色权限合并规则

当用户拥有多个角色时，最终权限按以下规则合并：

• 允许权限取并集：用户拥有所有角色的允许权限之和
• 拒绝权限优先：任一角色的拒绝规则会覆盖其他角色的允许规则

示例：

用户同时拥有：内容编辑 + 数据分析

角色权限：
- 内容编辑：允许访问文章表（读、写、改）
- 数据分析：允许访问订单表（仅读）

最终权限：
- 可以读写文章表的所有数据
- 可以查看订单表的数据（仅读）

成员管理

将用户添加到角色，实现权限分配。

添加成员的两种方式

方式一：在角色中添加成员

1. 访问 云开发平台/身份认证/权限控制 页面
2. 找到目标角色，点击「配置成员」
3. 点击「添加成员」批量选择用户
4. 确认后立即生效

方式二：在组织架构中管理

1. 访问 云开发平台/身份认证/组织架构 页面
2. 创建部门和岗位结构
3. 将用户添加到对应的组织节点
4. 为用户批量关联角色

💡 提示：组织架构方式适合企业应用，可以基于部门和岗位批量管理用户权限。

修改用户权限

修改用户权限有两种途径：

修改角色权限

• 在角色的权限配置中调整资源和数据权限
• 该角色下所有用户自动继承新权限
• 适合批量调整多个用户的权限

调整用户角色

• 将用户从某个角色移除
• 或添加用户到新角色
• 适合单个用户的权限调整

⚠️ 注意：权限变更可能需要一定时间生效，建议用户退出重新登录，立即应用新权限。

权限配置

为角色配置具体的访问权限，包括资源权限、数据权限两个维度。

资源权限

资源权限决定角色可以访问哪些 CloudBase 资源。

配置步骤：

1. 在角色卡片中点击「配置权限」
2. 选择「添加自定义策略」
3. 选择要授权的资源类型和具体资源

支持的资源类型：

资源类型	说明	典型应用场景
文档型数据库	NoSQL 数据库权限配置，文档型数据库权限说明	业务数据储存
MySQL 数据库	关系型数据库权限配置，MySQL 数据库权限说明	复杂业务数据
云函数	处理后端业务逻辑，云函数权限说明	API 调用、数据处理
云存储	文件存储，云存储权限管理	图片、视频、文档上传
微搭应用 / 数据模型 / APIs / 工作台	可在权限控制页面直接进行管理， 前往云开发平台/身份认证/权限控制，进入权限策略配置窗口，如下图	后台应用、内容管理、工作台（即云后台）等

权限策略配置窗口：

数据权限

数据权限控制角色可以访问哪些数据，支持行级和列级两种维度。

行级权限（数据行）

控制用户可以访问哪些数据行，实现数据隔离。

常见配置方式：

权限类型	说明	适用场景
所有数据	访问全部数据行	管理员、数据分析人员
仅自己的数据	只能访问自己创建的数据	普通用户、个人数据管理
特定条件数据	满足特定条件的数据（如部门）	部门经理、区域负责人

配置示例：

实际应用：

• 销售人员只能查看自己负责的客户数据
• 部门经理可以查看本部门的所有数据
• 区域经理可以查看所负责区域的数据

列级权限（数据列）

控制用户可以访问哪些字段（列），隐藏敏感信息。

配置选项：

• 可读字段：用户可以查看的字段列表
• 隐藏字段：对用户不可见的敏感字段

配置示例：

实际应用：

• 隐藏销售人员的成本和利润字段
• 隐藏客服人员的用户手机号和身份证号
• 隐藏普通员工的薪资和绩效数据

💡 提示：行级权限和列级权限可以同时使用，实现更精细的数据访问控制。

配置说明：

不同资源类型支持的操作权限可能有所差异，具体配置方式请参考对应的资源文档：

典型应用场景

场景一：个人博客网站

需求分析

个人博客需要支持游客浏览、用户评论和博主管理三种角色。

角色规划

角色	权限范围	使用对象
匿名用户	浏览文章、查看评论	所有访客
注册用户	浏览文章、发表评论、点赞	注册读者
管理员	发布文章、管理评论、网站设置	博客所有者

数据权限配置

文章表（blog_articles）：

角色	查看权限	创建权限	修改权限	删除权限
匿名用户	已发布文章	❌	❌	❌
注册用户	已发布文章+草稿	✅	仅自己的草稿	仅自己的草稿
管理员	所有文章	✅	✅	✅

评论表（comments）：

角色	查看权限	创建权限	修改权限	删除权限
匿名用户	所有评论	❌	❌	❌
注册用户	所有评论	✅	仅自己的评论	仅自己的评论
管理员	所有评论	✅	✅	✅

实施步骤

1. 启用匿名登录

在 登录方式管理 开启「允许匿名登入」。

2. 配置数据库权限

在数据库集合的权限设置中配置对应角色的访问权限，参考 文档型数据库权限。

3. 前端调用匿名登录

import cloudbase from '@cloudbase/js-sdk';

const app = cloudbase.init({
  env: 'your-env-id'
});

const auth = app.auth();

// 页面加载时执行匿名登录
auth.signInAnonymously().then(() => {
  console.log('匿名登录成功');
});

场景二：企业内部管理系统

需求分析

企业管理系统需要区分不同部门和岗位的访问权限，实现数据隔离和精细化管理。

角色规划

创建自定义角色：

1. 访问 权限控制 页面
2. 点击「创建角色」创建以下角色：

角色标识	角色名称	权限范围
content_editor	内容编辑	管理文章、产品等内容数据
data_analyst	数据分析	查看统计数据和分析报表
finance_admin	财务管理	管理订单、交易等财务数据
dept_manager	部门经理	管理本部门的数据和成员

数据权限配置

行级权限示例

配置"用户只能访问自己部门的数据"：

列级权限示例

隐藏敏感字段（如成本、利润）：

实施步骤

1. 创建组织架构

在 组织架构 中创建部门结构。

2. 配置角色权限

为每个角色配置资源权限和数据权限（行级+列级）。

3. 分配用户角色

将用户添加到对应部门，并关联相应角色。

场景三：协同编辑平台

需求分析

多人协同文档编辑平台，允许用户编辑他人创建的文档，需要严格的权限控制。

角色规划

角色	权限范围	使用对象
普通用户	查看所有文档、编辑自己的文档	注册用户
协作者	查看所有文档、编辑被授权的文档	被邀请的用户
管理员	所有文档的完整权限（查看、编辑、删除）	团队管理者

实现方案

⚠️ 安全警告：允许修改他人数据是高风险操作，必须实施严格的权限验证。

方案一：通过云函数修改数据（推荐）

云函数在服务端执行，可以绕过客户端权限限制，但需要在函数内部实现严格的权限验证：

// 云函数：editDocument
const cloudbase = require('@cloudbase/node-sdk');
const app = cloudbase.init();
const db = app.database();

exports.main = async (event, context) => {
  const { documentId, newContent } = event;
  const { userInfo } = context;
  
  // 1. 验证用户登录状态
  if (!userInfo || !userInfo.uid) {
    return { code: 401, message: '未登录' };
  }
  
  // 2. 查询文档信息
  const doc = await db.collection('documents')
    .doc(documentId)
    .get();
  
  if (!doc.data || doc.data.length === 0) {
    return { code: 404, message: '文档不存在' };
  }
  
  const document = doc.data[0];
  
  // 3. 权限验证：检查是否是作者或协作者
  const isOwner = document._openid === userInfo.openid;
  const isCollaborator = document.collaborators && 
    document.collaborators.includes(userInfo.uid);
  
  if (!isOwner && !isCollaborator) {
    return { code: 403, message: '无权编辑此文档' };
  }
  
  // 4. 执行更新
  const result = await db.collection('documents')
    .doc(documentId)
    .update({
      content: newContent,
      lastEditBy: userInfo.uid,
      lastEditAt: new Date()
    });
  
  return { code: 0, message: '更新成功', data: result };
};

方案二：通过安全规则配置（精细控制）

对于需要更复杂、更精细的权限控制场景，可以使用安全规则功能。

CloudBase 支持安全规则的资源：

资源类型	安全规则文档	适用场景
文档型数据库	数据库安全规则	文档级、字段级的权限控制
云存储	云存储安全规则	文件上传、下载、删除权限控制
云函数	云函数安全规则	函数调用权限控制

使用安全规则实现协同编辑：

{
  // 读权限：所有登录用户都可以查看文档
  "read": "auth != null",
  
  // 写权限：作者、协作者或管理员可以编辑
  "write": "doc._openid == auth.openid || doc.collaborators.includes(auth.uid) || auth.role == 'admin'"
}

💡 提示：安全规则在数据库层面生效，无需编写云函数即可实现复杂的权限控制逻辑。

安全最佳实践

管理员权限的谨慎使用

⚠️ 安全警告：管理员角色拥有系统最高权限（删除数据、修改配置、管理成员等），错误操作可能导致严重后果。

建议做法：

1. 最小化管理员数量：仅为必要人员授予管理员权限
2. 创建日常角色：为日常操作创建权限受限的自定义角色
3. 分离权限：根据职责划分不同权限级别的角色
4. 定期审查：定期检查管理员账号列表，移除不再需要的权限
5. 启用双因素认证：启用多因素认证验证，保障账号安全

权限最小化原则

遵循"最小权限原则"，仅授予用户完成工作所需的最小权限。

正确做法：

✅ 销售人员只能查看和编辑自己负责的客户数据
✅ 客服人员只能查看工单信息，但无法查看用户的支付信息
✅ 数据分析人员只能查看数据（只读权限），无法修改或删除

应避免的做法：

❌ 销售人员可以查看所有客户数据
❌ 客服人员拥有用户信息的完整访问权限
❌ 给普通员工授予管理员权限以"方便操作"

敏感数据保护

对于敏感数据，建议采用多层防护：

1. 列级权限：隐藏敏感字段（如身份证、银行卡号）
2. 数据脱敏：在展示时对敏感信息进行脱敏处理
3. 审计日志：记录所有对敏感数据的访问和修改操作
4. 定期审查：定期审查敏感数据的访问权限配置

权限变更管理

权限变更前：

1. 评估影响范围，确认变更不会影响业务正常运行
2. 在测试环境验证权限配置的正确性
3. 通知相关用户即将进行的权限调整

权限变更后：

1. 验证权限配置是否生效
2. 建议用户退出重新登录以立即应用新权限
3. 监控是否有权限相关的错误或异常

常见问题

Q1: 用户已添加权限，但仍然无法访问资源？

排查步骤：

1. 检查角色分配

   • 确认用户已被正确分配到目标角色
   • 在 用户管理 中查看用户的角色列表

2. 检查策略配置

   • 确认策略已保存并关联到正确的角色
   • 在 权限控制 中查看角色的策略配置

3. 检查权限生效时间

   • 权限变更可能需要一定时间生效
   • 建议用户退出重新登录以立即应用新权限

4. 检查网关策略

   • 可能被网关层的限制拦截
   • 检查用户关联的网关权限策略

5. 查看具体错误信息

   • 查看客户端或服务端的错误日志
   • 根据错误码针对性解决问题

Q2: 多个角色的权限如何合并？

当用户拥有多个角色时，权限合并遵循以下规则：

权限合并规则：

• 允许权限取并集：用户拥有所有角色的允许权限之和
• 拒绝权限优先：任一角色的拒绝规则会覆盖其他角色的允许规则

示例：

用户同时拥有：内容编辑 + 数据分析

角色权限：
- 内容编辑：允许访问文章表（读、写、改）
- 数据分析：允许访问订单表（仅读）、拒绝删除文章表

最终权限：
- 可以读写文章表，但不能删除文章（拒绝规则优先）
- 可以查看订单表的数据（仅读）

Q3: 如何实现"用户只能查看自己部门的数据"？

使用行级权限配置实现数据隔离：

实施步骤：

1. 在数据表中添加 department 字段，记录数据所属部门
2. 在用户信息中添加 department 字段，记录用户所属部门
3. 配置数据权限时，设置行级权限规则：doc.department == user.department

参考配置：

Q4: 安全规则和角色权限有什么区别？

角色权限（Role-based Access Control）：

• 基于用户角色的权限管理
• 适合企业级应用，支持组织架构
• 在控制台可视化配置
• 适合大部分常见场景

安全规则（Security Rules）：

详细说明见：数据库安全规则

• 基于表达式的文档级权限控制
• 支持更复杂的权限逻辑（如基于数据内容的权限判断）
• 需要编写规则表达式
• 适合需要精细控制的场景

推荐做法：

• 优先使用角色权限满足基本需求
• 对于复杂场景，结合安全规则实现更精细的控制
• 角色权限和安全规则可以同时使用，最终权限为两者的交集

Q5: 如何批量管理用户权限？

方法一：通过组织架构批量管理

1. 在 组织架构 中创建部门结构
2. 将用户添加到对应部门
3. 为部门统一配置角色，该部门的所有用户自动继承角色权限

方法二：通过修改角色权限

1. 找到需要调整的角色
2. 修改该角色的权限配置
3. 该角色下的所有用户自动应用新权限

方法三：使用 HTTP API 批量操作

对于大规模用户权限管理，可以使用 CloudBase HTTP API 进行批量操作，参考 HTTP API 文档。

相关文档

身份认证相关：

• 身份认证概述 - 了解 CloudBase 身份认证体系
• 管理用户 - 用户信息管理和账号操作
• 登录方式管理 - 配置和启用不同的登录方式
• JS SDK (V2) 身份认证 - Web 端身份认证 API
• HTTP API 登录认证接口 - HTTP API 身份认证

数据权限相关：

• 文档型数据库权限 - NoSQL 数据库权限管理
• 数据库安全规则 - 文档级权限控制
• MySQL 数据库权限 - 关系型数据库权限管理
• PG 数据权限管理 - PG 模式 RLS 权限管理

资源权限相关：

• 云函数权限控制 - 云函数调用权限管理
• 云存储权限管理 - 文件存储权限控制