DistCp 指南

基本用法

DistCp 最常見的呼叫是叢集間複製

bash$ hadoop distcp hdfs://nn1:8020/foo/bar \
hdfs://nn2:8020/bar/foo

這將把 nn1 上 /foo/bar 下的命名空間擴充到一個暫存檔中，將其內容分割到一組映射任務中，並在每個 NodeManager 上從 nn1 到 nn2 開始複製。

您還可以在命令列上指定多個來源目錄

bash$ hadoop distcp hdfs://nn1:8020/foo/a \
hdfs://nn1:8020/foo/b \
hdfs://nn2:8020/bar/foo

或者，等效地，從使用 -f 選項的檔案

bash$ hadoop distcp -f hdfs://nn1:8020/srclist \
hdfs://nn2:8020/bar/foo

其中 srclist 包含

hdfs://nn1:8020/foo/a
hdfs://nn1:8020/foo/b

從多個來源複製時，如果兩個來源發生衝突，DistCp 會中止複製並顯示錯誤訊息，但會根據指定的 選項 解決目標端的衝突。預設情況下，會略過目標端已存在的檔案（即不會以來源檔案取代）。每個工作結束時會報告略過的檔案數量，但如果複製器對某些檔案子集失敗，但在後續嘗試中成功，則報告可能不準確。

