Eclipse Mosquitto 2.1 中 per_listener_settings 弃用迁移指南：listener 级安全配置与插件按需挂载实战

本文面向使用 Eclipse Mosquitto 的运维与开发人员，讲解自 2.1 起被弃用、并将在 3.0 移除的 per_listener_settings 选项的完整替代方案：如何用 listener_allow_anonymous、listener_auto_id_prefix 等 listener 级安全选项，以及 plugin_load / plugin_use 插件挂载机制，在保留原有功能的前提下平滑迁移配置。读完本文，你将能识别旧配置中的隐患、按步骤重写配置，并理解这些新选项在 conf.c 中的底层解析行为与测试验证方式。

为什么 per_listener_settings 会被弃用

per_listener_settings 选项诞生于 Mosquitto 1.5，其目的是允许 allow_anonymous、password_file 这类安全选项按监听器（listener）生效，而不是像此前那样只能全局生效。但从设计上看，它引入了一个"切换开关"式的全局状态：开启后，后续出现的所有安全相关选项都被绑定到"当前 listener"上，一旦配置顺序、默认 listener 等细节处理不当，就容易出现配置被错误关联、安全策略意外放行的问题。

由于该设计带来大量混淆，Mosquitto 从 2.1 开始将其标记为弃用，并计划在 3.0 版本中彻底移除。官方迁移说明见 per_listener_settings 迁移文档，2.1 发布说明也明确列出了这一弃用决定（见 version-2-1-0-released.md 中 "per_listener_settings 被弃用，代之以新的 listener 专用选项"）。

在源码层面，per_listener_settings 的弃用警告在 conf.c 中通过 OPTION_DEPRECATED 宏输出：解析到该选项时会打印 "The 'per_listener_settings' option is now deprecated and will be removed in version 3.0"，并且该选项一旦被置为 true 就不允许再被改回（源码注释为"Once this is set, don't let it be unset"），同时要求它必须出现在任何其他安全设置之前，否则直接报错 "per_listener_settings must be set before any other security settings"。这些细节正是它容易踩坑的根源——配置顺序强依赖全局状态。

迁移前置条件

本次迁移涉及的替代选项均在 Mosquitto 2.1 中引入，因此：

• 必须升级到 2.1 或更高版本 才能使用下文全部方案；
• 如果你仍运行 1.x 或 2.0.x，请先升级，再执行迁移；
• 2.1 中 password_file、acl_file 等选项本身也被逐步弃用（password_file 已在 2.1 中标记弃用，见 version-2-1-0-released.md），建议在本次迁移中一并处理；
• 迁移完成后，per_listener_settings 选项可以从配置文件中删除；继续保留它只会收到弃用警告，且在 3.0 中会直接报错。

认证与鉴权配置的迁移

官方文档给出的认证相关迁移对应关系如下，逐个对照替换即可：

旧选项	新方案
acl_file	使用 mosquitto_acl_file 插件
password_file	使用 mosquitto_password_file 插件
allow_anonymous	listener 级 listener_allow_anonymous
auto_id_prefix	listener 级 listener_auto_id_prefix
allow_zero_length_clientid	无替代选项（见下文说明）

用插件替换 acl_file 与 password_file

旧写法通常是：

# 旧配置（已弃用）
per_listener_settings true
listener 1883
acl_file /etc/mosquitto/acl
password_file /etc/mosquitto/passwd

新写法改用插件加载（路径需按你的安装目录调整，下面以动态安全插件的典型路径为例）：

plugin_load acl /usr/lib/mosquitto_acl_file.so
plugin_opt_config_file /etc/mosquitto/acl

plugin_load password /usr/lib/mosquitto_password_file.so
plugin_opt_config_file /etc/mosquitto/passwd

listener 1883
plugin_use acl
plugin_use password

2.1 发布说明中提到 password_file 选项被弃用的原因正是"同样的代码被移入插件"（"the same code but moved into a plugin"），所以迁移后行为保持不变，只是加载方式改变。密码文件与 ACL 文件的格式本身不变，可参考 pwfile.example 与 aclfile.example。

用 listener_allow_anonymous 替代 allow_anonymous

allow_anonymous 是全局布尔选项，旧配置在 per_listener_settings 开启时借助"当前 listener"状态实现按监听器生效。新方案直接提供了 listener 级选项：

# 全局默认：禁止匿名（供未显式设置的 listener 继承）
allow_anonymous false

listener 1883
listener_allow_anonymous true    # 该 listener 允许匿名

listener 1884
listener_allow_anonymous false   # 该 listener 强制要求认证

listener 1885
# 未设置，回退到全局 allow_anonymous 的值（false）

行为要点（与官方文档及 mosquitto.conf 示例配置 一致）：

