流控策略（QoS policy）是一种管理对象存储访问流量资源的策略，支持按照用户需求管理多业务访问资源组的流控能力，保障多种业务在访问同一份存储资源情况下流量互不干扰，高效运行。 ## 适用场景 ### 阈值流控阈值流控支持按照账号、用户、角色等维度限制访问 TOS 资源组的流量，支持流控策略生效资源范围为 TOS 所有桶、指定桶或桶内指定对象等多种资源组合，实现多个业务隔离，确保不同业务之间的资源使用不会相互影响，适用于多租户、多部门、多产品使用 TOS 的场景。 ### 优先级流控在复杂的在线业务场景中，流量不仅需要隔离，更需要进行精细化的 QoS 分级管理。不同业务之间除了要防止恶性抢占外，还需满足并存的保底与抢占需求： * 核心业务保障：高优先级的核心业务（如在线交易、关键数据上传）必须得到充足的带宽保障，即使在系统总负载较高时，也不能因资源竞争而出现性能下降或“饿死”现象。 * 资源利用率最大化：在系统负载较低时，允许非核心业务（如离线分析、日志回传）临时“借用”空闲带宽，以提升整体资源利用率。当高优先级流量回升时，系统应能自动回收这部分“借用”的配额，确保核心业务不受影响。因此，优先级流控在阈值流控的基础上，引入多级优先级和保底配额设计。两种方案可互补使用，确保重要业务稳定运行，构建一个既能保障核心业务稳定、又能最大化资源利用率的 QoS 流控体系。 ## 生效规则 ### 阈值流控多层级限制同时生效时，实际配额取所有生效规则的最小值。例如请求同时匹配多个流控策略时，多个流控策略会同时生效；在此情况下，若多个流控策略存在相同类别的流控限制条件，按照配额最小的流控限制条件为准进行限流。 ### 优先级流控 * **保底配额** * 每个优先级都设置有保底配额，无论系统多繁忙，该优先级都能获得保底带宽或 QPS，确保核心业务稳定运行。 * 所有优先级的保底配额之和小于或等于资源总配额。 * **规则匹配** * 同一条流控策略配置中，优先级流控与阈值流控不能共存。 * 当一个请求同时满足多个优先级的条件时，系统将应用最高优先级的规则。例如，若请求同时匹配优先级 3 和优先级 2，则该请求被视为优先级 3。 * **配额抢占** * 高优先级可以抢占整体超出保底配额部分的配额，且更高优先级优先抢占。 * 低优先级也可以使用高优先级空闲的保底配额，但较高优先级优先使用。 ## 典型配置场景以下场景中流控策略总带宽为 100Gbps，优先级 1 到优先级 3。 **场景一：高优先级抢占低优先级超出保底的带宽** |**优先级** |**保底** |**需求** |**实际分配** |**说明** | |---|---|---|---|---| |优先级 3

|20Gbps

|80Gbps

|70Gbps

|获得保底 20Gbps + 抢占优先级 1 空闲的 10Gbps + 资源池剩余 40Gbps（扣除所有优先级保底）。 | |优先级 2 |20Gbps |30Gbps |20Gbps |获得保底 20Gbps，额外需求被优先级 3 抢占。 | |优先级 1 |20Gbps |10Gbps |10Gbps |按需分配 10Gbps，空闲保底 10Gbps 被优先级 3 抢占。 | **场景二：更高优先级优先抢占** |**优先级** |**保底** |**需求** |**实际分配** |**说明** | |---|---|---|---|---| |优先级 3 |25Gbps |60Gbps |60Gbps |获得保底 25Gbps + 高优先级抢占 35Gbps。 | |优先级 2 |25Gbps |40Gbps |35Gbps |获得保底 25Gbps + 次优先抢占剩余的 10Gbps。 | |优先级 1 |25Gbps |5Gbps |5Gbps |需求小于保底，按需分配 5Gbps。 | **场景三：保底之和小于总带宽** |**优先级** |**保底** |**需求** |**实际分配** |**说明** | |---|---|---|---|---| |优先级 3 |10Gbps |30Gbps |30Gbps |最高优先级，需求全满足。 | |优先级2 |10Gbps |50Gbps |50Gbps |次高优先级，需求全满足。 | |优先级 1 |10Gbps |50Gbps |20Gbps |获得保底 10Gbps + 剩余 10Gbps。 | ## 参数说明 Statement 是主要策略元素的容器，可以在一个策略中包含多个语句，每个 Statement 包含以下参数。 |参数 |是否必选 |说明 |示例 | |---|---|---|---| |Sid |可选 |策略名称，限制如下：

