本頁面說明如何使用時間點復原 (PITR) 功能，保留及復原 Cloud Firestore 中的資料。
如要瞭解 PITR 概念，請參閱「時間點復原」。
權限
如要取得管理 PITR 設定所需的權限，請要求管理員在您要啟用 PITR 的專案中，授予下列 IAM 角色：
- Cloud Datastore 擁有者 (
roles/datastore.owner)
如果是自訂角色，請確認已授予下列權限：
- 如要在建立資料庫時啟用 PITR，請執行
datastore.databases.create： - 如要更新現有資料庫的 PITR 設定，請按照下列步驟操作：
datastore.databases.updatedatastore.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。 - Cloud Firestore啟用 PITR 後，系統會開始保留該時間點之後的版本。
- 停用 PITR 後，您就無法在 PITR 期間讀取 PITR 資料。
- 如果停用 PITR 後立即重新啟用，系統將無法再提供過去的 PITR 資料。停用 PITR 前建立的任何 PITR 資料，都會在 PITR 到期日後刪除。
- 如果您在過去一小時內不慎刪除資料，且 PITR 已停用，請在刪除資料後一小時內啟用 PITR，即可還原資料。
- 對過期 PITR 資料執行的任何讀取作業都會失敗。
啟用 PITR
使用 PITR 前，請先啟用 Google Cloud 專案的計費功能。只有啟用帳單功能的 Google Cloud 專案才能使用 PITR 功能。
如要為資料庫啟用 PITR，請按照下列步驟操作：
控制台
前往 Google Cloud 控制台的「資料庫」頁面。
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「Disaster Recovery」(災害復原)。
按一下「編輯」即可編輯設定。
勾選「Enable point-in-time recovery」(啟用時間點還原) 核取方塊，然後按一下「Save」(儲存)。
啟用 PITR 功能會產生儲存空間費用。詳情請參閱定價。
如要停用 PITR，請在 Google Cloud 控制台的「災難復原」頁面中，取消勾選「啟用時間點復原」核取方塊。
gcloud
在建立資料庫時，使用 gcloud firestore databases create 和 --enable-ptir 指令啟用 PITR，如下所示：
gcloud firestore databases create\
--location=LOCATION\
--database=DATABASE_ID\
--type=firestore-native\
--enable-pitr
將值替換為下列內容：
LOCATION：要在哪個位置建立資料庫。DATABASE_ID- 設為資料庫 ID。
您可以使用 gcloud firestore databases update 指令停用 PITR，如下所示：
gcloud firestore databases update\
--database=DATABASE_ID\
--no-enable-pitr
將值替換為下列內容：
DATABASE_ID- 設為資料庫 ID 或 (預設)。
取得保留期限和最早版本時間
控制台
前往 Google Cloud 控制台的「資料庫」頁面。
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「Disaster Recovery」(災害復原)。
在「設定」部分，請注意「保留期限」和「最早版本時間」。
- 保留期限：Cloud Firestore 保留資料庫所有版本資料的期限。如果停用 PITR，保留期限為一小時；如果啟用 PITR，保留期限為七天。
- 最早版本時間：時間點復原 (PITR) 期間內可讀取資料舊版本的最早時間戳記。這個值會由 Cloud Firestore 持續更新，但查詢時會過時。如果您使用這個值復原資料，請務必將查詢值到啟動復原作業之間的時間納入考量。
- 時間點復原：如果已啟用 PITR，會顯示
Enabled。如果 PITR 已停用，您會看到Disabled。
gcloud
執行 gcloud firestore databases describe 指令，如下所示：
gcloud firestore databases describe --database=DATABASE_ID
將 DATABASE_ID 替換為資料庫 ID 或 '(default)'。
輸出內容如下：
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
其中：
earliestVersionTime：儲存最早 PITR 資料的時間戳記。pointInTimeRecoveryEnablement：如果啟用 PITR，則會顯示POINT_IN_TIME_RECOVERY_ENABLED。如果停用 PITR，您會看到POINT_IN_TIME_RECOVERY_DISABLED，或系統可能不會顯示pointInTimeRecoveryEnablement欄位。versionRetentionPeriod：以毫秒為單位，表示 PITR 資料的保留時間。如果停用時間點復原功能，值可以是一小時；如果啟用時間點復原功能，值可以是七天。
讀取 PITR 資料
您可以使用用戶端程式庫、REST API 方法或 FirestoreIO Apache Beam 連接器讀取 PITR 資料。用戶端程式庫
Java
您必須使用 ReadOnly 交易才能讀取 PITR 資料。您無法直接在讀取作業中指定 readTime。
詳情請參閱「交易和批次寫入」。
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();
節點
您必須使用 ReadOnly 交易才能讀取 PITR 資料。您無法直接在讀取作業中指定 readTime。
詳情請參閱「交易和批次寫入」。
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)}
);
REST API
所有 Cloud Firestore 讀取方法都支援 PITR 讀取，包括 get、list、batchGet、listCollectionIds、listDocuments、runQuery、runAggregationQuery 和 partitionQuery。
如要使用 REST 方法執行讀取作業，請嘗試下列其中一種做法：
在讀取方法要求中，將
readTime值做為readOptions方法中支援的 PITR 時間戳記傳遞。PITR 時間戳記可以是過去一小時內精確到微秒的時間戳記，也可以是過去一小時以外精確到整分鐘的時間戳記，但不得早於earliestVersionTime。搭配
BeginTransaction方法使用readTime參數，做為多個 PITR 讀取作業的ReadOnly交易一部分。
Apache Beam
使用 Cloud FirestoreIO Apache Beam 連接器，透過 Dataflow 大規模讀取或寫入 Cloud Firestore 資料庫中的文件。
Cloud FirestoreIO 連接器的下列讀取方法支援 PITR 讀取。這些讀取方法支援 withReadTime(@Nullable Instant readTime) 方法，可用於 PITR 讀取：
- FirestoreV1.BatchGetDocuments
- FirestoreV1.ListCollectionIds
- FirestoreV1.ListDocuments
- FirestoreV1.PartitionQuery
Java
下列程式碼可搭配範例 Dataflow 管道程式碼，用於大量讀取或寫入作業。本範例使用 withReadTime(@Nullable Instant readTime) 方法進行 PITR 讀取。
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())
...
如需 Dataflow 管道中的完整 readTime 範例清單，請參閱 GitHub 存放區。
從 PITR 資料匯出及匯入
您可以使用 gcloud firestore export 指令，將資料庫從 PITR 資料匯出至 Cloud Storage。您可以匯出時間戳記為過去七天內整分鐘的時間點復原資料，但不得早於 earliestVersionTime。如果指定時間戳記的資料已不存在，匯出作業就會失敗。
PITR 匯出作業支援所有篩選條件，包括匯出所有文件和匯出特定集合。
匯出資料庫，並將
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) 匯出作業失敗，您不需付費。
匯入資料庫。
按照「匯入所有文件」一文中的步驟，匯入匯出的資料庫。如果資料庫中已有任何文件，系統會覆寫該文件。
從資料庫複製
您可以將所選時間戳記的現有資料庫複製到新資料庫：
複製的資料庫是新資料庫，會建立在與來源資料庫相同的位置。
如要建立副本，Cloud Firestore 會使用來源資料庫的時間點復原 (PITR) 資料。複製的資料庫包括所有資料和索引。
根據預設，複製的資料庫會使用與來源資料庫相同的加密方式，也就是 Google 的預設加密或 CMEK 加密。您可以指定其他加密類型，或使用其他金鑰進行 CMEK 加密。
時間戳記的精細度為一分鐘，且指定過去的時間點，該時間點位於 PITR 視窗定義的期間內：
- 如果資料庫已啟用 PITR，您可以選取過去 7 天內的任何時間點 (如果啟用 PITR 的時間未滿 7 天，則為啟用 PITR 之後的任何時間點)。
- 如果未啟用 PITR，您可以選取過去一小時內的任一分鐘。
- 你可以查看資料庫說明中可選取的最早時間戳記。
主控台
Firebase 控制台不支援資料庫複製功能。您可以按照Google Cloud CLI的說明複製資料庫。
gcloud
使用 gcloud alpha firestore databases clone 指令複製資料庫：
gcloud alpha firestore databases clone \
--source-database='SOURCE_DATABASE_ID' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'
更改下列內容：
SOURCE_DATABASE_ID：您要複製的現有資料庫資料庫 ID。
PITR_TIMESTAMP：PITR 時間戳記，採用RFC 3339 格式，精確度達分鐘單位。例如：
2025-06-01T10:20:00.00Z或2025-06-01T10:30:00.00-07:00。DESTINATION_DATABASE_ID：新複製資料庫的資料庫 ID。這個資料庫 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'
變更複製資料庫的加密設定
根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：
- (預設)
use-source-encryption：使用與來源資料庫相同的加密設定。 google-default-encryption：使用 Google 的預設加密機制。customer-managed-encryption：使用 CMEK 加密。在--kms-key-name引數中指定金鑰 ID。
以下範例說明如何為複製的資料庫設定 CMEK 加密：
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'