mosquitto.conf文件详细配置
本文将所有配置项按功能分类逐一说明，分为以下几大模块：
文件格式说明：以
#开头的行是注释。配置行格式为变量名 值，变量名和值之间用单个空格分隔。
一、通用基础配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
pid_file |
空 | 写入进程 PID 的文件路径。通常设为 /var/run/mosquitto.pid |
user |
不设置 | 以 root 启动时，降权到此用户运行。不推荐留空 |
connection_messages |
true |
是否在日志中记录客户端连接/断开事件 |
include_dir |
无 | 指定一个目录，该目录下所有 .conf 文件都会被加载。应放在主文件最后 |
示例：
pid_file /var/run/mosquitto.pid
user mosquitto
connection_messages true
include_dir /etc/mosquitto/conf.d
二、监听器配置
2.1 基础监听器选项
| 配置项 | 默认值 | 说明 |
|---|---|---|
port |
1883 | 默认监听端口。不设置时只监听本地 loopback |
bind_address |
无 | 绑定到指定 IP 地址（如 192.168.1.100），不设则监听所有接口 |
listener |
无 | 定义额外监听器，格式：listener port [bind_address] |
max_connections |
-1 | 该监听器最大连接数，-1 表示无限制 |
protocol |
mqtt |
协议类型：mqtt（标准）或 websockets |
socket_domain |
自动 | 强制 IP 协议：ipv4 或 ipv6 |
http_dir |
无 | WebSocket 监听器下，指定 HTTP 静态文件目录 |
2.2 版本 2.0 重要行为变更
⚠️ 关键：从 Mosquitto 2.0 开始：
如果没有配置任何监听器，默认监听
127.0.0.1:1883（只允许本地连接）使用
-p参数指定的端口也只会绑定到 loopback如需对外开放，必须显式配置
listener并指定0.0.0.0或具体 IP
示例：
# 默认监听器 - 绑定到所有接口的 1883 端口
listener 1883 0.0.0.0
max_connections 10000
protocol mqtt
socket_domain ipv4
# WebSocket 监听器
listener 9001 0.0.0.0
protocol websockets
# 本地管理接口（只允许本机连接）
listener 1885 127.0.0.1
三、认证与安全配置
3.1 基础认证
| 配置项 | 默认值 | 说明 |
|---|---|---|
allow_anonymous |
见下文 | 是否允许无用户名密码的连接。无任何监听器时默认 true（仅本地）；否则默认 false |
password_file |
无 | 用户名密码文件路径（用 mosquitto_passwd 生成） |
acl_file |
无 | 访问控制列表文件路径 |
per_listener_settings |
false |
true 时认证选项可对不同监听器单独配置 |
allow_zero_length_clientid |
true |
是否允许客户端使用空 client ID（MQTT 3.1.1/5.0），Broker 会生成 |
auto_id_prefix |
auto- |
自动生成 client ID 时的前缀 |
check_retain_source |
true |
发布保留消息前，检查发布者的 ACL 权限是否仍然有效 |
3.2 证书/TLS 配置（每个监听器独立配置）
详细内容请参考
mosquitto-tls(7)手册
| 配置项 | 说明 |
|---|---|
cafile |
CA 证书文件路径（PEM 格式） |
capath |
CA 证书目录（需运行 c_rehash） |
certfile |
服务器证书文件 |
keyfile |
服务器私钥文件 |
tls_version |
TLS 版本：tlsv1.2、tlsv1.1、tlsv1 |
require_certificate |
false |
use_identity_as_username |
false |
crlfile |
证书吊销列表文件 |
ciphers |
加密套件列表 |
3.3 预共享密钥 (PSK) 配置
| 配置项 | 说明 |
|---|---|
psk_hint |
PSK 提示信息 |
psk_file |
PSK 密钥文件（格式：identity:key） |
use_identity_as_username |
使用 PSK identity 作为用户名 |
3.4 认证插件配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
auth_plugin_deny_special_chars |
true |
拒绝用户名/Client ID 中包含 + 或 # 的连接（防 CVE-2017-7650） |
认证模式决策树：
需要认证？
├─ 否 → allow_anonymous true
└─ 是 → allow_anonymous false
├─ 简单用户名/密码 → password_file
├─ 细粒度主题权限 → acl_file
├─ 证书认证 → certfile + keyfile + require_certificate true
└─ 大规模动态管理 → Dynamic Security Plugin
四、访问控制列表 (ACL) 配置
4.1 ACL 文件格式
ACL 文件通过 acl_file 指定，支持以下语法：
| 语法 | 说明 |
|---|---|
topic [read\|write\|readwrite] <topic> |
授权访问主题 |
topic deny <topic> |
明确拒绝（优先级最高） |
user <username> |
后续规则应用到特定用户 |
pattern [read\|write\|readwrite] <topic> |
动态主题（支持 %c=Client ID，%u=用户名） |
匹配顺序：先处理所有 deny 规则，再处理授权规则。
示例：
# 匿名用户只读 sensors/ 下的数据
topic read sensors/#
# 用户 admin 全部权限
user admin
topic readwrite #
# 设备只能发布自己的数据（动态）
pattern write sensors/%u/data
# 后端服务可读取所有设备数据
user backend
pattern read sensors/+/data
五、持久化配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
persistence |
false |
是否将内存数据持久化到磁盘 |
persistence_location |
当前目录 | 持久化文件存放路径（文件名为 mosquitto.db） |
autosave_interval |
1800 |
自动保存间隔（秒），0 表示只在退出或收到 SIGUSR1 时保存 |
autosave_on_changes |
false |
true 时基于变更次数触发保存，false 时基于时间触发 |
persistent_client_expiration |
无 | 持久会话客户端过期时间（格式：1h/2d/3w/4m/5y），超时未重连则清除 |
持久化说明：保存内容包括订阅关系、保留消息、队列中 QoS 1/2 消息。重启后可恢复。
六、日志配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
log_dest |
stderr |
输出目标：stderr、stdout、syslog、file <path>、topic |
log_type |
无（即全部不记录） | 日志类型：error、warning、notice、information、debug、subscribe、unsubscribe、websockets、all、none |
connection_messages |
true |
是否记录连接/断开事件 |
log_timestamp |
true |
日志是否包含时间戳 |
示例：
log_dest file /var/log/mosquitto/mosquitto.log
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information
connection_messages true
七、桥接配置 (Bridging)
桥接用于连接多个 MQTT Broker，形成分布式网络。
| 配置项 | 说明 |
|---|---|
connection <name> |
定义一个桥接连接 |
address <host>[:port] |
远程 Broker 地址 |
topic <pattern> [out\|in\|both] [qos-level] [local-prefix] [remote-prefix] |
桥接主题映射 |
remote_username / remote_password |
远程 Broker 认证 |
bridge_protocol_version |
协议版本：mqttv31 或 mqttv311 |
notifications |
是否发送桥接状态通知 |
cleansession |
桥接连接是否使用干净会话 |
start_type |
启动类型：automatic、lazy、once |
八、性能与限制配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
max_inflight_messages |
20 |
每个客户端同时进行中的 QoS 1/2 消息数，设为 1 保证顺序 |
max_queued_messages |
100 |
离线客户端队列最大消息数，0=无限制 |
queue_qos0_messages |
false |
是否队列化 QoS 0 消息（离线客户端） |
message_size_limit |
0 |
消息最大字节数，0=无限制 |
global_max_clients |
-1 |
全局最大客户端会话数（含在线和持久的离线会话） |
retry_interval |
20 |
重发 QoS 1/2 消息的间隔（秒） |
store_clean_interval |
10 |
消息存储清理间隔（秒） |
upgrade_outgoing_qos |
false |
是否将发出消息的 QoS 升级到订阅的 QoS（非标准，不推荐） |
allow_duplicate_messages |
true |
是否允许向重叠订阅发送重复消息（已弃用，未来版本移除） |
clientid_prefixes |
无 | 允许连接的 Client ID 前缀（已弃用） |
九、配置重载说明
Mosquitto 支持通过发送 SIGHUP 信号重新加载部分配置。
支持热重载的配置项
-
acl_file、allow_anonymous、allow_zero_length_clientid、auto_id_prefix -
autosave_interval、autosave_on_changes -
connection_messages、global_max_clients -
log_*、max_queued_messages、persistence*
不支持热重载的配置项
-
监听器（
listener、port、bind_address） -
TLS/SSL 证书相关
-
auth_plugin_deny_special_chars -
user、pid_file
重载方式：
# 重载配置
sudo kill -HUP $(cat /var/run/mosquitto.pid)
# 或使用 systemd
sudo systemctl reload mosquitto
十、最小生产配置示例
# ========== 基础 ==========
pid_file /var/run/mosquitto.pid
user mosquitto
connection_messages true
# ========== 监听器 ==========
# 外部访问端口
listener 1883 0.0.0.0
max_connections 10000
socket_domain ipv4
# TLS 端口
listener 8883 0.0.0.0
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false
# ========== 安全认证 ==========
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
allow_zero_length_clientid false
# ========== 持久化 ==========
persistence true
persistence_location /var/lib/mosquitto/
autosave_interval 900
# ========== 日志 ==========
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
log_type notice
# ========== 性能 ==========
max_inflight_messages 20
max_queued_messages 1000
message_size_limit 65536
# ========== 包含目录 ==========
include_dir /etc/mosquitto/conf.d
本文将所有配置项按功能分类逐一说明，分为以下几大模块：
文件格式说明：以
#开头的行是注释。配置行格式为变量名 值，变量名和值之间用单个空格分隔。
一、通用基础配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
pid_file |
空 | 写入进程 PID 的文件路径。通常设为 /var/run/mosquitto.pid |
user |
不设置 | 以 root 启动时，降权到此用户运行。不推荐留空 |
connection_messages |
true |
是否在日志中记录客户端连接/断开事件 |
include_dir |
无 | 指定一个目录，该目录下所有 .conf 文件都会被加载。应放在主文件最后 |
示例：
pid_file /var/run/mosquitto.pid
user mosquitto
connection_messages true
include_dir /etc/mosquitto/conf.d
二、监听器配置
2.1 基础监听器选项
| 配置项 | 默认值 | 说明 |
|---|---|---|
port |
1883 | 默认监听端口。不设置时只监听本地 loopback |
bind_address |
无 | 绑定到指定 IP 地址（如 192.168.1.100），不设则监听所有接口 |
listener |
无 | 定义额外监听器，格式：listener port [bind_address] |
max_connections |
-1 | 该监听器最大连接数，-1 表示无限制 |
protocol |
mqtt |
协议类型：mqtt（标准）或 websockets |
socket_domain |
自动 | 强制 IP 协议：ipv4 或 ipv6 |
http_dir |
无 | WebSocket 监听器下，指定 HTTP 静态文件目录 |
2.2 版本 2.0 重要行为变更
⚠️ 关键：从 Mosquitto 2.0 开始：
如果没有配置任何监听器，默认监听
127.0.0.1:1883（只允许本地连接）使用
-p参数指定的端口也只会绑定到 loopback如需对外开放，必须显式配置
listener并指定0.0.0.0或具体 IP
示例：
# 默认监听器 - 绑定到所有接口的 1883 端口
listener 1883 0.0.0.0
max_connections 10000
protocol mqtt
socket_domain ipv4
# WebSocket 监听器
listener 9001 0.0.0.0
protocol websockets
# 本地管理接口（只允许本机连接）
listener 1885 127.0.0.1
三、认证与安全配置
3.1 基础认证
| 配置项 | 默认值 | 说明 |
|---|---|---|
allow_anonymous |
见下文 | 是否允许无用户名密码的连接。无任何监听器时默认 true（仅本地）；否则默认 false |
password_file |
无 | 用户名密码文件路径（用 mosquitto_passwd 生成） |
acl_file |
无 | 访问控制列表文件路径 |
per_listener_settings |
false |
true 时认证选项可对不同监听器单独配置 |
allow_zero_length_clientid |
true |
是否允许客户端使用空 client ID（MQTT 3.1.1/5.0），Broker 会生成 |
auto_id_prefix |
auto- |
自动生成 client ID 时的前缀 |
check_retain_source |
true |
发布保留消息前，检查发布者的 ACL 权限是否仍然有效 |
3.2 证书/TLS 配置（每个监听器独立配置）
详细内容请参考
mosquitto-tls(7)手册
| 配置项 | 说明 |
|---|---|
cafile |
CA 证书文件路径（PEM 格式） |
capath |
CA 证书目录（需运行 c_rehash） |
certfile |
服务器证书文件 |
keyfile |
服务器私钥文件 |
tls_version |
TLS 版本：tlsv1.2、tlsv1.1、tlsv1 |
require_certificate |
false |
use_identity_as_username |
false |
crlfile |
证书吊销列表文件 |
ciphers |
加密套件列表 |
3.3 预共享密钥 (PSK) 配置
| 配置项 | 说明 |
|---|---|
psk_hint |
PSK 提示信息 |
psk_file |
PSK 密钥文件（格式：identity:key） |
use_identity_as_username |
使用 PSK identity 作为用户名 |
3.4 认证插件配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
auth_plugin_deny_special_chars |
true |
拒绝用户名/Client ID 中包含 + 或 # 的连接（防 CVE-2017-7650） |
认证模式决策树：
需要认证？
├─ 否 → allow_anonymous true
└─ 是 → allow_anonymous false
├─ 简单用户名/密码 → password_file
├─ 细粒度主题权限 → acl_file
├─ 证书认证 → certfile + keyfile + require_certificate true
└─ 大规模动态管理 → Dynamic Security Plugin
四、访问控制列表 (ACL) 配置
4.1 ACL 文件格式
ACL 文件通过 acl_file 指定，支持以下语法：
| 语法 | 说明 |
|---|---|
topic [read\|write\|readwrite] <topic> |
授权访问主题 |
topic deny <topic> |
明确拒绝（优先级最高） |
user <username> |
后续规则应用到特定用户 |
pattern [read\|write\|readwrite] <topic> |
动态主题（支持 %c=Client ID，%u=用户名） |
匹配顺序：先处理所有 deny 规则，再处理授权规则。
示例：
# 匿名用户只读 sensors/ 下的数据
topic read sensors/#
# 用户 admin 全部权限
user admin
topic readwrite #
# 设备只能发布自己的数据（动态）
pattern write sensors/%u/data
# 后端服务可读取所有设备数据
user backend
pattern read sensors/+/data
五、持久化配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
persistence |
false |
是否将内存数据持久化到磁盘 |
persistence_location |
当前目录 | 持久化文件存放路径（文件名为 mosquitto.db） |
autosave_interval |
1800 |
自动保存间隔（秒），0 表示只在退出或收到 SIGUSR1 时保存 |
autosave_on_changes |
false |
true 时基于变更次数触发保存，false 时基于时间触发 |
persistent_client_expiration |
无 | 持久会话客户端过期时间（格式：1h/2d/3w/4m/5y），超时未重连则清除 |
持久化说明：保存内容包括订阅关系、保留消息、队列中 QoS 1/2 消息。重启后可恢复。
六、日志配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
log_dest |
stderr |
输出目标：stderr、stdout、syslog、file <path>、topic |
log_type |
无（即全部不记录） | 日志类型：error、warning、notice、information、debug、subscribe、unsubscribe、websockets、all、none |
connection_messages |
true |
是否记录连接/断开事件 |
log_timestamp |
true |
日志是否包含时间戳 |
示例：
log_dest file /var/log/mosquitto/mosquitto.log
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information
connection_messages true
七、桥接配置 (Bridging)
桥接用于连接多个 MQTT Broker，形成分布式网络。
| 配置项 | 说明 |
|---|---|
connection <name> |
定义一个桥接连接 |
address <host>[:port] |
远程 Broker 地址 |
topic <pattern> [out\|in\|both] [qos-level] [local-prefix] [remote-prefix] |
桥接主题映射 |
remote_username / remote_password |
远程 Broker 认证 |
bridge_protocol_version |
协议版本：mqttv31 或 mqttv311 |
notifications |
是否发送桥接状态通知 |
cleansession |
桥接连接是否使用干净会话 |
start_type |
启动类型：automatic、lazy、once |
八、性能与限制配置
| 配置项 | 默认值 | 说明 |
|---|---|---|
max_inflight_messages |
20 |
每个客户端同时进行中的 QoS 1/2 消息数，设为 1 保证顺序 |
max_queued_messages |
100 |
离线客户端队列最大消息数，0=无限制 |
queue_qos0_messages |
false |
是否队列化 QoS 0 消息（离线客户端） |
message_size_limit |
0 |
消息最大字节数，0=无限制 |
global_max_clients |
-1 |
全局最大客户端会话数（含在线和持久的离线会话） |
retry_interval |
20 |
重发 QoS 1/2 消息的间隔（秒） |
store_clean_interval |
10 |
消息存储清理间隔（秒） |
upgrade_outgoing_qos |
false |
是否将发出消息的 QoS 升级到订阅的 QoS（非标准，不推荐） |
allow_duplicate_messages |
true |
是否允许向重叠订阅发送重复消息（已弃用，未来版本移除） |
clientid_prefixes |
无 | 允许连接的 Client ID 前缀（已弃用） |
九、配置重载说明
Mosquitto 支持通过发送 SIGHUP 信号重新加载部分配置。
支持热重载的配置项
-
acl_file、allow_anonymous、allow_zero_length_clientid、auto_id_prefix -
autosave_interval、autosave_on_changes -
connection_messages、global_max_clients -
log_*、max_queued_messages、persistence*
不支持热重载的配置项
-
监听器（
listener、port、bind_address） -
TLS/SSL 证书相关
-
auth_plugin_deny_special_chars -
user、pid_file
重载方式：
# 重载配置
sudo kill -HUP $(cat /var/run/mosquitto.pid)
# 或使用 systemd
sudo systemctl reload mosquitto
十、最小生产配置示例
# ========== 基础 ==========
pid_file /var/run/mosquitto.pid
user mosquitto
connection_messages true
# ========== 监听器 ==========
# 外部访问端口
listener 1883 0.0.0.0
max_connections 10000
socket_domain ipv4
# TLS 端口
listener 8883 0.0.0.0
cafile /etc/mosquitto/certs/ca.crt
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
require_certificate false
# ========== 安全认证 ==========
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
allow_zero_length_clientid false
# ========== 持久化 ==========
persistence true
persistence_location /var/lib/mosquitto/
autosave_interval 900
# ========== 日志 ==========
log_dest file /var/log/mosquitto/mosquitto.log
log_type error
log_type warning
log_type notice
# ========== 性能 ==========
max_inflight_messages 20
max_queued_messages 1000
message_size_limit 65536
# ========== 包含目录 ==========
include_dir /etc/mosquitto/conf.d
浙公网安备 33010602011771号