* 策略名称不能重复。

* 只能包含大小写字母、数字、中划线（\-）、下划线（_）、英文句号（.）、英文冒号（:）、百分号（%）。

* 长度限制在 1～255 字符之间。

如果不填，则 TOS 会自动生成策略名称。 |```Plain```
```{"Sid":"Test"}```
| |Quota |必填 |设置流控类别，取值说明如下：

* `WritesQps`：写请求的 QPS，取值为正整数。

* `ReadsQps`：读请求的 QPS，取值为正整数。

* `ListQps`：List 请求的 QPS，取值为正整数。

* `WritesRate`：上传带宽，单位为 Mbps，取值为正整数。

* `ReadsRate`：下载带宽，单位为 Mbps，取值为正整数。

* `FetchQps`：同步 FetchQPS，取值为正整数。

* `FetchRate`：同步 Fetch 带宽，单位为 Mbps,取值为正整数。

* `AsyncFetchQps`：异步 FetchQPS，取值为正整数。

* `AsyncFetchRate`：异步 Fetch 带宽，单位为 Mbps，取值为正整数。 |```Plain```
```"Quota": {```
``` "WritesQps": "100",```
``` "ReadsQps": "100",```
``` "ListQps": "100",```
``` "WritesRate": "10",```
``` "ReadsRate": "10",```
``` "FetchQps": "100",```
``` "FetchRate": "10",```
``` "AsyncFetchQps": "100",```
``` "AsyncFetchRate": "10"```
```}```
| |Priority |可选

说明

流控策略为优先级流控时，此参数为必选。

|流控策略优先级，定义了不同流量在资源竞争中的优先顺序，高优先级可抢占低优先级的资源。 |```Plain Text```
```"Priority": [```
``` {```
``` "PriorityLevel": 2,```
``` "GuaranteedQuota": {```
``` "WritesRate": "1000"```
``` },```
``` "Principal": [```
``` "trn:iam::200000:user/core-service"```
``` ],```
``` "Resource": "trn:tos:::critical-bucket2/*"```
``` },```
``` {```
``` "PriorityLevel": 1,```
``` "GuaranteedQuota": {```
``` "WritesRate": "1000"```
``` },```
``` "Principal": [```
``` "trn:iam::200000:user/core-service"```
``` ],```
``` "Resource": "trn:tos:::critical-bucket1/*"```
``` }```
``` ]```

| |PriorityLevel |可选

说明

流控策略为优先级流控时，此参数为必选。

|流控策略优先层级，取值规则如下：

* 取值为自然数，从数字 1 开始，需要连续且不能重复，例如支持 1/2、1/2/3，不支持 1/3。

* 至少配置 2 个优先层级，最多支持 3 个。优先层级数字越大，优先级越高。 |```Plain Text```
```{"PriorityLevel": 3}```

| |GuaranteedQuota |可选

说明

流控策略为优先级流控时，此参数为必选。

|保底配额，即为特定优先级预留的最小资源量，即使在系统满负荷时也能确保获得。取值同参数 `Quota`。

各个优先级都必须配置保底配额且必须大于 0，即每增加一个优先级，都需要给这个优先级增加保底配额。所有优先级的保底配额之和必须小于或等于总配额。 |```Plain Text```
```"GuaranteedQuota": {```
``` "WritesRate": "3000"```
```}```

| |Resource |可选

说明

设置流控策略时，您必须在 Resource 和 NotResource 参数中选择其一，用于指定流控作用的资源。

|设置流控策略作用的资源。

* 以字符串形式表示，不区分大小写，格式为 `"Resource": ["trn:tos:::{BucketName}/{Object}"]`。

* 支持通配符 `*`，说明如下：

* 将通配符 `*`设置在桶上，表示所有桶，例如 `"trn:tos:::*"`。

* 将通配符 `*`设置在对象上，表示桶内所有资源，例如`"trn:tos:::bucketname/*"`。

* 将通配符设置在对象前缀上，表示该前缀的所有对象，例如 `"trn:tos:::bucketname/objectPrefix*"`。 |```Plain```
```"Resource":[```
``` // 流控策略作用于所有桶。```
``` "trn:tos:::*",```
``` // 流控策略作用于 bucketname 桶下的所有对象。```
``` "trn:tos:::bucketname/*",```
``` // 流控策略作用于 bucketname 桶下前缀为 objectPrefix 的对象。```
``` "trn:tos:::bucketname/objectPrefix*"```
```]```
| |NotResource |可选

