排查文件系统转移问题

本文档介绍如何排查和解决转移和代理问题，以及如何找到代理日志来帮助您排查问题。

错误

下表介绍转移错误消息以及解决方法：

错误消息 错误类型 错误的含义 如何解决错误
在转移期间被修改 FILE_MODIFIED_FAILURE 每次 Storage Transfer Service 尝试复制源文件时，系统都会在转移过程中修改源文件。 防止在下一次 Storage Transfer Service 操作期间向指定文件写入数据。
转移失败 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 中不存在目标存储分区。 验证目标存储分区的拼写是否正确，以及它是否存在。
找不到内部元数据对象 METADATA_OBJECT_
NOT_FOUND_FAILURE		 Storage Transfer Service 会使用前缀 storage-transfer 将元数据存储在目标存储桶中。如果元数据文件在对应的转移操作完成之前被删除，则会显示此错误。 在所有转移作业完成之前，避免删除目标存储分区中前缀为 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 权限。
  • 由于对源文件系统的权限不足，代理无法读取文件或目录。

请验证以下内容：

  • 确保代理具有以下 IAM 角色：
    • storagetransfer.transferAgent
    • 对所有目标分区拥有 storage.admin 权限

    可向代理使用的服务账号授予上述两种角色之一，或者具有这些角色的用户可以在安装代理时使用自己的默认凭据。

  • 确保每个代理都可以读取源文件系统上的所有路径。
对象受存储分区的保留政策的约束，且无法删除、覆盖或归档 PERMISSION_FAILURE 存储分区具有有效的保留政策，并且存储分区中已存在该对象。Storage Transfer Service 无法覆盖存储桶中的现有对象。如果源文件发生变化，或者 Storage Transfer Service 由于网络状况而两次上传，但第一次上传是成功的，则会显示此错误。 验证 Cloud Storage 存储分区中的数据是否符合您的预期。您可以通过重新运行作业并确认错误，来确认源文件的大小和修改时间 (mtime) 与其 Cloud Storage 对象是否一致。
服务缺少足够的权限 SERVICE_PERMISSION_FAILURE Storage Transfer Service 没有足够的权限来执行操作。 Storage Transfer Service 使用 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 Transfer Service 兼容。 这是一个临时错误，与代理更新错误有关。如果出现这种情况，请执行以下操作：
  1. 停止所有代理。
  2. 通过运行以下命令拉取最新的 Docker 映像：sudo docker pull gcr.io/cloud-ingest/tsop-agent
  3. 发出 Docker run 命令以启动所有代理容器。
如果问题仍然存在，请与支持团队联系。
由于哈希值不匹配而失败 HASH_MISMATCH_FAILURE 每次 Storage Transfer Service 尝试上传此文件时，上传的字节都会损坏。这导致了本地文件的哈希值与生成的 Cloud Storage 对象的哈希值不匹配。 此错误可能是由多种潜在问题造成的。如果您在大型转移作业中看到少量的哈希值不匹配错误（小于 1%），请重试失败的文件。如果发现哈希值不匹配错误的比例很大（1% 或更高），我们建议调查代理机器上可能出现的内存、CPU 或其他硬件故障。
由于文件模式不受支持而失败 UNSUPPORTED_FILE_MODE Storage Transfer Service 遇到一个模式不受支持的文件（例如设备、套接字、已命名的管道或不规则文件）。 从源目录中移除这些特殊文件类型。
由于文件系统出错而失败 FILESYSTEM_ERROR 代理在执行文件系统操作（如读取、查找或统计）时遇到了文件系统或操作系统错误。 阅读失败说明，了解哪些文件系统操作失败。确保文件系统可供本地代理访问，并且可以响应基本文件操作。
由于未知错误而失败 UNKNOWN_FAILURE 出现意外错误。 阅读失败说明。如果失败说明中信息不足以解决问题，请与支持人员联系。
由于规范无效而失败 INVALID_SPEC 代理收到已损坏的内部规范。 请检查代理主机上的数据损坏情况；如果找不到任何损坏情况，请与支持团队联系。
由于清单文件为空或无效而失败 CONFORMANCE_FAILURE 由于格式无效或 CSV 条目无效，代理无法读取或获取有效的 CSV 字节。 确保清单条目是有效的文件路径。如果失败说明中信息不足以解决问题，请与支持人员联系。
由于权限遭拒错误，回退到可续传上传（而未采用分段上传） PERMISSION_FAILURE 此转移作业已启用分段上传，但尚未对存储桶设置正确的权限。 请参阅文件系统权限中的分段上传部分，了解所需的权限。

查看代理日志

代理日志包含与代理进程相关的信息，让您可以排查代理连接问题。如果您的代理在 Google Cloud Console 中列为已连接，并且您遇到了转移失败的问题，请参阅查看错误以查看转移错误示例。如需查看包含转移期间 Storage Transfer Service 记录的每个文件的日志，请参阅查看转移日志。

默认情况下，代理日志存储在 /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”的行表示所有线程的总聚合带宽，可用作读取吞吐量的代理。

  2. 使用 iPerf3 检查 Storage Transfer Service 的可用互联网带宽。

  3. 确保每个转移代理至少具有 4 个 vCPU 和 8GB 的 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

    在此输出中：

代理已连接，但作业失败

如果代理显示为已连接但转移作业失败，请查看失败作业的错误详情。

代理拒绝 IP 地址

如果您在 Squid 等代理后面运行应用并使用许可名单，则可能会因使用 IP 地址而非主机名而导致请求被拒绝。

如需解决此问题，请使用 docker run 命令运行代理，并添加以下标志：

--transfer-service-endpoint=storagetransfer.googleapis.com:443

如果您使用备用端点访问 googleapis.com（例如，对于 Private Service Connect），请将 googleapis.com 替换为备用端点。