跳到主要内容

安全规则

安全规则 是 CloudBase 云存储的 文件级权限控制 功能，通过自定义表达式精确控制每个文件的读写权限。

PG 模式

本文为传统模式专有功能。在 PG 模式下，文件级权限由 PostgreSQL 的 RLS Policy 表达，能力更强，参见 PG 模式云存储 - RLS 策略模式库。

配置入口​

在 云开发平台/云存储 ，点击「权限设置」，选择「自定义安全规则」即可配置安全规则。

⚠️ 注意：

  • 云开发控制台和服务端始终有所有文件读写权限，安全规则仅对客户端（小程序端、Web 等）发起的请求有效
  • 修改安全规则后，权限生效需要 1-3 分钟，请耐心等待
  • 发布前务必评估规则的安全性，避免 public 规则导致数据泄露

基本语法​

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

常用模板​

{
  "read": true,
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}

表达式语法​

内置变量​

变量名说明示例
auth用户登录信息auth.openid、auth.uid
resource文件资源信息resource.openid

auth 对象属性​

属性说明类型示例值
uid用户唯一标识（Web 端）string"abc123"
openid用户唯一标识（小程序端）string"oABC123"
loginType登录方式string"WECHAT"
LoginType 枚举值​
枚举值登录方式
WECHAT_PUBLIC微信公众号
WECHAT_OPEN微信开放平台
ANONYMOUS匿名登录
EMAIL邮箱登录
CUSTOM自定义登录

resource 对象属性​

属性说明类型示例值
openid文件创建者唯一标识string"oABC123"
path文件在云存储中的相对路径（不包含桶名），格式为 path/filename.jpgstringphotos/photo.jpg

运算符​

运算符说明示例
==等于auth.uid == resource.openid
!=不等于auth.loginType != 'ANONYMOUS'
>大于now \> resource.metadata.expireTime
<小于now \< resource.metadata.publishTime
>=大于等于auth.vipLevel \>= 3
<=小于等于resource.size \<= 10485760
&&逻辑与auth != null && auth.loginType == 'WECHAT'
||逻辑或auth.uid == resource.openid || auth.isAdmin

操作类型​

操作说明默认值
read读取文件（下载、获取 URL）false
write写入文件（上传、删除）false

正则表达式支持​

安全规则支持使用正则表达式来匹配文件路径，但仅支持 .test() 方法，不支持常见的 JavaScript 字符串方法。

支持的写法​

{
  "read": "/test/.test(resource.path)",
  "write": "false"
}

匹配路径中包含 test 的所有文件。

不支持的写法​

以下方法在安全规则中 不可用：

方法示例替代方案
startsWith()resource.path.startsWith('test/')使用 /^test\\//.test(resource.path)
includes()resource.path.includes('test/')使用 /test/.test(resource.path)
indexOf()resource.path.indexOf('test/') === 0使用 /^test\\//.test(resource.path)
match()resource.path.match(/^test\//)使用 /^test\\//.test(resource.path)
substr()resource.path.substr(0, 5) == 'test/'使用正则表达式或字符串相等判断

正则表达式语法规则​

规则说明示例
必须使用 .test()正则表达式必须通过 .test() 方法调用/^test/.test(resource.path)
斜杠转义路径分隔符 / 需要写成 \\//^uploads\\//.test(resource.path)
特殊字符转义正则特殊字符需要转义，如 . 写成 \\./.*\\.jpg$/.test(resource.path)
支持或运算可使用竖线进行简单或运算/test|uploads/.test(resource.path)
不支持分组不能使用括号进行复杂分组不支持 /^(test|uploads)\\//.test(...) 或 /\.(png|jpg)$/.test(...)，需使用 /^test\\//.test(...) || /^uploads\\//.test(...)
支持锚点支持 ^（开头）和 $（结尾）/^public/.test(...) 或 /\\.png$/.test(...)

实用示例​

多个公开目录​

{
  "read": "/^test\\//.test(resource.path) || /^uploads\\//.test(resource.path) || /^public\\//.test(resource.path)",
  "write": "resource.openid == auth.openid"
}

允许所有用户读取 test/、uploads/、public/ 目录下的文件，但只有创建者可写入。

特定类型文件公开​

{
  "read": "/\\.png$/.test(resource.path) || /\\.jpg$/.test(resource.path) || /\\.jpeg$/.test(resource.path) || /\\.gif$/.test(resource.path)",
  "write": "auth != null"
}

公开所有图片文件的读取权限，登录用户可上传。

💡 注意：由于不支持括号分组，需要使用多个正则表达式通过 || 连接。

分层权限控制​

{
  "read": "/^public\\//.test(resource.path) || (auth != null && /^private\\//.test(resource.path) && resource.openid == auth.uid)",
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}
  • public/ 目录所有人可读
  • private/ 目录仅文件创建者可读
  • 所有文件仅创建者可写

应用场景​

个人相册​

需求：用户只能查看和管理自己上传的照片。

{
  "read": "resource.openid == auth.openid || resource.openid == auth.uid",
  "write": "resource.openid == auth.openid || resource.openid == auth.uid"
}
// 小程序端 - 上传照片
wx.cloud.uploadFile({
  cloudPath: `photos/${Date.now()}.jpg`,
  filePath: tempFilePath,
});

// Web SDK - 获取自己的照片列表（需配合云函数查询）
app.callFunction({
  name: "getMyPhotos",
});

公共相册​

需求：只可读取公共文件夹 public 的文件

{
  "read": "/^public\\//.test(resource.path)",
  "write": "auth.uid == resource.openid || auth.openid == resource.openid"
}

跨平台兼容​

由于小程序端使用 auth.openid，Web 端使用 auth.uid，建议在安全规则中同时判断两者：

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