说明

设置流控策略时，您必须在 Resource 和 NotResource 参数中选择其一，用于指定流控作用的资源。

|设置不受流控所约束的资源。

* 以字符串形式表示，不区分大小写，格式为 `"NotResource": ["trn:tos:::{BucketName}/{Object}"]`。

* 支持通配符 `*`，说明如下：

* 将通配符 `*`设置在对象上，表示桶内所有资源，例如`"trn:tos:::bucketname/*"`。

* 将通配符设置在对象前缀上，表示该前缀的所有对象，例如 `"trn:tos:::bucketname/objectPrefix*"`。

说明

NotResource 不支持将通配符 *设置在桶上，表示所有桶，例如 "NotResource":["trn:tos:::*"]。

|```Plain```
```"NotResource":[```
``` // 流控策略作用于除 bucketname 桶以外的其他桶。```
``` "trn:tos:::bucketname/*",```
``` // 流控策略作用于除 bucketname 桶下前缀为 objectPrefix 的对象以外的其他对象。```
``` "trn:tos:::bucketname/objectPrefix*"```
```]```
| |Principal |可选

说明

设置流控策略时，您必须在 Principal 和 NotPrincipal 参数中选择其一，用于指定流控作用的账号。

|指定需要进行流控的账号、IAM 用户或角色。 |```Plain```
```"Principal": [```
``` // 对 200000**** 下的 tos_role 角色进行流控```
``` "trn:iam::200000****:role/tos_role",```
``` // 对 200000**** 下的 tos_user 用户进行流控```
``` "trn:iam::200000****:user/tos_user",```
``` // 对 200001**** 主账号进行流控。```
``` "trn:iam::200001****:root"```
``` // 对所有用户进行流控```
``` "*"```
``` ]```
| |NotPrincipal |可选

说明

设置流控策略时，您必须在 Principal 和 NotPrincipal 参数中选择其一，用于指定流控作用的账号。

|指定不受流控约束的账号、IAM 用户或角色。

说明

NotPrincipal 不支持单独使用 *，即不支持使用 "NotPrincipal": ["*"]。