• 若某 listener 未设置 listener_allow_anonymous，则使用全局 allow_anonymous 的值；
• 若同时设置了二者，listener_allow_anonymous 始终优先；
• 该选项不支持热重载（"Not reloaded on reload signal"，见 mosquitto.conf.5.xml 中 listener_allow_anonymous 条目），修改后需重启 broker。

源码实现上，解析器对 listener_allow_anonymous 直接写入当前 listener 的 security_options->allow_anonymous 字段（conf.c），从而天然实现"每监听器一份安全配置"，不再依赖全局切换开关。对应的集成测试见 01-connect-listener-allow-anonymous.py，该测试同时覆盖了全局 allow_anonymous 与各 listener 级覆盖值的组合矩阵。

用 listener_auto_id_prefix 替代 auto_id_prefix

auto_id_prefix 用于给自动生成的客户端 ID（即客户端未携带 client id 连接时）添加前缀，便于日志追踪，全局默认前缀为 auto-。迁移后：

listener 1883
listener_auto_id_prefix iot-    # 该 listener 的自动 ID 前缀

listener 1884
listener_auto_id_prefix edge-   # 不同 listener 可用不同前缀

约束与实现细节：

• 前缀长度不得超过 50 个字符，超出时解析器会报错 'listener_auto_id_prefix' length must be <= 50；
• 与 listener_allow_anonymous 一样，写入的是当前 listener 的 security_options->auto_id_prefix 字段，并同步计算 auto_id_prefix_len（见 conf.c 中 listener_auto_id_prefix 分支）；
• 该选项同样不支持热重载；
• 旧的 auto_id_prefix 选项在 2.1 中仍可解析，但会输出弃用提示并建议改用 listener_auto_id_prefix。

allow_zero_length_clientid 没有替代方案

官方文档明确指出：allow_zero_length_clientid 没有替代选项。这意味着迁移后，各 listener 将统一遵循全局默认行为（不允许零长度客户端 ID）。如果你的业务确实依赖零长度 client id，需要在迁移时评估客户端行为，必要时在客户端侧改为显式提供 client id，或使用自动生成的 ID（配合 listener_auto_id_prefix 提升可辨识度）。

插件按需挂载：plugin_load 与 plugin_use

旧模型的问题

在 2.1 之前，插件加载只有 plugin 与 global_plugin 两个选项：

• global_plugin：始终作用于所有 listener；
• plugin：在 per_listener_settings false 时作用于所有 listener，在 per_listener_settings true 时仅作用于"当前 listener"（通过 REQUIRE_LISTENER_IF_PER_LISTENER 与 conf__set_cur_security_options 实现，见 conf.c）。

也就是说，plugin 选项的行为会随 per_listener_settings 的取值而改变，这是造成混淆的又一来源。man 手册中 global_plugin 条目也说明了这一点：当 per_listener_settings false 时，global_plugin 与 plugin 行为完全相同（mosquitto.conf.5.xml）。

新模型：加载与使用分离

2.1 引入了职责分离的两个选项：

• plugin_load：把插件加载进 broker（可指定名称），等价于"注册"；
• plugin_use：把已加载的插件应用到某个 listener，等价于"挂载"。

global_plugin 仍然保留，用于"所有 listener 都启用某插件"的场景。

官方文档给出的示例配置如下：

plugin_load dynsec /usr/lib/mosquitto_dynamic_security.so
plugin_opt_config_file /mosquitto/data/dynamic-security.json

listener 1883
plugin_use dynsec

listener 1884
listener_allow_anonymous true

listener 1885
plugin_use dynsec

该配置的语义：

• 动态安全插件（dynamic-security）只被加载一次，但只挂载到 1883 与 1885 两个 listener；
• 1884 端口没有挂载任何插件，且显式设置了 listener_allow_anonymous true——官方文档特别提醒：这个端口极不安全，任何连接者都可以发布/订阅任意主题，生产中通常不应这样配置，此处仅为演示"某些 listener 不使用插件"的效果。

使用要点：

• plugin_use 引用的名称必须与 plugin_load 时给定的名称一致，否则解析器报错 Plugin '%s' not previously loaded（见 conf.c 中 plugin_use 分支）；
• plugin_load 的插件名不允许重复，重复定义会报错 Duplicate plugin name；
• plugin_use 只能作用于显式定义的 listener（REQUIRE_NON_DEFAULT_LISTENER），即不能挂在默认 listener 上；
• plugin_load / plugin_use 与 plugin / global_plugin 一样，不支持在热重载时使用（解析器在 reload 时直接跳过）；
• 插件专属的配置项（如 plugin_opt_config_file）必须在 plugin_load 之后出现，因为 REQUIRE_PLUGIN 宏要求"先有 plugin/global_plugin/plugin_load，再谈选项"。

若需要"所有 listener 都启用同一插件"，继续使用 global_plugin 即可，无需逐个 plugin_use：

