了解如何保护文件

Cloud Storage 提供了一种基于路径的声明式安全模型,称为面向 Cloud Storage 的 Firebase 安全规则,可让您快速轻松地保护自己的文件。

了解规则

面向 Cloud Storage 的 Firebase 安全规则用于确定哪些人对 Cloud Storage 中存储的文件拥有读取和写入权限,也可用于确定文件的层次结构以及文件中包含的元数据。基本类型的规则为 allow 规则,如果指定了视情况指定的条件,此规则可允许 readwrite 请求,例如:

// If no condition is specified, the rule evaluates to true
allow read;

// Rules can optionally specify a condition
allow write: if <condition>;

// Rules can also specify multiple request methods
allow read, write: if <condition>;

匹配路径

存储安全规则可匹配 (match) 用于访问 Cloud Storage 中文件的文件路径。规则可以匹配 (match) 确切路径或通配符路径。此外,还可以嵌套规则。如果匹配规则都不允许请求方法,或条件求得的值为 false,那么请求将遭拒。

完全匹配

// Exact match for "images/profilePhoto.png"
match /images/profilePhoto.png {
  allow write: if <condition>;
}

// Exact match for "images/croppedProfilePhoto.png"
match /images/croppedProfilePhoto.png {
  allow write: if <other_condition>;
}

嵌套匹配

// Partial match for files that start with "images"
match /images {
  // Exact match for "images/profilePhoto.png"
  match /profilePhoto.png {
    allow write: if <condition>;
  }

  // Exact match for "images/croppedProfilePhoto.png"
  match /croppedProfilePhoto.png {
    allow write: if <other_condition>;
  }
}

通配符匹配

规则还可用于使用通配符进行模式匹配 (match)。通配符是一个已命名变量,表示单字符串(如 profilePhoto.png)或多个路径段(如 images/profilePhoto.png)。

可以用大括号括住通配符名称(如 {string}),从而创建单字符串通配符。可以向通配符名称添加 =**(如 {path=**}),从而声明多段通配符。

// Partial match for files that start with "images"
match /images {
  // Exact match for "images/*"
  // e.g. images/profilePhoto.png is matched
  match /{imageId} {
    // This rule only matches a single path segment (*)
    // imageId is a string that contains the specific segment matched
    allow read: if <condition>;
  }

  // Exact match for "images/**"
  // e.g. images/users/user:12345/profilePhoto.png is matched
  // images/profilePhoto.png is also matched!
  match /{allImages=**} {
    // This rule matches one or more path segments (**)
    // allImages is a path that contains all segments matched
    allow read: if <other_condition>;
  }
}

如果一个文件有多个匹配规则,所有规则求得的值之间存在 OR 关系。也就是说,如果文件的任何一个匹配规则求得的值为 true,结果就为 true

在上述规则中,只要 conditionother_condition 中任何一个求得的值为 true,就可以读取文件“images/profilePhoto.png”;而只有当 other_condition 求得的值为 true 时,才能读取文件“images/users/user:12345/profilePhoto.png”。

可以从提供文件名或路径授权的 match 中引用通配符变量:

// Another way to restrict the name of a file
match /images/{imageId} {
  allow read: if imageId == "profilePhoto.png";
}

存储安全规则不采用级联形式,只有当请求的路径与已指定规则的路径匹配时才会对规则进行求值。

请求求值

上传、下载、元数据更改和删除操作是使用发送到 Cloud Storage 的 request 进行求值的。request 变量包含正在执行请求的文件路径、请求接收时间以及新的 resource 值(如果请求为写入操作)。此外,还包含 HTTP 标头和身份验证状态。

request 对象还包含用户的唯一 ID 和 request.auth 对象中的 Firebase 身份验证负载,我们将在相关文档的基于用户的安全性部分进一步阐述这一点。

request 对象中属性的完整列表如下:

属性 类型 说明
auth 映射<字符串, 字符串> 在用户登录后,提供 uid(用户的唯一 ID)和 token(Firebase 身份验证 JWT 声明的映射)。如果用户未登录,则为 null
params 映射<字符串, 字符串> 包含请求的查询参数的映射。
path 路径 表示正在执行请求的路径的 path
resource 映射<字符串, 字符串> 新资源值,仅当执行 write 请求时存在。
time 时间戳 时间戳,表示对请求进行求值时的服务器时间。

资源求值

对规则进行求值时,您可能还需要对正在上传、下载、修改或删除的文件的元数据进行求值。这样一来,您就可以创建功能强大的复杂规则来执行任务,例如仅允许上传包含特定内容类型的文件,或仅允许删除超过特定大小的文件。

面向 Cloud Storage 的 Firebase 安全规则在 resource 对象中提供文件元数据,其中包含 Cloud Storage 对象中提供的元数据键值对。可以在 readwrite 请求中检查这些属性,以确保数据完整性。

write 请求(如上传、元数据更新和删除请求)中,除了包含请求路径下现有文件的文件元数据的 resource 对象外,您还可以使用 request.resource 对象,其中包含在允许写入时要写入的一部分文件元数据。您可以使用这两个值来确保数据完整性,或强制实施应用约束(如文件类型或大小)。

resource 对象中属性的完整列表如下:

属性 类型 说明
name 字符串 此对象的完整名称
bucket 字符串 此对象所在存储分区的名称。
generation 整数 此对象的 GCS 对象生成
metageneration 整数 此对象的 GCS 对象元生成
size 整数 此对象的大小(以字节为单位)。
timeCreated 时间戳 表示此对象的创建时间的时间戳。
updated 时间戳 表示此对象的最后更新时间的时间戳。
md5Hash 字符串 此对象的 MD5 哈希。
crc32c 字符串 此对象的 crc32c 哈希。
etag 字符串 与此对象相关联的 etag。
contentDisposition 字符串 与此对象相关联的内容处置。
contentEncoding 字符串 与此对象相关联的内容编码。
contentLanguage 字符串 与此对象相关联的内容语言。
contentType 字符串 与此对象相关联的内容类型。
metadata 映射<字符串, 字符串> 开发者指定的其他自定义元数据的键值对。

request.resource 包含上述除 generationmetagenerationetagtimeCreatedupdated 外的所有属性。

完整示例

综上,您可以为图片存储解决方案创建完整的示例规则:

service firebase.storage {
 match /b/{bucket}/o {
   match /images {
     // Cascade read to any image type at any path
     match /{allImages=**} {
       allow read;
     }

     // Allow write files to the path "images/*", subject to the constraints:
     // 1) File is less than 5MB
     // 2) Content type is an image
     // 3) Uploaded content type matches existing content type
     // 4) File name (stored in imageId wildcard variable) is less than 32 characters
     match /{imageId} {
       allow write: if request.resource.size < 5 * 1024 * 1024
                    && request.resource.contentType.matches('image/.*')
                    && request.resource.contentType == resource.contentType
                    && imageId.size() < 32
     }
   }
 }
}

现在,我们将转到用户安全性部分,了解如何集成 Firebase 身份验证,以便按用户设置精确的文件访问权限。

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面