数据库安全规则

开发者工具 1.02.1911252 起支持配置

安全规则是一个让开发者可以灵活地自定义前端数据库读写权限的能力，通过配置安全规则，开发者可以精细化的控制集合中所有记录的读、写权限，自动拒绝不符合安全规则的前端数据库请求，保障数据安全。使用安全规则，你将获得以下能力：

  1. 灵活自定义集合记录的读写权限：获得比基础的四种基础权限设置更灵活、强大的读写权限控制，让读写权限控制不再强制依赖于 _openid 字段和用户 openid
  2. 防止越权访问和越权更新：用户只能获取通过安全规则限制的用户所能获取的内容，越权获取数据将被拒绝
  3. 限制新建数据的内容：让新建数据必须符合规则，如可以要求权限标记字段必须为用户 openid

同时随着安全规则的开放，前端批量更新（where.update、where.remove）也随之开放（基础库 2.9.4 起），开发者在进行批量更新时应搭配安全规则使用以保障数据安全。

简介

安全规则要求前端发起的查询条件必须是安全规则的子集，否则拒绝访问。比如定义一个读写访问规则是 auth.openid == doc._openid，则表示访问时的查询条件（doc）的 openid 必须等于当前用户的 openid （由系统赋值的不可篡改的 auth.openid 给出），如果查询条件没有包含这项，则表示尝试越权访问 _openid 字段不等于自身的记录，会被后台拒绝访问。

与基础权限配置的对比

除了安全规则外，云开发数据库提供了四种基础权限配置，适用于简单的前端访问控制，只支持 4 种预设的规则（对集合中的每条数据记录）：

  1. 所有用户可读，仅创建者可写
  2. 仅创建者可读写
  3. 所有用户可读
  4. 所有用户不可读写

但基础的设置给前端的访问权限控制是有一定局限性、同时会带来一些容易疑惑的、需要深入理解的系统默认行为：

  1. 访问权限控制要求只能基于记录的 _openid 字段和用户的 openid，控制粒度较粗、相对不灵活
  2. 当权限为 “仅创建者可读写” 时，查询时会默认给查询条件加上一条 _openid 必须等于用户 openid
  3. 当权限为 “仅创建者可读写” 或 “所有用户可读，仅创建者可写” 时，更新前会默认先带上 _openid 必须等于用户 openid 的查询条件，再将查询到的结果进行更新，即使是用 doc.update 也是如此（因此我们会见到即使我们没有对应 _id 的记录的访问权限，但是更新操作不会失败，只会在返回的结果中说明 updated 更新的记录数量为 0）。
  4. 创建记录时，会自动给记录加上 _openid 字段，值等于用户 openid，并且不允许用户在创建记录时尝试设置 _openid
  5. 更新记录时，不允许修改 _openid

因此，我们建议开发者使用新推出的数据库安全规则取代基础权限配置，可以让数据库访问的行为更加明确，同时取消需要深入理解的系统默认行为，让数据库权限控制更加简单明确。

新的安全规则与旧的四种基础权限配置的对应关系如下，我们在此先给出样例，下方再给出具体的安全规则使用指南：

新自定义安全规则与旧权限配置的对应关系

所有用户可读，仅创建者可写

  1. {
  2.   "read": true,
  3.   "write": "doc._openid == auth.openid"
  4. }

仅创建者可读写

  1. {
  2.   "read": "doc._openid == auth.openid",
  3.   "write": "doc._openid == auth.openid"
  4. }

所有用户可读

  1. {
  2.   "read": true,
  3.   "write": false
  4. }

所有用户不可读写

  1. {
  2.   "read": false,
  3.   "write": false
  4. }

规则编写

我们可以在控制台对各个集合分别配置安全规则，入口在集合权限配置页，在基础的四种权限配置外还提供了 “自定义规则” 的选项。

每个集合都有独立的安全规则配置，配置的格式为 json，比如如下一个在某集合上的安全规则配置：

  1. {
  2.   "read": "true",
  3.   "write": "auth.openid === doc._openid"
  4. }

这配置其实就对应着已有的 “所有用户可读，仅创建者可写” 这一权限配置。配置的 key 表示操作类型，value 是一个表达式，表示需要满足什么条件才允许相应的操作类型。当表达式解析为 true 时即代表相应类型的操作符合安全规则。

操作类型

支持配置的操作类型如下：

操作类型说明默认值
read读false
write写，可以细分为 create、update、deletefalse
create新建无
update更新无
delete删除无

规则表达式

规则表达式是类 js 的表达式，支持部分表达式，内置全局变量、全局函数。

全局变量

