迁移常见问题
本文介绍在使用在线迁移服务过程中可能遇到的常见问题，并提供相应的排查与解决方案。
如何评估迁移速度与迁移时长
关于迁移速度：
在线迁移服务默认会为每个任务提供固定的理论峰值带宽和QPS，具体详见带宽与QPS。您需要根据自身业务情况，合理设置能用于迁移的理论峰值带宽与QPS，以避免迁移访问与您的生产业务访问发生竞争，影响业务的正常运行。
迁移任务的速度不保证能达到理论峰值带宽和QPS。主要影响因素有：
访问源端、目的端的网络链路带宽和质量。对于链路长、时延大、丢包率高的网络（如公网跨国传输），可能会导致效率低下甚至文件传输频繁失败。建议您使用专线或加速链路进行传输，如阿里云OSS的传输加速域名。
源端、目的端的读写能力及文件的平均大小。对于源端，迁移会进行遍历、读取元信息和内容操作；对于目的端，迁移会进行写入元信息和内容、读取元信息操作。源端的遍历能力会影响任务的扫描速度；任意一端的读写能力都会影响任务的迁移速度。尤其是在迁移海量200KB以内的小文件时，对两端的读写能力有更高的要求。您可以用源端总数据量除以源端总文件数来粗略估算出单个文件的平均大小。
源端目录的数量及文件分布。对于LocalFS、FTP等具有目录概念的文件系统，在线迁移服务会以目录为单位进行逐级并发扫描。若目录数量过多、文件分布过于稀疏，将影响任务的扫描速度。
代理机器的软硬件配置及数量。如果您源端和（或）目的端数据地址有关联代理，则代理可能成为瓶颈。代理配置及数量选择请参看代理选型。
受制于上述因素，在线迁移服务不对迁移速度做任何保证。建议您在正式实施迁移前，先使用较小规模的数据量进行PoC验证，以便准确评估实际的迁移速度。
关于迁移时长：
在您评估出合理的迁移速度后，就可以根据总数据量、总文件数量估算出迁移时长。您可以按
总存储量 / 带宽、总文件数量 / QPS，分别估算出最快迁移时长，取二者中的较大值。最终估算出的迁移时长只是理论时长。迁移期间可能会遇到带宽波动、失败重试等问题，请务必做好应急预案与延期风险规划，尤其是在需要停服割接的生产环境数据迁移场景中。
在线迁移服务对单个任务有迁移资源分配上限，详见带宽与QPS。
以下是综合评估示例：
场景一：
问：源端为S3，共约1TB数据、1000万个文件，目的端为OSS，在北京地域创建任务，请问迁移需要多久时间？
答：根据带宽与QPS文档可知，北京地域单任务理论速度为2Gbps，2000个文件/秒。做如下计算：
按照存储量计算迁移时长：
1TB ÷ 2Gbps ≈ 1.1小时。按照文件个数计算迁移时长：
10000000 ÷ 2000个文件/秒 ≈ 1.4小时。理论计算迁移时长：取上述二者最大值，得到理论迁移时长为
1.4小时。
场景二：
问：源端为OSS，共约1TB数据、10万个文件，目的端为阿里云NAS，在新加坡地域创建任务，请问迁移需要多久时间？
答：根据带宽与QPS文档可知，新加坡地域单任务理论速度为1Gbps、2000个文件/秒。但由于目的地址是LocalFS，理论QPS上限为200个文件/秒。做如下计算：
按照存储量计算迁移时长：
1TB ÷ 1Gbps ≈ 2.3小时。按照文件个数计算迁移时长：
100000 ÷ 200个文件/秒 ≈ 500秒。理论计算迁移时长：取上述二者最大值，得到理论迁移时长为
2.3小时。
上述示例的计算结果仅为理论值，实际迁移速度、迁移时长务必以实际的迁移任务为准。
代理在控制台的状态异常
在线迁移服务的代理实例需要部署才能正常运行。若您按照正常流程部署后，控制台代理状态仍然显示连接异常，则可能有如下原因：
网络连通性问题。请参考使用代理迁移中的网络类型参数，确认代理机器到在线迁移服务域名的连通性。
凭据填写不正确或权限问题，如：
输入有误。如复制粘贴的AccessKeyId（或SecretAccessKey）不完整或有额外的干扰字符。
权限不足。填写的AccessKeyId必须具备以下任一权限，且资源范围必须是账号级别：
mgw:VerifyAgentTunnel
AliyunOSSImportReadOnlyAccess
AliyunOSSImportFullAccess
账号不匹配。如填写的AccessKeyId并不属于本RAM子账号，或本主账号下的其他RAM子账号。无论是否涉及跨账号迁移，您都只能使用当前主账号下的任一RAM子账号的凭据，且该RAM子账号必须具有上述三个权限之一。
凭据被网络策略限制。部署代理时，填写的AccessKeyId被RAM中的网络访问限制策略所限制。目前在线迁移服务的代理鉴权机制要求必须AccessKeyId必须允许所有网段都能正常访问。您可以在RAM中的AccessKey级访问限制策略中按照如下步骤添加允许所有公网访问白名单：
代理机器的操作系统时间不准确，和现实世界偏差超过5分钟。
部署命令被修改、粘贴不完整。请完整复制、粘贴控制台自动生成的代理部署命令，勿做任何修改，否则可能会导致代理运行异常。
如果代理状态不稳定，则可能有如下原因：
网络不稳定。当代理与在线迁移服务之间的网络质量不佳时，会出现偶发性连接异常。若代理机器所处的网络环境发生了变化，请参考使用代理迁移中的网络类型参数，重新确认代理机器到在线迁移服务域名的连通性。
代理压力大。正在执行迁移的代理可能会出现偶发性连接异常。如果迁移任务正常运行，则属于正常现象；如果机器出现平均负载（Load Average）较高时，请扩容代理实例来增强迁移能力，或降低任务的每秒迁移文件数上限参数。
关联的通道实例启用了限流。由于代理的健康检查也会少量消耗通道的QPS，可能与迁移请求发生竞争而被拒绝。建议适当放大通道的请求数/秒参数，或不做通道级限流。
代理进程已经退出。请参考代理进程的查看、启动与停止登录代理机器查看进程状态。当代理机器的实例规格低于推荐值时，可能会导致进程因内存不足而退出，实例规格参考代理选型。
同一个代理实例部署在多台机器上。每个代理实例仅能部署在一台机器上，重复部署会导致相互冲突，从而出现状态不稳定的现象。若您需要更换代理机器，请务必先停止旧代理机器上的进程，然后重新部署。
迁移任务没有进度
后台调度机制。正常情况下，任务启动后会有10-15分钟的入队调度时间，请耐心等待。
文件被过滤。如果任务配置了文件过滤器，且源端符合过滤条件的文件数量很少，则将会导致任务更新缓慢。
清单的预处理耗时。如果任务的源端是清单类型的数据地址，则需要有一定的预处理时间，预处理耗时和清单中的文件总数量呈正相关。
并发迁移大文件。若任务详情页面的带宽监控图数据趋势符合预期，则属于正常现象；
其他可能的原因：
如果源端是LocalFS或FTP类型，目录过多且文件分布稀疏，将导致扫描时过慢；或有目录因权限不足、损坏等原因导致无法正常访问，将导致扫描无法正常进行。
若目的端是LocalFS类型，当大批量迁移GB级及以上的大文件时，进度更新可能迟滞。您可以查看代理机器的实际带宽（如ECS云监控）来确认。
如果任意一端有关联代理，当代理实例对应的机器负载过大甚至连接异常时，都会影响任务的进度。
如何查看迁移失败文件
在迁移过程中，可能由于数据源访问权限不足、网络异常等原因导致部分文件迁移失败。您可以通过以下两种方式查看失败文件的具体原因：
方式一：推送迁移报告
您可以在创建任务时设置推送迁移报告，也可以在之后修改该配置。任务完成后，在线迁移服务会将完整的迁移记录写入到目的数据地址的指定位置。您可以通过审阅该迁移报告来定位迁移失败文件及其原因。
方式二：推送迁移日志
在创建迁移任务时设置推送迁移日志，在线迁移服务会将迁移过程中的日志实时推送至您的日志服务（SLS）。您可以在日志服务中查看相关日志，分析失败文件及其具体失败原因。
常见迁移失败原因
下表列出了迁移失败原因的错误码关键字（部分）。这些错误码可能会出现在下列场景中：
创建数据地址异常时，异常报错信息。
任务运行异常中断时，任务历史界面的异常报错信息。
迁移报告中的异常原因字段的内容。
错误码关键字 | 错误说明 | 处理建议 |
InvalidObjectName | 迁移到OSS的对象名称不合法，具体参看OSS对象命名规范。 | 修改源端对象名称后，重新启动任务。 |
InvalidObjectState | 对象状态不允许访问。当源端对象的存储类型为归档、冷归档等不可直接读取的类型，且未解冻（或开启归档直读）时发生此错误。 | 检查此对象在源端的存储类型，若需解冻，请等待解冻完成后，再进行重试迁移。 |
NoSuchKey | 迁移时源端对象不存在。 | 请检查源端对象是否存在。 |
LocalFsOpFailed | 使用POSIX接口操作LocalFS数据地址失败。 | 根据详细的错误信息进一步定位、处理。 |
LocalFileLockFailed | 写入LocalFS数据地址时并发过高所致。在目的端写操作压力过大时出现。 | 请降低任务的每秒迁移文件数上限阈值。建议先设置成最低值，观察报错情况，再逐步向上调整。 |
ObjectSizeTooLarge | 此文件的size超出在线迁移服务支持的最大限制。 | 在线迁移服务无法迁移此文件，请使用其他工具或手段迁移。 |
Forbidden、AccessDenied、Unauthorized、UserDisable | 访问此文件时被拒绝。如权限不足、创建重试任务时SecretAccessKey填写有误、源文件被kms加密、用户账号被禁用（欠费或违规）等。 | 检查创建数据地址对应的Bucket、AccessKeyId、SecretAccessKey或授权角色等信息填写是否正确，以及权限是否满足迁移。若是账号被禁用，请查看账户和bucket状态是否有异常。 |
CancelledDueToTimeout、InconsistentPartCount | 迁移此文件时访问超时导致全部或部分Part传输失败。通常在网络质量不佳、迁移带宽达到链路瓶颈时会出现。 | 请确保访问数据地址时的畅通性。 |
S3BackendError、 CosBackendError、 QiniuBackendError、 OssBackendError | 分别是访问S3、COS、QINIU、OSS数据地址时发生了异常。具体原因可根据错误详情分析。 | 可能是源站限流、压力过大等导致，建议降低迁移限流策略。 |
SourceMetaInvalid | 源端此文件的元数据信息的Key中包含无效字符。典型的场景是，OSS不支持用户自定义元数据的Key含有下划线。 如源端文件的元数据信息中Key含有下划线时，将报这类错误。示例：
| 修改或删除源端此文件的所有元数据信息中含下划线的Key后，再进行重试迁移。如左侧示例可改成短横线：
|
UnsupportedRedirect | 由于在线迁移服务不支持重定向响应，当http请求收到重定向（如状态码301、302）的响应时，会报此类错误。 典型的场景如：您创建源地址时，填写的域名参数显式填写了“http://”协议头，但对应的源服务端限制仅支持https协议访问时。 | 请检查源数据地址是否有重定向。尝试使用“https://”协议头进行重新创建源地址并迁移。 |
InconsistentStdMetadata | 文件迁移到目的端后，校验标准元数据失败。如Content-Type、Content-Disposition、Expires等在线迁移服务支持的http标准属性。 | 根据详细的错误信息进一步定位、处理。如是Expires不一致，可能是源端的Expires频繁动态变化所致。 |
CreateProjectFailed | 创建迁移任务时，迁移日志选项您选择为“推送”或“仅推送错误文件日志”，但未点击日志服务授权按钮，导致在线迁移服务尝试创建日志服务的Project时失败。 | 删除旧任务并重新创建任务，在创建界面点击日志服务授权按钮，确保其为“已授权”状态，并完成任务的创建。 |
迁移完成后发现两端数据量不一致
迁移任务运行完成后，若发现源端数据量和目的端数据量不一致，则可按照以下原因排查。
若是目的端数据量偏少。则可能的原因有：
两端数据有变动。如迁移过程中，源端可能有写数据操作；或目的端数据有删除（包括用户业务侧主动删除，或类似生命周期策略的被动删除）。
源端可能存在多版本数据（如OSS、S3、NAS回收站等），在线迁移服务只会迁移最新版本的数据。
统计延迟。可能是目标端数据统计有小时或天级别延迟，可查看对应的统计说明文档。或使用对应的工具（如ossutil）进行手动统计。
有部分数据被跳过。如某文件在源端的大小为1GB，同时在目的端的大小为100MB。但根据迁移任务的覆盖方式，该文件被判为跳过。
源端有碎片。在线迁移服务并不会迁移源端的碎片等非完整对象。
文件过滤器设置有误。若启用了文件过滤器，请检查配置规则是否符合预期，如是否有多余的空格等干扰字符。
源数据地址Prefix设置有误。如您指定了源地址的Prefix，则只会迁移此Prefix下的数据。
异构存储的统计差异。如NAS等文件系统类型的源，会将目录自身也计入存储占用。而OSS等对象存储类型的源，并没有目录的概念，空对象也并不会计入存储占用。
部分代理NAS挂载点异常。若源地址是LocalFS类型，且关联有多台代理，若其中一些代理的NAS挂载点异常，当迁移请求被派发到这些代理实例上时，将会由于访问源端文件报NotFound而被判为跳过，从而导致最终迁移数据量偏少。
若是目的端数据量偏多。则可能的原因有：
两端数据有变动。如迁移过程中，源端可能有删除数据操作（包括用户业务侧主动删除，或类似生命周期策略的被动删除）；或目的端数据有写数据操作。
目的端可能开启了多版本功能（如OSS、NAS回收站等），在线迁移服务会使用非多版本类的API将数据写入目的端，若目的端已启用多版本功能，则写入操作将会生成新版本的数据。
有部分数据被跳过。如某文件在源端的大小为100MB，同时在目的端的大小为1GB。但根据迁移任务的覆盖方式，该文件被判为跳过。
目的端有碎片或临时文件残留。在线迁移服务内部会根据文件大小自动选择合适的读写方式，若任务中断（用户主动操作或发生严重异常所致），或网络原因等导致部分文件迁移失败时，可能会在目的端残留碎片或临时文件。
文件过滤器设置有误。若启用了文件过滤器，请检查配置规则是否符合预期，如是否有多余的空格等干扰字符。
目的数据地址Prefix下存在其他数据。如您目的地址的Prefix下在迁移前就已存在部分数据，迁移并不会提前清空这些数据（但根据任务的覆盖方式，可能会覆盖同名文件）。
异构存储的统计差异。如NAS等文件系统类型的源，会将目录自身也计入存储占用。而OSS等对象存储类型的源，并没有目录的概念，空对象也并不会计入存储占用。
迁移报告的额外占用空间。如果用户选择推送迁移报告，则会在目的端生成迁移报告，迁移报告的占用大小取决于任务的迁移文件总数量。
源端产生额外下行流量、文件被重复迁移
正常情况下，在线迁移服务只会下载一次源端数据。如果您在迁移完成过后，发现源端的下行流量偏多，则可能的原因有：
失败内部重试。如果迁移过程中出现网络闪断、读写限流、代理性能瓶颈（若关联）等异常，则会自动对文件进行有限次数的重试操作。
外部系统访问。如在迁移期间，另有其他系统（如您的业务系统、cdn回源等）同时访问源端，则会与迁移产生的下行流量相互叠加。
如果您在执行多轮迁移时，先前迁移成功的文件仍然重复迁移，并没有跳过。则可能的原因有：
迁移任务覆盖方式参数不合理。若您的迁移任务的为强制覆盖，则在线迁移服务无论目的端的是否已有文件，总是会执行覆盖。
目标端配置有生命策略周期。在创建迁移任务时，若您选择保留文件最后修改时间，则源端文件的最后修改时间也将被设置到目的端。若目的端配置的生命周期策略有删除操作，则可能会出现“文件迁移后很快被删除”的现象。
源端文件频繁更新。若迁移任务的覆盖方式为根据最后修改时间覆盖，在第一轮迁移成功后，一旦源端文件的最后修改时间有更新（无论文件内容是否有更新），下一轮就会再次迁移。
OSS跨账号迁移问题汇总
仅OSS数据地址才涉及跨账号授权，NAS迁移并不涉及，具体请参考NAS跨账号迁移问题汇总。
仅OSS数据地址的bucket不属于本账号（操作在线迁移服务控制台的账号）时，才属于跨账号场景。
跨账号分为三个场景：其他账号迁移到本账号、本账号迁移到其他账号、其他账号迁移到其他账号（该场景操作复杂，不推荐，建议转换成前两种场景）。在迁移过程中，可能遇到授权的问题。总结如下：
授权操作的核心流程为：
本账号在RAM控制台创建RAM角色。具体步骤参考创建用于迁移数据的RAM角色。
将创建的角色名（RoleName）告知给其他账号的管理员。管理员在其待迁移的Bucket授权策略界面执行授权。具体请参考源Bucket授权或目的Bucket授权。
至此授权完成。本账号继续操作在线迁移服务，创建此待迁移的Bucket数据地址时，授权角色字段请使用上述步骤的RoleName。
跨账号授权完成后，创建其他账号的数据地址仍然报“权限不足”相关的错误。可能是RoleName有大写字母所致。即使RAM控制台上创建的原始RoleName含大写字母（如
MyOssImportRole），也务必请在bucket acl授权策略中用全小写字母（如myossimportrole）。
NAS跨账号迁移问题汇总
使用在线迁移服务时，即使迁移不同阿里云账号下NAS实例，也不涉及跨账号场景。因为在线迁移服务只会使用POSIX标准IO接口读写指定目录，并不感知其底层存储是否为NAS及其所属账号。
您必须部署代理，并将NAS挂载到代理上后，按照LocalFS数据地址类型操作。请务必注意目录映射，否则文件可能会读（或写）到非预期的磁盘路径上。
假设某用户需要将账号A的阿里云NAS迁移到本账号NAS下。执行步骤为：
将账号A的NAS挂载到某台机器M1上。M1可以是账号A的ECS（推荐），也可以是其他来源。能正常挂载账号A的NAS即可。
在线迁移服务控制台上，创建一个代理实例agent1，并将其部署在机器M1上。
将本账号的NAS挂载到另一台机器M2上。M2可以是本账号的ECS（推荐），也可以是其他来源。能正常挂载本账号NAS即可。
在线迁移服务控制台上，创建一个代理实例agent2，并将其部署在机器M2上。
确认在线迁移服务控制台上代理agent1、agent2的状态都是“正常”后，按照LocalFS之间迁移教程创建数据地址、迁移任务。