管理移轉代理程式

Storage 移轉服務代理程式是在開放容器倡議 (OCI) 容器中執行的應用程式，可與 Storage 移轉服務協調，以利進行涉及檔案系統或與 S3 相容的儲存空間的移轉作業。

根據預設，Storage 移轉服務會使用 Docker 建構及執行 OCI 容器。Storage 移轉服務也支援使用 Podman 管理容器，但您必須使用 podman run 指令安裝代理程式，才能使用 Podman。

如果轉移作業不涉及檔案系統或與 S3 相容的儲存空間，則不需要設定代理程式。

從 Amazon S3 轉移資料時，不需要代理程式。S3 相容儲存空間是指使用 S3 API，但並非由 Amazon 直接代管的儲存空間系統。

本文說明如何在伺服器上管理移轉代理程式。

總覽

• 代理程式程序是動態的。執行轉移作業時，您可以新增代理程式來提升效能。新啟動的代理程式會加入指派的代理程式集區，並執行現有轉移作業的工作。您可以藉此調整執行的代理程式數量，或根據轉移需求變化調整轉移效能。

• 代理程式程序是容錯集體。如果其中一個代理程式停止執行，其餘代理程式會繼續工作。如果所有代理程式都停止運作，當您新增代理程式時，轉移作業會從代理程式停止運作的位置繼續。這樣一來，您就不必監控代理程式、重試轉移作業，或實作復原邏輯。您可以透過 Google Kubernetes Engine 協調代理程式，修補、移動及動態擴充代理程式集區，且不會發生轉移停機時間。

  舉例來說，您在兩個代理程式執行期間提交兩項轉移作業。如果其中一個代理因機器重新啟動或作業系統修補程式而停止運作，其餘代理會繼續運作。這兩項轉移作業仍在進行中，但由於只有一個代理程式在移動資料，因此速度較慢。如果剩餘的代理程式也停止運作，由於沒有代理程式正在執行，所有轉移作業都會停止。重新啟動代理程式程序後，傳輸作業會從上次中斷處繼續。

• 代理程式程序屬於集區，會平行移動資料。因此，集區中的所有代理程式都必須有權存取您要轉移的所有資料來源。

  舉例來說，如果您要從特定檔案系統轉移資料，就必須將檔案系統掛接到代理程式集區中裝載代理程式的每部機器。如果集區中的部分代理程式可以存取資料來源，其他代理程式則無法，從該資料來源進行的轉移作業就會失敗。

事前準備

設定轉移作業前，請先確認您已設定存取權：使用者和服務帳戶。

如要使用 gcloud 指令，請安裝 gcloud CLI。

安裝並執行轉移代理程式

重要事項： 能夠建立轉移作業的使用者，可以從代理程式可存取的任何檔案系統目錄擷取資料，並將資料下載至該目錄。如果代理程式以根層級執行，並取得整個檔案系統的存取權，惡意行為人可能就能接管主機。強烈建議您限制代理程式存取權，只允許存取必要目錄。

建議每個代理程式集區至少安裝三個代理程式，最好是安裝在不同的機器上。如要進一步瞭解如何判斷要執行的代理程式數量，請參閱「發揮轉移代理程式的最佳效能」。

請勿在代理程式 ID 前置字元中加入個人識別資訊 (PII) 或安全性資料等私密資訊。資源名稱可能會傳播至其他 Google Cloud 資源的名稱，並向專案外部的 Google 內部系統公開。

如要安裝及執行轉移代理程式，請按照下列步驟操作：

Google Cloud 控制台

1. 前往 Google Cloud 控制台的「Agent pools」頁面。

   前往代理程式集區

2. 選取要新增代理程式的代理程式集區。

3. 按一下「安裝代理程式」。

4. 按照操作說明安裝及執行代理程式。

   如要進一步瞭解代理程式的指令列選項，請參閱「代理程式指令列選項」。

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 和密鑰：

  sudo docker run --ulimit memlock=64000000 -d --rm \
  -v HOST_DIRECTORY:CONTAINER_DIRECTORY \
  -v PATH/TO/KEY.JSON:/etc/gcloud/key.json:ro \
  -e AWS_ACCESS_KEY_ID=AWS_ACCESS_KEY_ID \
  -e AWS_SECRET_ACCESS_KEY=AWS_SECRET_ACCESS_KEY \
  gcr.io/cloud-ingest/tsop-agent:latest \
  --project-id=PROJECT_ID \
  --creds-file=/etc/gcloud/key.json \
  --hostname=$(hostname) \
  --agent-pool=POOL_NAME
  

• --gcs-api-endpoint=storage.LOCATION.rep.googleapis.com 指定 Cloud Storage 區域端點。指定 Cloud Storage 區域端點後，透過代理程式的所有資料傳輸流量都會保留在該 Google Cloud 區域內。詳情請參閱「區域端點」。

