Hadoop HDFS DistCp 大规模数据迁移检查清单

HDFS DistCp 是 Hadoop 生态中最常用的大规模数据迁移工具，但"跑起来"和"跑对了"之间隔着大量细节。本文从网络打通、内存调优、快照增量复制、ACL 同步四个环节给出一份可直接执行的检查清单，确保迁移不丢数据、不超时、权限不丢失。

一、网络打通检查

DistCp 的性能瓶颈首先出现在网络层面。源集群和目标集群之间需要满足以下条件。

带宽评估： 用 iperf3 测试源集群和目标集群之间的实际带宽。对于 10 TB 级别的数据迁移，10 Gbps 带宽需要约 2.5 小时（理论值），实际因序列化和压缩开销通常需要 4 到 6 小时。如果带宽不足 1 Gbps，优先考虑使用中间存储（如 HDFS 网关节点）做中转，或者在夜间带宽空闲时段执行。测试时注意区分 TCP 带宽和实际 HDFS 传输带宽——HDFS 的 RPC 握手和数据块校验会额外消耗约 10% 到 15% 的带宽。

端口连通性： DistCp 依赖 HDFS RPC 端口（默认 8020 或 9000）和 YARN 端口（默认 8088）。确保源集群的 DataNode 能访问目标集群的 NameNode，目标集群的 NodeManager 能访问源集群的 DataNode。用 telnet <target-namenode> 8020 逐端口测试。除了端口连通性，还需要确认防火墙规则没有限速或丢包——用 mtr 工具进行 100 次以上的路由追踪，观察丢包率和延迟波动。

Kerberos 认证： 如果集群启用了 Kerberos，需要在提交 DistCp 任务的节点上配置好 keytab 和 krb5.conf。常见错误是 keytab 过期或 principal 不匹配，导致任务启动后在数据传输阶段才报认证失败。建议在提交前用 kinit -kt <keytab> <principal> 手动测试认证是否通过。另一个容易忽略的问题是跨域认证——如果源集群和目标集群属于不同的 Kerberos realm，需要配置跨域 trust relationship，否则跨集群的 HDFS 操作会因为无法验证对端身份而失败。

二、DistCp 内存与并发调优

DistCp 默认的并发度和内存配置可能不适合大规模迁移场景。

Map 数量控制： DistCp 的 map 参数决定了并行复制的 map task 数量，默认值为 20。对于大规模迁移，建议将其设置为目标集群 DataNode 数量的 1.5 到 2 倍，这样每个 DataNode 上平均有 1 到 2 个 map task 在执行，充分利用磁盘 IO。但不宜过大——过多的 map task 会产生大量小文件写入，反而降低吞吐。如果迁移涉及大量小文件（平均文件大小小于 64 MB），建议先合并小文件再迁移，或者将 map 数控制在 50 以内。

JVM 堆内存： DistCp 的每个 map task 运行在独立的 JVM 中，默认堆内存为 256 MB。如果单个文件较大（如超过 1 GB），需要调大堆内存避免 OOM。通过 -Dmapreduce.map.memory.mb=4096 和 -Dmapreduce.map.java.opts=-Xmx3500m 调整 map task 的内存。注意 java.opts 应设为 memory.mb 的 80% 左右，留出空间给非堆内存和操作系统开销。对于 YARN 集群，还需要确保 NodeManager 的 yarn.nodemanager.resource.memory-mb 足够大，能够容纳所有 map task 同时运行所需的内存。

Bandwidth 限速： DistCp 的 bandwidth 参数限制每个 map task 的带宽（单位 MB/s），默认值为 0（不限速）。在共享集群上执行迁移时，建议设置为 50 到 100 MB/s，避免迁移任务占满网络导致其他业务受影响。在专用迁移网络上则不限速以最大化吞吐。

文件系统兼容性： 如果源集群和目标集群使用不同的 Hadoop 版本或文件系统（如从 HDFS 2.x 迁移到 HDFS 3.x，或从 HDFS 迁移到对象存储），需要确认 DistCp 的兼容性。某些情况下可能需要使用 --distcp-change-acl=false 或 --update 等参数来规避兼容性问题。

三、快照增量复制

全量迁移在数据量超过 10 TB 时耗时过长，快照增量复制可以大幅缩短后续迁移时间。

首次全量迁移： 使用标准 DistCp 命令完成首次全量复制：

hadoop distcp hdfs://source/path hdfs://target/path

创建 HDFS 快照： 在首次迁移完成后，对源路径创建快照：

hdfs dfsadmin -allowSnapshot /source/path
hdfs dfs -createSnapshot /source/path migration-snapshot-01