每個 NodeManager 都能連線並與來源和目標檔案系統通訊非常重要。對於 HDFS，來源和目標都必須執行相同版本的通訊協定，或使用向下相容的通訊協定；請參閱 [不同 HDFS 版本之間的複製] (#Copying_Between_Versions_of_HDFS)。

複製後，建議產生來源和目標的清單並進行交叉比對，以驗證複製是否真的成功。由於 DistCp 同時使用 Map/Reduce 和 FileSystem API，因此這三者之間或其中的任何問題都可能對複製造成負面且無聲的影響。有些人成功執行啟用 -update 的操作，以執行第二次傳遞，但使用者在嘗試此操作之前應先了解其語意。

另外值得注意的是，如果其他用戶端仍在寫入來源檔案，則複製可能會失敗。嘗試覆寫在目標端寫入的檔案也應該會在 HDFS 上失敗。如果來源檔案在複製之前被（重新）移除，則複製會失敗並顯示 FileNotFoundException。

請參閱詳細的命令列參考，以取得 DistCp 中所有可用選項的資訊。

更新和覆寫

-update 用於複製目標端不存在或與目標版本不同的來源檔案。-overwrite 會覆寫目標端存在的目標檔案。

更新和覆寫選項需要特別注意，因為它們處理來源路徑的方式與預設值有非常細微的不同。考慮從 /source/first/ 和 /source/second/ 複製到 /target/，其中來源路徑包含下列內容

hdfs://nn1:8020/source/first/1
hdfs://nn1:8020/source/first/2
hdfs://nn1:8020/source/second/10
hdfs://nn1:8020/source/second/20

當未在 DistCp 中呼叫 -update 或 -overwrite 時，DistCp 預設會在 /target 下建立目錄 first/ 和 second/。因此

distcp hdfs://nn1:8020/source/first hdfs://nn1:8020/source/second hdfs://nn2:8020/target

會在 /target 中產生下列內容

hdfs://nn2:8020/target/first/1
hdfs://nn2:8020/target/first/2
hdfs://nn2:8020/target/second/10
hdfs://nn2:8020/target/second/20

當指定 -update 或 -overwrite 時，會將來源目錄的內容複製到目標，而非來源目錄本身。因此

distcp -update hdfs://nn1:8020/source/first hdfs://nn1:8020/source/second hdfs://nn2:8020/target

會在 /target 中產生下列內容

hdfs://nn2:8020/target/1
hdfs://nn2:8020/target/2
hdfs://nn2:8020/target/10
hdfs://nn2:8020/target/20

進一步延伸，如果兩個來源資料夾都包含同名的檔案（例如 0），則兩個來源都會將一個項目對應到目的地的 /target/0。DistCp 會中止，而不是允許此衝突發生。

現在，考慮下列複製作業

distcp hdfs://nn1:8020/source/first hdfs://nn1:8020/source/second hdfs://nn2:8020/target

來源/大小

hdfs://nn1:8020/source/first/1 32
hdfs://nn1:8020/source/first/2 32
hdfs://nn1:8020/source/second/10 64
hdfs://nn1:8020/source/second/20 32

目標/大小

hdfs://nn2:8020/target/1 32
hdfs://nn2:8020/target/10 32
hdfs://nn2:8020/target/20 64

將會影響

hdfs://nn2:8020/target/1 32
hdfs://nn2:8020/target/2 32
hdfs://nn2:8020/target/10 64
hdfs://nn2:8020/target/20 32

略過 1，因為檔案長度和內容相符。複製 2，因為它不存在於目標中。覆寫 10 和 20，因為內容與來源不符。

如果使用 -update，則會略過 1，因為檔案長度和內容相符。複製 2，因為它不存在於目標中。覆寫 10 和 20，因為內容與來源不符。但是，如果另外使用 -append，則只會覆寫 10（來源長度小於目標）並將檔案變更附加到 20（如果檔案與目標的原始長度相符）。

如果使用 -overwrite，則也會覆寫 1。

同步

-diff 選項會使用快照差異從來源叢集同步檔案到目標叢集。它會複製、重新命名和移除快照差異清單中的檔案。

使用 -diff 選項時，必須包含 -update 選項。

目前，大多數雲端供應商無法順利地進行同步。

用法

hadoop distcp -update -diff <from_snapshot> <to_snapshot> <source> <destination>

範例

hadoop distcp -update -diff snap1 snap2 /src/ /dst/

上述指令會將快照 snap1 至 snap2 的變更（即從 snap1 至 snap2 的快照差異）套用在 /src/ 至 /dst/。顯然，它需要 /src/ 同時具有快照 snap1 和 snap2。但是，目標 /dst/ 也必須具有與 <from_snapshot> 同名的快照，在本例中為 snap1。目標 /dst/ 自 snap1 以來不應有新的檔案作業（建立、重新命名、刪除）。請注意，當此指令完成時，不會在 /dst/ 建立新的快照 snap2。

使用 -diff 選項需要 -update。

例如，如果在 /src/ 中，在建立 snap1 之後和建立 snap2 之前，新增了 1.txt 並刪除了 2.txt，則上述指令會將 1.txt 從 /src/ 複製到 /dst/，並從 /dst/ 刪除 2.txt。

同步行為將使用以下實驗進行說明。

# Create source and destination directories
hdfs dfs -mkdir /src/ /dst/
# Allow snapshot on source
hdfs dfsadmin -allowSnapshot /src/
# Create a snapshot (empty one)
hdfs dfs -createSnapshot /src/ snap1
# Allow snapshot on destination
hdfs dfsadmin -allowSnapshot /dst/
# Create a from_snapshot with the same name
hdfs dfs -createSnapshot /dst/ snap1

# Put one text file under /src/
echo "This is the 1st text file." > 1.txt
hdfs dfs -put 1.txt /src/
# Create the second snapshot
hdfs dfs -createSnapshot /src/ snap2

# Put another text file under /src/
echo "This is the 2nd text file." > 2.txt
hdfs dfs -put 2.txt /src/
# Create the third snapshot
hdfs dfs -createSnapshot /src/ snap3

hadoop distcp -update -diff snap1 snap2 /src/ /dst/

hdfs dfs -rm -skipTrash /dst/1.txt

hadoop distcp -update -diff snap1 snap3 /src/ /dst/

hdfs dfs -rm -skipTrash /dst/2.txt
# Create snap2 at destination, it contains 1.txt
hdfs dfs -createSnapshot /dst/ snap2

# Delete 1.txt from source
hdfs dfs -rm -skipTrash /src/1.txt
# Create snap4 at source, it only contains 2.txt
hdfs dfs -createSnapshot /src/ snap4

hadoop distcp -update -diff snap2 snap4 /src/ /dst/

原始命名空間延伸屬性保留

此區段僅適用於 HDFS。

如果目標和所有來源路徑名稱都在 /.reserved/raw 層級結構中，則會保留「原始」命名空間延伸屬性。「原始」xattr 由系統用於內部功能，例如加密元資料。只有透過 /.reserved/raw 層級結構存取時，使用者才能看到它們。

原始 xattrs 的保留僅基於是否提供 /.reserved/raw 前綴。-p (保留，見下文) 標記不會影響原始 xattrs 的保留。

若要防止保留原始 xattrs，只需在任何來源和目標路徑上不使用 /.reserved/raw 前綴。

如果僅在來源和目標路徑的子集上指定 /.reserved/raw 前綴，將會顯示錯誤並傳回非 0 退出代碼。

DistCp 驅動程式

DistCp 驅動程式元件負責

• 透過

  • OptionsParser 和
  • DistCpOptionsSwitch

• 分析傳遞至命令列上 DistCp 命令的引數，並將命令引數組裝成適當的 DistCpOptions 物件，並初始化 DistCp。這些引數包括

  • 來源路徑
  • 目標位置
  • 複製選項（例如是否更新複製、覆寫、保留哪些檔案屬性等）

• 透過

  • 呼叫複製清單產生器，以建立要複製的檔案清單。
  • 設定並啟動 Hadoop Map-Reduce 作業，以執行複製。
  • 根據選項，立即傳回 Hadoop MR 作業的控制代碼，或等到完成。

剖析器元素僅從命令列（或呼叫 DistCp::run() 時）執行。DistCp 類別也可以透過建構 DistCpOptions 物件和適當地初始化 DistCp 物件，以程式方式使用。

複製清單產生器

複製清單產生器類別負責建立要從來源複製的檔案/目錄清單。它們會檢查來源路徑的內容（包括萬用字元），並將所有需要複製的路徑記錄到 SequenceFile 中，供 DistCp Hadoop 作業使用。此模組中的主要類別包括

1. CopyListing：任何複製清單產生器實作都應實作的介面。也提供具體 CopyListing 實作的選擇方式的工廠方法。
2. SimpleCopyListing：CopyListing 的實作，接受多個來源路徑（檔案/目錄），並遞迴列出每個路徑下的所有個別檔案和目錄，以供複製。
3. GlobbedCopyListing：CopyListing 的另一個實作，會在來源路徑中展開萬用字元。
4. FileBasedCopyListing：CopyListing 的實作，從指定檔案中讀取來源路徑清單。

根據 DistCpOptions 中是否指定來源檔案清單，來源清單會以下列其中一種方式產生

1. 如果沒有來源檔案清單，則使用 GlobbedCopyListing。會展開所有萬用字元，並將所有展開項目轉送至 SimpleCopyListing，而 SimpleCopyListing 會建構清單（透過遞迴每個路徑）。
2. 如果指定來源檔案清單，則使用 FileBasedCopyListing。來源路徑會從指定檔案中讀取，然後轉送至 GlobbedCopyListing。然後如上所述建構清單。

可以透過提供 CopyListing 介面的自訂實作，自訂建構複製清單的方法。DistCp 在這裡的行為與舊版 DistCp 不同，在於路徑如何考量複製。

也可以透過傳遞 CopyFilter 介面的目前支援實作或撰寫新的實作，自訂不應複製的檔案篩選。這可以透過在 DistCpOptions 中設定 distcp.filters.class 來指定

1. distcp.filters.class 為 “RegexCopyFilter”。如果您使用此實作，則必須傳遞包含用於篩選的正規表示式的 “CopyFilter” distcp.filters.file。支援 java.util.regex.Pattern 指定的正規表示式。
2. distcp.filters.class 為 “RegexpInConfigurationFilter”。如果您使用此實作，則必須使用 “DistCpOptions” 中的 distcp.exclude-file-regex 參數傳遞正規表示式。支援 java.util.regex.Pattern 指定的正規表示式。與 “RegexCopyFilter” 相比，這是一種更動態的方法。
3. distcp.filters.class 為 “TrueCopyFilter”。如果未指定上述任何選項，則此選項會用作預設實作。

舊版實作只會列出必須複製到目標的路徑。例如，如果檔案已存在於目標（且未指定 -overwrite），則檔案甚至不會在 MapReduce 複製工作中考慮。在設定期間（即在 MapReduce 工作之前）確定這一點，涉及檔案大小和檢查總和比較，這可能會耗時。

新的 DistCp 會將此類檢查延後到 MapReduce 工作，從而減少設定時間。由於這些檢查會在多個映射中並行處理，因此效能會進一步提升。

InputFormats 和 MapReduce 元件

InputFormats 和 MapReduce 元件負責實際將檔案和目錄從來源複製到目的地路徑。在執行複製時，會使用在複製清單產生期間建立的清單檔案。這裡感興趣的類別包括

• UniformSizeInputFormat：此 org.apache.hadoop.mapreduce.InputFormat 實作提供與 Legacy DistCp 相同的負載平衡功能，讓各個映射處理的資料量大致相同。UniformSizeInputFormat 的目標是讓每個映射複製的位元組數目大致相同。因此，清單檔案會分割成多個路徑群組，讓每個 InputSplit 中檔案大小的總和大致等於其他映射。分割並非總是完美，但其簡單的實作可將設定時間維持在低水準。

• DynamicInputFormat 和 DynamicRecordReader：DynamicInputFormat 實作 org.apache.hadoop.mapreduce.InputFormat，是 DistCp 的新增功能。清單檔案會分割成多個「區塊檔案」，區塊檔案的數量會是 Hadoop 工作中要求的映射數目的倍數。在啟動工作之前，會將每個映射工作「指定」給其中一個區塊檔案（方法是將區塊重新命名為工作的 ID）。會使用 DynamicRecordReader 從每個區塊讀取路徑，並在 CopyMapper 中處理。處理完區塊中的所有路徑後，會刪除目前的區塊並取得新的區塊。此程序會持續進行，直到沒有更多區塊可用為止。這種「動態」方法讓速度較快的映射工作可以比速度較慢的工作處理更多路徑，進而加速整體 DistCp 工作。

• CopyMapper：此類別實作實體檔案複製。會將輸入路徑與輸入選項（在工作的設定中指定）進行比對，以判斷是否需要複製檔案。只有符合下列其中一個條件時，才會複製檔案

  • 目標中不存在同名檔案。
  • 目標中存在同名檔案，但檔案大小不同。
  • 目標中存在同名檔案，但檢查碼不同，且未指定 -skipcrccheck。
  • 目標中存在同名檔案，但指定了 -overwrite。
  • 目標中存在同名檔案，但區塊大小不同（且需要保留區塊大小）。

• CopyCommitter：此類別負責 DistCp 工作的提交階段，包括

  • 保留目錄權限（如果在選項中指定）
  • 清除暫存檔案、工作目錄等。

映射大小調整

預設情況下，DistCp 會嘗試調整每個映射的大小，讓每個映射複製的位元組數目大致相同。請注意，檔案是細微程度最高的層級，因此增加同時複製的數量（即映射）並不一定會增加同時複製的數量或整體處理量。

新的 DistCp 也提供一種「動態」調整映射大小的策略，讓速度較快的資料節點可以複製比速度較慢的節點更多的位元組。使用 -strategy dynamic（在架構中說明），而非將一組固定的來源檔案指定給每個映射工作，而是將檔案分割成多組。組數會超過映射數目，通常是 2-3 倍。每個映射會選取並複製區塊中列出的所有檔案。當區塊用盡時，會取得並處理新的區塊，直到沒有更多區塊為止。

不將來源路徑指定給固定映射，速度較快的映射工作（即資料節點）就能夠使用更多區塊，因此比速度較慢的節點複製更多資料。雖然這種分配並不均勻，但考量到每個映射器的容量，這種分配是公平的。

動態策略是由 DynamicInputFormat 實作。在大部分情況下，它都能提供優異的效能。

建議針對來源和目的地叢集的大小、複製的大小，以及可用的頻寬調整映射數目，以執行長時間執行和定期執行的作業。

在 HDFS 版本之間複製

要在兩個不同主要版本的 Hadoop 之間複製（例如，在 1.X 和 2.X 之間），通常會使用 WebHdfsFileSystem。與先前的 HftpFileSystem 不同，由於 webhdfs 可用於讀取和寫入作業，因此可以在來源和目的地叢集上執行 DistCp。遠端叢集指定為 webhdfs://<namenode_hostname>:<http_port>。在 Hadoop 叢集的相同主要版本之間複製時（例如，在 2.X 和 2.X 之間），請使用 hdfs 協定以獲得更好的效能。

透過 distcp 安全複製

當 webhdfs 使用 SSL 保護時，請使用「swebhdfs://」架構。如需更多資訊，請參閱 SWebHDFS 的 SSL 組態。

MapReduce 和其他副作用

如前所述，如果映射無法複製其輸入之一，將會產生多個副作用。

• 除非指定 -overwrite，否則在重新執行時，先前映射成功複製的檔案將標記為「已略過」。
• 如果映射失敗 mapreduce.map.maxattempts 次，將會終止其餘的映射工作（除非設定 -i）。
• 如果設定 mapreduce.map.speculative 為最終和 true，則複製結果未定義。

DistCp 和物件儲存

DistCp 可與物件儲存（例如 Amazon S3、Azure ABFS 和 Google GCS）搭配使用。

先決條件

1. 包含物件儲存實作的 JAR 位於類別路徑上，以及其所有相依性。
2. 除非 JAR 自動註冊其綑綁的檔案系統用戶端，否則可能需要修改組態以陳述實作檔案系統架構的類別。ASF 自有的所有物件儲存用戶端都是自註冊的。
3. 相關的物件儲存存取憑證必須在叢集組態中提供，或在所有叢集主機中提供。

DistCp 可用於上傳資料

hadoop distcp -direct hdfs://nn1:8020/datasets/set1 s3a://bucket/datasets/set1

下載資料

hadoop distcp s3a://bucket/generated/results hdfs://nn1:8020/results

在物件儲存之間複製資料

hadoop distcp s3a://bucket/generated/results \
  wasb://updates@example.blob.core.windows.net

以及在物件儲存內複製資料

hadoop distcp wasb://updates@example.blob.core.windows.net/current \
  wasb://updates@example.blob.core.windows.net/old

並使用 -update 僅複製已變更的檔案。

hadoop distcp -update -numListstatusThreads 20  \
  s3a://history/2016 \
  hdfs://nn1:8020/history/2016

由於物件儲存列出檔案的速度較慢，因此請考慮在對大型目錄樹執行 -update 作業時設定 -numListstatusThreads 選項（限制為 40 個執行緒）。

當 DistCp -update 與物件儲存體搭配使用時，一般而言只會比較個別檔案的修改時間與長度，不會比較任何檢查碼，如果兩個儲存體之間的檢查碼演算法不同。

• 具有不同檢查碼演算法的兩個物件儲存體之間的 distcp -update 會比較來源和目標檔案的修改時間以及檔案大小，以判斷是否略過檔案複製。此行為由屬性 distcp.update.modification.time 控制，預設設為 true。如果來源檔案比目標檔案最近修改，則假設內容已變更，且應更新檔案。我們需要確保機器之間沒有時鐘偏移。大多數物件儲存體確實具有目錄的有效時間戳記，這點無關緊要；只會比較檔案時間戳記。不過，重要的是讓用戶端電腦的時鐘接近基礎架構的時鐘，以便用戶端/HDFS 集群與物件儲存體之間的時間戳記一致。否則，變更的檔案可能會被遺漏/過於頻繁地複製。

• distcp.update.modification.time 僅會在兩個儲存體都沒有檢查碼驗證，導致兩個儲存體之間的檢查碼比較不相容時使用。即使將屬性設為 true，如果兩個儲存體之間有有效的檢查碼比較，也不會使用它。

若要關閉修改時間檢查，請在 core-site.xml 中設定這項設定

<property>
        <name>distcp.update.modification.time</name>
        <value>false</value>
</property>

備註

• -atomic 選項會導致暫時資料重新命名，因此會大幅增加作業結束時提交工作的時間。此外，由於除了 (選擇性的) wasb:// 以外的物件儲存體不提供目錄的原子重新命名，因此 -atomic 作業實際上並未提供所承諾的內容。避免使用。

• 不支援 -append 選項。

• 不支援 -diff 和 rdiff 選項

• 無論 -skipCrc 標記的值為何，都不會執行 CRC 檢查。

• 一般而言，所有 -p 選項（包括保留權限、使用者和群組資訊、屬性檢查碼和複製）都會被忽略。wasb:// 連接器會保留資訊，但不會強制執行權限。

• 有些物件儲存體連接器提供輸出記憶體內暫存的選項，例如 S3A 連接器。在複製大型檔案時使用此選項可能會觸發某種形式的記憶體不足事件，可能是堆疊溢位或 YARN 容器終止。如果叢集和物件儲存體之間的網路頻寬有限（例如在使用遠端物件儲存體時），這種情況特別常見。最好停用/避免此類選項，並依賴磁碟暫存。

• 單一物件儲存體內的複製作業仍會在 Hadoop 群集中進行，即使物件儲存體內部實作更有效率的 COPY 作業

  也就是說，例如以下作業

  hadoop distcp s3a://bucket/datasets/set1 s3a://bucket/datasets/set2

  會將每個位元組複製到 Hadoop 工作節點，然後再複製回儲存區。除了速度慢之外，這表示可能會產生費用。

• 可以使用 -direct 選項直接寫入物件儲存體目標路徑，避免可能非常耗時的暫時性檔案重新命名作業，否則會發生此類作業。