重定位存储桶
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。

本页面介绍将存储桶从一个位置重定位到另一个位置的过程。如需了解存储桶重定位，请参阅存储桶重定位。

准备工作

在启动存储桶重定位流程之前，请完成以下步骤：

启用管理中心。
启用软删除。
检查配额和限制，确保新位置有足够的配额来容纳存储桶的数据。
确定存储桶重定位类型，以了解是否需要写入停止时间。
移除所有现有的存储桶标记。
如果您使用资产清单报告，请保存配置。

所需的角色

如需获得将某个位置的存储桶重定位到另一个位置的权限，请让您的管理员为您授予项目的 Storage Admin (roles/storage.admin) 角色。

此角色提供可让您将存储桶从一个位置重定位到另一个位置的一组权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

经过身份验证的用户必须拥有存储桶的以下 IAM 权限，才能使用此方法：

storage.buckets.relocate
storage.bucketOperations.get
您需要此权限才能查看存储桶重定位操作的状态。
storage.bucketOperations.list
您需要此权限才能查看存储桶重定位操作列表。
storage.bucketOperations.cancel
您需要此权限才能取消存储桶重定位操作。

经过身份验证的用户可能还需要拥有存储桶的以下权限，才能使用此方法：

storage.bucket.get
您需要此权限才能在存储桶重定位操作的试运行和增量数据复制期间查看存储桶的元数据。
storage.objects.list 和 storage.objects.get
您需要这些权限才能查看要重定位到其他位置的存储桶中的对象列表。

您也可以通过自定义角色来获取这些权限，或者您也许能够通过其他预定义角色来获取这些权限。如需查看哪些角色与哪些权限相关联，请参阅适用于 Cloud Storage 的 IAM 角色。

如需了解如何授予项目角色，请参阅管理对项目的访问权限。

重定位存储桶

本部分介绍使用存储桶重定位将 Cloud Storage 存储桶从一个位置重定位到另一个位置的过程。在重定位存储桶时，您需要启动并监控增量数据复制过程，然后启动最终同步步骤。如需详细了解这些步骤，请参阅了解存储桶重定位过程。

执行试运行

为尽可能减少存储桶重定位过程中的潜在问题，我们建议您执行试运行。试运行可模拟存储桶重定位过程（但不会实际移动数据），帮助您提前发现和解决问题。试运行会检查以下不兼容情况：

虽然试运行无法找出所有可能的问题，因为某些问题可能仅在实时迁移期间才会出现（由于实时资源可用性等因素），但它可以降低在真正的重定位期间遇到非常耗时的问题的风险。

命令行

模拟存储桶重定位的试运行：

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION --dry-run

其中：

BUCKET_NAME 是要重定位的存储桶的名称。
LOCATION 是存储桶的目标位置。

启动试运行会启动一项长时间运行的操作。您会收到操作 ID 和操作说明。如需跟踪试运行的完成情况，您需要跟踪其进度。如需了解如何跟踪试运行的进度，请参阅获取长时间运行的操作的详细信息。

如果试运行暴露了任何问题，请先解决这些问题，然后再继续执行启动增量数据复制步骤。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

创建一个包含存储桶设置的 JSON 文件，其中必须包含 destinationLocation 和 validateOnly 参数。如需查看完整的设置列表，请参阅 Buckets: relocate 文档。以下是一些常用的设置，包括：
```
{
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "true"
}
```
其中：
- DESTINATION_LOCATION 是存储桶的目标位置。
- LOCATIONS 是用于可配置的双区域的位置代码列表。
- 将 validateOnly 设置为 true 以执行试运行。

使用 cURL 调用 JSON API：

curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

其中：

JSON_FILE_NAME 是您创建的 JSON 文件的名称。
BUCKET_NAME 是要重定位的存储桶的名称。

启动增量数据复制

命令行

启动存储桶重定位操作：

gcloud storage buckets relocate gs://BUCKET_NAME --location=LOCATION

其中：

BUCKET_NAME 是要重定位的存储桶的名称。
LOCATION 是存储桶的目标位置。

注意：创建可配置的双区域时，您必须将 --location 标志设置为与底层区域关联的位置代码，并且必须将 --placement 标志与有效的区域对结合使用。例如 --location=US --placement=US-CENTRAL1,US-EAST1

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

