（AI总结版）Docker + HBase 安装全过程总结（WSL2 + Win11）

Docker + HBase 安装全过程总结（WSL2 + Win11）

一、环境概览

项目	配置
操作系统	Windows 11 25H2
WSL 版本	WSL2
Linux 发行版	Ubuntu 24.04.3 LTS
Docker 版本	29.5.2 (Docker Desktop 4.75.0)
HBase 镜像	harisekhon/hbase (基于 HBase 2.1.3)

二、Docker Desktop 安装与配置

2.1 安装步骤

下载 Docker Desktop
- 访问 Docker Desktop: The #1 Containerization Tool for Developers | Docker
- 下载 Windows 版（AMD64 架构）
- 运行安装程序
安装选项选择
- 选择 Per-user installation（推荐，无需管理员权限）
- 勾选 Add shortcut to desktop
- 后续协议选择 Accept
- 首次启动选择 Continue without signing in
关键配置：WSL 2 集成
- Docker Desktop → Settings → Resources → WSL Integration
- 开启 Enable integration with my default WSL distro
- 开启 Ubuntu 发行版
- 点击 Apply & Restart

2.2 用户权限配置（重要）

问题：Docker 命令报 permission denied while trying to connect to the docker API

原因：当前用户不在 docker 用户组中

解决方案：

bash

复制代码

# 将用户加入 docker 组
sudo usermod -aG docker $USER

# 激活组权限（二选一）
# 方法一：退出 WSL 重新连接
exit
# 方法二：在当前会话中直接激活
newgrp docker

三、网络配置

3.1 代理配置问题

问题现象：

text

复制代码

failed to do request: Head "...": writing response to registry-1.docker.io:443: reading HTTP CONNECT: unexpected EOF

或

text

复制代码

connecting to 127.0.0.1:1080: connectex: No connection could be made because the target machine actively refused it

原因：Docker 仍在尝试使用已关闭的代理

解决方案 ：

Docker Desktop → Settings → Resources → Proxies

Docker Desktop proxy → No proxy
Containers proxy → No proxy
点击 Apply & Restart

3.2 镜像加速器配置

问题现象：

text

复制代码

Error response from daemon: failed to resolve reference "...": failed to do request: Head "...": EOF

或

text

复制代码

{"errors":[{"code":"TOOMANYREQUESTS","message":"免费节点当前繁忙..."}]}

原因：国内网络访问 Docker Hub 不稳定；免费镜像加速器有频率限制

解决方案 ：

Docker Desktop → Settings → Docker Engine → 配置 registry-mirrors：

json

复制代码

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io",
    "https://docker.xuanyuan.me"
  ]
}

点击 Apply & Restart 生效。

验证配置：

bash

复制代码

docker info | grep -A 5 "Registry Mirrors"

3.3 网络稳定性问题

问题现象 ：大镜像下载过程中断，出现 unexpected EOF 或 connection reset

原因：网络不稳定

解决方案：

直接重新执行 docker pull 命令，Docker 支持断点续传
可配合手机热点切换网络环境临时使用

四、用户名问题（重要踩坑）

问题现象：

text

复制代码

Error response from daemon: pull access denied for hello-world, repository does not exist or may require 'docker login'

原因：Windows 用户名以数字开头（如 86178），导致 Docker 在 WSL 中的权限解析失败

解决方案：在 WSL 中创建以字母开头的新用户

bash

复制代码

# 1. 创建新用户（以 jinqiu 为例）
sudo useradd -m -s /bin/bash jinqiu

# 2. 设置密码
sudo passwd jinqiu

# 3. 加入 sudo 组
sudo usermod -aG sudo jinqiu

# 4. 加入 docker 组
sudo usermod -aG docker jinqiu

# 5. 切换到新用户
su - jinqiu

# 6. 测试 Docker
docker run hello-world

五、HBase 安装步骤

5.1 拉取镜像

bash

复制代码

# 拉取 HBase 镜像（约 1GB）
docker pull harisekhon/hbase

# 验证镜像
docker images | grep hbase

5.2 运行容器

bash

复制代码

# 创建并启动 HBase 容器
docker run -d \
  --name hbase \
  -p 16010:16010 \
  -p 16000:16000 \
  -p 2181:2181 \
  -p 16020:16020 \
  -p 16030:16030 \
  harisekhon/hbase

端口说明：

端口	用途
16010	HBase Master Web UI
16000	HBase Master RPC
2181	ZooKeeper
16020	RegionServer RPC
16030	RegionServer Web UI

5.3 验证运行

bash

复制代码

# 查看容器状态
docker ps

# 查看启动日志
docker logs -f hbase
# 关键日志：Master has completed initialization

# 进入 HBase Shell
docker exec -it hbase hbase shell

5.4 HBase Shell 测试

text

复制代码

