遷移疑難排解
本節提供提示，協助您排解建立及管理 Datastream 和 Dataflow 管道時可能發生的常見問題。
排解 Datastream 連線設定檔問題
在遷移程序中，您需要建立兩個 Datastream 連線設定檔：一個用於從來源 MongoDB 相容資料庫讀取資料，另一個用於將資料寫入 Cloud Storage 值區。
這些步驟會使用 gcloud datastream connection-profiles create 指令。
使用這項指令建立 Datastream 連線設定檔時，系統會傳回類似下列範例的中繼資料：
metadata:
'@type': type.googleapis.com/google.cloud.datastream.v1.OperationMetadata
apiVersion: v1
createTime: '2025-05-15T21:49:05.022509533Z'
requestedCancellation: false
target: projects/PROJECT_ID/locations/LOCATION/connectionProfiles/SRC_CONNECTION_PROFILE_NAME
verb: create
name: projects/PROJECT_ID/locations/LOCATION/operations/operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6
您可以使用以 operation- 開頭的醒目顯示 ID，擷取指定資料串流作業的狀態。以上述輸出內容為例，下列 gcloud CLI 指令會擷取連線設定檔建立要求的詳細資料：
gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"
您可以在 Google Cloud 控制台中檢查 Datastream 連線設定檔和其他 Datastream 構件。
前往 Google Cloud 控制台的「Datastream」頁面：
排解 Datastream 串流問題
使用 gcloud datastream streams create 指令建立 Datastream 串流時，系統會傳回類似下列範例的中繼資料：
metadata:
'@type': type.googleapis.com/google.cloud.datastream.v1.OperationMetadata
apiVersion: v1
createTime: '2025-05-14T19:31:20.209503095Z'
requestedCancellation: false
target: projects/PROJECT_ID/locations/LOCATION/streams/DATASTREAM_NAME
verb: create
name: projects/PROJECT_ID/locations/LOCATION/operations/operation-1747251080085-6351d97f63eb8-43204f78-35c87474
您可以使用以 operation- 開頭的醒目顯示 ID，擷取指定資料串流作業的狀態。以上述輸出內容為例，下列 gcloud CLI 指令會擷取串流建立要求的詳細資料：
gcloud datastream operations describe \
operation-1747345744961-63533a26d9ee6-b2386fbf-204c28d6 \
--location="$LOCATION"
如要查詢現有串流的狀態，請使用：
gcloud datastream streams describe $DATASTREAM_NAME --location=$LOCATION
您可以在 Google Cloud 控制台中檢查 Datastream 串流和其他 Datastream 構件。
前往 Google Cloud 控制台的「Datastream」頁面：
排解 Dataflow pipeline 問題
您可以在 Google Cloud 控制台中監控 Dataflow 管道執行作業。
前往 Google Cloud 控制台的「Dataflow」頁面：
排解可重試的錯誤
可重試的錯誤是暫時性錯誤，最終會成功。常見的可重試錯誤包括：
- 網路或連線問題
- 交易爭用
- 因負載平衡而關閉的連線
如果因發生錯誤而無法寫入目的地，系統會將文件儲存在 Cloud Storage bucket 中，位置由 Dataflow 範本的 deadLetterQueueDirectory 參數指定。根據預設，系統會重試可重試的錯誤，次數上限為 dlqMaxRetryCount 參數指定的次數。
如要直接檢查 Dead Letter Queue (DLQ)，請前往 DLQ_LOCATION 環境變數中指定的路徑。路徑會包含時間戳記資料夾的階層，內含無法寫入與 MongoDB 相容的 Firestore 資料庫的文件和更新的 JSON 記錄。
假設 Dead Letter Queue 只包含因可重試錯誤而失敗的文件，您可以嘗試在只處理這個佇列的模式下執行 Dataflow 範本，藉此排空佇列。如要這麼做，請將 runMode 參數設為 retryDLQ，如以下範例所示：
DLQ_START_TIME="$(date +'%Y%m%d%H%M%S')"
gcloud dataflow flex-template run "dataflow-mongodb-to-firestore-$DLQ_START_TIME" \
--template-file-gcs-location gs://dataflow-templates-us-central1/latest/flex/Cloud_Datastream_MongoDB_to_Firestore \
--region $LOCATION \
--num-workers $NUM_WORKERS \
--temp-location $TEMP_OUTPUT_LOCATION \
--additional-user-labels "" \
--parameters inputFilePattern=$INPUT_FILE_LOCATION,\
inputFileFormat=avro,\
fileReadConcurrency=10,\
connectionUri=$FIRESTORE_CONNECTION_URI,\
databaseName=$FIRESTORE_DATABASE_NAME,\
shadowCollectionPrefix=shadow_,\
batchSize=500,\
deadLetterQueueDirectory=$DLQ_LOCATION,\
dlqRetryMinutes=10,\
dlqMaxRetryCount=500,\
processBackfillFirst=false,\
runMode=retryDLQ,\
directoryWatchDurationInMinutes=10,\
streamName=$DATASTREAM_NAME,\
stagingLocation=$STAGING_LOCATION,\
autoscalingAlgorithm=THROUGHPUT_BASED,\
maxNumWorkers=$MAX_WORKERS,\
workerMachineType=$WORKER_TYPE
排解無法重試的錯誤
常見的非重試錯誤包括：
- 不支援的 BSON 型別
- 用做
_id的不支援 BSON 型別 - 不支援 0L 做為
_id - 文件大小超過 Firestore 的 4 MB 上限
無法重試的錯誤會儲存在 Cloud Storage bucket 中，位置由 Dataflow 範本的 deadLetterQueueDirectory 參數指定。
檢查無效信件佇列 (DLQ)
所有處理作業停止後 (表示系統不會處理任何有效流量，也不會重試任何發生錯誤的事件)，發生錯誤的事件就會保留在 Cloud Storage 中。
您可以檢查交易寫入事件，確認處理作業已停止，且沒有處理輸送量，也沒有產生新的記錄項目。
您可以直接從 Cloud Storage 檢查 DLQ：
- 前往 DLQ_LOCATION 環境變數中指定的 Cloud Storage 位置。
在根據時間戳記建構的巢狀資料夾樹狀結構中，展開資料夾即可查看佇列中的最新內容。檔案可能已分片，如下列範例所示：
檢查每個檔案，查看未套用至目的地資料庫的文件和更新。每則訊息都會包含原始事件的酬載和發生的例外狀況。
出現可重試錯誤的可能性極低，尤其是使用
dlqMaxRetryCount參數的低值時，但一般來說，因上述原因而進入 DLQ 的事件無法重試。您可以選擇中止遷移作業，並將應用程式流量恢復至來源資料庫，解決來源資料庫中的 Firestore 資料限制，然後重新執行整個遷移程序；也可以針對每個 DLQ 事件解決資料問題，然後重試處理這些事件。
針對每個 DLQ 檔案中的每一列，您可以：
編輯文件酬載，將不支援的資料類型轉換為替代資料類型。文件酬載會採用標準擴充 JSON 格式。以標準擴充 JSON 格式表示新的資料類型。
將 0L 文件
_id重新指派給新的 Long，或指派給其他資料類型，例如 String。如果現有程式碼預期_id全為 Long，重新指派至其他資料類型可能需要變更應用程式邏輯。如果文件超過 Firestore 的 4 MB 限制，可以將文件分成較小的檔案，或是壓縮內容。不過，這需要變更應用程式邏輯來處理資料。
從 DLQ 檔案中刪除資料列，忽略該事件。
如要修改 DLQ 檔案，您必須在本地下載 .json 檔案，修改內容，然後重新上傳至相同的 Cloud Storage 位置，覆寫原始檔案。如果檔案中參照的所有文件都可以安全地從遷移作業中排除，則可以刪除整個檔案。
修改 DLQ 檔案後，您可以在 retryDLQ 模式下，透過遷移 Dataflow 範本重新執行這些事件。
下列指令會啟動新的 Dataflow 管道，只處理 Dead Letter Queue 中的項目：
DLQ_START_TIME="$(date +'%Y%m%d%H%M%S')"
gcloud dataflow flex-template run "dataflow-mongodb-to-firestore-$DLQ_START_TIME" \
--template-file-gcs-location gs://dataflow-templates-us-central1/latest/flex/Cloud_Datastream_MongoDB_to_Firestore \
--region $LOCATION \
--num-workers $NUM_WORKERS \
--temp-location $TEMP_OUTPUT_LOCATION \
--additional-user-labels "" \
--parameters inputFilePattern=$INPUT_FILE_LOCATION,\
inputFileFormat=avro,\
fileReadConcurrency=10,\
connectionUri=$FIRESTORE_CONNECTION_URI,\
databaseName=$FIRESTORE_DATABASE_NAME,\
shadowCollectionPrefix=shadow_,\
batchSize=500,\
deadLetterQueueDirectory=$DLQ_LOCATION,\
dlqRetryMinutes=10,\
dlqMaxRetryCount=500,\
processBackfillFirst=false,\
runMode=retryDLQ,\
directoryWatchDurationInMinutes=10,\
streamName=$DATASTREAM_NAME,\
stagingLocation=$STAGING_LOCATION,\
autoscalingAlgorithm=THROUGHPUT_BASED,\
maxNumWorkers=$MAX_WORKERS,\
workerMachineType=$WORKER_TYPE