从零到一：EMQX部署实战与典型故障排查指南
1. EMQX简介与版本选择
EMQX是一款开源的分布式MQTT消息服务器，专为物联网场景设计。它就像物联网世界的"交通枢纽"，负责处理海量设备之间的消息传递。我第一次接触EMQX是在一个智能家居项目中，当时需要处理上万台设备的同时在线连接，传统方案根本扛不住这个压力。
目前EMQX主要有4.x和5.x两个大版本系列。新手建议从5.x开始，因为：
- 5.x版本对新手更友好，配置更简单
- 性能优化更明显，单机支持百万级连接
- 社区支持更活跃，遇到问题更容易找到解决方案
提示：生产环境建议选择长期支持版(LTS)，比如5.0.26版本就很稳定，我们团队已经跑了半年多没出过问题。
2. 安装准备与环境配置
2.1 系统要求检查
在安装前，先确认服务器是否符合最低要求：
- 内存：至少2GB（实测4GB才能稳定运行）
- 磁盘：10GB以上空间
- 操作系统：CentOS 7+/Ubuntu 18.04+
用这个命令检查系统信息：
free -h # 查看内存 df -h # 查看磁盘 uname -a # 查看系统版本2.2 依赖安装
EMQX需要一些基础依赖，不同系统安装命令不同：
CentOS/RHEL系统：
sudo yum install -y openssl epel-release sudo yum install -y libatomicUbuntu/Debian系统：
sudo apt update sudo apt install -y libatomic1 openssl我遇到过最坑的问题是glibc版本过低，报错信息很隐晦。解决方法是用这个命令升级：
sudo yum update glibc3. 详细安装步骤
3.1 通过包管理器安装
这是最推荐的方式，会自动处理依赖关系：
CentOS/RHEL：
curl -s https://assets.emqx.com/scripts/install-emqx-rpm.sh | sudo bash sudo yum install -y emqxUbuntu/Debian：
curl -s https://assets.emqx.com/scripts/install-emqx-deb.sh | sudo bash sudo apt install -y emqx安装完成后别急着启动，先检查下安装是否完整：
rpm -qa | grep emqx # CentOS dpkg -l | grep emqx # Ubuntu3.2 手动安装（适合离线环境）
有时候生产环境不能联网，就需要手动下载安装包：
- 官网下载对应版本的.rpm或.deb包
- 上传到服务器
- 执行安装：
sudo yum localinstall emqx-5.0.26-el7-amd64.rpm # CentOS sudo dpkg -i emqx-5.0.26-ubuntu18.04-amd64.deb # Ubuntu4. 服务启动与验证
4.1 启动EMQX服务
安装完成后，启动服务：
sudo systemctl start emqx检查服务状态：
sudo systemctl status emqx正常应该看到"active (running)"字样。如果没起来，先别慌，后面会讲排查方法。
4.2 验证基础功能
用这几个命令检查核心功能：
emqx_ctl status # 查看节点状态 netstat -tlnp | grep emqx # 检查端口监听 curl http://localhost:18083/api/v5/status # API检查正常应该看到1883(MQTT)、8883(SSL)、18083(控制台)等端口都在监听状态。
5. 防火墙配置
5.1 开放必要端口
要让外部设备连接，需要开放这些端口：
sudo firewall-cmd --permanent --add-port=1883/tcp sudo firewall-cmd --permanent --add-port=8883/tcp sudo firewall-cmd --permanent --add-port=18083/tcp sudo firewall-cmd --reload5.2 云服务器安全组
如果在阿里云、AWS等云平台，还需要配置安全组规则：
- 登录云平台控制台
- 找到安全组配置
- 添加入站规则，允许上述TCP端口
6. 典型故障排查
6.1 节点无响应问题
症状：emqx_ctl status显示"not responding to pings"
排查步骤：
- 检查Erlang cookie是否一致：
cat /var/lib/emqx/.erlang.cookie所有节点的cookie必须相同
- 检查主机名解析：
hostname -f ping $(hostname)- 检查节点名称配置：
vi /etc/emqx/emqx.conf确保node.name配置正确，比如：
node.name = emqx@127.0.0.16.2 端口未监听问题
症状：netstat看不到1883等端口
解决方法：
- 检查EMQX是否真的启动了：
ps aux | grep emqx- 查看日志找线索：
tail -100f /var/log/emqx/emqx.log常见错误：
- 端口被占用：修改conf文件换个端口
- 权限不足：用root启动或修改权限
- 配置错误：检查listen配置项
7. 日常运维命令
7.1 服务管理
sudo systemctl start emqx # 启动 sudo systemctl stop emqx # 停止 sudo systemctl restart emqx # 重启 sudo systemctl enable emqx # 设置开机自启7.2 监控与调试
emqx_ctl cluster status # 查看集群状态 emqx_ctl clients list # 查看连接客户端 emqx_ctl topics list # 查看活跃主题7.3 日志查看
tail -f /var/log/emqx/emqx.log # 实时日志 journalctl -u emqx -f # systemd日志8. 性能调优建议
8.1 基础参数调整
修改/etc/emqx/emqx.conf：
listeners.tcp.default.max_connections = 100000 listeners.ssl.default.max_connections = 500008.2 系统参数优化
调整内核参数：
echo "net.ipv4.tcp_max_syn_backlog = 10240" >> /etc/sysctl.conf echo "net.core.somaxconn = 10240" >> /etc/sysctl.conf sysctl -p8.3 监控设置
建议配置Prometheus监控：
# 修改emqx.conf prometheus.enabled = true prometheus.interval = 15s然后用Grafana导入官方仪表板模板，实时监控各项指标。