安全规则

安全规则 是 CloudBase 数据库的 文档级权限控制 功能，通过自定义表达式精确控制每条数据的读写权限。

配置入口

在 云开发平台/文档型数据库/集合管理 选择「权限管理」，点击「切换到安全规则」。

基本语法

{
  "read": "表达式",    // 读取权限控制表达式
  "write": "表达式"   // 写入权限控制表达式
}

⚠️ 注意：前端查询条件必须是安全规则的子集，否则访问被拒绝。当安全规则使用 doc.字段名 时，查询条件必须包含对应字段。

常用模板

仅创建者可读写

{
  "read": "doc._openid == auth.openid",
  "write": "doc._openid == auth.openid"
}

// 查询当前用户创建的文档
db.collection('articles').where({
  _openid: '{openid}'
}).get()

公开读取，创建者可写

{
  "read": true,
  "write": "doc._openid == auth.openid"
}

// 读取所有文档
db.collection('articles').get()

// 更新自己创建的文档
db.collection('articles').where({
  _openid: '{openid}'
}).update({ title: '更新后的标题' })

基于状态控制

{
  "read": "doc.published == true || doc.author == auth.openid",
  "write": "doc.author == auth.openid"
}

// 查询已发布的文档
db.collection('articles').where({
  published: true
}).get()

// 查询自己的所有文档
db.collection('articles').where({
  author: '{openid}'
}).get()

跨平台兼容

{
  "read": "doc.userId == auth.openid || doc.userId == auth.uid",
  "write": "doc.userId == auth.openid || doc.userId == auth.uid"
}

💡 注意：小程序端使用 auth.openid ，Web端使用 auth.uid 。查询时使用 {openid} 变量会自动适配。

{openid} 变量

查询条件中可使用字符串常量 {openid} ，系统会自动替换为对应的用户身份标识（小程序端为 openid ，Web端为 uid ）。

// 使用 {openid} 变量查询当前用户数据
db.collection('articles').where({
  author: '{openid}'
}).get()

表达式语法

内置变量

变量名	说明	示例
auth	用户登录信息	auth.openid、auth.uid
doc	文档数据或查询条件字段	doc.userId、doc.status
now	当前时间戳	now > doc.expireTime

运算符

运算符	说明	示例
==	等于	auth.openid == doc.userId
!=	不等于	doc.status != 'deleted'
in	包含于	auth.openid in doc.editors
&&	逻辑与	auth.openid == doc.userId && doc.published
||	逻辑或	auth.openid == doc.userId || doc.public

操作类型

操作	说明	默认值
read	读取文档	false
write	写入文档	false
create	创建文档	继承 write
update	更新文档	继承 write
delete	删除文档	继承 write

get 函数

用于跨文档权限验证，语法：get('database.集合名.文档ID')

{
  "read": "auth.openid in get(`database.room.${doc.roomId}`).members"
}

重要提示

使用 get 函数时，查询条件必须包含被引用的字段，否则会返回 DATABASE_PERMISSION_DENIED 错误。

正确示例：

// 查询条件包含 roomId 字段
db.collection('messages').where({
  roomId: 'room123'
}).get()

错误示例：

// 缺少 roomId 字段，会返回权限拒绝错误
db.collection('messages').where({
  _id: 'msg123'
}).get()

限制条件：

• 查询条件必须包含 get 函数中引用的 doc 字段
• in 操作符中的数组长度必须为1
• 一个表达式最多3个 get 函数
• 嵌套深度最多为2层
• 每个 get 函数会产生一次数据库读取操作

应用场景

文章发布系统

{
  "read": "doc.published == true || doc.author == auth.openid || doc.author == auth.uid",
  "update": "doc.author == auth.openid || doc.author == auth.uid",
  "delete": "(doc.author == auth.openid || doc.author == auth.uid) && doc.published == false"
}

// 查询已发布的文章
db.collection('articles').where({ published: true }).get()

// 查询自己的文章
db.collection('articles').where({ author: '{openid}' }).get()

// 更新自己的文章
db.collection('articles').where({
  author: '{openid}',
  _id: 'article123'
}).update({ title: '更新后的标题' })

协作文档系统

{
  "read": "auth.openid in doc.readers || auth.uid in doc.readers || auth.openid in doc.editors || auth.uid in doc.editors || doc.owner == auth.openid || doc.owner == auth.uid",
  "write": "auth.openid in doc.editors || auth.uid in doc.editors || doc.owner == auth.openid || doc.owner == auth.uid",
  "delete": "doc.owner == auth.openid || doc.owner == auth.uid"
}

// 查询有权限读取的文档
db.collection('documents').where(_.or([
  { readers: _.in(['{openid}']) },
  { editors: _.in(['{openid}']) },
  { owner: '{openid}' }
])).get()

群聊系统

消息集合：

{
  "read": "auth.openid in get(`database.room.${doc.roomId}`).members",
  "create": "auth.openid in get(`database.room.${doc.roomId}`).members",
  "update": "auth.openid == doc.sender"
}

// 查询房间消息（必须包含 roomId）
db.collection('messages').where({
  roomId: 'room123'
}).get()

房间集合：

{
  "read": "auth.openid in doc.members",
  "write": "doc.owner == auth.openid"
}

// 查询加入的房间
db.collection('rooms').where({
  members: _.in(['{openid}'])
}).get()