使用時間點復原 (PITR)
本頁說明如何使用時間點復原 (PITR) 功能，保留及復原 Firestore 中的資料。
如要瞭解 PITR 概念，請參閱「時間點復原」。
權限
如要取得管理 PITR 設定所需的權限，請要求管理員在您要啟用 PITR 設定的專案中，授予您 Cloud Datastore 擁有者 (roles/datastore.owner) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。
這個預先定義的角色具備管理 PITR 設定所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：
所需權限
如要管理 PITR 設定，您必須具備下列權限：
-
如要在建立資料庫時啟用 PITR，請執行下列操作：
datastore.databases.create -
如要更新現有資料庫的時間點復原設定，請按照下列步驟操作：
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。 - 啟用 PITR 後，Firestore 會開始保留該時間點之後的版本。
- 停用 PITR 後，您就無法在 PITR 期間讀取 PITR 資料。
- 如果停用 PITR 後立即重新啟用，系統將無法再提供過去的 PITR 資料。停用 PITR 前建立的任何 PITR 資料，都會在 PITR 到期日後刪除。
- 如果您在過去一小時內不慎刪除資料，且 PITR 已停用，請在刪除資料後一小時內啟用 PITR，即可還原資料。
- 對過期 PITR 資料執行的任何讀取作業都會失敗。
啟用 PITR
使用 PITR 前，請先為 Google Cloud 專案啟用計費功能。只有啟用計費功能的 Google Cloud 專案才能使用 PITR 功能。
如要為資料庫啟用 PITR，請按照下列步驟操作：
控制台
前往 Google Cloud 控制台的「Databases」頁面。
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「Disaster Recovery」(災難復原)。
按一下「編輯」即可編輯設定。
勾選「Enable point-in-time recovery」(啟用時間點還原) 核取方塊，然後按一下「Save」(儲存)。
啟用 PITR 功能會產生儲存費用。詳情請參閱定價。
如要停用 PITR，請在 Google Cloud 控制台的「Disaster Recovery」(災害復原) 頁面中，取消勾選「Enable point-in-time recovery」(啟用時間點復原) 核取方塊。
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 控制台的「Databases」頁面。
從資料庫清單中選取所需資料庫。
在導覽選單中，按一下「Disaster Recovery」(災難復原)。
在「設定」部分，請注意「保留期限」和「最早版本時間」。
- 保留期限：Firestore 保留資料庫所有資料版本的期限。如果停用 PITR，保留期限為一小時；如果啟用 PITR，保留期限為七天。
- 最早版本時間：時間點復原 (PITR) 期間內可讀取資料舊版本的最早時間戳記。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
所有 Firestore 讀取方法都支援 PITR 讀取，包括 get、list、batchGet、listCollectionIds、listDocuments、runQuery、runAggregationQuery 和 partitionQuery。
如要使用 REST 方法執行讀取作業，請嘗試下列其中一種做法：
在讀取方法要求中，將
readTime值做為readOptions方法中支援的 PITR 時間戳記傳遞。PITR 時間戳記可以是過去一小時內的微秒精確度時間戳記，也可以是過去一小時以外的整分鐘時間戳記，但不得早於earliestVersionTime。搭配
BeginTransaction方法使用readTime參數，做為多個 PITR 讀取作業的ReadOnly交易一部分。
Apache Beam
使用 FirestoreIO Apache Beam 連接器，透過 Dataflow 大規模讀取或寫入 Firestore 資料庫中的文件。
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 存放區。
從資料庫複製
您可以將現有資料庫在所選時間戳記的狀態複製到新資料庫：
複製的資料庫是新資料庫，會建立在與來源資料庫相同的位置。
Firestore 會使用來源資料庫的時間點復原 (PITR) 資料進行複製。複製的資料庫包括所有資料和索引。
根據預設，複製的資料庫會採用與來源資料庫相同的加密方式，也就是使用 Google 的預設加密機制或 CMEK 加密機制。您可以指定不同的加密類型，或是使用不同的金鑰進行 CMEK 加密。
時間戳記的精細度為一分鐘，且指定過去的時間點，該時間點位於 PITR 視窗定義的期間內：
- 如果資料庫已啟用 PITR，您可以選取過去 7 天內的任何時間點 (如果啟用 PITR 的時間未滿 7 天，則可選取的時間範圍會更短)。
- 如果未啟用 PITR，您可以選取過去一小時內的任一分鐘。
- 你可以查看資料庫說明中可選取的最早時間戳記。
控制台
gcloud
使用 gcloud firestore databases clone 指令複製資料庫：
gcloud firestore databases clone \
--source-database='SOURCE_DATABASE' \
--snapshot-time='PITR_TIMESTAMP' \
--destination-database='DESTINATION_DATABASE_ID'
更改下列內容：
SOURCE_DATABASE：要複製的現有資料庫名稱。名稱格式為
projects/PROJECT_ID/databases/SOURCE_DATABASE_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 firestore databases clone \
--source-database='projects/example-project/databases/(default)' \
--snapshot-time='2025-06-01T10:20:00.00Z' \
--destination-database='example-dest-db'
如要在複製資料庫時繫結某些標記，請使用先前的指令搭配 --tags 旗標，這是要繫結的標記 KEY=VALUE 組合的選用清單。
範例：
gcloud 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
根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：
- (預設)
use-source-encryption：使用與來源資料庫相同的加密設定。 google-default-encryption：使用 Google 的預設加密機制。customer-managed-encryption：使用 CMEK 加密。在--kms-key-name引數中指定金鑰 ID。
以下範例說明如何為複製的資料庫設定 CMEK 加密：
gcloud 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'
Firebase CLI
使用 firebase firestore:databases:clone 指令複製資料庫：
firebase firestore:databases:clone \
'SOURCE_DATABASE' \
'DESTINATION_DATABASE' \
--snapshot-time 'PITR_TIMESTAMP'
更改下列內容：
SOURCE_DATABASE：要複製的現有資料庫名稱。名稱格式為
projects/PROJECT_ID/databases/SOURCE_DATABASE_ID。DESTINATION_DATABASE：新複製資料庫的資料庫名稱。名稱格式為
projects/PROJECT_ID/databases/DESTINATION_DATABASE_ID。這個資料庫名稱不得與現有資料庫相關聯。PITR_TIMESTAMP：PITR 時間戳記，採用 RFC 3339 格式，精確度為分鐘。例如：
2025-06-01T10:20:00.00Z或2025-06-01T10:30:00.00-07:00。如未指定，系統會選擇目前時間的快照，並向下取整至分鐘。
根據預設，複製的資料庫會與來源資料庫採用相同的加密設定。如要變更加密設定，請使用 --encryption-type 引數：
- (預設)
USE_SOURCE_ENCRYPTION：使用與來源資料庫相同的加密設定。 GOOGLE_DEFAULT_ENCRYPTION：使用 Google 的預設加密機制。CUSTOMER_MANAGED_ENCRYPTION：使用 CMEK 加密。在--kms-key-name引數中指定金鑰 ID。
以下範例說明如何為複製的資料庫設定 CMEK 加密：
firebase firestore:databases:clone \
'projects/example-project/databases/(default)' \
'projects/example-project/databases/example-dest-db' \
--snapshot-time 'PITR_TIMESTAMP' \
--encryption-type CUSTOMER_MANAGED_ENCRYPTION
限制
複製作業不會複製 (default) 資料庫中的 App Engine 搜尋資料或 blob 實體。這項資料僅適用於 (default) 資料庫，如果從 (default) 複製到不支援這類資料的資料庫，這項資料就沒有用處，因此會從副本中排除。
從 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 bucket，以及儲存匯出檔案的選用路徑前置字串。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 匯出作業失敗，系統不會收取任何費用。
匯入資料庫。
按照「匯入所有文件」一文中的步驟，匯入匯出的資料庫。如果資料庫中已有任何文件，系統會覆寫該文件。