• --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 值	記憶體上限設定
  6g	6 GB
  6gb	6 GB
  6GiB	6 GiB

  注意： 這個標記不會限制容器記憶體總量，請將這個值設為容器 RAM 總量的 50% 至 60%，以免發生 OOM 錯誤。

• --network=DOCKER_NETWORK：為這個容器指定 Docker 網路。指定 --network=host 可減少網路負擔，進而提升效能，但容器會取得主機網路的完整存取權。

• --kerberos-disable-pa-fx-fast 會禁止代理程式使用 FAST 協商與 Kerberos 進行 HDFS 轉移作業。如果 Kerberos 金鑰分配中心 (KDC) 不支援 FAST 協商，請使用這個旗標。

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 格式的服務帳戶金鑰。方法如下：

1. 將金鑰的主體機器位置掛接至容器上的任何路徑。例如：-v $HOME/.config/gcloud/credentials.json:/key.json:ro。這表示金鑰位於主體機器上的 $HOME/.config/gcloud/credentials.json，且應掛接為容器上的 /key.json。ro 表示檔案在容器中為唯讀。
2. 將金鑰的容器路徑指定為 --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 值	記憶體上限設定
  6g	6 GB
  6gb	6 GB
  6GiB	6 GiB

  注意： 這個標記不會限制容器記憶體總量，請將這個值設為容器 RAM 總量的 50% 至 60%，以免發生 OOM 錯誤。

• --network=DOCKER_NETWORK：為這個容器指定 Docker 網路。指定 --network=host 可減少網路負擔，藉此提升效能，但會允許容器完整存取主機的網路。

• --kerberos-disable-pa-fx-fast 會禁止代理程式使用 FAST 協商與 Kerberos 進行 HDFS 轉移作業。如果 Kerberos 金鑰分配中心 (KDC) 不支援 FAST 協商，請使用這個旗標。

疑難排解

如果 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 不會變更作業系統設定的標籤。

確認服務專員連線

如要確認代理程式已連線，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Agent pools」頁面。

   前往代理程式集區

   系統會顯示代理程式集區，以及已連線的代理程式數量。

2. 選取代理程式集區，即可查看已連線代理程式的詳細資料。

如果新代理程式在建立後 10 分鐘內未顯示在代理程式集區頁面，請參閱「代理程式未連線」。

監控代理活動

您可以使用 Cloud Monitoring 監控代理程式活動。

您可以監控 project、agent_pool 和 agent_id 維度。

您可以根據這項監控資料設定快訊，在轉移作業發生潛在問題時收到通知。如要這麼做，請針對下列任一 Google Cloud 指標建立快訊：

指標名稱	說明內容	建議用途
storagetransfer.googleapis.com/agent/transferred_bytes_count	評估特定代理程式在特定時間點，跨所有服務工作移動資料的速度。	成效下滑警示。
storagetransfer.googleapis.com/agent/connected	布林值，如果 Google Cloud 最近收到代理程式的心跳訊息，則為 True。	代理程式失敗警示 低於您認為可維持合理效能的必要客服人員數量 回報代理程式電腦的問題

服務專員更新

為確保 Storage 移轉服務 代理程式具備最新功能、安全性修補程式和錯誤修正項目，您必須定期以新容器取代舊容器。

最新的代理程式容器映像檔位於 Artifact Registry 的 latest 標記下方：gcr.io/cloud-ingest/tsop-agent。

如有新映像檔可用，請更換代理程式。您可以分批更換，以免影響進行中的轉移作業。啟動新代理程式前，請務必先提取新的容器映像檔，避免使用電腦中舊的快取版本。

比較容器版本

如要查看執行中容器的容器版本，請擷取其資訊清單摘要的前 12 個字元：

sudo docker inspect --format='{{index .RepoDigests 0}}' $(sudo docker inspect --format='{{.Image}}' CONTAINER_ID) | sed 's/.*sha256://' | cut -c1-12

將這個簡短摘要與 Artifact Registry 中發布的「名稱」欄進行比較。

如要在指令列中查看最新摘要，請執行 docker pull gcr.io/cloud-ingest/tsop-agent:latest 下載最新映像檔，然後執行下列指令查看簡短摘要：

docker inspect --format='{{index .RepoDigests 0}}' gcr.io/cloud-ingest/tsop-agent:latest | sed 's/.*sha256://' | cut -c1-12

可更新容器

如要對代理程式執行滾動式更新，請按照下列步驟操作：

gcloud CLI

1. 在每部機器上，從 Artifact Registry 提取最新的容器映像檔：

   sudo docker pull gcr.io/cloud-ingest/tsop-agent:latest

2. 列出這部電腦上執行的所有代理程式：

   sudo docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

3. 刪除單一代理程式：

   gcloud transfer agents delete --ids=CONTAINER_ID

4. 安裝一個新代理程式：

   gcloud transfer agents install --pool=POOL_NAME --count=1 \
   --mount-directories=MOUNT_DIRECTORIES
   

