Storage 移轉服務代理程式是在開放容器倡議 (OCI) 容器中執行的應用程式，可與 Storage 移轉服務協調，進行涉及檔案系統或與 S3 相容的儲存空間的移轉作業。
根據預設，Storage 移轉服務會使用 Docker 建構及執行 OCI 容器。Storage 移轉服務也支援使用 Podman 管理容器；如要使用 Podman，您必須使用 podman run 指令安裝代理程式。
如果轉移作業不涉及檔案系統或與 S3 相容的儲存空間，則不需要設定代理程式。
與 S3 相容的儲存空間是指使用 S3 API，但並非由 Amazon 直接代管的儲存空間系統。本文說明如何在伺服器上管理移轉代理程式。
總覽
代理程式程序是動態的。在轉移期間，您可以新增代理程式來提升效能。新啟動的代理程式會加入指派的代理程式集區，並執行現有轉移作業的工作。您可以藉此調整執行的代理程式數量，或根據轉移需求變化調整轉移效能。
代理程式程序是容錯集體。如果其中一個代理程式停止執行，其餘代理程式會繼續工作。如果所有代理程式都停止運作，當您新增代理程式時，轉移作業會從代理程式停止運作的位置繼續。這樣一來，您就不必監控代理程式、重試轉移作業，或實作復原邏輯。您可以透過 Google Kubernetes Engine 協調代理程式，修補、移動及動態調整代理程式集區，不必擔心轉移期間發生停機問題。
舉例來說，您在兩個代理程式執行時提交兩項轉移作業。如果其中一個代理程式因機器重新啟動或作業系統修補程式而停止運作，其餘代理程式會繼續運作。這兩項轉移作業仍在進行中，但由於只有一個代理程式在移動資料，因此速度較慢。如果剩餘的代理程式也停止運作，由於沒有代理程式正在執行，所有轉移作業都會停止進度。重新啟動代理程式程序時，傳輸作業會從上次中斷的地方繼續。
代理程式程序屬於集區。這些工作人員會共同平行移動資料。因此，集區中的所有代理程式都必須有相同的存取權，才能存取您要轉移的所有資料來源。
舉例來說，如果您要從特定檔案系統轉移資料，則必須將檔案系統掛接至代理程式集區中裝載代理程式的每部機器。如果集區中的部分代理程式可以存取資料來源，其他代理程式則無法，從該資料來源進行的轉移作業就會失敗。
事前準備
設定轉移作業前，請先確認您已為使用者和服務帳戶設定存取權。
如要使用 gcloud 指令，請安裝 gcloud CLI。
安裝及執行轉移代理程式
建議每個代理程式集區至少安裝三個代理程式，最好是安裝在不同的機器上。如要進一步瞭解如何判斷要執行的代理程式數量，請參閱「發揮轉移代理程式的最佳效能」。
請勿在代理程式 ID 前置字串中加入個人識別資訊 (PII) 或安全性資料等私密資訊。資源名稱可能會傳播至其他 Google Cloud 資源的名稱，並可能向專案外部的 Google 內部系統公開。如要安裝及執行轉移代理程式，請按照下列步驟操作：
Google Cloud 控制台
gcloud CLI
如要使用 gcloud CLI 安裝一或多個代理程式，請執行 gcloud transfer agents install：
gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
--mount-directories=MOUNT_DIRECTORIES
這項工具會引導您完成安裝代理程式的所有必要步驟。這項指令會在電腦上安裝 NUM_AGENTS 代理程式，對應至指定為 POOL_NAME 的集區名稱，並使用 gcloud 憑證驗證代理程式。集區名稱必須存在，否則會傳回錯誤。
--mount-directories 標記為選用項目，但強烈建議使用。這個值是以半形逗號分隔的檔案系統目錄清單，可授予代理程式存取權。如果省略這個標記，系統會將整個檔案系統掛接至代理程式容器。詳情請參閱 gcloud 參考資料。
與 S3 相容的來源
安裝代理程式以搭配 S3 相容來源使用時，您必須提供 AWS 憑證，方法是將憑證設為環境變數 (AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 的值)，或將憑證儲存在系統設定檔中做為預設憑證。
export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=POOL_NAME \
--creds-file=/relative/path/to/service-account-key.json
使用服務帳戶金鑰
如要使用服務帳戶金鑰執行代理程式，請使用 --creds-file 選項：
gcloud transfer agents install --pool=POOL_NAME --count=NUM_AGENTS \
--creds-file=/relative/path/to/service-account-key.json
更多資訊
如需完整的選用標記清單，請執行 gcloud transfer agents install --help 或參閱 gcloud transfer 參考資料。
Docker
使用 Docker 安裝代理程式前，請按照操作說明安裝 Docker。
docker run 指令會安裝一個代理程式。如要增加集區中的代理程式數量，請視需要重複執行這個指令。
安裝代理程式時，您可以選擇使用gcloud預設憑證或服務帳戶進行驗證。
預設憑證
如要讓 Docker 容器透過您的gcloud預設憑證進行驗證，請執行以下指令，建立包含您應用程式預設憑證檔案的 Docker 磁碟區：
sudo docker run -ti --name gcloud-config google/cloud-sdk gcloud auth application-default login
接著使用下列指令安裝代理程式，並使用 --volumes-from 旗標掛接 gcloud-config 憑證磁碟區：
sudo docker run --ulimit memlock=64000000 -d --rm \ --volumes-from gcloud-config \ -v HOST_DIRECTORY:CONTAINER_DIRECTORY \ gcr.io/cloud-ingest/tsop-agent:latest \ --project-id=PROJECT_ID \ --hostname=$(hostname) \ --agent-pool=POOL_NAME
服務帳戶驗證
如要使用服務帳戶憑證安裝及執行轉移代理程式 docker run，請使用 --creds-file 旗標指定 JSON 格式服務帳戶金鑰的路徑。
路徑必須以字串 /transfer_root 做為前置字串。
如要進一步瞭解服務帳戶金鑰，請參閱「建立及管理服務帳戶金鑰」。
sudo docker run --ulimit memlock=64000000 -d --rm \ -v HOST_DIRECTORY:CONTAINER_DIRECTORY \ -v PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \ gcr.io/cloud-ingest/tsop-agent:latest \ --project-id=PROJECT_ID \ --creds-file=/etc/gcloud/key.json \ --hostname=$(hostname) \ --agent-pool=POOL_NAME
選項和旗標
將上述範例中的變數替換成下列資訊：
HOST_DIRECTORY是主機上要複製的目錄。您可以使用多個-v旗標，指定要從中複製的其他目錄。CONTAINER_DIRECTORY是對應至代理程式容器的目錄。必須與HOST_DIRECTORY相同。PROJECT_ID是託管移轉作業的專案 ID。POOL_NAME是要安裝這個代理程式的代理程式集區名稱。如果省略這個旗標，系統會將代理程式安裝到專案的transfer_service_default集區。
docker run 指令支援其他旗標。
--enable-mount-directory會將整個檔案系統掛接至容器的/transfer_root目錄下。如果指定--enable-mount-directory，系統就不會套用使用-v旗標的目錄限制。--creds-file=/etc/gcloud/key.json指定容器中 JSON 格式服務帳戶憑證檔案的路徑。這個檔案會透過指令中的-v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro標記掛接。--enable-s3指定這個代理程式用於從與 S3 相容的儲存空間轉出資料。使用這個選項安裝的代理程式無法用於從 POSIX 檔案系統轉移資料。如果移轉來源是 AWS S3 或與 S3 相容的儲存空間，請使用環境變數傳遞存取金鑰 ID 和私密金鑰：
-e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \ -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY--env HTTPS_PROXY=PROXY指定網路上的轉送 Proxy。PROXY的值是 Proxy 伺服器的 HTTP 網址和通訊埠。請務必指定 HTTP 網址 (而非 HTTPS 網址)，以免在傳輸層安全標準 (TLS) 加密中造成雙重包裝要求。雙重包裝要求會阻止 Proxy 伺服器傳送有效的傳出要求。--agent-id-prefix=ID_PREFIX指定代理程式 ID 的選用前置字串，用於在 Google Cloud 主控台中識別代理程式或其機器。使用前置字元時，代理程式 ID 的格式為prefix + hostname + Docker container ID。--log-dir=LOGS_DIRECTORY會修改代理程式寫入記錄的目錄。預設目錄為/tmp/。如果尚未指定
--enable_mount_directory，則必須以/transfer_root為這個路徑加上前置字元。例如：/transfer_root/logs。--max-physical-mem=MAX_MEMORY：代理程式預設最多使用 8 GiB 的系統記憶體。如果預設值不符合您的環境，可以指定相關的最大記憶體用量，格式如下：max-physical-mem值記憶體上限設定 6g6 GB 6gb6 GB 6GiB6 GiB --network=DOCKER_NETWORK：為這個容器指定 Docker 網路。指定--network=host可減少網路負擔，藉此提升效能，但會允許容器完整存取主機的網路。
Podman
使用 Podman 安裝代理程式前，請先安裝 Podman：
sudo apt-get update
sudo apt-get -y install podman
安裝代理程式時，您可以選擇使用gcloud預設憑證或服務帳戶進行驗證。
預設憑證
如要讓代理程式容器透過 Google Cloud CLI 預設憑證進行驗證，請執行以下指令，建立包含應用程式預設憑證檔案的磁碟區：
gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin gcr.io sudo podman pull gcr.io/google.com/cloudsdktool/google-cloud-cli:stable sudo podman run -ti --replace --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth application-default login
然後使用下列指令安裝代理程式，並使用 --volumes-from 旗標掛接 gcloud-config 憑證磁碟區。這項指令會安裝一個代理程式。如要增加集區中的代理程式數量，請視需要多次重新執行這項指令。
sudo podman run --ulimit memlock=64000000 -d --rm \ --volumes-from gcloud-config \ -v HOST_DIRECTORY:CONTAINER_DIRECTORY \ gcr.io/cloud-ingest/tsop-agent:latest \ --project-id=PROJECT_ID \ --hostname=$(hostname) \ --agent-pool=POOL_NAME
服務帳戶驗證
如要使用服務帳戶憑證安裝及執行轉移代理程式，您必須在容器中提供 JSON 格式的服務帳戶金鑰。方法如下：
- 將金鑰的主機位置掛接到容器上的任何路徑。例如：
-v $HOME/.config/gcloud/credentials.json:/key.json:ro。這表示金鑰位於主機的$HOME/.config/gcloud/credentials.json，且應以/key.json形式掛接至容器。ro表示檔案可供容器以唯讀模式存取。 - 將索引鍵的容器路徑指定為
--creds-file的值。 在先前步驟的範例中，請指定--creds-file=/key.json。
如要進一步瞭解服務帳戶金鑰，請參閱「建立及管理服務帳戶金鑰」。
sudo podman run --ulimit memlock=64000000 -d --rm \ -v HOST_DIRECTORY:CONTAINER_DIRECTORY \ -v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \ gcr.io/cloud-ingest/tsop-agent:latest \ --project-id=PROJECT_ID \ --creds-file=/etc/gcloud/key.json \ --hostname=$(hostname) \ --agent-pool=POOL_NAME
選項和旗標
將上述範例中的變數替換成下列資訊：
HOST_DIRECTORY是主機上要複製的目錄。您可以使用多個-v旗標，指定要從中複製的其他目錄。CONTAINER_DIRECTORY是對應至代理程式容器的目錄。必須與HOST_DIRECTORY相同。PROJECT_ID是託管移轉作業的專案 ID。POOL_NAME是要安裝這個代理程式的代理程式集區名稱。如果省略這個旗標，系統會將代理程式安裝到專案的transfer_service_default集區。
podman run 指令支援其他旗標。
--enable-mount-directory會將整個檔案系統掛接至容器的/transfer_root目錄下。如果指定--enable-mount-directory，系統就不會套用使用-v旗標的目錄限制。--creds-file=/etc/gcloud/key.json指定容器中 JSON 格式服務帳戶憑證檔案的路徑。這個檔案會透過指令中的-v <var>HOST_PATH/TO/KEY.JSON</var>:/etc/gcloud/key.json:ro標記掛接。--enable-s3指定這個代理程式用於從與 S3 相容的儲存空間轉出資料。使用這個選項安裝的代理程式無法用於從 POSIX 檔案系統轉移資料。如果移轉來源是 AWS S3 或與 S3 相容的儲存空間，請使用環境變數傳遞存取金鑰 ID 和私密金鑰：
-e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \ -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY ```--env HTTPS_PROXY=PROXY指定網路上的轉送 Proxy。PROXY的值是 Proxy 伺服器的 HTTP 網址和通訊埠。請務必指定 HTTP 網址 (而非 HTTPS 網址)，以免在傳輸層安全標準 (TLS) 加密中造成雙重包裝要求。雙重包裝要求會阻止 Proxy 伺服器傳送有效的傳出要求。--agent-id-prefix=ID_PREFIX指定代理程式 ID 的選用前置字串，用於在 Google Cloud 主控台中識別代理程式或其機器。使用前置字元時，代理程式 ID 的格式為prefix + hostname + OCI container ID。--log-dir=LOGS_DIRECTORY會修改代理程式寫入記錄的目錄。預設目錄為/tmp/。如果尚未指定
--enable_mount_directory，則必須以/transfer_root為這個路徑加上前置字元。例如：/transfer_root/logs。--max-physical-mem=MAX_MEMORY：代理程式預設最多使用 8 GiB 的系統記憶體。如果預設值不符合您的環境，可以指定相關的最大記憶體用量，格式如下：max-physical-mem值記憶體上限設定 6g6 GB 6gb6 GB 6GiB6 GiB --network=DOCKER_NETWORK：為這個容器指定 Docker 網路。指定--network=host可減少網路負擔，藉此提升效能，但會允許容器完整存取主機的網路。
疑難排解
如果 SELinux 設定要求在掛接到容器的磁碟區內容上加上標籤，請將 :Z 旗標新增至磁碟區：
sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-v HOST_PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/etc/gcloud/key.json:ro \
--hostname=$(hostname) \
--agent-pool=POOL_NAME
如果沒有標籤，安全系統可能會禁止在容器內執行的程序使用內容。根據預設，Podman 不會變更 OS 設定的標籤。
確認服務專員連線
如要確認代理程式已連線，請按照下列步驟操作：
前往 Google Cloud 控制台的「Agent pools」頁面。
系統會顯示代理程式集區，以及已連線的代理程式數量。
選取代理程式集區，即可查看已連線代理程式的詳細資料。
如果新代理程式在建立後 10 分鐘內未顯示在代理程式集區頁面，請參閱「代理程式未連線」。
監控服務專員活動
您可以使用 Cloud Monitoring 監控代理程式活動。
您可以監控 project、agent_pool 和 agent_id 維度。
您可以根據這項監控資料設定快訊，在轉移作業發生潛在問題時收到通知。如要這麼做，請在下列任一 Google Cloud 指標上建立快訊：
| 指標名稱 | 說明內容 | 建議用途 |
|---|---|---|
| storagetransfer.googleapis.com/agent/transferred_bytes_count | 評估特定代理程式在特定時間點，跨所有服務工作移動資料的速度。 | 成效下滑警示。 |
| storagetransfer.googleapis.com/agent/connected | 布林值，針對最近收到心跳訊息的每個代理程式，這個值為 True。 Google Cloud |
|
停止代理程式
如要停止代理程式，請在代理程式的 Docker 容器 ID 上執行 docker stop。如要找出 ID 並停止代理程式，請按照下列步驟操作：
前往 Google Cloud 控制台的「Agent pools」頁面。
選取要停止的代理程式所屬的代理程式集區。
從清單中選取代理程式。使用「篩選器」欄位搜尋前置字元、服務專員狀態、服務專員年齡等。
按一下「停止代理程式」。系統會顯示
docker stop指令和特定容器 ID。在執行代理程式的電腦上執行指令。如果
docker stop指令執行成功，會傳回容器 ID。
停止後，代理程式會在代理程式集區清單中顯示為「已中斷連線」。
重新啟動代理程式
停止的代理程式無法重新啟動。請改為將新代理程式安裝到代理程式集區。
刪除代理程式
如要刪除特定代理程式，請列出在電腦上執行的代理程式：
docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent
然後將代理程式 ID 傳遞至 transfer agents delete：
gcloud transfer agents delete --ids=id1,id2,…
如要刪除機器上執行的所有代理程式，請使用 --all 旗標或 --uninstall 旗標。這兩個旗標都會刪除機器上的所有代理程式；此外，--uninstall 旗標還會解除安裝代理程式 Docker 映像檔。
gcloud transfer agents delete --all
gcloud transfer agents delete --uninstall
檔案系統移轉詳細資料
增量轉移
Storage 移轉服務會先計算來源和目的地的資料，判斷上次轉移後新增、更新或刪除的來源檔案，這麼做是為了減少從電腦傳送的資料量、有效率地使用頻寬，並縮短傳輸時間。
為偵測檔案是否已變更，我們會檢查來源檔案的上次修改時間和大小，並與上次複製檔案時記錄的上次修改時間和大小進行比較。系統偵測到新檔案或變更的檔案時，會將整個檔案複製到目的地。如要進一步瞭解檔案更新間隔，請參閱資料一致性詳細資料。
根據預設，我們會偵測來源中刪除的檔案，但不會採取任何行動。如果建立或編輯時選擇「刪除來源中沒有的目的地檔案」同步選項，轉移作業會刪除目的地中對應的物件。
如果選擇「來源位置中沒有的檔案也會從目標位置刪除」同步選項，來源位置中意外刪除的檔案也會從目標位置刪除。為避免資料因誤刪而遺失，建議您啟用目的地 bucket 的物件版本管理功能。這樣一來，如果不小心刪除檔案，就能將 Cloud Storage 中的物件還原為舊版。
資料一致性詳細資料
如果移轉作業成功，系統會移轉所有來源檔案，且這些檔案在作業執行期間未經過修改。在轉移期間建立、更新或刪除的來源檔案，可能不會反映在目的地資料集中。
Storage 轉移服務會根據檔案的上次修改時間和大小，判斷檔案是否已變更。如果更新檔案時未變更上次修改時間或大小，且您啟用 delete-objects-from-source 選項，該變更的資料可能會遺失。
使用 delete-objects-from-source 功能時，強烈建議您在轉移期間凍結來源的寫入作業，以免資料遺失。
如要凍結來源的寫入作業，請執行下列任一操作：
- 複製要轉移的目錄，然後將複製的目錄做為轉移來源。
- 停止將資料寫入來源目錄的應用程式。
如果需要擷取傳輸期間發生的變更，您可以重新執行傳輸作業，或在作業執行期間將來源檔案系統設為唯讀。
由於 Cloud Storage 沒有目錄的概念，因此不會移轉空白來源目錄。