|```Plain```
``` "NotPrincipal": [```
``` // 对 200000**** 下的 tos_role 角色不进行流控，流控除 200000**** 下的 tos_role 角色以外的角色。```
``` "trn:iam::200000****:role/tos_role",```
``` // 对 200000**** 下的 tos_user 用户不进行流控，流控除 200000**** 下的 tos_user 用户以外的用户。```
``` "trn:iam::200000****:user/tos_user",```
``` // 对 200001**** 主账号不进行流控，流控除 200001**** 以外的账号。```
``` "trn:iam::200001****:root"```
``` ]```
| |Condition |可选 |指定流控策略在哪些情况下生效。关于条件的详细说明，请参见[条件说明](https://www.volcengine.com/docs/6349/1346387#aNd3FkmH)。 |```Plain```
```"Condition": {```
``` "IpAddress": {```
``` "SourceIp": [```
``` "192.168.0.1",```
``` "192.168.0.3"```
``` ]```
``` }```
```}```
| ## 条件说明条件决定流控策略生效的要求，只有请求信息满足条件时，流控策略才会生效。条件由条件键、条件运算符及值组成。流控策略支持的条件如下。 ### 支持的条件 |**键** |**类型** |**键说明** |**值说明** | |---|---|---|---| |CurrentTime |Date |服务器接收请求的时间，UTC 时间，格式必须为 ISO 8601，基本格式为 yyyy\-MM\-ddTHH:mmZ（UTC 时间）。 |输入 ISO 8601 格式的日期。

例如设置条件为 `CurrentTime 大于 2023-10-13T15:00:00Z`，则被授予流控策略的账号执行相应动作时，请求时间必须大于 2023\-10\-13T15:00:00Z，否则流控策略不会生效。 | |EpochTime |Numeric |自 1970 年 1 月 1 日（UTC/GMT 午夜）来经过的秒数，不包括闰秒。 |输入秒数。

例如设置条件为 `EpochTime 大于 1697187692`，则被授予流控策略的账号执行相应动作时，请求时间必须大于 1697187692，否则流控策略不会生效。 | |SourceIp |String |请求发起的源 IP。 |输入 IP 地址或者 IP 段，如有多个 IP 请以英文逗号分隔。

例如设置条件为 `SourceIp 等于 192.168.0.1`，则被授予流控策略的账号执行相应动作时，请求发起的源 IP 必须为 192.168.0.1，否则流控策略不会生效。 | |SourceVpc |String |请求所在的 VPC。 |输入 VPC ID。

例如设置条件为 `SourceVpc 等于 vpc-2d****ez0n`，则被授予流控策略的账号执行相应动作时，请求所在的 VPC 必须是 `vpc-2d****ez0n`，否则流控策略不会生效。 | |UserAgent |String |请求的客户端代理程序。 |输入 Agent 详细信息和通配符（\*）。

例如设置条件为 `UserAgent 等于 tos go sdk v2.6.0`，则被授予流控策略的账号执行相应动作时，请求的客户端代理程序必须为 tos go sdk v2.6.0，否则流控策略不会生效。 | |Referer |String |请求发起的链接。 |输入 URL。

例如设置条件为 `Referer 等于 http://console.volcengine.com`，则被授予流控策略的账号执行相应动作时，请求头必须为 `http://console.volcengine.com`，否则流控策略不会生效。 | |Host |String |请求访问的域名。 |输入访问域名。

例如设置条件为 `Host 等于 bucktename.tos-cn-beijing.volces.com`，则被授予流控策略的账号执行相应动作时，请求访问的域名必须为 `bucktename.tos-cn-beijing.volces.com`，否则流控策略不会生效。 | |NetPlane |String |请求来源的网络平面。 |仅支持配置 `public`，表示请求来源为公网。

例如设置条件为 `NetPlane 等于 public`，则被授予流控策略的账号执行相应动作时，请求来源必须为公网，否则流控策略不会生效。 | |ProjectName |String |请求资源归属的项目。 |输入资源归属的项目。

例如输入项目等于 `test`，则被授予流控策略的账号执行相应动作时，访问的资源必须归属于 `test`，否则流控策略不会生效。 | |DataAccessPointTrn |String |请求为指定接入点设置流控策略。 |输入接入点 `TRN`。

例如设置条件为 `DataAccessPointTrn 等于`

`trn:tos:cn-beijing:214748****:accesspoint/bbb`，表示通过`trn:tos:cn-beijing:214748****:accesspoint/bbb` 接入点访问桶内资源时，流控策略才会生效。

说明

仅为接入点设置流控策略时，才需要使用 DataAccessPointTrn 条件。

说明

仅为接入点设置流控策略时，才需要使用 DataAccessPointAccount 条件。

| |AccessPointNetworkOrigin |String |请求为指定网络来源的所有接入点设置流控策略。 |输入 VPC 或 Internet，取值说明如下：

* VPC：为所有网络来源为 **VPC** 的接入点设置流控策略。

* Internet：为所有网络来源为**互联网**的接入点设置流控策略。

例如设置 `AccessPointNetworkOrigin 等于 VPC`，表示网络来源为 **VPC** 的接入点访问桶内资源时，流控策略才会生效。

说明

仅为接入点设置流控策略时，才需要使用 AccessPointNetworkOrigin 条件。

| ### 运算符说明流控策略中不同的条件对应了不同的运算符，详细说明如下所示。 |**适用条件** |**运算符说明** | |---|---| |* UserAgent

* Referer

* SourceVPC

* Host

* ProjectName

* DataAccessPointTrn

* DataAccessPointAccount

* AccessPointNetworkOrigin |* **等于**：与设置的条件值完全匹配。

* **不等于**：与设置的条件值不匹配。

* **等于（不区分大小写**）：忽略大小写后，与设置的条件值完全匹配。

* **不等于（不区分大小写）** ：忽略大小写后，与设置的条件值不完全匹配。

* **Like**：支持通配符（\*）的正则匹配，例如 `like abc*`，就是以 `abc` 开头的所有字符，区分大小写。

* **Not Like**：支持通配符（\*）的正则匹配，例如 `Not like abc*`，就是除以 `abc` 开头的所有字符，区分大小写。 | |* CurrentTime

* EpochTime |* **等于**：与设置的条件值相等。

* **不等于**：与设置的条件值不相等。

* **小于**：小于设置的条件值。

* **小于等于**：小于等于设置的条件值。

* **大于**：大于设置的条件值。

* **大于等于**：大于等于设置的条件值。 | |* SourceIp

* NetPlane |* **等于**：与设置的条件值相等。

* **不等于**：与设置的条件值不相等。 | ## 配置方法流控策略支持两种配置方式，您可以参考以下内容，选择合适的配置方式： * [使用可视化视图创建流控策略](https://www.volcengine.com/docs/6349/1364438#a5380bf5) * [使用 JSON 视图创建流控策略](https://www.volcengine.com/docs/6349/1364438#94ae834d)