创建快照前需要确认 HDFS 集群开启了快照功能（dfs.namenode.snapshot.enabled=true），并且目标路径没有被其他任务写入。快照创建是原子操作，不会影响正在运行的读写请求，但如果文件数量超过百万级，快照创建本身可能需要数分钟。

增量迁移： 基于快照进行增量复制，DistCp 会自动对比快照差异，只传输新增和修改的文件：

hadoop distcp -update -delete \
  hdfs://source/path/.snapshot/migration-snapshot-01 \
  hdfs://target/path

关键参数 -update 只复制源端有变化的文件，-delete 删除目标端源端已删除的文件。如果不加 -delete，目标端会保留已删除的"孤儿"文件。需要注意的是，-update 基于文件大小和修改时间判断是否需要复制，而不是内容校验——如果文件内容相同但修改时间不同，仍然会被重新复制。

快照命名建议用日期编号（如 migration-20260801），便于追踪迁移进度。每次增量迁移前确认前一次迁移已完成，避免快照与实际状态不一致。建议建立快照清理策略，只保留最近 5 到 10 个快照，避免快照占用过多 NameNode 内存。

四、ACL 与权限同步

HDFS 的 ACL（Access Control List）不会随文件内容自动迁移。DistCp 默认只复制 POSIX 权限（owner、group、mode），ACL 条目需要额外处理。

检查源端 ACL： 用 hdfs dfs -getfacl -R /source/path 导出完整的 ACL 规则。检查是否存在自定义 ACL 条目（如特定用户的读写权限），这些条目不会被 DistCp 自动迁移。

DistCp 的 -pb 参数可以在复制时保留 POSIX 权限，但不处理 ACL。如果需要同步 ACL，有两种方案：第一种是在目标端手动用 hdfs dfs -setfacl 批量导入，适合 ACL 规则较少的场景；第二种是编写脚本，解析 getfacl 的输出并在目标端重建，适合 ACL 规则复杂的场景。第二种方案的核心逻辑是按目录结构遍历源端的 ACL 输出，对每个目录在目标端执行 setfacl -m 命令。

对于 Ranger 或 Sentry 等外部权限管理系统的策略，需要单独导出和导入，DistCp 不涉及这一层。如果目标集群也使用 Ranger，建议在迁移完成后统一在 Ranger 控制台中重新配置策略，而不是逐文件同步 ACL。

验证权限： 迁移完成后用 hdfs dfs -getfacl 对比源端和目标端的 ACL 输出，确保关键目录的权限一致。特别注意 superuser 和 service account 的权限——如果目标集群的用户名不同，需要映射到对应的本地用户。可以用 hdfs dfs -chown 批量修改文件的 owner 和 group。

五、迁移后的数据校验

迁移完成不等于迁移正确。至少需要执行以下校验。

文件数量对比： 分别在源端和目标端执行 hdfs dfs -count -R，文件总数和目录总数必须一致。如果总数不一致，用 hdfs dfs -ls -R 逐级对比，定位缺失或多余的文件。

文件大小抽样： 随机抽取 5% 到 10% 的文件，用 md5sum 对比源端和目标端的校验和。对于大文件（超过 1 GB），可以先用 hdfs dfs -tail 抽取文件尾部内容进行对比，快速判断是否完整。

Checksum 验证： DistCp 的 -checksum 参数可以在复制时验证数据完整性。在正式迁移前用小数据集测试 checksum 的行为，确认它对你的 HDFS 版本有效。注意：不同 Hadoop 版本的 checksum 算法可能不同（CRC32C vs CRC32），跨版本迁移时需要确认算法一致性。

迁移性能记录： 记录每次迁移的耗时、传输速率、失败 map task 数量等指标，作为后续增量迁移的基准。如果增量迁移的耗时远超预期，可能是 -update 参数的文件对比逻辑导致了不必要的重新传输，需要检查源端文件的修改时间是否被意外更新。

EasyMR 基于 Hadoop 自研增强，全面适配国产芯片与操作系统，通过 EasyManager 提供一站式部署与运维能力，在大规模数据迁移场景下支持集群管理和监控，帮助降低迁移过程中的运维复杂度。

迁移路径总结

HDFS DistCp 大规模迁移的成功取决于四个环节的配合：网络确保连通性和带宽、内存调优避免 OOM、快照实现增量复制减少迁移窗口、ACL 同步保证权限不丢失。按照本文的检查清单逐项验证，在小数据集上完成试迁移后再执行全量操作，是降低迁移风险的最有效方法。

如果你即将执行一次大规模 HDFS 迁移，建议先用 iperf3 测试网络带宽，然后用 1 GB 的测试数据跑一次完整的 DistCp 流程（包含 ACL 和校验），确认所有参数正确后再启动正式迁移。正式迁移时先执行全量，然后建立快照用于后续增量同步，最终在业务低峰期执行数据校验，确保迁移结果与源端一致。