本文說明如何排解及解決移轉和代理程式問題,以及如何找到代理程式記錄,協助您排解問題。
錯誤
下表說明轉移錯誤訊息和解決方法:
| 錯誤訊息 | 錯誤類型 | 錯誤代表的意義 | 如何解決錯誤 |
|---|---|---|---|
| 在轉移期間修改 | 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 | 移轉代理程式的權限不足,無法執行作業。這項錯誤有兩種可能原因:
|
請確認下列事項:
|
| 物件受 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 呼叫。
確認服務帳戶具備下列角色:
|
| 不支援代理 | AGENT_UNSUPPORTED_VERSION | 代理程式版本與 Storage 移轉服務不再相容。 | 這是暫時性錯誤,與代理程式更新失敗有關。如果發生這種情況,請按照下列步驟操作:
|
| 雜湊不相符,因此失敗 | 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.ERRORagent.FATALagent.INFO
傳輸速度緩慢
如果資料轉移時間過長,請檢查下列事項:
檔案系統的讀取處理量應約為所需上傳速度的 1.5 倍。您可以使用 FIO 測試檔案系統的讀取處理量。
安裝 fio:
sudo apt install -y fio建立新目錄
fiotest:TEST_DIR=/mnt/mnt_dir/fiotestsudo 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」的行代表所有執行緒的總頻寬,可用來代表讀取處理量。
使用 iPerf3 檢查 Storage 移轉服務可用的網際網路頻寬。
確認每個移轉代理程式至少有 4 個 vCPU 和 8 GB 的 RAM。
如果確認上述條件後,傳輸時間仍過長,可以新增代理程式,增加資料檔案系統的並行連線數量。
如要進一步瞭解如何充分提升移轉代理程式的效能,請參閱「代理程式最佳做法」。
排解代理錯誤
下列各節說明如何排解及解決移轉代理程式錯誤:
代理程式未連線
如果 Google Cloud 控制台未顯示轉移代理程式已連線:
確認代理程式可以連線至 Cloud Storage API:
在轉移代理程式所在的機器上執行下列指令,測試代理程式與 Cloud Storage API 的連線:
gcloud storage cp test.txt gs://my-bucket更改項目:
my-bucket:Cloud Storage bucket 的名稱。
如果專案使用 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 指令,請參閱「安裝及執行移轉代理程式」。