此页面由 Cloud Translation API 翻译。

管理转移代理

Storage Transfer Service 代理是在 Open Container Initiative (OCI) 容器内运行的应用，它们与 Storage Transfer Service 进行协调，以便执行涉及文件系统或 S3 兼容存储空间的转移作业。

默认情况下，Storage Transfer Service 使用 Docker 构建和运行 OCI 容器。Storage Transfer Service 还支持使用 Podman 进行容器管理；您必须使用 podman run 命令安装代理，才能使用 Podman。

如果您的转移作业不涉及到文件系统或兼容 S3 的存储空间，则无需设置代理。

本文档介绍如何在服务器上管理转移代理。

概览

代理进程是动态的。运行转移时，可以添加代理以提高性能。新启动的代理会加入分配的代理池，并通过现有转移作业执行工作。您可以使用此功能调整正在运行的代理数量，或调整转移性能以适应不断变化的转移需求。
代理进程是容错的集合。如果其中一个代理停止运行，则其余代理将继续工作。如果所有代理都停止，则在重启代理时，转移会从代理停止的位置继续进行。这样您就无需监控代理、重试转移或实现恢复逻辑。通过协调代理与 Google Kubernetes Engine，您可以修补、迁移和动态扩缩您的代理池，而无需停止转移。

例如，您在两个代理运行时提交两个转移作业。如果其中一个代理由于机器重启或操作系统修补而停止运行，则其余的代理将继续工作。两个转移作业仍在运行，但由于单个代理正在移动数据，速度会较慢。如果剩余的代理也停止，则所有转移作业会停止进行，因为没有代理正在运行。重启代理进程时，转移会从中断位置恢复。
代理进程在一个池中。它们会以并行方式集体迁移数据。因此，池中的所有代理都必须对您要转移的所有数据源具有相同的访问权限。

例如，如果要从特定文件系统转移数据，则必须将文件系统装载到托管代理池中的代理的每台机器上。如果池中的某些代理可以访问某一数据源，而其他代理无法访问，那么您将无法从该数据源成功转移。

准备工作

在配置转移作业之前，请确保您已配置相应的访问权限：针对用户和服务账号。

如果您要使用 gcloud 命令，请安装 gcloud CLI。

安装并运行转移代理

我们建议为每个代理池安装至少三个代理，并且这些代理最好是安装在不同的机器上。如需详细了解如何确定要运行的代理数量，请参阅最大限度地提高转移代理性能。

请勿在代理 ID 前缀中包含敏感信息，例如个人身份信息 (PII) 或安全数据。资源名称可能会传播到其他 Google Cloud 资源的名称，并且可能会向您项目之外的 Google 内部系统公开。

如需安装并运行转移代理，请执行以下操作：

Google Cloud 控制台

在 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

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:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/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 标志的目录限制。

注意：如果代理以 root 身份运行且被授予整个文件系统的访问权限，恶意操作者可能会获得接管主机的权限。强烈建议您限制代理的访问权限，以仅允许其访问必要的目录。
--creds-file=CREDENTIAL_FILE 指定 JSON 格式的服务账号凭据文件的路径。除非您使用 --enable_mount_directory，否则必须执行以下操作：
1. 使用 -v 标志挂载凭据文件。
2. 在 --creds-file 的路径前添加 /transfer_root 前缀。
例如：
```
-v /tmp/key.json:/tmp/key.json \
--creds-file=/transfer_root/tmp/key.json
```
--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 的值是代理服务器的 HTTP 网址和端口。确保您指定 HTTP 网址（而不是 HTTPS 网址），以避免在 TLS 加密中重复封装请求。重复封装的请求会阻止代理服务器发送有效的出站请求。
--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：代理默认使用 8GiB 系统内存的上限。如果默认环境不适合您的环境，您可以通过以下格式指定相关的最大内存使用量：

max-physical-mem 值内存上限设置

6g 6 GB

6gb 6 GB

6GiB 6 GiB