变量类型说明
authobject用户登录信息，auth.openid 是用户 openid
docobject记录内容，用于匹配记录内容/查询条件
nownumber当前时间的时间戳

运算符

运算符说明示例示例解释(集合查询)
==等于auth.openid == ‘zzz’用户的 openid 为 zzz
!=不等于auth.openid != ‘zzz’用户的 openid 不为 zzz
>大于doc.age>10查询条件的 age 属性大于 10
>=大于等于doc.age>=10查询条件的 age 属性大于等于 10
<小于doc.age<10查询条件的 age 属性小于 10
<=小于等于doc.age<=10查询条件的 age 属性小于等于 10
in存在在集合中auth.openid in [‘zzz’,’aaa’]用户的 openid 是[‘zzz’,’aaa’]中的一个
!(xx in [])不存在在集合中，使用 in 的方式描述 !(a in [1,2,3])!(auth.openid in [‘zzz’,’aaa’])用户的 openid 不是[‘zzz’,’aaa’]中的任何一个
&&与auth.openid == ‘zzz’ && doc.age>10用户的 openid 为 zzz 并且查询条件的 age 属性大于 10
||或auth.openid == ‘zzz’ || doc.age>10用户的 openid 为 zzz 或者查询条件的 age 属性大于 10
.对象元素访问符auth.openid用户的 openid
[]数组访问符属性doc.favorites[0] == ‘zzz’查询条件的 favorites 数组字段的第一项的值等于 zzz

全局函数

get：获取指定记录

get 函数，用于在安全规则中获取其记录来参与到安全规则的匹配中，函数的参数格式是 `database.集合名.记录id` ，可以接收变量，值可以通过多种计算方式得到，例如使用字符串模版进行拼接（database.${doc.collction}.${doc.\_id}）。

如果有对应对象，则函数返回记录的内容，否则返回空。

示例：

  1. {
  2.   "read": "true",
  3.   "delete": "get(`database.user.${id}`).isManager"
  4. }

get 函数有以下限制条件：

  1. get 参数中存在的变量 doc 需要在 query 条件中以 == 或 in 方式出现，若以 in 方式出现，只允许 in 唯一值， 即 doc.shopId in array, array.length == 1
  2. 一个表达式最多可以有 3 个 get 函数，最多可以访问 3 个不同的文档。
  3. get 函数的嵌套深度最多为 2， 即 get(get(path))。

读操作触发与配额消耗说明：

get 函数的执行会计入数据库请求数，同样受数据库配额限制。在未使用变量的情况下，每个 get 会产生一次读操作，在使用变量时，对每个变量值会产生一次 get 读操作。例如：

假设某集合 shop 上有如下规则：

  1. {
  2.   "read": "auth.openid == get(`database.shop.${doc._id}`).owner",
  3.   "write": false
  4. }

在执行如下查询语句时会产生 5 次读取。

  1. db.collection('shop').where(_.or([{_id:1},{_id:2},{_id:3},{_id:4},{_id:5}])).get()

规则匹配

对于查询或更新操作，输入的查询条件必须是安全规则的子集。系统不会去实际取数据，而会判断输入的查询条件是否是安全规则的子集，如果不是，则代表正在尝试访问没有权限访问的数据，会直接拒绝操作。

可能生效的操作类型包括 read、write、update、delete

示例：

  1. // 集合 test 的安全规则配置限制只能查询 age > 10 的记录
  2. {
  3.   "read": "doc.age > 10"
  4. }
  6. // 符合安全规则
  7. const res = await db.collection('test').where({
  8.   age: _.gt(10)
  9. }).get()
  11. // 不符合安全规则
  12. const res = db.collection('test').where({
  13.   age: _.gt(8)
  14. }).get()

对于 create，则会校验写入的数据是否符合安全规则。

{openid} 变量

在查询时，当前用户 openid 是常用的变量，在新的安全规则体系下，要求显式传入 openid，因此为了方便开发者、让开发者无需每次先通过云函数获取用户 openid，我们规定查询条件中可使用一个字符串常量 {openid}，在后台中发现该字符串时会自动替换为小程序用户的 openid，如假设有安全规则：

  1. {
  2.   "read": "doc.publisher == auth.openid"
  3. }

则发起读请求时可以使用 {openid} 常量，效果等同于显示传入当前用户的实际 openid ：

  1. db.collection('test').where({
  2.   publisher: '{openid}'
  3. }).get()

未登录模式

未登录模式即无登录态的模式，在未登录模式中，auth 为空，开发者可以以此判断是未登录用户的访问。未登录模式的场景有如：

  1. 单页模式：小程序/小游戏分享到朋友圈被打开时
  2. Web 未登录模式：没有登录的 Web 环境中（见多端支持）

