最佳实践
本文档提供云开发身份认证与权限控制的最佳实践指南，帮助开发者快速理解和接入身份认证模块，构建安全可靠的应用系统。
功能介绍
核心概念
云开发身份认证体系包含两个核心部分 ：
- 身份认证：解决"用户是谁"的问题，支持手机号、邮箱、微信、匿名等多种登录方式
- 权限控制：解决"用户能调用什么资源"的问题，通过角色和策略精细化管理资源访问权限
完整的身份认证接入需要理解：登录方式 → 角色体系 → 成员管理 → 权限策略 → 安全配置。
登录方式
云开发支持多种登录方式，需要先在 云开发平台/身份认证/登录方式 中开启，可根据应用场景灵活选择：
| 登录方式 | 适用场景 | 配置入口 |
|---|---|---|
| 手机号登录 | 需要实名认证的应用 | 登录方式管理 |
| 邮箱登录 | 企业应用、国际化应用 | 登录方式管理 |
| 微信登录 | 微信生态应用 | 登录方式管理 |
| 匿名登录 | 无需注册即可使用的功能 | 注册配置 |
| 用户名密码 | 传统 Web 应用 | 登录方式管理 |
💡 建议：应用可以同时开启多种登录方式，让用户自主选择。
角色体系
角色定义
角色是权限的载体，通过将用户分配到不同角色，实现精细化的权限管理。系统提供以下预设角色：
| 角色类型 | 说明 | 典型使用场景 |
|---|---|---|
| 管理员 | 拥有所有权限，可管理环境、成员、资源 | 项目负责人、技术主管 |
| 所有用户 | 包含所有已登录和未登录用户 | 公开内容访问控制 |
| 组织成员 | 添加到组织架构的用户 | 企业内部应用访问 |
| 外部用户 | 除组织成员外，非匿名登录的用户 | C端应用用户，需要登录进行访问，如电商应用等 |
| 匿名用户 | 未登录的访客 | 公开页面、营销落地页 |
⚠️ 重要提醒：管理员角色拥有系统的最高权限，包括删除数据、修改配置、管理成员等敏感操作，请谨慎使用。
自定义角色
当预设角色无法满足业务需求时，可以创建自定义角色：
- 访问 云开发平台/身份认证/权限控制 页面
- 点击「创建角色」
- 设置角色标识和描述，例如：
content_editor：内容编辑data_analyst：数据分析finance_admin：财务管理
- 为角色配置访问权限
角色权限合并规则
当用户拥有多个角色时，权限合并遵循以下规则：
- 允许权限取并集：用户拥有所有角色的允许权限之和
- 拒绝权限优先：任一角色的拒绝规则会覆盖其他角色的允许规则
示例：
用户角色：内容编辑 + 数据分析
- 内容编辑：允许访问文章表（读、写、改）
- 数据分析：允许访问订单表（仅读）
- 结果：用户可以读写文章，可以查看订单
成员管理
成员添加
将用户添加到角色，有以下两种方式：
方式一：在角色中添加成员
- 访问 云开发平台/身份认证/权限控制 页面找到目标角色
- 点击角色的「配置成员」
- 点击「添加成员」批量选择用户
- 确认后立即生效
方式二：在组织架构中管理
- 访问 云开发平台/身份认证/组织架构 页面
- 创建部门和岗位结构
- 将用户添加到对应的组织节点
- 批量为用户关联角色
成员权限变更
修改用户权限有两种途径：
- 修改角色权限：该角色下所有用户自动继承新权限
- 调整用户角色：将用户从某个角色移除或添加到新角色
💡 提示：权限变更可能需要一定时间生效，建议用户退出重新登录。
权限控制
权限配置模型
云开发的权限控制基于以下模型：
权限配置 = 资源范围 + 数据范围 + 操作类型
- 资源范围：该角色可以访问哪些资源（数据表、云函数、云存储等）
- 数据范围：可以访问哪些数据（全部数据、仅自己创建的数据、特定条件数据）
- 操作类型：可以执行什么操作（查看、创建、修改、删除）
数据行权限
通过行级权限控制用户可以访问哪些数据行（记录）。常见的配置方式：
- 所有数据：用户可以访问全部数据
- 仅自己的数据：用户只能访问自己创建的数据
- 特定条件数据：用户只能访问满足特定条件的数据（如所属部门、特定状态等）
**示例：**销售人员只能查看自己负责的客户数据
数据列权限
通过字段级权限控制用户可以访问哪些字段（列）。可以配置：
- 可读字段：用户可以查看的字段列表
- 隐藏字段：对用户不可见的敏感字段
**示例：**隐藏销售人员的成本和利润字段
💡 提示：行级权限和字段级权限可以同时使用，实现更精细的数据访问控制。
操作权限
为角色配置对资源的操作权限：
- 查看（Read）：读取数据
- 创建（Create）：新增数据
- 修改（Update）：编辑数据
- 删除（Delete）：删除数据
不同资源类型支持的操作权限可能有所差异，具体请参考相应的资源文档：
典型场景实践示例
场景一：个人博客网站
需求描述
个人博客需要支持游客浏览、用户评论和博主管理三种场景。
角色规划
| 角色 | 权限范围 | 使用对象 |
|---|---|---|
| 匿名用户 | 浏览文章、查看评论 | 所有访客 |
| 注册用户 | 浏览文章、发表评论、点赞 | 注册读者 |
| 管理员 | 发布文章、管理评论、网站设置 | 博客所有者 |
数据权限配置
文章表（blog_articles）权限设置：
- 匿名用户：仅可读取已发布文章
- 注册用户：可读取已发布文章和自己写的草稿
- 管理员：拥有所有权限
评论表（comments）权限设置：
- 匿名用户：仅可查看评论
- 注册用户：可查看所有评论，可修改/删除自己的评论
- 管理员：拥有所有权限
实施步骤
import cloudbase from '@cloudbase/js-sdk';
const app = cloudbase.init({
env: 'your-env-id'
});
const auth = app.auth();
// 默认执行匿名登录操作
auth.signInAnonymously();
场景二：企业内部管理系统
需求描述
企业管理系统需要区分不同部门和岗位的访问权限，实现数据隔离。
角色规划
自定义角色创建：
- 在 权限控制 页面创建自定义角色
- 根据岗位职责设置角色标识，例如：
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: 为什么用户已经添加了权限，但仍然无法访问？
排查步骤：
- 检查角色分配：确认用户已被分配到正确的角色
- 检查策略状态：确认策略已保存并关联到正确的角色上
- 检查生效时间：权限变更可能需要一定时间生效，建议用户退出重新登录
- 检查网关策略：可能被网关层的限制拦截，检查用户关联的网关权限策略
- 查看报错信息：查看具体拒绝原因，针对性解决
Q2: 多个角色的权限如何合并？
当用户拥有多个角色时，权限合并遵循以下规则：
- 允许权限取并集：用户拥有所有角色的允许权限之和
- 拒绝权限优先：任一角色的拒绝规则会覆盖其他角色的允许规则
示例：
用户角色：内容编辑 + 数据分析
- 内容编辑：允许访问文章表（读、写、改）
- 数据分析：允许访问订单表（仅读）
- 结果：用户可以读写文章，可以查看订单