MQTT 镜像部署文档
MQTT 镜像部署文档 - 简化版
📋 概述
本文档提供MQTT服务的快速Docker部署方案，专注于三个核心功能：
- 启动容器 - 一键启动MQTT服务
- 设置密码 - 安全认证配置
- 挂载数据 - 数据持久化存储
🚀 快速部署
1. 创建项目目录
mkdir mqtt-deployment
cd mqtt-deployment
2. 创建 Docker Compose 配置
创建 docker-compose.yml 文件：
version: '3.8'services:mqtt-broker:image: eclipse-mosquitto:latestcontainer_name: mqttrestart: unless-stoppedports:- "1883:1883" # MQTT协议端口volumes:- ./mosquitto/config:/mosquitto/config # 配置文件目录- ./mosquitto/data:/mosquitto/data # 数据目录- ./mosquitto/log:/mosquitto/log # 日志目录command: mosquitto -c /mosquitto/config/mosquitto.conf
3. 测试容器并生成密码文件
# 1. 先启动一个测试容器
docker run --rm -d --name mqtt-test -p 1883:1883 eclipse-mosquitto:latest# 2. 进入测试容器创建用户密码
docker exec -it mqtt-test sh# 3. 在容器内创建密码文件（将 your_username 替换为你的用户名）
mosquitto_passwd -c /tmp/passwd your_username
# 根据提示输入密码# 4. 退出容器
exit# 5. 从测试容器复制密码文件到本地
docker cp mqtt-test:/tmp/passwd ./mosquitto/config/passwd# 6. 停止测试容器
docker stop mqtt-test
4. 创建配置文件
# 创建基础配置文件
cat > mosquitto/config/mosquitto.conf << EOF
# 基本配置
persistence true
persistence_location /mosquitto/data
log_dest file /mosquitto/log/mosquitto.log# 监听1883端口
listener 1883# 密码认证配置
allow_anonymous false
password_file /mosquitto/config/passwd
EOF
5. 启动MQTT服务
docker-compose up -d
🔐 添加更多用户（可选）
如果需要添加更多用户：
# 进入运行中的容器
docker-compose exec mqtt-broker sh# 添加新用户（不使用 -c 参数，避免覆盖现有文件）
mosquitto_passwd /mosquitto/config/passwd another_user# 退出容器
exit# 重启服务使新用户生效
docker-compose restart
🔍 连接测试
命令行测试
订阅消息（终端1）：
mosquitto_sub -h localhost -t "test/topic" -u "your_username" -P "your_password"
发布消息（终端2）：
mosquitto_pub -h localhost -t "test/topic" -m "Hello, MQTT!" -u "your_username" -P "your_password"
图形化工具测试
推荐使用 MQTTX 或其他MQTT客户端工具：
- 服务器地址:
localhost - 端口:
1883 - 用户名:
your_username - 密码:
your_password
📁 目录结构说明
mqtt-deployment/
├── docker-compose.yml # Docker编排文件
└── mosquitto/├── config/│ ├── mosquitto.conf # MQTT配置文件│ └── passwd # 用户密码文件├── data/ # 持久化数据存储└── log/└── mosquitto.log # 服务日志
⚙️ 服务管理
基本操作
# 启动服务
docker-compose up -d# 停止服务
docker-compose down# 重启服务
docker-compose restart# 查看服务状态
docker-compose ps# 查看日志
docker-compose logs -f mqtt-broker
用户管理
# 添加新用户
docker-compose exec mqtt-broker mosquitto_passwd /mosquitto/config/passwd new_user# 删除用户
docker-compose exec mqtt-broker mosquitto_passwd -D /mosquitto/config/passwd username# 查看用户列表
docker-compose exec mqtt-broker cat /mosquitto/config/passwd
🔧 配置说明
主要配置项
| 配置项 | 说明 | 默认值 |
|---|---|---|
persistence | 数据持久化 | true |
persistence_location | 数据存储位置 | /mosquitto/data |
log_dest | 日志输出 | file /mosquitto/log/mosquitto.log |
listener | 监听端口 | 1883 |
allow_anonymous | 允许匿名连接 | false |
password_file | 密码文件位置 | /mosquitto/config/passwd |
高级配置（可选）
如需更多功能，可在 mosquitto.conf 中添加：
# 启用WebSocket支持
listener 9001
protocol websockets# 设置最大连接数
max_connections 1000# 设置消息大小限制
message_size_limit 268435456# 启用桥接功能
connection bridge-to-broker
address remote.broker.com:1883
topic sensors/# out 0
🚨 故障排查
常见问题
1. 无法连接MQTT服务
# 检查容器状态
docker-compose ps# 检查端口占用
netstat -tlnp | grep 1883# 查看容器日志
docker-compose logs mqtt-broker
2. 认证失败
# 检查密码文件是否存在
docker-compose exec mqtt-broker ls -la /mosquitto/config/passwd# 验证用户密码
docker-compose exec mqtt-broker mosquitto_passwd -c /mosquitto/config/passwd test_user
3. 数据丢失
# 检查数据目录挂载
docker-compose exec mqtt-broker ls -la /mosquitto/data# 检查配置文件
cat mosquitto/config/mosquitto.conf
📊 监控和维护
日志管理
# 查看实时日志
docker-compose logs -f mqtt-broker# 查看日志文件
tail -f mosquitto/log/mosquitto.log# 清理旧日志
find mosquitto/log/ -name "*.log" -mtime +30 -delete
备份和恢复
# 备份配置和数据
tar -czf mqtt-backup-$(date +%Y%m%d).tar.gz mosquitto/# 恢复备份
tar -xzf mqtt-backup-20240101.tar.gz
🔒 安全建议
- 修改默认端口：生产环境建议使用非标准端口
- 启用SSL/TLS：配置证书加密传输
- 定期更新密码：建议定期更换用户密码
- 网络隔离：使用防火墙限制访问来源
- 监控连接：定期检查异常连接
📞 技术支持
- 官方文档: Eclipse Mosquitto
- Docker Hub: eclipse-mosquitto
- 社区支持: Mosquitto Mailing List
注意: 本部署方案适用于开发和测试环境，生产环境请根据实际需求进行安全加固。