创建一个包含存储桶设置的 JSON 文件。如需查看完整的设置列表，请参阅 Buckets: relocate 文档。以下是一些常用的设置，包括：
```
{
  "destinationLocation": "DESTINATION_LOCATION",
  "destinationCustomPlacementConfig": {
      "dataLocations": [
        LOCATIONS,
        ...
        ]
    },
  "validateOnly": "false"
}
```
其中：
- DESTINATION_LOCATION 是存储桶的目标位置。
- LOCATIONS 是用于可配置的双区域的位置代码列表。
- 将 validateOnly 设置为 false，以启动存储桶重定位的增量数据复制步骤。

使用 cURL 调用 JSON API：

curl -X POST --data-binary @JSON_FILE_NAME \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 "https://storage.googleapis.com/storage/v1/b/bucket=BUCKET_NAME/relocate"

其中：

JSON_FILE_NAME 是您创建的 JSON 文件的名称。
BUCKET_NAME 是要重定位的存储桶的名称。

监控增量数据复制

存储桶重定位过程是一项长时间运行的操作，如需了解其进度，必须对其进行监控。您可以定期检查长时间运行的操作列表，了解增量数据复制步骤的状态。如需了解如何获取长时间运行的操作的详细信息、列出或取消长时间运行的操作，请参阅在 Cloud Storage 中使用长时间运行的操作。

以下示例展示了增量数据复制操作生成的输出：

done: false
kind: storage#operation
metadata:
'@type': type.googleapis.com/google.storage.control.v2.RelocateBucketMetadata
commonMetadata:
  createTime: '2024-10-21T04:26:59.666Z
  endTime: '2024-12-29T23:39:53.340Z'
  progressPercent: 99
  requestedCancellation: false
  type: relocate-bucket
  updateTime: '2024-10-21T04:27:03.2892'
destinationLocation: US-CENTRAL1
finalizationState: 'READY'
progress:
  byteProgressPercent: 100
  discoveredBytes: 200
  remainingBytes: 0
  discoveredObjectCount: 10
  remainingObjectCount: 8
  objectProgressPercent: 100
  discoveredSyncCount: 8
  remainingSyncCount: 0
  syncProgressPercent: 100
relocationState: SYNCING
sourceLocation: US
validateOnly: false
writeDowntimeExpireTime: '2024-12-30T10:34:01.786Z'
name: projects//buckets/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w
response:
  '@type': type.googleapis.com/google.storage.control.v2.RelocateBucketResponse
  selfLink: https://storage.googleusercontent.com/storage/v1_ds/b/my-bucket1/operations/Bar7-1b0khdew@nhenUQRTF_R-Kk4dQ5V1f8fzezkFcPh3XMvlTqJ6xhnqJ1h_QXFIeAirrEqkjgu4zPKSRD6WSSG5UGXil6w

下表介绍了增量数据复制操作生成的输出中的关键字段：

字段名称	说明	可能的值
`done`	表示存储桶重定位操作已完成。	`false`、`true`
`kind`	表示此资源代表存储操作。
`metadata`	提供操作的相关信息。
`metadata.@type`	表示操作类型为存储桶重定位。
`metadata.commonMetadata`	所有操作通用的元数据。
`metadata.commonMetadata.createTime`	长时间运行的操作的创建时间。
`metadata.commonMetadata.endTime`	长时间运行的操作的结束时间。
`metadata.commonMetadata.progressPercent`	长时间运行的操作的估算进度，用百分比表示。	`0` 到 `100`%。值为 `-1` 表示进度未知或不适用。
`metadata.commonMetadata.requestedCancellation`	指示用户是否已请求取消长时间运行的操作。	`false`、`true`
`metadata.commonMetadata.type`	指示长时间运行的操作的类型。
`metadata.commonMetadata.updateTime`	上次更新长时间运行的操作的时间。
`metadata.destinationLocation`	存储桶的目标位置。
`metadata.finalizationState`	指示是否已准备好启动最终同步步骤。	`READY`：表示您可以启动最终同步步骤。但是，我们建议您等到 `progressPercent` 字段的值达到 `99`。 `WAITING_ON_SYNC`：表示您不能启动最终同步步骤。 `NOT_REQUIRED`：表示此存储桶不需要最终同步步骤，可以跳过此步骤。 `BLOCKED_ON_ERRORS`：表示最终同步步骤由于错误而暂时停止。您需要先解决错误，然后才能继续执行此步骤。 `RUNNING`：表示最终同步步骤正在进行。 `FINALIZED`：表示最终同步步骤已成功完成。
`metadata.progress`	重定位操作的进度详情。
`metadata.progress.byteProgressPercent`	已复制字节的进度，用百分比表示。	`0` 到 `100`%。值为 `-1` 表示进度未知或不适用。
`metadata.progress.discoveredBytes`	在源存储桶中发现的字节数。
`metadata.progress.discoveredObjectCount`	在源存储桶中发现的对象数量。
`metadata.progress.discoveredSyncCount`	在源存储桶中发现的对象元数据更新的数量。
`metadata.progress.objectProgressPercent`	已复制对象的进度，用百分比表示。	`0` 到 `100`%。值为 `-1` 表示进度未知或不适用。
`metadata.progress.remainingBytes`	要从源存储桶复制到目标存储桶的剩余字节数。
`metadata.progress.remainingObjectCount`	要从源存储桶复制到目标存储桶的剩余对象数量。
`metadata.progress.remainingSyncCount`	要同步的剩余对象元数据更新的数量。
`metadata.progress.syncProgressPercent`	对象元数据更新的同步进度，用百分比表示。	`0` 到 `100`%。值为 `-1` 表示进度未知或不适用。
`metadata.relocationState`	存储桶重定位的整体状态	`SYNCING`：表示增量数据复制步骤正在将对象从源存储桶复制到目标存储桶。 `FINALIZING`：表示已启动最终同步步骤。 `FAILED`：表示增量数据复制步骤遇到错误，未成功完成。 `SUCCEEDED`：表示增量数据复制步骤已成功完成。 `CANCELLED`：表示增量数据复制步骤已取消。
`metadata.sourceLocation`	存储桶的来源位置。
`metadata.validateOnly`	指示是否已启动存储桶重定位的试运行。	`false`、`true`
`metadata.writeDowntimeExpireTime`	写入停止的到期时间。
`name`	此重定位操作的唯一标识符。格式：`projects/_/buckets/bucket-name/operations/operation-id`
`response`	操作的响应。
`response.@type`	响应的类型。
`selfLink`	此操作的链接。

