1. 为什么用 Docker 搭 HDFS 集群比虚拟机更省心
很多人第一次接触 Hadoop 完全分布式集群，第一反应是开三台虚拟机，装系统、配网络、改 hosts、传安装包，一套流程走下来大半天就没了。更让人头疼的是，虚拟机一旦快照损坏或者磁盘写满，整个集群就得推倒重来。我自己早期也是这么干的，后来改用 Docker 之后，搭建一套可用的 HDFS 完全分布式集群，从零到能跑通hdfs dfs -ls /，熟练的话二十分钟以内就能搞定。
这个方案的核心思路很简单：用 Docker 容器模拟多台物理机，每个容器跑一个 Hadoop 进程角色，通过自定义的 bridge 网络让它们互相通信。NameNode 单独一个容器，DataNode 开两到三个容器，再配一个容器跑 SecondaryNameNode 或者 ResourceManager。这样做的好处是资源占用小、启动快、销毁重建成本极低，特别适合学习和本地验证。
不过这里有个前提需要说清楚：Docker 搭建的 HDFS 集群，本质上还是单机上的多进程模拟，它不具备真正跨物理机的容灾能力。如果你的目标是生产环境部署，那这套方案只能作为功能验证和开发测试用，真正的生产集群还是要考虑物理机或者专业的容器编排方案。但对于学习 HDFS 的架构原理、验证配置参数、调试客户端连接来说，Docker 方案完全够用，而且效率高得多。
我见过不少人卡在第一步就放弃了，原因往往不是技术难度大，而是被各种环境问题消耗了耐心。Docker 恰好能把环境问题标准化，你只需要关注 Hadoop 本身的配置逻辑。接下来我会把整个搭建过程拆开讲，包括镜像怎么选、网络怎么规划、配置文件每一项为什么这么写、启动顺序为什么不能乱，以及我踩过的那些坑。
2. 镜像选择与基础环境规划
2.1 为什么不用官方 hadoop 镜像
Docker Hub 上确实有 hadoop 相关的镜像，但我不推荐直接用。原因有三个：第一，很多官方镜像的 Hadoop 版本偏老，默认配置和现在的文档对不上；第二，镜像里预装的 JDK 版本和 SSH 配置不一定符合你的需求，改起来反而麻烦；第三，你很难搞清楚镜像构建过程中到底改了哪些配置，出了问题排查成本高。
我的做法是基于一个干净的 Linux 基础镜像自己装。推荐用ubuntu:20.04或者centos:7，这两个系统的软件源稳定，社区资料多。JDK 用 OpenJDK 8，Hadoop 用 3.3.x 版本，这个组合经过大量验证，兼容性最好。
注意：Hadoop 3.x 对 JDK 版本有要求，JDK 8 和 JDK 11 都可以，但 JDK 17 及以上会有模块化相关的兼容问题，不建议新手尝试。
2.2 容器角色分配与资源预估
一套最小可用的完全分布式 HDFS 集群，至少需要三个节点：一个 NameNode、一个 SecondaryNameNode、一个 DataNode。但为了体现"完全分布式"的特点，DataNode 最好开两个，这样能看到数据块在多个节点之间的复制效果。
| 容器名称 | 角色 | 建议内存 | 建议 CPU |
|---|---|---|---|
| namenode | NameNode | 1.5G | 1 核 |
| secondarynamenode | SecondaryNameNode | 1G | 1 核 |
| datanode1 | DataNode | 1G | 1 核 |
| datanode2 | DataNode | 1G | 1 核 |
四个容器加起来大概需要 4.5G 内存，如果你的开发机有 16G 内存，跑这套集群绰绰有余。如果内存紧张，可以把 SecondaryNameNode 和 NameNode 合并到一个容器里，但这样就不算严格的完全分布式了，学习效果会打折扣。
2.3 网络模式的选择逻辑
Docker 的网络模式有 bridge、host、none 几种。搭 HDFS 集群必须用自定义 bridge 网络，不能用默认的 bridge。原因是默认 bridge 网络里容器之间只能用 IP 通信，不支持自动 DNS 解析，而 Hadoop 的配置文件里需要写主机名。自定义 bridge 网络可以让容器通过容器名互相访问，这样配置文件里直接写namenode、datanode1这样的主机名就行，不用去查 IP。
创建自定义网络的命令很简单：
docker network create --subnet=172.20.0.0/16 hdfs-net指定子网是为了避免和宿主机已有的网段冲突。172.20 这个网段一般不会被占用，比较安全。创建好之后，启动容器时加上--network hdfs-net参数即可。
3. 构建带 SSH 和 JDK 的基础镜像
3.1 Dockerfile 的编写要点
Hadoop 的启动脚本依赖 SSH 来批量启动从节点进程，所以容器里必须装 SSH 服务，并且配置免密登录。这是整个搭建过程中最容易出问题的地方，我详细说一下。
FROM ubuntu:20.04 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && apt-get install -y \ openjdk-8-jdk \ openssh-server \ openssh-client \ vim \ net-tools \ curl \ && rm -rf /var/lib/apt/lists/* RUN mkdir -p /var/run/sshd RUN ssh-keygen -t rsa -P '' -f ~/.ssh/id_rsa \ && cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys \ && chmod 600 ~/.ssh/authorized_keys RUN echo "PermitRootLogin yes" >> /etc/ssh/sshd_config \ && echo "PasswordAuthentication no" >> /etc/ssh/sshd_config ENV JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64 ENV PATH=$JAVA_HOME/bin:$PATH EXPOSE 22 CMD ["/usr/sbin/sshd", "-D"]这个 Dockerfile 里有几个关键点需要解释。DEBIAN_FRONTEND=noninteractive是为了避免安装过程中弹出交互式配置界面卡住构建。ssh-keygen生成密钥对之后直接把公钥追加到authorized_keys，这样容器内部自己连自己就不需要密码了。PermitRootLogin yes是允许 root 用户通过 SSH 登录，Hadoop 脚本默认用当前用户启动，容器里一般就是 root。
3.2 免密登录的验证方法
镜像构建完成后，先启动一个测试容器验证 SSH 免密是否生效：
docker run -it --rm --name ssh-test hdfs-base:1.0 bash进入容器后执行：
ssh localhost如果不需要输入密码就直接进入了，说明免密配置成功。如果提示Permission denied，检查authorized_keys的权限是不是 600，以及.ssh目录权限是不是 700。这两个权限不对，SSH 会拒绝使用密钥。
实操心得：很多人在这里卡住是因为
.ssh目录权限被设成了 777，SSH 出于安全考虑会忽略权限过松的密钥文件。记住.ssh是 700，authorized_keys是 600，id_rsa是 600。
3.3 镜像构建与打标签
docker build -t hdfs-base:1.0 .构建完成后用docker images确认镜像存在。这个基础镜像后面四个容器都要用，所以先把它准备好，后面启动容器就快了。
4. 四个容器的启动与 Hadoop 配置落地
4.1 启动容器并挂载配置目录
我习惯把 Hadoop 的配置文件放在宿主机的一个目录里，然后挂载到容器中。这样做的好处是改配置不用进容器，直接在宿主机编辑就行，而且容器销毁重建后配置还在。
先在宿主机创建目录结构：
mkdir -p ~/hdfs-cluster/{namenode,secondarynamenode,datanode1,datanode2}然后依次启动四个容器：
docker run -d --name namenode --network hdfs-net --hostname namenode \ -v ~/hdfs-cluster/namenode:/opt/hadoop-config \ -p 9870:9870 -p 9000:9000 hdfs-base:1.0 docker run -d --name secondarynamenode --network hdfs-net --hostname secondarynamenode \ -v ~/hdfs-cluster/secondarynamenode:/opt/hadoop-config \ hdfs-base:1.0 docker run -d --name datanode1 --network hdfs-net --hostname datanode1 \ -v ~/hdfs-cluster/datanode1:/opt/hadoop-config \ hdfs-base:1.0 docker run -d --name datanode2 --network hdfs-net --hostname datanode2 \ -v ~/hdfs-cluster/datanode2:/opt/hadoop-config \ hdfs-base:1.0NameNode 容器额外映射了 9870 和 9000 两个端口。9870 是 Hadoop 3.x 的 Web UI 端口，9000 是 HDFS 的 RPC 通信端口。客户端从宿主机访问 HDFS 时需要用到 9000。
4.2 在容器内安装 Hadoop
四个容器都需要安装 Hadoop。为了省事，可以先在一个容器里装好，然后用docker commit生成新镜像，再基于新镜像重建其他容器。但更干净的做法是写一个安装脚本，在每个容器里执行一遍。
# 进入 namenode 容器 docker exec -it namenode bash # 下载并解压 Hadoop cd /opt curl -O https://archive.apache.org/dist/hadoop/common/hadoop-3.3.6/hadoop-3.3.6.tar.gz tar -xzf hadoop-3.3.6.tar.gz mv hadoop-3.3.6 hadoop其他三个容器重复同样的操作。如果觉得下载慢，可以在宿主机下载好之后用docker cp复制进去。
4.3 核心配置文件逐项拆解
Hadoop 的配置文件都在$HADOOP_HOME/etc/hadoop/目录下。需要改的有五个文件：core-site.xml、hdfs-site.xml、workers、hadoop-env.sh、ssh相关配置。
core-site.xml定义 HDFS 的默认文件系统和临时目录：
<configuration> <property> <name>fs.defaultFS</name> <value>hdfs://namenode:9000</value> </property> <property> <name>hadoop.tmp.dir</name> <value>/opt/hadoop/data/tmp</value> </property> </configuration>fs.defaultFS写的是namenode这个主机名，因为容器在自定义 bridge 网络里可以通过容器名解析。hadoop.tmp.dir是 Hadoop 的临时目录，NameNode 的元数据和 DataNode 的数据块默认都放在这个目录下面。这个目录一定要确保存在并且有写权限，否则启动时会报错。
hdfs-site.xml定义副本数和各节点数据目录：
<configuration> <property> <name>dfs.replication</name> <value>2</value> </property> <property> <name>dfs.namenode.name.dir</name> <value>file:///opt/hadoop/data/namenode</value> </property> <property> <name>dfs.datanode.data.dir</name> <value>file:///opt/hadoop/data/datanode</value> </property> <property> <name>dfs.namenode.secondary.http-address</name> <value>secondarynamenode:9868</value> </property> </configuration>副本数设为 2，因为我们只有两个 DataNode。如果设成 3，HDFS 会一直提示副本不足，虽然不影响使用，但看着不舒服。dfs.namenode.secondary.http-address指定 SecondaryNameNode 的地址，Hadoop 3.x 默认端口是 9868。
workers文件列出所有 DataNode 的主机名：
datanode1 datanode2这个文件在启动 DataNode 时会被读取，start-dfs.sh脚本会根据这个列表逐个 SSH 到对应节点启动 DataNode 进程。
hadoop-env.sh里需要显式指定 JAVA_HOME：
export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64虽然镜像里已经设了环境变量，但 Hadoop 的启动脚本有时候读不到，显式写一遍最保险。
4.4 配置文件的同步策略
四个容器都需要同一份配置文件。我的做法是在宿主机编辑好一份，然后用docker cp复制到每个容器：
for node in namenode secondarynamenode datanode1 datanode2; do docker cp core-site.xml $node:/opt/hadoop/etc/hadoop/ docker cp hdfs-site.xml $node:/opt/hadoop/etc/hadoop/ docker cp workers $node:/opt/hadoop/etc/hadoop/ docker cp hadoop-env.sh $node:/opt/hadoop/etc/hadoop/ done这样能保证四个节点的配置完全一致，避免因为配置差异导致节点之间通信失败。
5. 格式化与启动过程中的关键细节
5.1 格式化 NameNode 的正确姿势
第一次启动集群之前，必须格式化 NameNode。这个操作只能在 NameNode 容器里执行，而且只能执行一次。
docker exec -it namenode bash hdfs namenode -format格式化成功的标志是看到Storage directory /opt/hadoop/data/namenode has been successfully formatted这行输出。如果看到Re-format filesystem的提示，说明之前已经格式化过了，这时候要谨慎，重新格式化会清空所有元数据。
注意：如果你改了
dfs.namenode.name.dir的路径，或者删除了数据目录，需要重新格式化。但如果是正常重启集群，绝对不要重复格式化，否则 DataNode 的 clusterID 和 NameNode 对不上，DataNode 会拒绝连接。
5.2 启动顺序为什么不能乱
HDFS 的启动有严格的依赖关系。正确的顺序是：先启动 NameNode，再启动 DataNode，最后启动 SecondaryNameNode。虽然start-dfs.sh脚本会按顺序帮你启动，但理解这个顺序背后的原因很重要。
NameNode 是 HDFS 的大脑，它维护着整个文件系统的元数据。DataNode 启动时需要向 NameNode 注册并汇报自己持有的数据块信息。如果 NameNode 还没起来，DataNode 会不断重试连接，日志里会刷一堆Connection refused。SecondaryNameNode 负责定期合并 NameNode 的 edits 和 fsimage，它也需要先能连上 NameNode。
启动命令：
# 在 namenode 容器里执行 start-dfs.sh这个脚本会读取 workers 文件，SSH 到每个 DataNode 启动进程。如果 SSH 免密没配好，这一步会卡住或者报错。
5.3 验证集群是否真正跑起来了
启动完成后，用jps命令检查各节点的进程：
| 节点 | 期望进程 |
|---|---|
| namenode | NameNode |
| secondarynamenode | SecondaryNameNode |
| datanode1 | DataNode |
| datanode2 | DataNode |
如果某个节点缺少对应进程，去$HADOOP_HOME/logs/目录下看日志。最常见的错误是端口占用和权限问题。
还可以通过 Web UI 验证：在宿主机浏览器访问http://localhost:9870，能看到 HDFS 的概览页面，里面会显示活跃的 DataNode 数量。如果显示 2 个活跃节点，说明集群正常。
再做一个实际的文件操作测试：
hdfs dfs -mkdir -p /test/input echo "hello hdfs" > test.txt hdfs dfs -put test.txt /test/input/ hdfs dfs -cat /test/input/test.txt能正常创建目录、上传文件、读取文件，说明整个 HDFS 集群工作正常。
6. 那些让我折腾半天的坑与排查思路
6.1 DataNode 启动后立刻退出
这是最常见的问题。DataNode 进程起来几秒钟就没了，jps看不到。排查步骤是这样的：先看 DataNode 的日志，日志里通常会写java.net.ConnectException: Connection refused或者clusterID mismatch。
如果是Connection refused，说明 DataNode 连不上 NameNode。检查两个地方：一是 NameNode 是否真的启动了，二是core-site.xml里的fs.defaultFS写的主机名能不能解析。在 DataNode 容器里执行ping namenode，如果能 ping 通说明网络没问题。
如果是clusterID mismatch，说明 DataNode 之前加入过另一个集群，它的 clusterID 和当前 NameNode 不一致。解决办法是删除 DataNode 的数据目录，重新启动让它重新注册。这也是为什么我强调不要重复格式化 NameNode。
6.2 SSH 免密登录在容器间失效
start-dfs.sh需要从 NameNode 免密 SSH 到各个 DataNode。虽然我们在镜像构建时配了本机免密，但容器之间的免密需要额外处理。
最简单的办法是把 NameNode 的公钥复制到所有 DataNode 的authorized_keys里。可以写个脚本批量做：
# 在 namenode 容器里获取公钥 cat ~/.ssh/id_rsa.pub # 把公钥内容追加到每个 datanode 的 authorized_keys docker exec datanode1 bash -c "echo '公钥内容' >> ~/.ssh/authorized_keys" docker exec datanode2 bash -c "echo '公钥内容' >> ~/.ssh/authorized_keys"验证方法是在 namenode 容器里执行ssh datanode1，不需要密码就能进入就说明配置成功。
6.3 端口映射与客户端连接问题
如果你在宿主机上用 Java 客户端连接 HDFS，会遇到一个经典问题：客户端通过localhost:9000连上 NameNode 后，NameNode 返回的 DataNode 地址是容器内部的 IP 和主机名，宿主机无法解析datanode1这个主机名，导致后续的数据读写失败。
解决办法有两个：一是在宿主机的 hosts 文件里加上容器 IP 和主机名的映射；二是配置dfs.client.use.datanode.hostname为 true，并且在hdfs-site.xml里指定 DataNode 使用主机名通信。我一般用第一种方法，简单直接。
# 查看容器 IP docker inspect -f '{{.NetworkSettings.Networks.hdfs-net.IPAddress}}' datanode1 # 在宿主机 /etc/hosts 里添加 172.20.0.3 datanode1 172.20.0.4 datanode26.4 内存不足导致进程被 kill
Hadoop 默认的 JVM 堆内存配置偏大，NameNode 默认 4G，DataNode 默认 4G。如果宿主机内存不够，容器里的进程会被系统 OOM killer 干掉。
解决办法是修改hadoop-env.sh，显式设置堆内存：
export HDFS_NAMENODE_OPTS="-Xmx1024m -Xms512m" export HDFS_DATANODE_OPTS="-Xmx512m -Xms256m" export HDFS_SECONDARYNAMENODE_OPTS="-Xmx512m -Xms256m"这样每个进程的内存占用就降下来了，四个容器加起来 3G 左右就能跑起来。
7. 集群的日常维护与快速重建
7.1 停止与重启的正确操作
停止集群用stop-dfs.sh，在 NameNode 容器里执行。这个脚本会按相反顺序停止各节点进程。停止之后，容器的数据目录里还保留着元数据和数据块，下次启动时不需要重新格式化，直接start-dfs.sh就能恢复。
如果只是想重启某个 DataNode，可以单独在对应容器里执行hdfs --daemon stop datanode和hdfs --daemon start datanode。NameNode 会自动感知到 DataNode 的下线和上线。
7.2 用 Docker Compose 一键管理
手动敲四个docker run命令太麻烦，用 Docker Compose 可以把整个集群定义在一个文件里：
version: '3' services: namenode: image: hdfs-base:1.0 container_name: namenode hostname: namenode networks: - hdfs-net ports: - "9870:9870" - "9000:9000" volumes: - ./namenode:/opt/hadoop-config secondarynamenode: image: hdfs-base:1.0 container_name: secondarynamenode hostname: secondarynamenode networks: - hdfs-net datanode1: image: hdfs-base:1.0 container_name: datanode1 hostname: datanode1 networks: - hdfs-net datanode2: image: hdfs-base:1.0 container_name: datanode2 hostname: datanode2 networks: - hdfs-net networks: hdfs-net: driver: bridge有了这个文件，docker-compose up -d一键启动，docker-compose down一键销毁，重建集群的成本几乎为零。
7.3 数据持久化的取舍
容器销毁后数据就没了，这是 Docker 的特性。如果你希望数据保留，需要把数据目录挂载到宿主机。但 HDFS 的数据目录结构比较复杂，直接挂载可能会遇到权限问题。我的建议是：学习阶段不用太在意数据持久化，集群跑通了、验证了功能就行，需要保留的数据及时导出到宿主机。
如果确实需要持久化，可以在docker-compose.yml里给每个服务加上数据目录的 volume 映射，但要确保宿主机目录的权限和容器内用户匹配。
7.4 从这套集群还能延伸学什么
集群跑起来只是第一步。基于这套环境，你可以继续验证很多 HDFS 的核心机制。比如手动 kill 掉一个 DataNode 进程，观察 NameNode 的 Web UI 上活跃节点数的变化，以及副本重新复制的触发过程。比如上传一个大文件，然后用hdfs fsck /path -files -blocks -locations查看每个数据块分布在哪些 DataNode 上。再比如修改副本数配置，观察集群如何自动调整数据分布。
这些实验在虚拟机上做成本很高，但在 Docker 里就是几条命令的事。把集群当成一个可以随意折腾的沙盒，学习效率会高很多。
我个人在实际操作中的体会是，Docker 搭 HDFS 集群最大的价值不是省资源，而是让"重建"这件事变得毫无心理负担。虚拟机时代我不敢随便改配置，怕搞坏了要重装；现在配置改错了，docker-compose down再up一下，两分钟就回到干净状态。这种敢于试错的环境，才是学习分布式系统最需要的。