global_plugin /usr/lib/mosquitto_acl_file.so

源码与测试佐证

plugin_use 的挂载本质是把插件附加到目标 listener 的安全选项链上：config__plugin_add_secopt(cur_plugin, cur_listener->security_options)（见 conf.c）。这与旧模型里 plugin 在 per_listener_settings true 时"绑定当前 listener"的效果一致，但不再依赖全局状态。

仓库中的集成测试 09-plugin-load-acl.py 同时验证了新模型与旧模型的等价性：测试用同一个 plugin_load acl 定义，在 1883 端口 plugin_use acl 挂载 ACL 插件、在 1884 端口不挂载；断言结果是 1883 上发布被 ACL 拒绝的主题收到 NOT_AUTHORIZED，而 1884 上同一主题可以正常发布——这直接印证了"按 listener 决定插件是否生效"的行为。该测试还分别在 per_listener_settings false 与 true 两种旧配置下各跑一遍，确认迁移前后行为一致。

完整迁移示例：从旧配置到新配置

下面是一个完整的迁移对照。旧配置（2.0 风格，已弃用）：

# 旧配置
per_listener_settings true

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
auto_id_prefix mqtt-

listener 1884
allow_anonymous true
auto_id_prefix anon-

新配置（2.1+ 推荐写法）：

# 新配置
plugin_load password /usr/lib/mosquitto_password_file.so
plugin_opt_config_file /etc/mosquitto/passwd

plugin_load acl /usr/lib/mosquitto_acl_file.so
plugin_opt_config_file /etc/mosquitto/acl

# 全局默认：未显式设置的 listener 一律禁止匿名
allow_anonymous false

listener 1883
plugin_use password
plugin_use acl
listener_auto_id_prefix mqtt-

listener 1884
listener_allow_anonymous true
listener_auto_id_prefix anon-

新旧行为对照：

行为	旧配置效果	新配置效果
1883 认证	password_file + acl_file	password 插件 + acl 插件（同一代码移入插件）
1883 匿名	禁止	继承全局 allow_anonymous false，禁止
1884 匿名	允许	listener_allow_anonymous true，允许
1883 自动 ID 前缀	mqtt-	listener_auto_id_prefix mqtt-
1884 自动 ID 前缀	anon-	listener_auto_id_prefix anon-

迁移完成后建议执行以下验证步骤：

1. 检查配置文件语法：mosquitto -c /path/to/mosquitto.conf -p 0（启动后确认无 "deprecated" 告警即可）；
2. 用 mosquitto_pub / mosquitto_sub（见 client）分别连接 1883 与 1884，验证匿名策略与插件鉴权行为符合预期；
3. 观察日志中的自动生成客户端 ID，确认前缀与各 listener 的设置一致；
4. 若启用持久化，注意确认监听器变更在重启后正确生效（listener 相关选项不支持热重载，需完整重启）。

常见问题与排查

Q1：迁移后日志仍出现 "deprecated" 警告？ 说明配置中仍残留 per_listener_settings（或 password_file/acl_file/auto_id_prefix）等旧选项。弃用警告仅提示，不会阻止启动，但 3.0 起这些选项将无法解析，建议尽早清理。

Q2：plugin_use 报 "Plugin not previously loaded"？ 检查 plugin_use 后面的名称是否与 plugin_load 中给定的名称完全一致（区分大小写），并确认 plugin_load 行位于 plugin_use 之前。

Q3：某些 listener 明明设置了 listener_allow_anonymous，匿名连接仍被拒绝？ 确认该 listener 是否还加载了强制认证的插件（如 password 插件），插件鉴权优先级高于匿名设置；同时确认配置修改后已完整重启 broker（该选项不支持热重载）。

Q4：plugin_opt_* 选项报错？ plugin_opt_*（兼容旧名 auth_opt_*）必须出现在对应 plugin_load 之后，且不能用于 reload 流程。

Q5：迁移后行为与旧配置不一致？ 优先检查"默认 listener"问题：旧配置在 per_listener_settings true 时，若安全选项出现在任何 listener 之前，会被绑定到自动创建的默认 listener（1883）；新配置则要求 plugin_use、listener_* 等选项明确放在目标 listener 块内，迁移时应把每个安全选项逐一归位。

参考资源

• 迁移官方文档：per_listener_settings.md
• 配置解析实现：src/conf.c（per_listener_settings、listener_allow_anonymous、listener_auto_id_prefix、plugin_load、plugin_use 各分支）
• 完整示例配置：mosquitto.conf
• 手册页（含各选项默认值与 reload 行为）：mosquitto.conf.5.xml
• ACL 文件插件：plugins/acl-file/plugin.c
• 密码文件插件：plugins/password-file/plugin.c
• 集成测试：09-plugin-load-acl.py、01-connect-listener-allow-anonymous.py