---
title: "ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST - OceanBase 数据库 V4.5.0 | OceanBase 文档中心"
description: ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST 描述 该语句用于变更本租户备份或归档路径的源端配置（ zone 、 idc 或 region 配置）、I/O 限流参数（ max_iops 和 max_bandwidth ）以及 access_id 和 access_key 等密钥信…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.5.0

# ALTER/CHANGE/MODIFY EXTERNAL_STORAGE_DEST

更新时间：2026-03-18 09:13:16

[编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.5.0/zh-CN/700.reference/500.sql-reference/100.sql-syntax/200.common-tenant-of-mysql-mode/600.sql-statement-of-mysql-mode/1430.alter-system-change-external-storage-dest-of-mysql-mode.md)  

## 描述

该语句用于变更本租户备份或归档路径的源端配置（`zone`、`idc` 或 `region` 配置）、I/O 限流参数（`max_iops` 和 `max_bandwidth`）以及 `access_id` 和 `access_key` 等密钥信息。修改后，新的配置信息将会覆盖原来的配置信息。

## 使用限制及注意事项

- 仅用户租户可以执行该语句，系统租户（sys 租户）不能执行该语句。
 - 修改路径的 `zone`、`idc` 或 `region` 配置前，如果需要设置 Region 层级或 IDC 层级，需要先通过 `ALTER SYSTEM MODIFY ZONE zone_name SET REGION=region_name;` 或 `ALTER SYSTEM MODIFY ZONE zone_name SET IDC=idc_name;` 语句分别设置 Region 信息或 IDC 信息。推荐设置 IDC 层级的源端配置，利用有较多网络带宽资源的 IDC 来执行备份任务的同时，备份任务有更多的可选节点范围，同时用户也不需要关注集群中 IDC 内 Zone 的变化情况。
 - 修改备份路径的源端配置时，如果有备份任务正在执行，由于正在执行的任务至多需要分钟级时间才能感知到配置的变化，故在配置修改期间，仍可能会有配置范围外的节点访问备份路径，导致产生跨机房或跨地域的流量。
 - 仅对象存储路径支持变更 I/O 限流参数（`max_iops` 和 `max_bandwidth`） 以及 `access_id` 和 `access_key` 信息。如果备份介质为 NFS 的路径设置 I/O 限流参数（`max_iops` 和 `max_bandwidth`）或者 `access_id`、`access_key` 信息，系统会返回不支持的错误，错误码为 `1235`。
 - 为对象存储路径设置 `ACCESS_INFO` 属性（`access_id` 和 `access_key` 信息）时，如果参数的格式不正确（例如，有多余的 `=`、缺少 `access_id` 或 `access_key`），系统会报错 `OB_OBJECT_STORAGE_PERMISSION_DENIED`（错误码为 `-9116`）。
 - 备份路径或归档路径使用 Assume Role 方式访问对象路径时：

     - 如果设置 `ACCESS_INFO = 'access_id=new_access_id&access_key=new_access_key'`，系统会报错。
     - 如果仅设置 `ATTRIBUTE` 中的 I/O 限流参数（不设置 `ACCESS_INFO` 属性），系统可能提示不支持或者设置后不生效。
 - 允许为同一路径多次设置相同的 `ATTRIBUTE` + `ACCESS_INFO` 属性。

## 权限要求

执行该语句的用户需要拥有 `ALTER SYSTEM` 权限。有关 OceanBase 数据库权限的详细介绍，参见 [MySQL 模式下的权限分类](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004479241)。

## 语法

```sql
ALTER SYSTEM {ALTER|CHANGE|MODIFY} EXTERNAL_STORAGE_DEST
  PATH [=] 'path'
  SET [ATTRIBUTE = '[{zone=zone_name | idc=idc_name | region=region_name}][&max_iops=iops_num][&max_bandwidth=bandwidth_num]']
  [ACCESS_INFO = 'access_id=new_access_id&access_key=new_access_key'];

```

## 参数说明

