排解檔案系統傳輸問題

本文說明如何排解及解決移轉和代理程式問題,以及如何找到代理程式記錄,協助您排解問題。

錯誤

下表說明轉移錯誤訊息和解決方法:

錯誤訊息 錯誤類型 錯誤代表的意義 如何解決錯誤
在轉移期間修改 FILE_MODIFIED_FAILURE 每次 Storage 移轉服務嘗試複製來源檔案時,來源檔案都會在移轉期間遭到修改。 在下次 Storage 移轉服務作業期間,禁止寫入指定檔案。
無法移轉 PRECONDITION_FAILURE 每次 Storage 移轉服務嘗試上傳檔案時,與來源檔案相關聯的 Cloud Storage 物件都會遭到修改。 建立移轉工作時,請使用不重複的 Cloud Storage 物件前置字串,避免多項移轉工作將同一個檔案寫入同一個 Cloud Storage bucket。
找不到來源目錄 SOURCE_DIR_NOT_FOUND 指定的來源路徑不正確,或是路徑正確,但並非所有代理程式都能存取該路徑。 檢查移轉工作設定,並確認下列事項:
找不到工作的來源或目的地目錄 ROOT_DIR_NOT_FOUND 指定來源/目的地路徑不正確,或是路徑正確,但並非所有代理程式都能存取該路徑。 檢查移轉工作設定,並確認下列事項:
找不到檔案 FILE_NOT_FOUND_FAILURE 系統找到來源檔案,但在轉移至 Cloud Storage 前就已刪除。 如果檔案誤遭刪除,請還原檔案,以便在下次移轉工作中上傳。
找不到目的地 bucket BUCKET_NOT_FOUND Cloud Storage 中沒有目的地 bucket。 確認目的地 bucket 拼寫正確且確實存在。
找不到內部中繼資料物件 METADATA_OBJECT_
NOT_FOUND_FAILURE
Storage 移轉服務會將中繼資料儲存在目的地 bucket 中,並加上前置字串 storage-transfer。如果中繼資料檔案在對應的移轉作業完成前遭到刪除,就會顯示這則錯誤訊息。 在所有轉移工作完成前,請勿刪除目的地 bucket 中前置字串為 storage-transfer/ 的物件。
檔案名稱無效,因此無法建立 INVALID_FILE_NAME 來源檔案的路徑無效。 請檢查並修正指定的檔案路徑。確認路徑使用 Cloud Storage 支援的字元。
儲存空間級別無效,因此失敗 INVALID_FILE_STORAGE_CLASS 指定來源的儲存空間級別不允許讀取。 請參閱雲端服務供應商的說明文件,瞭解如何將資料移至允許複製資料的儲存空間級別。
支援續傳的上傳作業工作階段 URI 無效,因此失敗 SESSION_URI_INVALID 支援續傳的上傳作業 ID 或工作階段 URI 已過期或取消。 系統不正確地重試失敗作業。請與支援團隊聯絡。
檔案大小無效,因此失敗 INVALID_FILE_SIZE 檔案大小無效。 如要轉移至 Cloud Storage,請確認檔案大小介於 0 至 5 TiB (Cloud Storage 物件大小上限) 之間。
因權限問題而失敗 PERMISSION_FAILURE 和 UNAUTHENTICATED 移轉代理程式的權限不足,無法執行作業。這項錯誤有兩種可能原因:
  • 代理的 Google Cloud 權限不足。
  • 代理程式對來源檔案系統的權限不足,無法讀取檔案或目錄。

請確認下列事項:

  • 確認代理程式具備下列 IAM 角色:
    • roles/storagetransfer.transferAgent
    • 所有目的地或中繼 bucket 的 roles/storage.objectUser

    您可以將上述任一角色授予代理使用的服務帳戶,或讓具備這些角色的使用者在安裝代理時使用預設憑證。

  • 確認每個代理程式都能讀取來源檔案系統上的所有路徑。
物件受 bucket 的資料保留政策規範,無法刪除、覆寫或封存 PERMISSION_FAILURE 值區設有資料保留政策,且物件已存在於值區中。Storage 移轉服務無法覆寫 bucket 中的現有物件。如果檔案在來源端有所變更,或 Storage 移轉服務因網路狀況而嘗試上傳兩次,且第一次上傳成功,系統就會顯示這則錯誤訊息。 確認 Cloud Storage bucket 中的資料符合預期。您可以重新執行工作,確認沒有任何錯誤,藉此確認來源檔案的大小和修改時間 (mtime) 與 Cloud Storage 物件對應項目相符。
服務權限不足 SERVICE_PERMISSION_FAILURE Storage 移轉服務的權限不足,無法執行作業。 Storage 移轉服務會使用服務代理 (通常格式為 project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com) 存取資源。如要判斷特定 PROJECT_NUMBER,請使用 googleserviceaccounts.get API 呼叫。 確認服務帳戶具備下列角色:
  • 專案的 roles/storagetransfer.serviceAgent。
  • 所有目的地或中繼值區的 roles/storage.objectCreator、roles/storage.objectViewer 和 roles/storage.legacyBucketReader (請參閱「設定接收器的存取權:Cloud Storage」)。
