使用时间点恢复 (PITR)

本页面介绍如何使用时间点恢复 (PITR) 在与 MongoDB 兼容的 Cloud Firestore 中保留和恢复数据。

如需了解 PITR 概念，请参阅时间点恢复。

权限

如需获取管理 PITR 设置所需的权限，请让管理员向您授予您想要启用 PITR 的项目的以下 IAM 角色：

• Cloud Datastore Owner (roles/datastore.owner)

对于自定义角色，请确保已为其授予以下权限：

• 如需在创建数据库时启用 PITR：datastore.databases.create
• 如需更新现有数据库上的 PITR 设置：datastore.databases.update、datastore.databases.list
• 如需从 PITR 数据进行读取：datastore.databases.get、datastore.entities.get、datastore.entities.list
• 如需导出 PITR 数据：datastore.databases.export
• 如需导入 PITR 数据：datastore.databases.import
• 如需克隆数据库，请执行以下操作：datastore.databases.clone

准备工作

在开始使用 PITR 之前，请注意以下几点：

• 启用 PITR 后，您无法立即开始读取过去 7 天内的数据。
• 如果您要在创建数据库时启用 PITR，必须使用 gcloud firestore databases create 命令。使用 Google Cloud 控制台创建数据库时不支持启用 PITR。
• 启用 PITR 后，与 MongoDB 兼容的 Cloud Firestore 会从此时间点开始保留版本。
• 停用 PITR 后，您将无法在 PITR 窗口中读取 PITR 数据。
• 如果您在停用 PITR 后立即将其重启，则过去的 PITR 数据将不再可用。系统将在 PITR 失效日期之后删除停用 PITR 之前创建的任何 PITR 数据。
• 如果您在过去一小时内不小心删除了数据并停用了 PITR，则可以在删除后的一小时内启用 PITR，从而恢复数据。
• 对已过期的 PITR 数据执行的任何读取操作都会失败。

启用 PITR

在使用 PITR 之前，请为 Google Cloud 项目启用结算功能。只有启用了结算功能的 Google Cloud 项目才能使用 PITR 功能。

如需为数据库启用 PITR，请执行以下操作：

gcloud firestore databases create\
  --location=LOCATION\
  --database=DATABASE_ID\
  --type=firestore-native\
  --enable-pitr

gcloud firestore databases update\
  --database=DATABASE_ID\
  --no-enable-pitr

获取保留期限和最早版本时间

gcloud firestore databases describe --database=DATABASE_ID

    appEngineIntegrationMode: ENABLED
    concurrencyMode: PESSIMISTIC
    createTime: '2021-03-24T17:02:35.234Z'
    deleteProtectionState: DELETE_PROTECTION_DISABLED
    earliestVersionTime: '2023-06-12T16:17:25.222474Z'
    etag: IIDayqOevv8CMNTvyNK4uv8C
    keyPrefix: s
    locationId: nam5
    name: projects/PROJECT_ID/databases/DATABASE_ID
    pointInTimeRecoveryEnablement: POINT_IN_TIME_RECOVERY_DISABLED
    type: FIRESTORE_NATIVE
    uid: 5230c382-dcd2-468f-8cb3-2a1acfde2b32
    updateTime: '2021-11-17T17:48:22.171180Z'
    versionRetentionPeriod: 3600s

读取 PITR 数据

  Firestore firestore = …

  TransactionOptions options =
          TransactionOptions.createReadOnlyOptionsBuilder()
              .setReadTime(
                  com.google.protobuf.Timestamp.newBuilder()
                      .setSeconds(1684098540L)
                      .setNanos(0))
              .build();

  ApiFuture<Void> futureTransaction = firestore.runTransaction(
              transaction -> {
                // Does a snapshot read document lookup
                final DocumentSnapshot documentResult =
                    transaction.get(documentReference).get();

                // Executes a snapshot read query
                final QuerySnapshot queryResult =
                  transaction.get(query).get();
              },
              options);

  // Blocks on transaction to complete
  futureTransaction.get();

const documentSnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(documentRef),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

