# 存储管理

## 文件管理

[微信云托管-对象存储-存储管理](https://cloud.weixin.qq.com/cloudrun/storage)中管理所有存储文件内容，并可以查看上传后文件的详细信息。

![全局](https://res8.wxqcloud.qq.com.cn/wxdoc/5ea28cb4-07bc-482d-83fe-efb166b6fdef.png)

### 一、文件操作

存储在文件操作的具体动作描述如下：

1. 上传文件：支持同时上传多个文件；
2. 上传文件夹：可直接从文件管理器将要上传的文件夹拖入控制台即可上传，支持拖入多个文件 & 文件夹；
3. 新建文件夹：方便文件归类管理；
4. 删除：支持批量删除，勾选对应文件/文件夹，点击删除按钮即可；
5. 面包屑路径栏：面包屑显示当前文件位置，点击对应的面包屑位置显示对应文件夹下文件内容；

### 二、文件名命名限制

上传的文件命名限制如下，请注意规避：

- 不能为空
- 不能以 `/` 开头
- 不能出现连续 `/`
- 编码长度最大为 850 个字节
- 推荐使用大小写英文字母、数字，即 `[a-z，A-Z，0-9]` 和符号 `-`、`!`、`_`、`.`、`*` 及其组合
- 不支持 ASCII 控制字符中的字符上(`↑`)，字符下(`↓`)，字符右(`→`)，字符左(`←`)，分别对应 CAN(24)，EM(25)，SUB(26)，ESC(27)
- 如果用户上传的文件或文件夹的名字带有中文，在访问和请求这个文件或文件夹时，中文部分将按照 URL Encode 规则转化为百分号编码。
- 不建议使用的特殊字符: `^` `"` `\` `{` `}` `[` `]` `~` `%` `#` `\` `>` `<` 及 ASCII 128-255 十进制
- 可能需特殊处理后再使用的特殊字符`:` `，` `:` `;` `=` `&` `$` `@` `+` `?` `空格` 及 ASCII 字符范围：00-1F 十六进制（0-31 十进制）以及 7F（127 十进制）

### 三、查看文件详情

点击「文件名称」，右侧弹窗显示文件详情内容；

![](https://res8.wxqcloud.qq.com.cn/wxdoc/7834495d-d8c4-4d90-a228-d5178da2c5d1.png)

文件详情内容显示文件名称、文件大小、文件格式、ETag、上传者 OpenID、上传时间、存储位置、下载地址、FileID、预览图片等字段内容；

## 存储权限

对象存储可以对读写权限进行设置，开发者可以配置规则来适应存储安全性要求。

需要注意的是：

1. 权限设置仅对前端（小程序端/网页 SDK）访问生效，微信云托管控制台始终拥有所有读写权限。
2. 这里的限制是接口层面的，比如上传、下载、删除等接口遵循权限设置，直接通过控制台获取的 url 路径不受限制。

存储权限预设了一些基础的权限，可以满足常见的需求：

- **所有用户可读、仅文件创建者可写**：适用场景：用户头像、用户公开相册等
- **仅文件创建者可读写：适用场景**：私密相册、网盘文件等
- **所有用户可读（只有管理员可写）**：适用场景：文章配图、商品图片等
- **所有用户不可读（只有管理员可读写）**：适用场景：业务日志等

如果你对权限有更多灵活性的需求，可以使用安全规则方式设置，以下是 ”所有用户可读、仅文件创建者可写“ 的安全规则示例：

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

### 一、安全规则概述

存储安全规则用于确定哪些人对云存储桶中存储的文件拥有读取和写入权限，也可用于文件中包含的元数据校验。规则通过 `json` 来描述，允许在满足条件时允许 `read` 及 `write` 操作，当 `boolean` 或 表达式计算结果为 `true` 是则表示通过允许访问，否则拒绝访问，示例配置如下：

```ts
{
  "read": boolean | condition expression string,
}
```

`json` 配置的 `key`，是用户的**操作类型**，`value` 是一个表达式。当表达式执行结果的值是 `true` 的时候，用户的操作允许执行；否则，用户的操作则不被允许。

| 操作类型 | 说明                     | 默认值 |
| :------- | :----------------------- | :----- |
| read     | 读取文件，例如：download | false  |
| write    | 上传/覆盖文件，删除文件  | false  |

规则验证所依据的上下文通过 `auth`、`resource` 对象获得，其提供可验证身份的上下文信息（`auth.uid`）和对象所有权（`resource.openid`）等信息。

```json
{
  "read": "auth.uid == resource.openid",
  "write": "auth != null"
}
```

### 二、安全规则示例

> **注意**：发布之前，请务必评估你的规则，确保它们可以为你的应用提供所需的最高级别的安全性。如果发布应用时设置的是 `public` 规则，可能会导致你存储的数据遭到意外访问或未经授权的访问。若设置的是 `default` 规则，可能导致你的数据无法被管理员外的用户访问。

存储安全规则以存储桶为控制边界，默认规则下不允许任何非管理端的资源访问，未实现基础的权限控制，可以根据需求设置如下的安全规则：

#### 所有用户可读，仅所有者写

```js
{
  "read": true,
  "write": "resource.openid == auth.openid"
}
```

#### 仅所有者可读写

```js
{
  "read": "resource.openid == auth.openid"
  "write": "resource.openid == auth.openid"
}
```

#### 所有用户可读，仅管理者可写

```js
{
  "read": true,
  "write": false
}
```

#### 仅管理者可读写

```js
{
  "read": false,
  "write": false
}
```

### 三、校验说明

#### 1. 存储安全规则对所有文件的访问生效

#### 2. 身份校验

上传、下载、删除操作使用请求携带的 `auth` 身份校验状态进行求值。

| 变量名 | 类型          | 说明                                                   |
| :----- | :------------ | :----------------------------------------------------- |
| auth   | Auth(参见下面 Auth 对象) | 在用户登录后，提供 openid。如果用户未登录，则为 null。 |

Auth 对象

| 字段名 | 类型   | 说明                                |
| :----- | :----- | :---------------------------------- |
| openid | string | 用户 openid，仅在已登录方式下存在值 |

#### 3. 资源校验

对规则进行校验是，可能还需要对正在上传/下载/修改或删除的文件元数据进行校验，这样可以创建功能强大的复杂规则来执行任务，例如允许上传包含特定内容类型的文件。

存储安全规则通过 `resource` 对象提供文件元数据，可以在 `read`，`write` 时校验这些属性，确保正确的访问。

Resource 对象

| 属性   | 类型   | 说明                            |
| ------ | ------ | ------------------------------- |
| openid | string | 文件私有归属标识，标记所有者 id |

## 存储配置

在[微信云托管-对象存储-存储配置](https://cloud.weixin.qq.com/cloudrun/storage)中，包含 3 项信息：

![](https://res8.wxqcloud.qq.com.cn/wxdoc/1841b09c-53dc-473d-924c-1476e0aadaa1.png)

### 一、对象存储信息

- **对象存储桶**：在上传接口操作时会看到有关此存储桶的信息
- **对象存储地域**：默认上海地域

### 二、安全域名

通过配置安全域名白名单，对应的域名才能使用对象存储接口进行文件的上传或其他操作。

单击「添加安全域名」按钮，输入自己的业务域名来增加，增加后该域名即可使用对象存储接口而没有跨域或其他问题。

需要说明：

在一开始，微信云托管会为您自动生成 4 类默认安全域名：

- **localhost:8080**：本地安全域名方便开发者进行本地调试。
- **localhost:80**：本地安全域名方便开发者进行本地调试。
- ***.ap-shanghai.app.tcloudbase.com**：微信云托管公网访问域名。
- ***.tcb.qcloud.la**：对象存储域名。

### 三、缓存配置

可以针对文件的 CDN 回源时间进行管理，默认所有文件的回源时间为 2 分钟。

规则支持 `文件名` 、`文件类型` 和 `文件夹` 三种匹配方式。

支持三种配置方式：

1. 按文件类型设置缓存过期时间

   - 配置缓存时间时可填入多项，每项用 ; 隔开，内容区分大小写，必须是以 . 开头的文件后缀，例如 .png。
   - 刷新时间设置为 0 时，不缓存，所有请求转发至用户源站，缓存时间设置最大值不能超过 365 天。
   - 输入框默认提示：例如 .png，.jpg，.php。

2. 按文件夹设置缓存过期时间

   - 配置缓存时间时可填入多项，每项用 ; 隔开，内容区分大小写，必须是以 / 开头的文件夹。
   - 刷新时间设置为 0 时，不缓存，所有请求转发至用户源站，缓存时间设置最大值不能超过 365 天。

3. 按文件设置缓存过期时间

   - 配置缓存时间时可填入多项，每项用 ; 隔开，内容区分大小写，支持匹配某一类型文件，例如 /test/abc/`*.jpg`。
   - 单击保存，将进行配置部署，您需等待 5 分钟左右。

> **注意：**过短的缓存时间将大幅度消耗 CDN 流量，建议在开发时合理配置缓存时间。

#### 什么是缓存配置

对象存储内的文件默认 CDN 加速，开发者可以通过改变缓存配置来控制 CDN 遵循的过期规则。
合理地配置缓存时间，能够有效的提升命中率，降低回源率，节省您的流量资源消耗。
用户访问资源会首先去 CDN 节点请求，若节点有缓存则返回资源，无缓存则回源获取。

> 注意：

> 刷新时间设置为 0 时，不缓存，所有请求转发至用户源站；缓存时间设置最大值不能超过 365 天。

> 在控制台中上传文件/文件夹，会自动刷新节点内的缓存文件。

> 配置部署中，若您再次编辑缓存配置，会覆盖之前的配置。以最后一次部署结果为准。

#### 缓存策略优先级

配置项列表底部优先级高于顶部优先级。

当设置了多条缓存策略时，相互之间会有重复，假如某域名已配置如下缓存配置：

目标 | 缓存时长 |
--- | --- |
所有文件|2 分钟
.php .jsp .aspx| 0 秒
.jpg .png .gif|300 秒
/test/*.jpg|400 秒
/test/abc.jpg|200 秒

假设域名为 `cloud.weixin.qq.com` ，资源为 `cloud.weixin.qq.com/test/abc.jpg`，其匹配方式如下：

- 匹配第一条所有文件，命中，此时缓存时间为 2 分钟。
- 匹配第二条，未命中。
- 匹配第三条，命中，此时缓存时间为 300 秒。
- 匹配第四条，命中，此时缓存时间为 400 秒。
- 匹配第五条，命中，此时缓存时间为 200 秒。

- 因此最终缓存时间为 200 秒，以最后一次匹配生效。