升级与兼容指引

由于安全规则要求查询条件是安全规则的子集，同时摒弃了旧有权限配置的隐式默认行为，因此启动安全规则需要开发者注意以下升级/兼容处理：

1. doc 操作需转为 where 操作

因 doc 操作（doc.get, doc.set 等）是仅指定 _id 进行的操作，因此其查询条件大部分情况下并不会满足安全规则（除非在 "read": true 下进行读操作或在 "write": true 的情况下进行写操作），因此需要转换为等价的、查询条件包含安全规则或是其子集的形式。例：

假设在集合 todo 上有以下权限规则：

  1. {
  2.   "read": "doc._openid == auth.openid",
  3.   "write": "doc._openid == auth.openid"
  4. }

旧权限配置可以通过 db.collection('todo').doc('x').get() 获取记录内容，新安全规则需要改为：

  1. db.collection('todo').where({
  2.   _id: 'x',
  3.   _openid: '{openid}',
  4. })

doc.update, doc.remove 同理，注意 doc.set 无法使用，需要用 doc.update 替代。

2. 从旧权限配置升级后，查询更新语句都需明确指定 openid

因升级前查询条件可以不传 _openid，而升级后要求显示传入以保证查询条件符合安全规则，因此所有查询条件均需传入 openid，还是以上一节中的安全规则示例为例，对旧权限配置中的如下查询语句：

  1. db.collection('todo').where({
  2.   progress: _.lt(50)
  3. }).get()

需要改为：

  1. db.collection('todo').where({
  2.   _openid: '{openid}',
  3.   progress: _.lt(50)
  4. }).get()

在开放安全规则后，where.update 和 where.remove 也在小程序端开放了，可以进行符合安全规则的批量更新，如：

  1. db.collection('todo').where({
  2.   _openid: '{openid}',
  3.   category: 'sport'
  4. }).update({
  5.   progress: _.inc(10)
  6. })

示例

以下给出三个简易示例：群聊、信息流评论、商品订单管理。

示例 1：群聊

集合定义

user

  1. {
  2.   _id: string,
  3.   _openid: string,
  4.   name: string,
  5. }

room

  1. {
  2.   _id: string,
  3.   owner: string, // 群主 openid
  4.   name: string, // 群名
  5.   members: string[], // 成员 openid 列表
  6. }

message

  1. {
  2.   _id: string,
  3.   room: string, // 房间 id
  4.   sender: string, // 发送者 openid
  5.   content: string, // 消息内容
  6.   time: Date, // 发送时间
  7.   withdrawn: boolean, // 是否已撤回
  8. }

权限规则

user 权限规则

  1. {
  2.   "read": "doc._openid == auth.openid", // 私有读
  3.   "write": "doc._openid == auth.openid", // 仅能修改自己的信息
  4. }

room 权限规则

  1. {
  2.   "read": "auth.openid in get('database.room.${doc._id}').members", // 仅群成员可以读群信息
  3.   // 要求管理房间的写操作不能在前端：
  4.   //  - 原子：建群时需保证room集合的members和各个成员的rooms都写入
  5.   //  - 权限：仅群主能修改群信息
  6.   //  - 权限：仅群成员可以拉新成员进群
  7.   //  - 权限：仅群主可以踢人
  8.   "write": false
  9. }

message 权限规则

  1. {
  2.   // 仅能读取自己所在房间的聊天消息，且不允许读取已撤回的消息
  3.   "read": "auth.openid in get('database.room.${doc.room}').members && doc.withdrawn == false",
  4.   // 只能在云函数写:
  5.   //  - 仅能在自己所在的房间发消息
  6.   //  - 只能修改自己发送的消息
  7.   //  - 不能删除自己发送的消息（只能撤回）
  8.   "create": "auth.openid in get('database.room.${doc.room}').members",
  9.   "update": "auth.openid == doc.sender",
  10.   "delete": false
  11. }

查询 / 监听示例

监听自己所在的某个房间的某个时间点之后的新消息（就是监听已接收的某个消息后的新消息）：

  1. wx.cloud.init({
  2.   env: '环境 ID',
  3. })
  4. const db = wx.cloud.database()
  5. const _ = db.command
  7. const watcher = db.collection('message').where({
  8.   room: '房间 id',
  9.   time: _.gt(new Date('2019-09-01 10:00')),
  10. }).watch({
  11.   onChange: snapshot => {
  12.     console.log(`新事件`, snapshot)
  13.   },
  14.   onError: err => {
  15.     console.error(`监听错误`, err)
  16.   }
  17. })

示例 2：信息流评论

集合定义