不支援代理 AGENT_UNSUPPORTED_VERSION 代理程式版本與 Storage 移轉服務不再相容。 這是暫時性錯誤,與代理程式更新失敗有關。如果發生這種情況,請按照下列步驟操作:
  1. 停止所有代理。
  2. 執行下列指令,提取最新的 Docker 映像檔: sudo docker pull gcr.io/cloud-ingest/tsop-agent:latest
  3. 發出 Docker run 指令,啟動所有代理程式容器。
如果問題仍未解決,請與支援團隊聯絡。
雜湊不相符,因此失敗 HASH_MISMATCH_FAILURE Storage 移轉服務每次嘗試上傳這個檔案時,上傳的位元組都會損毀。這會導致地端部署檔案的雜湊與產生的 Cloud Storage 物件雜湊不符。 這項錯誤可能是由多個潛在問題所造成。如果大型移轉作業中雜湊不符失敗的比例很低 (低於 1%),請重試失敗的檔案。如果雜湊不相符失敗率偏高 (1% 以上),建議您調查代理程式機器上潛在的記憶體、CPU 或其他硬體故障。
不支援檔案模式,因此失敗 UNSUPPORTED_FILE_MODE Storage 移轉服務遇到不支援模式的檔案,例如裝置、通訊端、命名管道或不規則檔案。 從來源目錄中移除這些特殊檔案類型。
檔案系統發生錯誤,因此失敗 FILESYSTEM_ERROR 代理程式在執行檔案系統作業 (例如讀取、搜尋或統計) 時,發生檔案系統或作業系統錯誤。 請參閱失敗說明,瞭解哪個檔案系統作業失敗。確認地端部署代理程式可存取檔案系統,且檔案系統可回應基本檔案作業。
檔案系統空間不足,因此失敗 FILESYSTEM_NO_SPACE_ON_DEVICE 代理程式在執行檔案系統作業 (例如開啟或寫入) 時,空間不足。 請參閱失敗說明,瞭解哪項檔案系統作業失敗。確認檔案系統有足夠的空間執行檔案作業。
發生不明錯誤,因此失敗 UNKNOWN_FAILURE 發生未預期的錯誤。 請參閱失敗說明。如果失敗說明未提供足夠資訊來解決問題,請與支援團隊聯絡。
規格無效,因此失敗 INVALID_SPEC 代理收到損毀的內部規格。 請檢查代理主機上的資料是否損毀,如果找不到任何損毀,請與支援團隊聯絡。
資訊清單檔案空白或無效,因此失敗 CONFORMANCE_FAILURE 代理程式無法讀取或取得有效的 CSV 位元組,因為格式或 CSV 項目無效。 請確認資訊清單項目是有效的檔案路徑。如果失敗說明中的資訊不足以解決問題,請與支援團隊聯絡。
發生權限遭拒錯誤,因此改為支援續傳的上傳作業,而非多部分上傳作業 PERMISSION_FAILURE 這項移轉作業已啟用分段上傳功能,但值區未設定正確權限。 如要瞭解必要權限,請參閱「設定接收器的存取權:Cloud Storage」。
項目未依順序列出 INCOMPATIBLE_LIST_ORDER_FAILURE 來源檔案系統傳回的檔案清單順序與 Storage 移轉服務不相容。Storage 移轉服務要求來源檔案系統按照字典順序傳回檔案。 確認檔案系統會按照字典排列順序傳回檔案。

查看代理記錄

代理記錄包含與代理程序相關的資訊,可協助您排解代理連線問題。如果代理程式在 Google Cloud 控制台中列為已連線,但移轉作業失敗,請參閱「查看錯誤詳細資料」,瞭解移轉錯誤範例。如要查看記錄,瞭解 Storage 移轉服務在移轉期間考量的每個檔案,請參閱「查看移轉記錄」。

根據預設,代理程式記錄會儲存在 /tmp。您可以使用 --log-dir=logs-directory 指令列選項變更位置。

記錄檔名稱如下:

agent.hostname.username.log.log-level.timestamp

記錄名稱元件如下:

  • hostname:代理程式執行所在的主機名稱。
  • username:執行代理程式的使用者名稱。
  • log-level 必須是下列其中一個值:
    • INFO - 資訊訊息
    • ERROR:轉移期間發生錯誤,但轉移工作仍可繼續。
    • FATAL:發生錯誤,導致轉移工作無法繼續。
  • timestamp:時間戳記,格式為 YYYYMMDD-hhmmss.thread-id。