# 查看集群状态
status 'simple'

# 列出所有表
list

# 创建表
create 'test', 'cf'

# 插入数据
put 'test', 'row1', 'cf:name', 'Alice'

# 查询数据
get 'test', 'row1'

# 扫描表
scan 'test'

# 退出
exit

5.5 Web UI 访问

浏览器打开：http://localhost:16010

六、完整的问题排查清单

步骤	检查项	验证命令	常见问题	解决方案
1	WSL 版本	`wsl --list --verbose`	版本为 1	`wsl --set-default-version 2`
2	Docker 服务	`docker --version`	命令未找到	安装 Docker Desktop
3	WSL 集成	Settings → WSL Integration	未开启	开启 Ubuntu 集成
4	用户权限	`groups`	无 docker 组	`sudo usermod -aG docker $USER`
5	网络连通	`ping baidu.com`	无法解析	配置 DNS
6	镜像加速	`docker info	grep -A 5 "Registry Mirrors"`	无输出
7	代理配置	Settings → Proxies	仍尝试代理	设置为 No proxy
8	拉取测试	`docker pull hello-world`	失败	检查网络/加速器

七、环境清理与重置

清理 Docker 缓存

bash

复制代码

# 清理未使用的镜像、容器、网络
docker system prune -a

# 清理构建缓存
docker builder prune

重置 Docker Desktop

Settings → Troubleshoot → Reset to factory defaults

完全卸载 HBase 容器

bash

复制代码

docker stop hbase
docker rm hbase
docker rmi harisekhon/hbase

完全卸载 Docker Desktop

Windows 设置 → 应用 → Docker Desktop → 卸载
手动删除 C:\Users\用户名\AppData\Local\Docker
手动删除 C:\Users\用户名\AppData\Roaming\Docker

八、经验总结

8.1 关键教训

用户名不能以数字开头 --- WSL/Docker 环境对此敏感，会引发难以排查的权限问题
免费镜像加速器有频率限制 --- 高峰期返回 429 错误，需配置多个备用源
Docker 代理配置容易遗留 --- 关闭代理软件后必须手动将 Docker 代理设为 No proxy
大镜像下载支持断点续传 --- 中断后直接重试即可，无需重新开始
先验证基础环境再安装目标组件 --- docker run hello-world 是黄金测试命令

8.2 正确安装路径

text

复制代码

1. 确保 WSL2 正常运行
   ↓
2. 安装 Docker Desktop，配置 WSL 集成
   ↓
3. 创建字母开头的 Linux 用户，加入 docker 组
   ↓
4. 配置镜像加速器（registry-mirrors）
   ↓
5. 关闭 Docker 代理设置（Proxies → No proxy）
   ↓
6. 测试 hello-world
   ↓
7. 拉取目标镜像
   ↓
8. 运行容器并验证

8.3 快速复用配置

将以下配置保存为 docker-daemon.json：

json

复制代码

{
  "registry-mirrors": [
    "https://docker.1ms.run",
    "https://docker.m.daocloud.io"
  ]
}

将以下命令保存为 docker-setup.sh：

bash

复制代码

#!/bin/bash
# Docker 环境初始化脚本

# 创建新用户（需要 sudo 权限）
# sudo useradd -m -s /bin/bash dev
# sudo passwd dev
# sudo usermod -aG sudo dev
# sudo usermod -aG docker dev

# 验证安装
docker --version
docker info | grep -A 5 "Registry Mirrors"
docker run hello-world

echo "Docker 环境验证完成"

九、常用命令速查

Docker 基础命令

bash

复制代码

# 镜像管理
docker pull <镜像名>
docker images
docker rmi <镜像ID>

# 容器管理
docker run -d --name <名称> <镜像>
docker ps
docker ps -a
docker stop <容器名>
docker start <容器名>
docker restart <容器名>
docker rm <容器名>

# 日志与交互
docker logs -f <容器名>
docker exec -it <容器名> <命令>

# 系统清理
docker system prune -a

HBase 专用命令

bash

复制代码

# 进入 HBase Shell
docker exec -it hbase hbase shell

# 查看 HBase Web UI
# 浏览器打开 http://localhost:16010

# 查看 HBase 日志
docker logs -f hbase

# 重启 HBase
docker restart hbase

十、最终验证清单

验证项	命令	预期结果
Docker 版本	`docker --version`	显示版本号
Docker 运行	`docker ps`	无报错
镜像加速器	`docker info	grep -A 5 "Registry Mirrors"`
拉取测试	`docker run hello-world`	显示 Hello from Docker
HBase 镜像	`docker images	grep hbase`
HBase 容器	`docker ps	grep hbase`
HBase Shell	`docker exec -it hbase hbase shell`	进入 Shell
Web UI	浏览器访问 `localhost:16010`	显示 HBase Master 界面