| 参数 | 描述 |
| --- | --- |
| path | 指定待变更密钥信息的备份路径或归档路径。要求路径必须为当前租户已经设置的备份路径或归档路径，且必须为对象存储路径，同时路径中需要包含 `host` 信息。以 OSS 为例，该路径的格式如下：`oss://oceanbase-test-bucket/backup/databackup?host=***`。 |
| zone=zone_name \| idc=idc_name \| region=region_name | 指定当前备份路径或归档路径的源端。支持选择 `zone`、`idc` 或 `region` 三个不同层级的配置，只能同时选择一个层级或者不设置。如果不显式指定，则默认不设置。  修改归档路径的源端配置时：    - 由于日志归档的所有流量均由 Leader 副本写入，故对日志归档路径来说，没有访问优先级的差异，只是限制访问归档路径的节点范围。如果需要设置多个 Zone、多个 IDC 或多个 Region，多个值之间使用英文逗号（,）或英文分号（;）分隔。例如，`zone=z1,z2;z3` 表示指定 `z1`、`z2`、`z3` 为归档路径的源端。 - 修改 `zone`、`idc` 或 `region` 时，要求 Leader 副本在指定的 `zone`、`idc` 或 `region` 中，否则，日志归档将会无法推进。    修改备份路径的源端配置时：    - 如果需要设置多个 Zone、多个 IDC 或多个 Region，多个 Zone/IDC/Region 之间使用英文逗号（,）和英文分号（;）分隔。其中：      - 英文逗号（,）表示在选择执行备份任务节点时，左右两边的 Zone/IDC/Region 内的节点具有相同的优先级。     - 英文分号（;）表示左边 Zone/IDC/Region 内的节点优先级比右边的高，即优先选择左边的 Zone/IDC/Region 内的节点执行备份任务。例如，如果设置为 `zone=z1,z2;z3` 表示指定 `z1`、`z2`、`z3` 作为备份的源端，`z1`、`z2` 在同一优先级，且 `z1`、`z2` 的优先级高于 `z3`。 - 修改备份路径的 `zone`、`idc` 或 `region` 配置时，要求 Root Service 的 Leader 节点在指定的 `zone`、`idc` 或 `region` 中，否则，备份任务将无法成功向目标备份路径写入备份元数据，最终导致备份任务执行失败。建议备份路径源端设置包含 Primary Zone 范围。 |
| max_iops | 指定当前备份路径或归档路径允许使用的最大 IOPS。取值为正整数，表示每秒约多少次 I/O 请求。未显式设置时，表示该路径不限制 IOPS，由底层对象存储及网络能力决定。  示例：`max_iops=1000` |
| max_bandwidth | 指定当前备份路径或归档路径允许使用的最大带宽。取值为含单位的正整数。支持的单位为 kb、mb、gb，分别表示 KB/s、MB/s、GB/s。未显式设置时，表示该路径不限制带宽。  示例：`max_bandwidth=1000mb` |
| access_id=new_access_id&access_key=new_access_key | 指定变更后的新的 `access_id` 和 `access_key` 信息。`access_id` 与 `access_key` 需要同时填写。 |

## 示例

### 修改归档路径的源端配置

假设归档路劲原来的源端配置为 `zone=z1,z2,z3`，现在需要将源端配置更改为 `region=region1`。修改后，仅 `region1` 中的节点可以访问该路径。

- OSS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'region=region1';

  ```
 - NFS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='file:///data/nfs/backup/archive' SET ATTRIBUTE = 'region=region1';

  ```
 - S3

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'region=region1';

  ```
 - 兼容 S3 协议的对象存储（OBS/GCS/COS）

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'region=region1';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ATTRIBUTE = 'region=region1';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'region=region1';

  ```

### 修改备份路径的源端配置

假设备份路径原来的源端配置为 `zone=z1,z2;z3`，现在需要将源端配置更改为 `idc=idc1;idc2`。修改后，`idc1`、`idc2` 中的节点可以访问该路径，且`idc1` 的优先级高于 `idc2`。

- OSS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'idc=idc1;idc2';

  ```
 - NFS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='file:///data/nfs/backup/data' SET ATTRIBUTE = 'idc=idc1;idc2';

  ```
 - S3

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'idc=idc1;idc2';

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'idc=idc1;idc2';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ATTRIBUTE = 'idc=idc1;idc2';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'idc=idc1;idc2';

  ```

### 变更归档路径的 `access_id` 和 `access_key` 信息

- OSS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```
 - S3

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=cos.ap-xxxx.myqcloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```

### 变更备份路径的 `access_id` 和 `access_key` 信息

- OSS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```
 - S3

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ACCESS_INFO = 'access_id=******&access_key=******';

  ```

### 设置归档路径的 I/O 限流参数（`max_iops` 和 `max_bandwidth`）

可以同时设置 `max_iops` 和 `max_bandwidth` 参数，也可以单独设置 `max_iops` 或 `max_bandwidth` 参数。仅对象存储路径支持设置，NFS 路径不支持设置 I/O 限流参数。

- OSS

  同时设置 `max_iops` 和 `max_bandwidth` 参数，示例如下。

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

  单独设置 `max_iops`，示例如下。

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000';

  ```

  单独设置 `max_bandwidth`，示例如下。

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/archive?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_bandwidth=1000mb';

  ```
 - S3

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=https://storage.googleapis.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/archive?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

### 设置备份路径的 I/O 限流参数（`max_iops` 和 `max_bandwidth`）

#### 说明

I/O 限流参数设置建议：

- 对于高并发、带宽敏感的多租户环境，可以为不同的备份路径设置不同的 `max_iops` 或 `max_bandwidth` 参数值，用于隔离备份对线上业务带宽和 IOPS 的影响。
 - 建议结合实际网络带宽和对象存储的限速策略，先从较低值开始，逐步调整。例如，先从设置为 `max_iops=500&max_bandwidth=100mb` 开始观察，再根据备份耗时与业务峰值进行微调。

- OSS

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_iops=1000';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='oss://oceanbase-test-bucket/backup/data?host=****.aliyun-inc.com' SET ATTRIBUTE = 'max_bandwidth=1000mb';

  ```
 - S3

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=s3.<region>.amazonaws.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM CHANGE EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=obs.****.myhuaweicloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM ALTER EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test-bucket/backup/data?host=https://storage.googleapis.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

  ```shell
  obclient(root@mysql001)[(none)]> ALTER SYSTEM MODIFY EXTERNAL_STORAGE_DEST PATH='s3://oceanbase-test/backup/data?host=cos.ap-xxxx.myqcloud.com' SET ATTRIBUTE = 'max_iops=1000&max_bandwidth=1000mb';

  ```

## 相关文档

- [修改备份路径的源端配置](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004475969)
 - [备份路径和归档路径源端配置案例](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004475592)
 - [更新对象存储的密钥信息](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000004475586)

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线