Eclipse Mosquitto 1.0.1 版本解析：Windows 服务 log_dest 默认值与 Python on

物联网
消息队列
后端
网络/通信

【免费下载链接】mosquitto

Eclipse Mosquitto - An open source MQTT broker

项目地址：https://gitcode.com/gh_mirrors/mo/mosquitto

Mosquitto 1.0.1 是 2012 年 8 月 15 日发布的纯缺陷修复版本，紧随引入 SSL/TLS 支持的重大版本 1.0 之后。本篇以官方发布说明 www/posts/2012/08/version-1-0-1-released.md 为主体，逐项拆解其五类修复（Broker 日志默认值、客户端库 Python 回调、客户端帮助输出、CMake 构建脚本、文档），并结合当前仓库中的配置解析源码、Windows 服务入口与日志回调实现，说明这些修复对应的机制与可验证依据。

版本定位：1.0.1 修复了什么

发布说明明确指出：这是一个 bugfix release，核心变化有两项：

修复 Python 模块中on_log()回调被调用时参数不正确的问题（Launchpad 缺陷 #1036818）；
修复 Mosquitto 作为Windows 服务运行时log_dest选项的默认值问题。

其余修复集中在文档与构建脚本层面。该版本的所有修复条目在 ChangeLog.txt 的1.0.1 - 20120815段落（约 2802 行起）中有完整归档，与发布说明一一对应：

模块	1.0.1 修复内容	对应缺陷
Broker	修复作为 Windows 服务运行时的默认`log_dest`	—
Client library	修复 Python`on_log()`回调调用参数错误	#1036818
Clients	编译时不支持 TLS/TLS-PSK 时不再显示相关 usage 帮助	—
Build scripts	修复 CMake 中 TLS-PSK 支持、man 页安装、`SYSCONFDIR`取值	#1036908
Documentation	修正 man 页 mqtt/MQTT 大小写、更新 compiling.txt、修正 mosquitto.py 回调文档、删除过期脚本	#1036607、#1037088

需要说明的版本背景：1.0 版本（20120814，见 ChangeLog.txt 中1.0 - 20120814段落）刚刚加入 SSL/TLS 与 TLS-PSK 支持，1.0.1 仅隔一天发布，因此其构建脚本修复（CMake 中 TLS-PSK 支持、man 页安装）本质上是对 1.0 新增 TLS 功能构建链的收尾修补。

Broker：Windows 服务下 log_dest 默认值修复

问题本质

log_dest决定 broker 日志的写入目标（syslog、文件、stdout、stderr、MQTT topic 等）。当 mosquitto 作为 Windows 服务运行时，此前默认日志目标会错误地指向 stdout/stderr，而服务进程没有控制台，这导致日志行为异常甚至日志内容被发送到意外的地方。1.0.1 将其默认值修正为不写日志。

当前仓库中的源码证据

配置初始化的代码路径在 src/conf.c 中，277～296 行可以看到这一修复在后继版本中的最终形态：

#if defined(WIN32) || defined(__CYGWIN__) if(service_handle){ /* This is running as a Windows service. Default to no logging. Using * stdout/stderr is forbidden because the first clients to connect will * get log information sent to them for some reason. */ config->log_dest = MQTT3_LOG_NONE; }else{ config->log_dest = MQTT3_LOG_STDERR; } #else config->log_facility = LOG_DAEMON; config->log_dest = MQTT3_LOG_STDERR | MQTT3_LOG_DLT; ... #endif

注释解释了原因：服务模式下使用 stdout/stderr 是被禁止的，因为“第一个连接的客户端会莫名其妙地收到日志信息”——这是 Windows 服务控制管理器的重定向行为导致的典型陷阱。非 Windows 平台的默认值则是stderr | dlt并配合 syslog facilityLOG_DAEMON。

判断“是否以服务方式运行”依据的全局句柄service_handle，其赋值与整个服务生命周期管理在 src/service.c 中实现：service_main()（约 81 行）负责注册服务控制处理器并从<服务名>_DIR环境变量拼出配置路径后调用main()；service_install()、service_uninstall()分别处理mosquitto.exe install/uninstall。也就是说，broker 以服务模式启动时走的是这条独立入口，service_handle非空正是 src/conf.c 中默认日志值切换的判断条件。

log_dest 的完整取值

各日志目标的位标志定义在 src/mosquitto_broker_internal.h 第 50～61 行，log_dest采用按位或组合，可以配置多行同时生效：

标志	值	含义
`MQTT3_LOG_NONE`	0x00	不输出日志
`MQTT3_LOG_SYSLOG`	0x01	写入 syslog
`MQTT3_LOG_FILE`	0x02	写入文件（需带文件名）
`MQTT3_LOG_STDOUT`	0x04	标准输出
`MQTT3_LOG_STDERR`	0x08	标准错误
`MQTT3_LOG_TOPIC`	0x10	发布到`log`前缀的 MQTT topic
`MQTT3_LOG_DLT`	0x20	Windows 调试监听器
`MQTT3_LOG_ANDROID`	0x40	Android logcat（仅`ANDROID`编译时）
`MQTT3_LOG_ALL`	0xFF	全部

配置解析逻辑位于 src/conf.c 约 1817～1868 行：log_dest逐行解析，支持none、syslog、stdout、stderr、topic、dlt、android、file <路径>（file 只允许出现一次，重复或缺少文件名会报Error: Duplicate "log_dest file" value./Error: Empty "log_dest file" value in configuration.）。

官方配置与手册中的说明

仓库自带的示例配置 mosquitto.conf（504～533 行）对log_dest的注释与这一行为一致：