注意：metadata.commonMetadata.progressPercent 显示长时间运行的操作的总体完成情况。当所有步骤完成后，该值会达到 100%。这是唯一可靠的完全成功指标。其他进度指标显示字节、对象和元数据的迁移情况。这些指标可能比 metadata.commonMetadata.progressPercent 更早达到 100%。在字节、对象和元数据迁移完成后，存储桶重定位会完成最后几个步骤，之后 metadata.commonMetadata.progressPercent 会更新为 100%。

与其他 Cloud Storage 功能交互时，可能会因相关限制而遇到一些问题。如需详细了解限制，请参阅限制。

启动最终同步步骤

在最终同步步骤中，您无法对存储桶执行写入操作。我们建议您将最终同步步骤安排在尽可能减少应用中断的时间段。

在继续操作之前，请检查监控增量数据复制过程步骤的输出中的 finalizationState 值，确认存储桶已完全准备就绪。如需继续执行最终同步步骤，finalizationState 值必须为 READY。

如果您过早启动最终同步步骤，命令会返回错误消息 The relocate bucket operation is not ready to advance to finalization running state，但重定位过程会继续进行。

建议您等到 progressPercent 值为 99 时，再启动最终同步步骤。

命令行

当 finalizationState 值为 READY 时，启动存储桶重定位操作的最终同步步骤：

gcloud storage buckets relocate --finalize --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

其中：

BUCKET_NAME 是要重定位的存储桶的名称。
OPERATION_ID 是长时间运行的操作的 ID，该 ID 会在您调用的方法的响应中返回。例如，调用 gcloud storage operations list 会返回以下响应，长时间运行的操作 ID 为 AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74。

 `name: projects/_/buckets/my-bucket/operations/AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74`

设置 ttl 标志，以便更好地控制重定位过程。例如：

gcloud storage buckets relocate --finalize --ttl TTL_DURATION --operation=projects/_/buckets/BUCKET_NAME/operations/OPERATION_ID

其中：

TTL_DURATION 是重定位过程中写入停止阶段的存留时间 (TTL)。它以字符串表示，例如 12h 表示 12 个小时。TTL_DURATION 决定写入停止阶段允许的时长上限。如果写入停止时间超过此限制，重定位过程会自动回滚到增量复制步骤，并且会重新启用对存储桶的写入操作。该值必须介于 6h（6 小时）到 48h（48 小时）的范围。如果未指定，则默认值为 12h（12 小时）。

REST API

JSON API

安装并初始化 gcloud CLI，以便为 Authorization 标头生成访问令牌。

