排解檔案系統傳輸問題

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

錯誤

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

錯誤訊息 錯誤類型 錯誤代表的意義 如何解決錯誤
檔案在移轉過程中遭到修改 FILE_MODIFIED_FAILURE 每次 Storage 移轉服務嘗試複製來源檔案時，來源檔案都會在移轉期間遭到修改。 在下一次 Storage 移轉服務作業期間，防止寫入指定檔案。
無法移轉 PRECONDITION_FAILURE 每次 Storage Transfer Service 嘗試上傳檔案時，與來源檔案相關聯的 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 中不存在目的地值區。 確認目的地 bucket 的拼字正確無誤，且該 bucket 存在。
找不到內部中繼資料物件 METADATA_OBJECT_
NOT_FOUND_FAILURE		 Storage 移轉服務會將中繼資料儲存在目的地值區，並加上 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
  • 代理程式在來源檔案系統的權限不足，因此無法讀取檔案或目錄。

請確認下列事項：
物件受值區的保留政策限制，無法刪除、覆寫或封存 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 每次 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 已為這項轉移作業啟用多部分上傳功能，但值區未設定正確的權限。 如要瞭解必要權限，請參閱「多部分上傳」一節的 檔案系統權限。
條目順序錯誤 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」的行代表所有執行緒的總匯總頻寬，可用於做為讀取處理量的 Proxy。

  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

    輸出內容如下：

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

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

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，並將路徑設為自訂憑證檔案。