排解檔案系統傳輸問題

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

錯誤

下表說明轉移錯誤訊息及其解決方法：

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

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

  2. 如果專案使用 VPC Service Controls，請查看代理程式記錄，找出錯誤。如果 VPC Service Controls 設定錯誤，INFO 代理程式記錄會包含下列錯誤：

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

    在這個輸出內容中：

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

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

代理伺服器拒絕 IP 位址

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

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

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

如果您使用其他端點存取 googleapis.com (例如 Private Service Connect)，請將 googleapis.com 替換為其他端點。