重定位存储桶

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

准备工作

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

1. 配置Storage Intelligence。

2. 启用软删除。

3. 检查配额和限制，确保新位置有足够的配额来容纳存储桶的数据。

4. 确定存储桶重定位类型，以了解是否需要写入停止时间。

5. 移除所有现有的存储桶标记。

6. 如果您使用资产清单报告，请保存配置。

7. 获取必需的角色，如下一部分中所述。

获取所需角色

如需获得重定位存储桶所需的权限，请让您的管理员为您授予项目的 Storage Admin (roles/storage.admin) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含迁移存储桶所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需迁移存储桶，您需要具备以下权限：

• 重定位存储桶： storage.buckets.relocate
• 查看存储桶重定位操作的状态： storage.bucketOperations.get
• 查看项目的存储桶重定位操作列表： storage.bucketOperations.list
• 取消存储桶重定位操作： storage.bucketOperations.cancel
• 在试运行和存储桶重定位阶段查看存储桶的元数据： storage.buckets.get
• 获取要迁移的存储桶中的对象： storage.objects.get
• 列出要迁移的存储桶中的对象： storage.objects.list

您也可以使用自定义角色或其他预定义角色来获取这些权限。

重定位存储桶

本部分介绍将 Cloud Storage 存储桶从一个位置重定位到另一个位置的过程。

如需迁移存储桶，请完成以下步骤：

1. 通过试运行测试存储桶迁移（可选）

2. 启动存储桶重定位流程

3. 启动最终同步步骤

如需详细了解这些步骤，请参阅了解存储桶重定位过程。

通过试运行测试存储桶重定位（可选）

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

• 客户管理的加密密钥 (CMEK) 或客户提供的加密密钥 (CSEK)
• 锁定的保留政策
• 启用了临时冻结的对象
• 分段上传

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

控制台

1. 在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击要迁移的存储桶的名称。
3. 在存储桶详情页面上，点击配置标签页。
4. 在概览部分，点击位置字段旁边的 修改。
5. 在迁移存储桶页面上，输入存储桶的新位置。完成以下每一步后，点击继续以继续执行后续步骤：
   1. 在确认您计划重定位的存储桶部分中，查看存储桶及其位置。
   2. 在继续之前部分，查看阻止重定位的配置。如果您的存储桶受到限制，请考虑使用 Storage Transfer Service 作为替代解决方法。

   3. 在选择要将存储桶重定位到何处部分，执行以下操作：

      1. 选择位置类型。

      2. 选择一个位置，用于存储存储桶中的对象数据。

         系统会根据来源位置和目标位置告知您是否需要写入停机时间。如需了解迁移类型和停机时间，请参阅迁移类型。

   4. 在选择您希望以哪种方式继续操作部分中，点击从试运行入手（推荐）。试运行可模拟重定位过程，以便在不移动数据的情况下发现潜在问题。
   5. 点击继续。
6. 点击开始。
7. 在从试运行入手确认对话框中，查看显示的消息，然后点击开始试运行。

启动试运行后，系统会开始执行一项长时间运行的操作。您可以在存储桶详情页面的操作标签页中监控进度。

命令行

如需启动试运行，请运行带有 --dry-run 标志的 gcloud storage buckets relocate 命令：

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

其中：

• BUCKET_NAME 是要重定位的存储桶的名称。

• LOCATION 是存储桶的目标位置。

启动试运行后，系统会开始执行一项长时间运行的操作。您会收到操作 ID 和操作说明。通过获取长时间运行的操作的详细信息来跟踪试运行的进度和完成情况。

如果试运行暴露了任何问题，请先解决这些问题，然后再继续执行重定位步骤。

JSON API

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

2. 创建一个包含存储桶设置的 JSON 文件，其中必须包含 destinationLocation 和 validateOnly 参数。如需查看完整的设置列表，请参阅 Buckets: relocate 文档。以下是一些常用的设置，包括：

   {
     "destinationLocation": "DESTINATION_LOCATION",
     "destinationCustomPlacementConfig": {
       "dataLocations": [
         LOCATIONS,
           ...
           ]
       },
     "validateOnly": "true"
     }

   其中：

   • DESTINATION_LOCATION 是存储桶的目标位置。
   • LOCATIONS 是用于可配置的双区域的位置代码列表。
   • 将 validateOnly 设置为 true 以执行试运行。

3. 使用 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_NAME/relocate"

   其中：

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

   启动试运行后，系统会开始执行一项长时间运行的操作。当满足以下条件时，试运行会成功：

   • 试运行报告显示没有错误。

   • operations 资源会返回 true 的 done 字段值。

     {
     "kind": "storage#operation",
     "name": "projects/_/buckets/bucket/operations/operation_id",
     "metadata": {
       "@type": OperationMetadataType*,
       metadata OperationMetadata*
     },
     "done": "true",
     "response": {
           "@type": ResponseResourceType*,
           response ResponseResource*
         }
       }

     如果试运行暴露了任何问题，请先解决这些问题，然后再继续执行启动重定位步骤。

启动存储桶重定位

控制台

