使用時間點復原 (PITR)

本頁說明如何使用時間點還原 (PITR) 功能，保留及還原與 MongoDB 相容的 Cloud Firestore 資料。

如要瞭解 PITR 概念，請參閱「時間點復原」。

權限

如要取得管理 PITR 設定所需的權限，請要求管理員在您要啟用 PITR 的專案中，授予下列 IAM 角色：

• Cloud Datastore 擁有者 (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 後，您無法立即開始讀取七天前的資料。
• 如要在建立資料庫時啟用 PITR，請務必使用 gcloud firestore databases create 指令。使用 Google Cloud 控制台建立資料庫時，系統不支援啟用 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 加密。

• 時間戳記的精細度為一分鐘，且指定過去的時間點，位於 PITR 視窗定義的期間內：

  • 如果資料庫已啟用 PITR，您可以選取過去 7 天內的任何時間點 (如果啟用 PITR 的時間未滿 7 天，則為啟用 PITR 之後的任何時間點)。
  • 如果未啟用 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='projects/example-project/databases/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='projects/example-project/databases/example-dest-db' \
--encryption-type='customer-managed-encryption' \
--kms-key-name='projects/example-project/locations/us-central1/keyRings/example-key-ring/cryptoKeys/example-key'

從 PITR 資料匯出及匯入

您可以使用 gcloud firestore export 指令，從 PITR 資料將資料庫匯出至 Cloud Storage。您可以匯出時間戳記為過去七天內整分鐘的時間點復原資料，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，匯出作業就會失敗。

PITR 匯出作業支援所有篩選條件，包括匯出所有文件和匯出特定集合。

1. 匯出資料庫，並將 snapshot-time 參數指定為所選復原時間戳記。

   gcloud

   執行下列指令，將資料庫匯出至 bucket。

   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. 匯入資料庫。

   按照「匯入所有文件」一文中的步驟，匯入匯出的資料庫。如果資料庫中已有任何文件，系統會覆寫該文件。