const querySnapshot = await firestore.runTransaction(
    updateFunction => updateFunction.get(query),
    {readOnly: true, readTime: new Firestore.Timestamp(1684098540, 0)}
);

  Instant readTime = Instant.ofEpochSecond(1684098540L);

  PCollection<Document> documents =
      pipeline
          .apply(Create.of(collectionId))
          .apply(
              new FilterDocumentsQuery(
                  firestoreOptions.getProjectId(), firestoreOptions.getDatabaseId()))
          .apply(FirestoreIO.v1().read().runQuery().withReadTime(readTime).withRpcQosOptions(rpcQosOptions).build())
  ...

从数据库克隆

您可以将现有数据库在选定时间点的数据克隆到新的数据库中：

• 克隆的数据库是一个新数据库，将在源数据库所在的同一位置创建。

  为了创建克隆，Cloud Firestore 使用源数据库的时间点恢复 (PITR) 数据。克隆的数据库包含所有数据和索引。

• 默认情况下，克隆的数据库将采用与源数据库相同的加密方式（Google 默认加密或 CMEK 加密）。您可以指定其他加密类型，也可以使用其他密钥进行 CMEK 加密。

• 时间戳的粒度为 1 分钟，它指定了过去的一个时间点，该时间点必须在 PITR 时间窗口定义的时段内：

  • 如果数据库已启用 PITR，您可以选择过去 7 天内的任意一分钟（如果 PITR 启用时间不足 7 天，则可选择启用以来的任意一分钟）。
  • 如果未启用 PITR，您可以选择过去一小时内的任意一分钟。
  • 您可以在数据库的说明中查看可选择的最早时间戳。

gcloud alpha firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--tags=key1=value1,key2=value2

gcloud alpha firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

限制

克隆操作不会从 (default) 数据库克隆App Engine 搜索数据或 blob 实体。此类数据仅对 (default) 数据库有效，如果您从 (default) 克隆到不支持此类数据的数据库，此类数据将毫无用处，因此会从克隆中排除。

从 PITR 数据导出和导入

您可以使用 gcloud firestore export 命令将数据库从 PITR 数据导出到 Cloud Storage。您可以导出 PITR 数据，其中时间戳为过去七天内的整分钟时间戳，但不早于 earliestVersionTime。如果指定的时间戳已不存在数据，导出操作将失败。

PITR 导出操作支持所有过滤条件，包括导出所有文档和导出特定集合。

1. 导出数据库，将 snapshot-time 参数指定为所选恢复时间戳。

   gcloud

   运行以下命令，将数据库导出到存储桶。

   gcloud firestore export gs://BUCKET_NAME_PATH \
       --snapshot-time=PITR_TIMESTAMP \
       --collection-ids=COLLECTION_IDS \
       --namespace-ids=NAMESPACE_IDS
   

   其中：

   • BUCKET_NAME_PATH - 有效的 Cloud Storage 存储桶（包含可选路径前缀），用于存储导出文件。
   • PITR_TIMESTAMP - 分钟粒度的 PITR 时间戳，例如 2023-05-26T10:20:00.00Z 或 2023-10-19T10:30:00.00-07:00。
   • COLLECTION_IDS - 集合 ID 或集合组 ID 的列表，例如 'specific-collection-group1','specific-collection-group2'。
   • NAMESPACE_IDS - 命名空间 ID 的列表，例如 'customer','orders'。

   在导出 PITR 数据之前，请注意以下几点：

   • 以 RFC 3339 格式指定时间戳。例如 2023-05-26T10:20:00.00Z 或 2023-10-19T10:30:00.00-07:00。
   • 请确保您指定的时间戳是过去七天内的整分钟时间戳，但不早于 earliestVersionTime。如果指定的时间戳已不存在数据，则会生成错误。 时间戳必须是整分钟，即使指定的时间在过去一小时内也是如此。
   • 您无需为失败的 PITR 导出付费。

2. 导入到数据库。

   按照导入所有文档中的步骤导入您导出的数据库。如果数据库中已有任何文档，这类文档将会被覆盖。