記錄目錄包含各優先順序層級最新記錄的符號連結:

  • agent.ERROR
  • agent.FATAL
  • agent.INFO

傳輸速度緩慢

如果資料轉移時間過長,請檢查下列事項:

  1. 檔案系統的讀取處理量應約為所需上傳速度的 1.5 倍。您可以使用 FIO 測試檔案系統的讀取處理量。

    安裝 fio:

     sudo apt install -y fio
     

    建立新目錄 fiotest:

     TEST_DIR=/mnt/mnt_dir/fiotest
     sudo mkdir -p $TEST_DIR
     

    測試讀取處理量:

     sudo fio --directory=$TEST_DIR --direct=1
        --rw=randread --randrepeat=0 --ioengine=libaio --bs=1M --iodepth=8
        --time_based=1 --runtime=180 --name=read_test --size=1G
     

    執行上述指令後,Fio 會產生報表。標示為「bw」的行代表所有執行緒的總頻寬,可用來代表讀取處理量。

  2. 使用 iPerf3 檢查 Storage 移轉服務可用的網際網路頻寬。

  3. 確認每個移轉代理程式至少有 4 個 vCPU 和 8 GB 的 RAM。

如果確認上述條件後,傳輸時間仍過長,可以新增代理程式,增加資料檔案系統的並行連線數量。

如要進一步瞭解如何充分提升移轉代理程式的效能,請參閱「代理程式最佳做法」。

排解代理錯誤

下列各節說明如何排解及解決移轉代理程式錯誤:

代理程式未連線

如果 Google Cloud 控制台未顯示轉移代理程式已連線:

  1. 確認代理程式可以連線至 Cloud Storage API:

    1. 在轉移代理程式所在的機器上執行下列指令,測試代理程式與 Cloud Storage API 的連線:

      gcloud storage cp test.txt gs://my-bucket

      更改項目:

      my-bucket:Cloud Storage bucket 的名稱。

  2. 如果專案使用 VPC Service Controls,請查看代理記錄,瞭解是否有錯誤。如果 VPC Service Controls 設定錯誤,INFO 代理記錄會包含下列錯誤:

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    在這個輸出內容中:

代理程式已連線,但工作失敗

如果代理程式顯示為已連線,但移轉工作失敗,請查看失敗工作的錯誤詳細資料。

Proxy 拒絕 IP 位址

如果您在 Squid 等 Proxy 後方執行,並使用許可清單,則可能會因為使用 IP 位址而非主機名稱,而導致要求遭到拒絕。

如要解決這個問題,請使用 docker run 指令執行代理程式,並新增下列旗標:

--transfer-service-endpoint=storagetransfer.googleapis.com:443

如果您使用替代端點連線至 googleapis.com (例如 Private Service Connect),請將 googleapis.com 替換為替代端點。

代理程式無法使用自行簽署的憑證連線至 HTTPS 端點

如果代理程式無法使用自行簽署憑證連線至 HTTPS 端點,請使用額外的 -v 選項,將自訂憑證套件掛接至容器的預設位置 (/etc/ssl/certs)。

如要執行這項操作,請修改 docker run 指令,加入下列旗標:

-v PATH_TO_LOCAL_CERT:/etc/ssl/certs/ca-certificates.crt

更改項目:

  • PATH_TO_LOCAL_CERT:自訂憑證檔案的路徑。

代理無法啟動:KDC 未適當回應 FAST 協商

嘗試啟動 HDFS 移轉作業的移轉代理程式時,如果代理程式無法啟動,並傳回類似下列的錯誤:

Failed to start the agent, err = failed to create HDFS client: Couldn't find the hdfs client: no available namenodes: SASL handshake: [Root cause: KRBMessage_Handling_Error] KRBMessage_Handling_Error: AS Exchange Error: AS_REP is not valid or client password/keytab incorrect < KRBMessage_Handling_Error: KDC did not respond appropriately to FAST negotiation

如果 Kerberos 金鑰發布中心 (KDC) 不支援 FAST 協商,就會發生這項錯誤,因為代理程式預設會嘗試使用 FAST 協商進行 HDFS 移轉。

如要解決這個問題,請在啟動代理程式時新增 --kerberos-disable-pa-fx-fast 旗標,防止代理程式使用 FAST 協商。

只有在使用 Docker 或 Podman 執行代理程式時,才支援這個旗標。使用 gcloud transfer agents install 指令時,系統不支援這項功能。

請按照下列方式,將旗標附加至 docker run 或 podman run 指令:

docker run --rm -v /usr/local/transfer_agent:/tmp/transfer_agent \
  gcr.io/cloud-ingest/tsop-agent:latest \
  --project-id=PROJECT_ID \
  --hostname=$(hostname) \
  --kerberos-disable-pa-fx-fast

如要進一步瞭解 docker 和 podman 指令,請參閱「安裝及執行移轉代理程式」。