1. 在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击要迁移的存储桶的名称。
3. 在存储桶详情页面上，点击配置标签页。
4. 在概览部分，点击位置字段旁边的 修改。
5. 在迁移存储桶页面上，输入存储桶的新位置。完成以下每一步后，点击继续以继续执行后续步骤：
   1. 在确认您计划重定位的存储桶部分中，查看存储桶及其位置。
   2. 在继续之前部分，查看阻止重定位的配置。如果您的存储桶受到限制，请考虑使用 Storage Transfer Service 作为替代解决方法。

   3. 在选择要将存储桶重定位到何处部分，执行以下操作：

      1. 选择位置类型。

      2. 选择一个位置，用于存储存储桶中的对象数据。

         系统会根据来源位置和目标位置告知您是否需要写入停机时间。如需了解迁移类型和停机时间，请参阅迁移类型。

   4. 在选择处理方式部分中，点击立即迁移。
   5. 点击继续。
6. 如需开始迁移流程，请点击开始。
7. 在立即迁移确认对话框中，查看显示的消息，然后点击开始迁移。

启动重定位流程后，系统会开始执行长时间运行的操作。您可以在存储桶详情页面的操作标签页中监控进度。

命令行

如需启动存储桶重定位，请运行 gcloud storage buckets relocate 命令：

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

其中：

• BUCKET_NAME 是要重定位的存储桶的名称。

• LOCATION 是存储桶的目标位置。

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

JSON API

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

2. 创建一个包含存储桶设置的 JSON 文件。如需查看完整的设置列表，请参阅 Buckets: relocate 文档。以下是一些常用的设置，包括：

   {
     "destinationLocation": "DESTINATION_LOCATION",
     "destinationCustomPlacementConfig": {
     "dataLocations": [
       LOCATIONS,
       ...
       ]
       },
     "validateOnly": "false"
     }

   其中：

   • DESTINATION_LOCATION 是存储桶的目标位置。
   • LOCATIONS 是用于可配置的双区域的位置代码列表。
   • 将 validateOnly 设置为 false，以启动存储桶重定位。

3. 使用 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_NAME/relocate"

   其中：

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

监控重定位过程

控制台

如需监控预演或重定位流程的进度，请完成以下步骤：

1. 在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击要迁移的存储桶的名称。

3. 在存储桶详情页面上，点击操作标签。

4. 在显示的存储桶操作列表中，点击试运行操作或重定位操作以查看其详细信息。

操作详情页面会显示迁移摘要、关键指标和错误摘要。

命令行

启动存储桶重定位后，系统会开始执行长时间运行的操作。您会收到操作 ID 和操作说明。通过获取长时间运行的操作的详细信息，跟踪迁移过程的进度和完成情况。

JSON API

存储桶重定位是一项长时间运行的操作，需要进行监控。如需检查流程状态，请定期查看长时间运行的操作详情。如需了解如何检查迁移过程的状态，请参阅获取长时间运行的操作的详细信息。

以下示例展示了重定位操作生成的输出：

  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
  estimatedWriteDowntimeDuration: '7200s'
  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.estimatedWriteDowntimeDuration	估计的写入停止时长；一旦 finalizationState 为 READY，系统就会填充此值。	最小值为 7200s。
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 功能交互时遇到问题，请参阅限制。

启动最终同步步骤

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

控制台

如需启动最终同步步骤，请完成以下步骤：

1. 在 Google Cloud 控制台中，转到 Cloud Storage 存储桶页面。
   

   进入“存储桶”

2. 在存储桶列表中，点击要迁移的存储桶的名称。

3. 在存储桶详情页面上，点击操作标签。

4. 在存储桶操作列表中，点击重定位操作以查看操作详情页面。在操作详情页面上，当数据复制完成至少 99% 时，系统会显示一条消息栏，指示现在是开始最终同步的最佳时机。

5. 可选：如需设置允许的最长写入停机时间，请点击设置允许的最长停机时间 (TTL)，然后指定最长停机时间。

6. 点击开始最终同步。

7. 在显示的确认对话框中，点击开始以开始最终同步。

操作详情页面会显示迁移摘要、关键指标和错误摘要。

命令行

在继续操作之前，请检查启动存储桶重定位步骤的输出中的 finalizationState 值，确认存储桶已完全准备就绪。

当 finalizationState 值为 READY 时，运行 gcloud storage buckets relocate 命令以启动最终同步：

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 小时）。

JSON API

在继续操作之前，请检查存储桶重定位步骤的输出中的 finalizationState 值，确认存储桶已完全准备就绪。finalizationState 值必须为 READY 才能继续。

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

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

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

2. 创建一个包含存储桶重定位设置的 JSON 文件。如需查看完整的设置列表，请参阅 Buckets: advanceRelocateBucket 文档。以下是一些常用的设置，包括：

   {
   "expireTime": "EXPIRE_TIME",
   "ttl": "TTL_DURATION"
   }

   其中：

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

3. 使用 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 列表，请参阅操作：列表。

成功重定位存储桶后，您在 14 天内无法再次启动同一存储桶的重定位。

验证存储桶重定位过程

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

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

• 轮询长时间运行的操作：存储桶重定位是一项长时间运行的操作。您可以使用 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 通知。

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

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

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

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

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

• 失败的存储桶重定位可能会在目标存储桶中留下过时的资源（例如临时文件或不完整的数据副本）。您必须等待 7 到 14 天，然后才能再次启动到相同目标位置的存储桶重定位。您可以立即启动到其他目标位置的存储桶重定位。

• 如果目标位置不是存储数据的最佳位置，建议您回滚重定位操作。但是，您无法立即发起重定位。您需要等待最多 14 天，才能再次启动重定位过程，以保持稳定性并避免数据冲突。

后续步骤

• 了解存储桶重定位。