EMQX 是一款开源的 MQTT 服务器，体验一年下来非常稳定。我使用的是社区自托管版本（开源版），对于个人需求来说，开源版功能已经足够使用，无需购买商业收费版。
搭建采用的服务器是一台 1C1G 的服务器，内存只有 1G 属于勉强够用，偶尔会出现告警日志 high_system_memory_usage。近期考虑服务器迁移，顺便将内存升级到 2G。迁移过程中遇到了一些问题，在此记录下来。
发生了什么问题?
一言以蔽之，就是迁移后无法正常还原实例。讲道理这应该是一个很简单的问题，但无论我翻阅官方文档，还是和 AI 不断拉扯，实例虽然正常启动，但里面的数据却不对。索性我只能纯手工慢慢排查，最后总结出了正确的还原步骤。
我的环境是 Debian 12+、Docker，作为读者的你如果按我的操作执行，或许需要酌情调整。
快捷部署
1
2
3
4
5
6
7
8
| docker volume create emqx
docker run -d \
--name emqx \
--hostname mqtt \
--network host \
--restart unless-stopped \
-v emqx:/opt/emqx \
emqx/emqx:5.8.5
|
可以看出来非常简单，这条命令是一年多以前的搭建部署命令。因为当时就考虑到后期会迁移，所以使用了 volume 挂载到容器内部；其次网络类型直接使用 host，是为了简化网络管理，后期还要考虑反向代理和防火墙 UFW 策略。
部署成功后，默认启动的管理面板端口是 18083，默认账号密码 admin/public。
备份数据
备份配置数据
来到旧服务器，找到对应的 emqx 容器，执行以下命令：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
| # 执行备份命令
docker exec -it emqx emqx ctl data export
# Exporting data to "data/backup/emqx-export-2026-01-20-06-37-42.695.tar.gz"...
# Exporting cluster configuration...
# Exporting additional files from EMQX data_dir: "data"...
# Exporting built-in database...
# Exporting emqx_admin database table...
# Exporting emqx_app database table...
# Exporting emqx_psk database table...
# Exporting emqx_authn_mnesia database table...
# Exporting emqx_authn_scram_mnesia database table...
# Exporting emqx_acl database table...
# Exporting emqx_banned_rules database table...
# Exporting emqx_banned database table...
# Data has been successfully exported to data/backup/emqx-export-2026-01-20-06-37-42.695.tar.gz.
|
可以看到备份成功，容器内部的保存路径为：/opt/emqx/data/backup/emqx-export-2026-01-20-06-37-42.695.tar.gz，随后通过 docker cp 命令将其下载到本地。
备份卷数据
1
2
| # 执行压缩打包，并把最后的 emqx-volume-data.tar.gz 文件下载到本地
tar -cvzf ./emqx-volume-data.tar.gz -C /var/lib/docker/volumes/emqx/_data .
|
至此备份成功，你的本地应该有了两个文件，请将它们上传到新服务器：
- emqx-volume-data.tar.gz
- emqx-export-2026-01-20-06-37-42.695.tar.gz
迁移还原
1. 确保主机名一致
需要确保迁移前后的主机名完全一致，否则后期实例启动无法识别主节点数据。我的旧服务器主机名是 mqtt，所以在新服务器执行以下命令：
1
2
3
4
| # 执行后需重启才能完全生效
hostnamectl set-hostname mqtt
# 编辑文件 /etc/hosts，找到 127.0.0.1 对应的主机名，统一改为 mqtt
|
此步骤其实非必须，可以在部署时通过环境变量透传指定主机名，但我的建议还是确保一致，否则会增加部署命令的复杂度。
2. 还原 volume 启动实例
1
2
3
4
5
6
7
8
9
10
11
12
| # 创建卷数据
docker volume create emqx
# 还原数据
tar -xzvf ./emqx-volume-data.tar.gz -C /var/lib/docker/volumes/emqx/_data
# 启动实例
docker run -d \
--name emqx \
--hostname mqtt \
--network host \
--restart unless-stopped \
-v emqx:/opt/emqx \
emqx/emqx:5.8.5
|
此时你应该通过 docker logs -f emqx 观察容器是否启动成功。
3. 还原配置数据
通过 docker cp 命令将 emqx-export-2026-01-20-06-37-42.695.tar.gz 复制到容器内部，放到路径 /opt/emqx 即可：
1
2
3
4
5
6
7
8
| # 进入容器内部
docker exec -it emqx bash
# 执行还原
emqx ctl data import /opt/emqx/emqx-export-2026-01-20-06-37-42.695.tar.gz
# 退出容器
exit
|
最后执行 docker restart emqx 重启容器，迁移完成。随后上线检查一下数据是否正确。
总结
部署非常简单，配置好数据卷后一条命令即可启动成功。
迁移还原的话，要考虑到三个方面，且执行先后顺序不能乱：
- 确保主机名一致
- 打包迁移还原 volume 数据
- CLI 命令备份还原配置数据
参考