`max-physical-mem` 值	内存上限设置
`6g`	6 GB
`6gb`	6 GB
`6GiB`	6 GiB

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
  ```

Then use the following command to install an agent, using the
`--volumes-from` flag to mount the `gcloud-config` credentials volume.
The command installs one agent. To increase the number of agents in your
pool, re-run this command as many times as required.

```sh
  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
  ```

服务账号身份验证

如需使用服务账号凭据安装和运行转移代理，请使用 --creds-file 标志指定 JSON 格式的服务账号密钥的路径。

该路径必须以字符串 /transfer_root 为前缀。

如需详细了解服务账号密钥，请参阅创建和管理服务账号密钥。

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/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 标志的目录限制。

注意：如果代理以 root 身份运行且被授予整个文件系统的访问权限，恶意操作者可能会获得接管主机的权限。强烈建议您限制代理的访问权限，以仅允许其访问必要的目录。
--creds-file=CREDENTIAL_FILE 指定 JSON 格式的服务账号凭据文件的路径。除非您使用 --enable_mount_directory，否则必须执行以下操作：
1. 使用 -v 标志挂载凭据文件。
2. 在 --creds-file 的路径前添加 /transfer_root 前缀。
例如：
```
-v /tmp/key.json:/tmp/key.json \
--creds-file=/transfer_root/tmp/key.json
```
--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 的值是代理服务器的 HTTP 网址和端口。确保您指定 HTTP 网址（而不是 HTTPS 网址），以避免在 TLS 加密中重复封装请求。重复封装的请求会阻止代理服务器发送有效的出站请求。
--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：代理默认使用 8GiB 系统内存的上限。如果默认环境不适合您的环境，您可以通过以下格式指定相关的最大内存使用量：

max-physical-mem 值内存上限设置

6g 6 GB

6gb 6 GB

6GiB 6 GiB

`max-physical-mem` 值	内存上限设置
`6g`	6 GB
`6gb`	6 GB
`6GiB`	6 GiB

问题排查

如果您的 SELinux 配置要求在挂载到容器中的卷内容上放置标签，请将 :Z 标志添加到卷中：

sudo podman run --ulimit memlock=64000000 -d --rm \
-v HOST_DIRECTORY:CONTAINER_DIRECTORY:Z \
-v PATH/TO/KEY.JSON:PATH/TO/KEY.JSON \
gcr.io/cloud-ingest/tsop-agent:latest \
--project-id=PROJECT_ID \
--creds-file=/transfer_root/PATH/TO/KEY.JSON
--hostname=$(hostname) \
--agent-pool=POOL_NAME

如果没有标签，安全系统可能会阻止在容器内运行的进程使用相应内容。默认情况下，Podman 不会更改操作系统设置的标签。

确认代理连接

如需确认代理是否已连接，请执行以下操作：

在 Google Cloud 控制台中，转到代理池页面。

转到“代理池”

系统会显示您的代理池以及已连接的代理数量。
选择一个代理池，以查看有关连接的代理的详细信息。

如果新代理在创建后 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 布尔值。	代理故障提醒未达到您认为合理性能所需的代理数量发出代理机器有问题的信号

停止代理

如需停止代理，请在代理的 Docker 容器 ID 上运行 docker stop。如需查找 ID 并停止代理，请执行以下操作：

在 Google Cloud 控制台中，转到代理池页面。

转到“代理池”
选择包含要停止的代理的代理池。
从列表中选择代理。使用过滤条件字段搜索前缀、代理状态、代理存在时间等。
点击停止代理。系统会显示包含特定容器 ID 的 docker stop 命令。
在运行代理的机器上运行该命令。成功的 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 Transfer Service 通过计算源和目标位置的数据来确定自上次转移后新增、更新或删除的源文件，开始所有转移。我们这样做是为了减少从机器发送的数据量，有效利用带宽以及减少转移时间。

为了检测文件是否已更改，我们会检查源文件的最后修改时间和大小，并将其与上次复制文件时记录的修改时间和大小进行比较。当我们检测到新文件或更改后的文件时，我们会将整个文件复制到目标位置。如需详细了解文件新鲜度，请参阅数据一致性详细信息。

默认情况下，我们会检测在来源上删除的文件，但不会对其进行操作。如果在创建或修改时选择同步选项删除源位置中也不存在的目标文件，您的转移将删除目标位置的相应对象。

如果选择同步选项删除源位置中也不存在的目标文件，则在源中意外删除的文件也会在目标位置中删除。为防止意外删除造成数据丢失，如果您选择使用此选项，我们建议您在目标存储分区中启用对象版本控制。如果不小心删除了某个文件，则可以将 Cloud Storage 中的对象恢复为旧版本。

数据一致性详情

成功的转移操作将转移在操作的整个运行期间存在且未修改过的所有源文件。在转移期间创建、更新或删除的源文件可能会也可能不会在目标数据集中反映这些更改。

Storage Transfer Service 会使用文件的上次修改时间和大小来确定其是否已更改。如果更新文件时没有更改其上次修改时间或大小，并且您启用了 delete-objects-from-source 选项，则您可能会丢失此更改中的数据。

使用 delete-objects-from-source 功能时，我们强烈建议您在传输期间冻结对来源的写入，以防止数据丢失。

如需冻结对来源的写入，请执行以下操作之一：

克隆要转移的目录，然后使用克隆的目录作为转移来源。
停止写入源目录的应用。

如果必须捕获转移期间发生的更改，您可以重新运行转移，或者在操作运行时将源文件系统设置为只读。

由于 Cloud Storage 没有目录概念，因此不会转移空的源目录。

管理转移代理

概览

准备工作

安装并运行转移代理

Google Cloud 控制台

gcloud CLI

兼容 S3 的来源

使用服务账号密钥

更多信息

Docker

默认凭据

服务账号身份验证

选项和标志

Podman

默认凭据

服务账号身份验证

选项和标志

问题排查

确认代理连接

监控代理活动

停止代理

删除代理

文件系统转移详情

增量转移

数据一致性详情