#log_dest stderr # ... 多行 log_dest 可同时使用，例如 # "log_dest file /var/log/mosquitto.log". # 当作为 Windows 服务运行时，stdout/stderr 不可用， # 会默认为 "log_dest none"，如需日志须显式配置。 # 如希望完全禁用日志，使用 "log_dest none"。

man/mosquitto.conf.5.xml 中log_dest条目（约 605～643 行）同样写明：作为 Windows 服务运行时默认为log_dest none，neither stdout nor stderr logging is available（stdout 与 stderr 日志均不可用）。阅读发布说明时可以将这一条修复直接对照到上述源码与手册描述——三者构成完整闭环。

Client library：Python on_log() 回调参数修复

发布说明的第二项核心修复是：Pythonon_log()回调被调用时传入了错误的参数（缺陷 #1036818）。当时 Python 模块是随源码构建的绑定，broker/客户端内部触发日志时会以错误的实参组合调用用户回调，导致回调内参数错位甚至异常。

当前仓库中该回调的 C 侧契约仍然清晰可查。回调函数指针声明在 lib/mosquitto_internal.h（约 400 行）：

void (*on_log)(struct mosquitto *, void *userdata, int level, const char *str);

实际触发点位于 lib/logging_mosq.c 第 41～54 行：日志函数在格式化完成后，仅当mosq->on_log非空时，以(mosq, mosq->userdata, (int)priority, s)四参形式回调，参数顺序为——客户端实例、用户数据、日志级别（priority）、格式化后的日志字符串。注册接口mosquitto_log_callback_set()定义于 lib/callbacks.c（约 131 行），公共头文件中的签名与文档注释见 include/mosquitto/libmosquitto_callbacks.h（约 420～434 行）。C++ 封装 lib/cpp/mosquittopp.cpp 则通过静态包装函数on_log_wrapper()把四参 C 回调收窄为on_log(int level, const char *str)虚函数（约 127～131、275 行）。

1.0.1 修复的正是 Python 绑定层调用该回调时实参与上述签名不符的问题；理解当前 C 侧签名即可判断任何语言绑定中on_log回调的正确参数形态。

Clients：按编译选项裁剪 TLS 帮助输出

发布说明中 Clients 条目为：当编译时不支持 TLS/TLS-PSK 时，客户端不再显示 TLS/TLS-PSK 相关的 usage 帮助。这属于体验性修复——例如以WITH_TLS=no构建后运行mosquitto_pub --help，此前会列出--cafile、--psk等无效选项，误导使用者。该修复的验证方式很直接：在无 TLS 构建的客户端上运行mosquitto_pub -h，输出中不再包含 TLS 选项段落；反之，默认构建（当前 CMake 构建默认开启 TLS）则会完整列出。

Build scripts：CMake 构建链修复

1.0 版本新增 TLS 与 TLS-PSK 后，CMake 构建暴露出三处问题，1.0.1 全部修复：

TLS-PSK 支持：CMake 文件未正确传递 PSK 相关编译开关，导致声称支持 PSK 的构建实际不可用。仓库中的 cmake/ 目录保留了依赖发现脚本（如 cmake/FindCUnit.cmake、cmake/Findargon2.cmake），顶层 CMakeLists.txt 负责WITH_TLS、WITH_TLS_PSK等选项的组装——1.0.1 修补的即这类开关传递链；
man 页安装：CMake 安装的 man 页目标不正确，修复后make install可正常安装 man/ 下的mosquitto.8、mosquitto.conf.5、mosquitto_pub.1等手册页（构建清单见 man/CMakeLists.txt）；
SYSCONFDIR：在 *nix 上安装到/usr前缀时SYSCONFDIR取值错误（缺陷 #1036908），会导致 mosquitto.conf 被安装到非预期路径。该问题影响的是“配置文件默认放置位置”，与 mosquitto.conf 示例文件在源码树的定位不同——示例文件仅供复制，真正的安装路径由 CMake 的SYSCONFDIR决定。

除 CMake 外，项目同时维护 Makefile 构建体系（顶层 Makefile 与 config.mk），发布说明将其归入 “build script fixes” 的范畴。

Documentation：文档修复清单

1.0.1 的文档修复包括四类，均可在仓库中对照：

mqtt/MQTT 大小写统一：man/ 目录下各手册页（如 man/mqtt.7.xml）中协议名称的大小写已规范化；
更新 compiling.txt：编译说明文档的刷新，当前仓库中对应的可读内容为 README-compiling.md（1.0 时代为 compiling.txt，后随文档迁移演化为现文件）；
修正 mosquitto.py 回调文档（缺陷 #1036607）：与上文on_log参数修复同属 Python 模块文档质量问题；
杂项拼写与清理（缺陷 #1037088）：修正多处笔误并删除过期脚本。

验证与延伸阅读

结合当前仓库验证该版本相关行为，推荐路径：

核对版本记录：在 ChangeLog.txt 中定位1.0.1 - 20120815与1.0 - 20120814两个段落，确认修复范围仅为 bugfix、无新增功能；
核对日志默认值逻辑：阅读 src/conf.c（277～296 行）中service_handle分支与 src/service.c 中service_main()的服务启动流程，确认 Windows 服务默认log_dest none的实现依据；
核对配置写法：参考 mosquitto.conf（504～533 行）中log_dest的注释与 man/mosquitto.conf.5.xml 的条目说明，掌握多目标日志的合法组合；
核对日志回调契约：以 lib/logging_mosq.c 的回调触发点和 include/mosquitto/libmosquitto_callbacks.h 中的mosquitto_log_callback_set()声明作为on_log参数的权威参考。