最佳实践

本文档提供云开发身份认证与权限控制的最佳实践指南，帮助开发者快速理解和接入身份认证模块，构建安全可靠的应用系统。

功能介绍

核心概念

云开发身份认证体系包含两个核心部分：

• 身份认证：解决"用户是谁"的问题，支持手机号、邮箱、微信、匿名等多种登录方式
• 权限控制：解决"用户能调用什么资源"的问题，通过角色和策略精细化管理资源访问权限

完整的身份认证接入需要理解：登录方式 → 角色体系 → 成员管理 → 权限策略 → 安全配置。

登录方式

云开发支持多种登录方式，需要先在 云开发平台/身份认证/登录方式 中开启，可根据应用场景灵活选择：

登录方式	适用场景	配置入口
手机号登录	需要实名认证的应用	登录方式管理
邮箱登录	企业应用、国际化应用	登录方式管理
微信登录	微信生态应用	登录方式管理
匿名登录	无需注册即可使用的功能	注册配置
用户名密码	传统 Web 应用	登录方式管理

💡 建议：应用可以同时开启多种登录方式，让用户自主选择。

角色体系

角色定义

角色是权限的载体，通过将用户分配到不同角色，实现精细化的权限管理。系统提供以下预设角色：

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

⚠️ 重要提醒：管理员角色拥有系统的最高权限，包括删除数据、修改配置、管理成员等敏感操作，请谨慎使用。

自定义角色

当预设角色无法满足业务需求时，可以创建自定义角色：

1. 访问 云开发平台/身份认证/权限控制 页面
2. 点击「创建角色」
3. 设置角色标识和描述，例如：
   • content_editor：内容编辑
   • data_analyst：数据分析
   • finance_admin：财务管理
4. 为角色配置访问权限

角色权限合并规则

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

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

示例：

用户角色：内容编辑 + 数据分析
- 内容编辑：允许访问文章表（读、写、改）
- 数据分析：允许访问订单表（仅读）
- 结果：用户可以读写文章，可以查看订单

成员管理

成员添加

将用户添加到角色，有以下两种方式：

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

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

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

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

成员权限变更

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

• 修改角色权限：该角色下所有用户自动继承新权限
• 调整用户角色：将用户从某个角色移除或添加到新角色

💡 提示：权限变更可能需要一定时间生效，建议用户退出重新登录。

权限控制

权限配置模型

云开发的权限控制基于以下模型：

权限配置 = 资源范围 + 数据范围 + 操作类型

• 资源范围：该角色可以访问哪些资源（数据表、云函数、云存储等）
• 数据范围：可以访问哪些数据（全部数据、仅自己创建的数据、特定条件数据）
• 操作类型：可以执行什么操作（查看、创建、修改、删除）

数据行权限

通过行级权限控制用户可以访问哪些数据行（记录）。常见的配置方式：

• 所有数据：用户可以访问全部数据
• 仅自己的数据：用户只能访问自己创建的数据
• 特定条件数据：用户只能访问满足特定条件的数据（如所属部门、特定状态等）

示例：销售人员只能查看自己负责的客户数据

数据列权限

通过字段级权限控制用户可以访问哪些字段（列）。可以配置：

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

示例：隐藏销售人员的成本和利润字段

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

操作权限

为角色配置对资源的操作权限：

• 查看（Read）：读取数据
• 创建（Create）：新增数据
• 修改（Update）：编辑数据
• 删除（Delete）：删除数据

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

• 文档型数据库权限
• MySQL数据库权限
• 云函数权限控制

典型场景实践示例

场景一：个人博客网站

需求描述

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

角色规划

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

数据权限配置

文章表（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();

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

需求描述

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

角色规划

自定义角色创建：

1. 在 权限控制 页面创建自定义角色
2. 根据岗位职责设置角色标识，例如：
   • content_editor：内容编辑
   • data_analyst：数据分析
   • finance_admin：财务管理

数据权限配置

行级权限配置：

实现"用户只能访问自己部门的数据"：

字段级权限配置：

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

场景三：协同编辑平台

需求描述

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

角色规划

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

实现方案

⚠️ 安全警告：允许修改他人数据是高风险操作，必须谨慎实施权限控制。

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

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

// 云函数：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 的安全规则功能。

CloudBase 支持安全规则的资源：

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

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

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

安全配置建议

管理员角色的谨慎使用

⚠️ 重要提醒：管理员角色拥有系统的最高权限，包括删除数据、修改配置、管理成员等敏感操作。

建议做法：

• 为日常操作创建权限受限的自定义角色
• 仅在必要时使用管理员账号
• 定期审查管理员账号列表
• 为管理员账号启用双因素认证

权限最小化原则

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

✓ 推荐：销售人员只能查看自己负责的客户数据
✗ 避免：销售人员可以查看所有客户数据

常见问题与解决方案

Q1: 为什么用户已经添加了权限，但仍然无法访问？

排查步骤：

1. 检查角色分配：确认用户已被分配到正确的角色
2. 检查策略状态：确认策略已保存并关联到正确的角色上
3. 检查生效时间：权限变更可能需要一定时间生效，建议用户退出重新登录
4. 检查网关策略：可能被网关层的限制拦截，检查用户关联的网关权限策略
5. 查看报错信息：查看具体拒绝原因，针对性解决

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

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

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

示例：

用户角色：内容编辑 + 数据分析
- 内容编辑：允许访问文章表（读、写、改）
- 数据分析：允许访问订单表（仅读）
- 结果：用户可以读写文章，可以查看订单

相关资源

• JS SDK (V2)/身份认证
• HTTP API/登录认证接口
• 文档型数据库/权限管理
• MySQL数据库/权限管理
• 云函数/权限管理
• 云存储/权限管理