Windows+WSL2+Ubuntu+Docker Desktop部署EMQX v5 落地文档

Windows+WSL2+Ubuntu+Docker Desktop部署EMQX v5 落地文档

文档说明

基础信息

• 适用系统：Windows10/Windows11 家庭版/专业版（支持WSL2）

• 部署架构：Windows主机 → WSL2(Ubuntu) → Docker → EMQX MQTT服务

• 服务版本：EMQX v5.3.2

• 适配说明 ：针对国内网络优化，规避Docker官网境外网页无法访问、网易/百度镜像源解析失败问题，补充离线安装包、国内可用备用镜像

名词概念对照

名词	说明	对比传统虚拟机
WSL2	Windows原生内置轻量Linux子系统，秒级启动，动态分配内存	相比VMware占用资源极低，和Windows系统无缝互通
Ubuntu	主流Linux发行版，作为Docker容器运行底层环境	无需单独安装虚拟机系统，开箱即用
Docker Desktop	Windows端容器可视化管理工具，依托WSL2运行容器	图形化操作，无需复杂命令行配置容器环境
EMQX	高性能MQTT消息服务器，负责物联网设备消息中转、订阅分发	本地部署适合网关、物联网设备本地调试，无需公网服务器

---

一、安装WSL2 + Ubuntu（全程无外网依赖）

1. 打开管理员终端

Win+X，选择【Windows终端(管理员)】或【PowerShell(管理员)】

2. 一键安装Ubuntu并启用WSL2

# 默认安装Ubuntu，自动开启WSL2、虚拟机平台功能
wsl --install -d Ubuntu

# 可选：指定安装路径到D盘，避免占用C盘空间
wsl --install -d Ubuntu --location D:\WSL\Ubuntu

3. 关键步骤

1. 命令执行完毕后，必须重启电脑，WSL功能才能生效

2. 重启后开始菜单打开Ubuntu，自定义Linux用户名、登录密码（牢记密码，后续sudo命令需要）

4. 校验WSL版本（必做）

wsl -l -v

✅ 正常输出结果：VERSION列必须为2

NAME      STATE    VERSION
Ubuntu    Running  2

5. 常见WSL报错修复

• 报错0x800701bc：缺少WSL2内核更新包，微软官网下载内核补丁安装即可

• 版本显示1：执行 wsl --set-default-version 2 强制默认WSL2

---

二、Docker Desktop安装（解决境外官网无法访问问题）

1. 问题说明

原官方下载地址：https://www.docker.com/products/docker-desktop 为境外网页，国内直接访问报错无法打开，放弃官网下载，使用国内镜像站离线安装包

2. 国内Docker Desktop离线下载地址（可用）

• 阿里云镜像站：https://mirrors.aliyun.com/docker-toolbox/windows/docker-desktop/

• 选择最新稳定版exe安装包下载，全程国内高速下载

3. 安装配置步骤

1. 运行安装包，必须勾选 Use WSL 2 instead of Hyper-V

2. 安装完成启动Docker Desktop，选择【Continue without signing in】跳过账号登录

4. 绑定WSL2运行后端

打开Docker Desktop → 右上角⚙️设置

1. General通用设置：勾选 Use the WSL 2 based engine

2. Resources资源 → WSL集成：开启Ubuntu系统集成

3. 点击Apply & Restart保存并重启Docker

5. 校验Docker环境

# Ubuntu终端 / PowerShell均可执行
docker --version
docker run --rm hello-world

输出Hello from Docker!即代表Docker环境搭建成功

---

三、修复WSL内Docker权限报错

报错现象

permission denied while trying to connect to the docker daemon

修复命令（Ubuntu终端执行）

sudo usermod -aG docker $USER
newgrp docker

执行后无需重启，即可免sudo直接使用docker命令

---

四、Docker镜像加速配置（解决网易/百度镜像解析失败）

原有问题说明

原有国内镜像源失效：

1. 网易镜像：https://hub-mirror.c.163.com 网页解析失败

2. 百度镜像：https://mirror.baidubce.com 网页解析失败

直接替换为华为云 SWR加速源

修改Docker引擎配置

Docker设置 → Docker Engine，替换全部配置代码：

{
  "registry-mirrors": [
    "https://docker.mirrors.huaweicloud.com"
  ],
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false
}

点击Apply & Restart重启Docker，镜像拉取速度大幅提升

---

五、Docker部署EMQX v5服务

1. 拉取EMQX镜像

docker pull emqx/emqx:5.3.2

2. 启动EMQX容器（全端口映射）

docker run -d --name emqx \
-p 1883:1883 \
-p 8083:8083 \
-p 8084:8084 \
-p 8883:8883 \
-p 18083:18083 \
emqx/emqx:5.3.2

返回一串容器ID，代表容器后台启动成功

3. 访问EMQX管理后台

• 访问地址：http://localhost:18083

• 默认账号：admin

• 默认密码：public

• ⚠️ 首次登录强制修改初始密码，务必妥善保存

---

六、EMQX端口用途对照表

端口号	协议	用途说明
1883	TCP	设备/网关标准MQTT接入端口（最常用）
8083	WebSocket	网页端MQTT连接端口
8883	TCP/TLS	加密MQTT接入端口（生产环境推荐）
8084	WebSocket/TLS	加密网页端MQTT连接端口
18083	HTTP	EMQX可视化管理后台端口

---

七、常用Docker运维命令

docker ps                     # 查看正在运行的容器
docker ps -a                  # 查看全部容器（含已停止）
docker logs emqx              # 查看EMQX运行日志，排查报错
docker stop emqx              # 停止EMQX容器
docker start emqx             # 启动EMQX容器
docker restart emqx           # 重启EMQX容器
docker rm -f emqx             # 强制删除容器（镜像保留，重启无需重新拉取）
docker images                 # 查看本地所有Docker镜像

---

八、局域网网关/硬件设备接入EMQX配置

1. 获取电脑局域网IP

ipconfig

找到无线/以太网适配器IPv4地址，例：192.168.3.105

2. Windows防火墙放行1883端口（关键，否则外网设备连不上）

1. Win+R输入 wf.msc 打开高级防火墙

2. 左侧选择【入站规则】→ 右侧【新建规则】

3. 规则类型：端口 → 协议TCP，特定端口1883

4. 操作：允许连接 → 域/专用/公网全部勾选

5. 规则名称：EMQX-MQTT-1883，完成创建

3. 网关设备MQTT接入参数

配置项	填写内容
MQTT服务地址(Broker)	电脑局域网IPv4地址
端口	1883
MQTT版本	MQTT 3.1.1 / MQTT5
上报主题	自定义，例：device/gateway/data
QoS等级	推荐1（保证消息至少送达一次）

---

九、全套部署常见问题汇总

故障现象	根因	解决方案
Docker官网无法打开	境外网址国内网络拦截	使用阿里云国内镜像站下载离线安装包
网易、百度镜像解析失败	官方镜像源已失效	替换为中科大、阿里云可用镜像源
WSL docker命令权限不足	当前用户未加入docker用户组	执行文档内权限分组命令
局域网设备无法连接EMQX	Windows防火墙拦截端口	手动放行1883端口入站规则
镜像拉取超时缓慢	默认直连国外Docker Hub	开启国内镜像加速

---