重複上述步驟，直到所有電腦上的所有代理程式都已替換完畢。

Docker

1. 在每部機器上，從 Artifact Registry 提取最新的容器映像檔：

   sudo docker pull gcr.io/cloud-ingest/tsop-agent:latest

2. 列出這部電腦上執行的所有代理程式：

   sudo docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

3. 停止一個代理程式：

   sudo docker stop CONTAINER_ID

4. 安裝一個新代理程式：

   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
   

重複上述步驟，直到所有電腦上的所有代理程式都已替換完畢。

Podman

1. 在每部機器上，從 Artifact Registry 提取最新的容器映像檔：

   sudo podman pull gcr.io/cloud-ingest/tsop-agent:latest

2. 列出這部電腦上執行的所有代理程式：

   sudo podman container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

3. 停止一個代理程式：

   sudo podman stop CONTAINER_ID

4. 安裝一個新代理程式：

   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
   

重複上述步驟，直到所有電腦上的所有代理程式都已替換完畢。

代理二進位檔更新

除了容器更新之外，更新指令碼也會在容器內執行，自動擷取最新的代理程式二進位檔。容器執行時，這項指令碼每 5 分鐘會輪詢一次，確認是否有二進位更新。系統會自動套用二進位更新，無須重新啟動容器。

如果停用自動更新，我們可能無法支援舊版代理程式的效能問題偵錯。在這種情況下，我們通常會要求您更新至最新版本，才會提供進一步支援。

停止代理程式

如要停止服務專員，請在服務專員的容器 ID 上執行 docker stop 或 podman stop。 如要找出 ID 並停止代理程式，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「Agent pools」頁面。

   前往代理程式集區

2. 選取要停止的代理程式所在的代理程式集區。

3. 從清單中選取代理程式。使用「篩選器」欄位搜尋前置字元、服務專員狀態、服務專員年齡等。

4. 按一下「停止代理程式」，畫面會顯示 docker stop 指令和特定容器 ID。

5. 在執行代理程式的電腦上執行指令。

   附註： 如果您使用 Podman，請將指令中的 docker 替換為 podman。

   如果停止指令執行成功，會傳回容器 ID。

停止後，代理程式會在代理程式集區清單中顯示為「已中斷連線」。

重新啟動代理程式

停止的代理程式無法重新啟動。請改為將新代理程式安裝至代理程式集區。

刪除代理程式

如要刪除特定代理程式，請列出在電腦上執行的代理程式。

Docker

sudo docker container list --all --filter ancestor=gcr.io/cloud-ingest/tsop-agent

Podman

sudo podman 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 移轉服務會先計算來源和目的地的資料，判斷上次移轉後新增、更新或刪除的來源檔案，這麼做是為了減少從電腦傳送的資料量、有效率地使用頻寬，並縮短傳輸時間。

為偵測檔案是否已變更，我們會檢查來源檔案的上次修改時間和大小，並與上次複製檔案時記錄的上次修改時間和大小進行比較。偵測到新檔案或變更的檔案時，我們會將整個檔案複製到目的地。如要進一步瞭解檔案的新鮮度，請參閱「資料一致性詳細資料」。

根據預設，我們會偵測來源中刪除的檔案，但不會採取任何行動。建立或編輯轉移作業時，如果選擇「刪除來源中沒有的目的地檔案」同步選項，轉移作業就會刪除目的地中的對應物件。

如果選擇「來源位置中沒有的檔案也會從目標位置刪除」同步選項，來源位置中意外刪除的檔案也會從目標位置刪除。為避免因意外刪除而造成資料遺失，建議您選擇使用這個選項時，在目標值區中啟用物件版本管理功能。這樣一來，如果意外刪除檔案，就能將 Cloud Storage 中的物件還原為舊版。

資料一致性詳細資料

如果轉移作業成功，系統會轉移作業執行期間存在且未修改的所有來源檔案。如果來源檔案是在轉移期間建立、更新或刪除，目的地資料集可能不會反映這些變更。

Storage 移轉服務會根據檔案的上次修改時間和大小，判斷檔案是否已變更。如果檔案更新後，上次修改時間或大小未變更，且您啟用 delete-objects-from-source 選項，則該變更可能會導致資料遺失。

使用 delete-objects-from-source 功能時，強烈建議您在轉移期間凍結來源的寫入作業，以防資料遺失。

如要凍結來源的寫入作業，請執行下列任一操作：

• 複製要轉移的目錄，然後將複製的目錄做為轉移來源。
• 停止寫入來源目錄的應用程式。

如果需要擷取傳輸期間發生的變更，您可以重新執行傳輸作業，或在作業執行期間將來源檔案系統設為唯讀。

由於 Cloud Storage 沒有目錄的概念，因此不會移轉空白來源目錄。

重要事項： 強烈建議您先確認轉移作業是否成功，再刪除來源資料。這項服務無法還原 Cloud Storage 中的資料。