创建一个包含存储桶重定位设置的 JSON 文件。如需查看完整的设置列表，请参阅 Buckets: advanceRelocateBucket 文档。以下是一些常用的设置，包括：
```
{
    "expireTime": "EXPIRE_TIME",
    "ttl": "TTL_DURATION"
}
```
其中：
- EXPIRE_TIME 是写入停止到期的时间。
- TTL_DURATION 是重定位过程中写入停止阶段的存留时间 (TTL)。它以字符串表示，例如 12h 表示 12 个小时。TTL_DURATION 决定写入停止阶段允许的时长上限。如果写入停止时间超过此限制，重定位过程会自动回滚到增量复制步骤，并且会重新启用对存储桶的写入操作。该值必须介于 6h（6 小时）到 48h（48 小时）的范围。如果未指定，则默认值为 12h（12 小时）。
使用 cURL 调用 JSON API：
```
curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://storage.googleapis.com/storage/v1/b/bucket/BUCKET_NAME/operations/OPERATION_ID/advanceRelocateBucket"
```
其中：
- JSON_FILE_NAME 是您创建的 JSON 文件的名称。
- BUCKET_NAME 是要重定位的存储桶的名称。
- OPERATION_ID 是长时间运行的操作的 ID，该 ID 会在您调用的方法的响应中返回。例如，调用 Operations: list 会返回以下响应，长时间运行的操作 ID 为 AbCJYd8jKT1n-Ciw1LCNXIcubwvij_TdqO-ZFjuF2YntK0r74。

验证存储桶重定位过程

启动重定位后，请验证重定位已成功完成。本部分提供了有关确认数据传输成功的指导。

使用以下方法验证重定位流程成功完成：

轮询长时间运行的操作：存储桶重定位是一项长时间运行的操作。您可以使用 operation id 轮询长时间运行的操作，以监控操作进度，并通过验证 success 状态来确认其已成功完成。这涉及定期查询操作状态，直到操作达到终止状态。如需了解如何监控长时间运行的操作，请参阅在 Cloud Storage 中使用长时间运行的操作。
分析 Cloud Audit Logs 条目：Cloud Audit Logs 会详细记录您的 Google Cloud 环境中的事件和操作。您可以分析与重定位相关的 Cloud Audit Logs 条目，以验证重定位的成功。分析日志，查找可能表明在数据传输过程中出现问题的任何错误、警告或意外行为。如需了解如何查看 Cloud Audit Logs 日志，请参阅查看审核日志。

以下日志条目可帮助您确定迁移是否成功：
- 重定位成功：Relocate bucket succeeded. All existing objects are now in the new placement configuration.
- 重定位失败：Relocate bucket has failed. Bucket location remains unchanged.
使用 Pub/Sub 通知，您还可以设置提醒，以便在日志中出现特定成功或失败事件时收到通知。如需了解如何设置 Pub/Sub 通知，请参阅配置适用于 Cloud Storage 的 Pub/Sub 通知。

完成存储桶重定位后的任务

成功重定位存储桶后，请完成以下步骤：

可选：恢复存储桶上所有基于标记的访问权限控制。
在重定位过程中，现有的资产清单报告配置不会保留，您需要手动重新创建这些配置。如需了解如何创建资产清单报告配置，请参阅创建资产清单报告配置。
更新您的基础设施即代码配置（例如 Terraform 和 Google Kubernetes Engine 配置连接器），以指定存储桶的新位置。
区域级端点与特定位置相关联，您需要修改应用代码以反映新的端点。

如何处理失败的存储桶重定位操作

在处理失败的存储桶重定位操作之前，请考虑以下因素：

失败的存储桶重定位可能会在目标存储桶中留下过时的资源（例如临时文件或不完整的数据副本）。您必须等待 7 到 14 天，然后才能再次启动到相同目标位置的存储桶重定位。您可以立即启动到其他目标位置的存储桶重定位。
如果目标位置不是存储数据的最佳位置，建议您回滚重定位操作。但是，您无法立即发起重定位。您需要等待最多 14 天，才能再次启动重定位过程。此限制是为了确保稳定性并防止数据冲突。

后续步骤

了解存储桶重定位。

重定位存储桶 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

所需权限

重定位存储桶

执行试运行

命令行

REST API

JSON API

启动增量数据复制

命令行

REST API

JSON API

监控增量数据复制

启动最终同步步骤

命令行

REST API

JSON API

验证存储桶重定位过程

完成存储桶重定位后的任务

如何处理失败的存储桶重定位操作

后续步骤

重定位存储桶
使用集合让一切井井有条根据您的偏好保存内容并对其进行分类。