本文档介绍如何排查和解决转移和代理问题,以及如何找到代理日志来帮助您排查问题。
错误
下表介绍转移错误消息以及解决方法:
错误消息 | 错误类型 | 错误的含义 | 如何解决错误 |
---|---|---|---|
在转移期间被修改 | 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 | 转移代理没有足够的权限来执行操作。此错误有两种可能性:
|
请验证以下内容:
|
对象受存储分区的保留政策的约束,且无法删除、覆盖或归档 | 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 ,请使用
<ph type="x-smartling-placeholder"></ph>
googleserviceaccounts.get API 调用。
<ph type="x-smartling-placeholder"></ph>
验证服务账号是否具有以下角色:
|
代理不受支持 | AGENT_UNSUPPORTED_VERSION | 代理版本不再与 Storage Transfer Service 兼容。 | 这是一个临时错误,与代理更新错误有关。如果出现这种情况,请执行以下操作:
|
由于哈希值不匹配而失败 | 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.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”的行表示所有线程的总聚合带宽,可用作读取吞吐量的代理。
使用 iPerf3 检查 Storage Transfer Service 的可用互联网带宽。
确保每个转移代理至少具有 4 个 vCPU 和 8GB 的 RAM。
如果您已检查上述条件,但仍存在较长的转移时间,则可以添加其他代理以增加与数据文件系统的并发连接数量。
如需详细了解如何最大限度地提高转移代理的性能,请参阅代理最佳做法。
排查代理错误
以下部分介绍了如何排查和解决转移代理错误:
代理未连接
如果转移代理在 Google Cloud 控制台中未显示为已连接:
验证代理是否可以连接到 Cloud Storage API:
在转移代理所在的机器上运行以下命令,以测试该代理与 Cloud Storage API 的连接:
gcloud storage cp test.txt gs://my-bucket
您需要将:
my-bucket
替换为 Cloud Storage 存储分区的名称。
如果您的项目使用 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
替换为
备用端点。