排查文件系统转移问题

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

错误

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

错误消息 错误类型 错误的含义 如何解决错误
在转移期间被修改 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 替换为 备用端点。