user: 用户信息集合，以用户 openid 为 id

  1. {
  2.   _id: string, // openid
  3.   _openid: string,
  4.   name: string,
  5.   isManager: boolean, // 管理员标记位
  6. }

article: 文章集合

  1. {
  2.   _id: string,
  3.   publisher: string, // 发布者 openid
  4.   content: string, // 内容
  5. }

comment: 评论集合

  1. {
  2.   _id: string,
  3.   commenter: string, // 评论者 openid
  4.   articleId: string, // 被评论的文章 id
  5.   content: string, // 评论内容
  6. }

安全规则

article 安全规则

  1. {
  2.   "read": true, // 公有读
  3.   "create": "doc.publisher == auth.openid", // 都可以发文章，但对数据一致性校验，要求 publisher 为发布者 openid
  4.   "update": "doc.publisher == auth.openid || get('database.user.${auth.openid}').isManager", // 仅发布者或管理员可以更新
  5.   "delete": "doc.publisher == auth.openid || get('database.user.${auth.openid}').isManager", // 仅发布者或管理员可以删除
  6. }

comment 安全规则

  1. {
  2.   "read": true, // 公有读
  3.   "create": "doc.commenter == auth.openid", // 都可以发评论，但对数据一致性校验，要求 publisher 为发布者 openid
  4.   "update": "doc.commenter == auth.openid || get('database.user.${auth.openid}').isManager", // 仅发布者或管理员可以更新
  5.   "delete": "doc.commenter == auth.openid || get('database.user.${auth.openid}').isManager", // 仅发布者或管理员可以删除
  6. }

查询示例

创建一条评论：

  1. wx.cloud.init({
  2.   env: '环境 ID',
  3. })
  4. const db = wx.cloud.database()
  5. const _ = db.command
  7. const result = await db.collection('comment').add({
  8.   data: {
  9.     commenter: '{openid}', // 用 {openid} 变量，后台会自动替换为当前用户 openid
  10.     articleId: '文章 ID',
  11.     content: '评论内容',
  12.   },
  13. })
  15. console.log('创建结果', result)

示例 3：商品订单管理

假设需要构建一个简易商品管理系统，有商店信息，一个商店对应多个商品、多个订单，商品信息公开可查，只有商店所有者或管理员可以查看自己商店的订单信息。

集合定义

shop 商店集合

  1. {
  2.   _id: string,
  3.   name: string, // 商店名
  4.   location: GeoPoint, // 商店地理位置
  5.   owner: string, // 商店拥有者 openid
  6.   managers: string[], // 商店管理员 openid 列表
  7. }

item 商品集合

  1. {
  2.   _id: string,
  3.   shopId: string, // 所在商店
  4.   name: string, // 商品名
  5.   price: number, // 价格
  6.   stock: number, // 库存
  7. }

order 订单集合

  1. {
  2.   _id: string,
  3.   shopId: string, // 下单的商店
  4.   itemId: string, // 下单的商品
  5.   price: number, // 成交价格
  6.   amount: number, // 成交数量
  7.   status: string, // 状态
  8.   createTime: Date, // 创建时间
  9.   updateTime: Date, // 更新时间
  10. }

权限规则

shop 安全规则：

  1. {
  2.   "read": true, // 公有读
  3.   "write": false, // 仅云函数端写
  4. }

item 安全规则：

  1. {
  2.   // 公有读
  3.   "read": true,
  4.   // 仅商店所有者或管理员可写
  5.   "write": "auth.openid == get(`database.shop.${doc.shopId}`).owner || auth.openid in get(`database.shop.${doc.shopId}`).managers",
  6. }

order 安全规则：

  1. {
  2.   // 仅商店所有者或管理员可读写
  3.   "read": "auth.openid == get(`database.shop.${doc.shopId}`).owner || auth.openid in get(`database.shop.${doc.shopId}`).managers",
  4.   "write": "auth.openid == get(`database.shop.${doc.shopId}`).owner || auth.openid in get(`database.shop.${doc.shopId}`).managers",
  5.   // 仅云函数端可删除订单记录
  6.   "delete": false,
  7. }

查询 / 监听示例

监听自己所在商店的新订单动态：

  1. wx.cloud.init({
  2.   env: '环境 ID',
  3. })
  4. const db = wx.cloud.database()
  5. const _ = db.command
  7. const watcher = db.collection('order').where({
  8.   shopId: '商店 id',
  9.   createTime: _.gt(new Date()),
  10. }).watch({
  11.   onChange: snapshot => {
  12.     console.log(`新事件`, snapshot)
  13.   },
  14.   onError: err => {
  15.     console.error(`监听错误`, err)
  16.   }
  17. })