排查本地转移问题

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

排查 Cloud Console 中的转移错误

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

错误消息 错误类型 错误的含义 如何解决错误
在转移期间被修改 FILE_MODIFIED_FAILURE 每次 Transfer Service for On Premises Data 尝试上传源文件时,源文件在上传期间被修改。 在下一次 Transfer Service for On Premises Data 操作期间,防止向指定文件写入数据。
转移失败 PRECONDITION_FAILURE 每次 Transfer Service for On Premises Data 尝试上传源文件时,与源文件关联的 Cloud Storage 对象都会被修改。 创建转移作业时使用唯一的 Cloud Storage 对象前缀,防止多个转移作业将同一文件写入同一 Cloud Storage 存储分区。
找不到源目录 SOURCE_DIR_NOT_FOUND 指定的源路径不正确,或者路径正确,但并非所有代理都有权访问该路径。 检查转移作业配置并验证:
文件未找到 FILE_NOT_FOUND_FAILURE 找到了源文件,但它在转移到 Cloud Storage 之前将删除。 如果该文件被错误地删除,请进行恢复,以便下一个转移作业可以上传该文件。
找不到目标存储分区 BUCKET_NOT_FOUND Cloud Storage 中不存在目标存储分区。 验证目标存储分区的拼写是否正确,以及它是否存在。
找不到内部元数据对象 METADATA_OBJECT_NOT_FOUND_FAILURE Transfer Service for On Premises Data 会使用前缀 storage-transfer 将元数据存储在目标存储分区中。如果元数据文件在对应的转移操作完成之前被删除,则会显示此错误。 在所有转移作业完成之前,避免删除目标存储分区中前缀为 storage-transfer/ 的对象。
由于文件名无效而失败 INVALID_FILE_NAME 源文件的路径无效。 验证并修复指定的文件路径。验证路径是否使用 Cloud Storage 支持的字符
由于权限问题而失败 PERMISSION_FAILURE 代理没有足够的权限来执行操作。此错误有两种可能性:
  • 代理没有足够的 Google Cloud 权限。
  • 由于对源文件系统的权限不足,代理无法读取文件或目录。
验证以下内容:
  • 确保代理具有以下 IAM 角色:
    • roles/pubsub.editor
    • 对所有目标分区拥有 roles/storage.admin 权限
    可向代理使用的服务帐号授予上述两种角色之一,或者具有这些角色的用户可以在安装代理时使用自己的默认凭据。
  • 确保每个代理都可以读取源文件系统上的所有路径。
服务缺少足够的权限 SERVICE_PERMISSION_FAILURE Transfer Service for On Premises Data 没有足够的权限来执行操作。 Transfer Service for On Premises Data 使用服务帐号 cloud-ingest-dcp@cloud-ingest-prod.iam.gserviceaccount.com 访问资源。验证该服务帐号是否具有以下角色:
  • 对项目拥有 roles/pubsub.editor 权限
  • 对所有目标存储分区拥有 roles/storage.admin 权限。
代理不受支持 AGENT_UNSUPPORTED_VERSION 代理版本不再与 Transfer Service for On Premises Data 兼容。 这是一个临时错误,与代理更新错误有关。如果出现这种情况,请执行以下操作:
  1. 停止所有代理
  2. 通过运行以下命令拉取最新的 Docker 映像:sudo docker pull gcr.io/cloud-ingest/tsop-agent
  3. 发出 Docker run 命令以启动所有代理容器。
如果问题仍然存在,请与支持团队联系。
由于哈希值不匹配而失败 HASH_MISMATCH_FAILURE 每次 Transfer Service for On Premises Data 尝试上传此文件时,上传的字节都会损坏。这导致了本地文件的哈希值与生成的 Cloud Storage 对象的哈希值不匹配。 此错误可能是由多种潜在问题造成的。如果您在大型转移作业中看到少量的哈希值不匹配错误(小于 1%),请重试失败的文件。如果发现哈希值不匹配错误的比例很大(1% 或更高),我们建议调查代理机器上可能出现的内存、CPU 或其他硬件故障。
由于文件模式不受支持而失败 UNSUPPORTED_FILE_MODE Transfer Service for On Premises Data 遇到一个模式不受支持的文件(例如设备、套接字、已命名的管道或不规则文件)。 从源目录中移除这些特殊文件类型。
由于文件系统出错而失败 FILESYSTEM_ERROR 代理在执行文件系统操作(如读取、还原或统计)时遇到了文件系统或操作系统错误。 阅读失败说明,了解哪些文件系统操作失败。确保文件系统可供本地代理访问,并且可以响应基本文件操作。
由于未知错误而失败 UNKNOWN_FAILURE 出现意外错误。 阅读失败说明。如果失败说明中信息不足以解决问题,请与支持人员联系。
由于规范无效而失败 INVALID_SPEC 代理收到已损坏的内部规范。 请检查代理主机上的数据损坏情况;如果找不到任何损坏情况,请与支持团队联系。

查看代理日志

代理日志包含与代理进程相关的信息,让您可以排查代理连接问题。如果您的代理在 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

排查代理错误

以下部分介绍了如何排查和解决本地代理错误:

代理未连接

如果本地转移代理在 Google Cloud Console 中未显示为已连接:

  1. 验证代理是否可以连接到 Cloud Storage API 和 Pub/Sub API,且不存在网络或身份验证问题:

    1. 在转移代理所在的机器上运行以下命令,以测试该代理与 Cloud Storage API 的连接:

      gsutil cp test.txt gs://my-bucket

      您需要将:

      my-bucket 替换为 Cloud Storage 存储分区的名称。

    2. 在转移代理所在的机器上运行以下命令,以测试该代理与 Pub/Sub API 的连接:

      gcloud pubsub topics list --project=project-id

      您需要将:

      project-id 替换为您的 Google Cloud 项目名称。

  2. 如果您的项目使用 VPC Service Controls,请查看代理日志中的错误。如果 VPC Service Controls 配置不正确,INFO 代理日志将包含以下错误:

    Request is prohibited by organization's policy. vpcServiceControlsUniqueIdentifier: id

    在此输出中:

代理已连接,但作业失败

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