企业官网建设流程全解析

• 后端
• 消息队列
• 消息路由

本文是一份面向 Debian/Ubuntu 用户的 Mosquitto 自打包实战指南，源自 making-mosquitto-packages-for-debian-yourself.md。当发行版官方源中的 Mosquitto 版本落后、或你需要按自己的编译选项定制 broker 时，可以遵循"下载源码 → 套用官方打包元数据 → debuild → dpkg -i"这条命令行路线，在十几分钟内得到可直接安装的 .deb 包。读完本文，你将掌握 Debian 包命名规范、构建依赖清单、debuild 完整流程，以及 Mosquitto 仓库中与打包相关的编译开关与构建体系。

为什么需要自己动手打包 Debian 包

这篇发布于 2012-11-27 的博文解释了问题的起因：Debian 在 Mosquitto 1.0 发布之前就已进入 feature freeze（特性冻结），这意味着官方源中的 Mosquitto 版本会在很长时间内停留在旧版本，等不到上游的新功能与修复。与其干等，不如把打包工作自己做——而且这个流程"fairly straightforward"（相当直接），全程只需命令行操作。

需要说明的是，这条自打包路线是当时（1.1.2 时代）的解决方案，但从源码自行构建 .deb 的通用方法论至今依然成立，且与当前仓库的 Makefile/CMake 构建体系完全兼容。当前仓库的版本号为 2.1.2（见 config.mk 中的VERSION=2.1.2），操作步骤中的版本号替换为实际版本即可。

准备工作：下载源码并整理打包元数据

1. 下载并解压 Mosquitto 源码包

从官方下载页获取对应版本的源码 tarball（各版本源码包地址见 www/pages/download.md），然后解压：

# 从官方下载页获取 mosquitto-1.1.2.tar.gz（将版本号替换为你需要的版本） wget <官方下载页中 mosquitto-1.1.2.tar.gz 的地址> tar -zxf mosquitto-1.1.2.tar.gz

解压后会得到一个包含完整源码的mosquitto-1.1.2/目录。这个 tarball 也可以通过仓库自身的make dist目标生成：仓库根 Makefile 中定义了dist : reallyclean规则，它会将DISTFILES列出的全部目录与文件（libcommon、lib、apps、client、plugins、src、man、test 等）汇总并打包成dist/mosquitto-${VERSION}.tar.gz。

2. 重命名 tarball 以符合 Debian 命名规范

Debian 对上游源码包有严格的命名约定，必须命名为<源码包名>_<版本号>.orig.tar.gz（下划线分隔、带.orig标记），这样dpkg-buildpackage才能识别出"原始上游源码"与"Debian 打包补丁"的边界：

mv mosquitto-1.1.2.tar.gz mosquitto_1.1.2.orig.tar.gz

注意文件名中包名与版本号之间是下划线mosquitto_1.1.2.orig.tar.gz，这与常规源码包名中的连字符不同，拼写错误会导致后续构建步骤无法识别源码。

3. 获取 Debian 官方的打包文件（.debian.tar.xz）

打包所需的 Debian 元数据（debian/目录）无需自己从零编写。当时可以从 Debian 软件包站点的 mosquitto 源码包页面下载.debian.tar.xz，其中包含：

• debian/control：包描述、依赖关系、维护者信息；
• debian/rules：debuild实际执行的构建规则脚本；
• debian/changelog：打包版本历史；
• debian/patches/：由 quilt 管理的对上游源码的补丁序列；
• 各种 init 脚本、systemd 单元、配置文件等。

把这个.debian.tar.xz解包到源码目录内，即可得到完整的debian/目录结构。qult 补丁机制由下面要安装的quilt工具驱动，Debian 的构建流程会自动将其应用到上游源码上。

安装构建依赖

正式构建前，需要安装一套完整的编译与打包工具链。原文档给出的命令如下：

sudo apt-get install build-essential python quilt libwrap0-dev libssl-dev devscripts python-setuptools

各软件包的用途：

这些依赖与 README-compiling.md 中列出的平台依赖清单相互印证：在 Debian 系系统上，OpenSSL 对应libssl-dev，而测试还需要 cunit、googletest/gmock、python 等。若你的打包目标是裁剪某些特性，可以结合 config.mk 中的WITH_*开关（如WITH_TLS=no、WITH_WEBSOCKETS=no）调整依赖，但一般建议保持官方 Debian 包的默认配置。

使用 debuild 构建软件包

依赖就绪后，进入源码目录执行debuild：

cd mosquitto-1.1.2/ debuild

debuild是devscripts包提供的封装工具，它按顺序完成以下工作：

1. 以fakeroot权限调用dpkg-buildpackage；
2. 自动应用debian/patches/中的 quilt 补丁；
3. 按debian/rules执行构建（对应仓库中各子目录的 Makefile）；
4. 运行lintian对生成的包做静态检查；
5. 输出.deb、.dsc、.changes、.buildinfo等产物。

构建完成后，父目录中会出现一组 .deb 文件，例如：

• mosquitto_1.1.2-1_amd64.deb：broker 主程序；
• libmosquitto1_1.1.2-1_amd64.deb：客户端 C 库；
• mosquitto-clients_1.1.2-1_amd64.deb：mosquitto_pub/mosquitto_sub等命令行客户端；
• 以及libmosquitto-dev、mosquitto-doc等配套包。

这对应着仓库的模块化构建结构：根 Makefile 中的DIRS=libcommon lib apps client plugins src依次构建公共库、客户端库、命令行工具、插件与 broker 主体，最终由debian/rules把它们组织成多个独立的二进制包。

安装生成的 .deb 包

在父目录中找到需要的 .deb 文件，用dpkg -i逐个安装：

sudo dpkg -i <deb 文件>

例如：

sudo dpkg -i mosquitto_1.1.2-1_amd64.deb sudo dpkg -i mosquitto-clients_1.1.2-1_amd64.deb

如果dpkg提示缺少运行时依赖，可随后执行sudo apt-get -f install让 apt 自动补齐。安装后，broker 的可执行文件位于/usr/sbin/mosquitto（见 src/Makefile 中install目标对prefix/sbin的安装规则），默认配置示例为/etc/mosquitto/mosquitto.conf（仓库根目录的 mosquitto.conf 即其来源，安装时以.example后缀存放）。

仓库源码视角：打包背后发生了什么

编译开关与发行版策略

config.mk 是纯 Makefile 构建体系（Linux 上make编译）的用户配置中心，几乎所有特性都可以在打包时按需裁剪：

• WITH_TLS：broker 与客户端的 SSL/TLS 支持，对应依赖libssl-dev；
• WITH_WRAP：tcpd/libwrap 支持，对应依赖libwrap0-dev；
• WITH_BRIDGE：broker 的桥接（bridge）能力，用于连接其他 broker；
• WITH_PERSISTENCE：持久化数据库支持，将 retained 消息与持久订阅写入文件；
• WITH_SYSTEMD：systemd 集成，开启后需要libsystemd-dev；
• WITH_WEBSOCKETS：WebSocket 支持（yes/lws/no）；
• WITH_DOCS：man 手册构建，需要 xsltproc 与 docbook-xsl。

Debian 官方包通常会按发行版策略启用大部分特性，而自打包的最大价值正是在于可以自由开关这些选项，例如为嵌入式环境关闭WITH_BRIDGE、WITH_SYS_TREE以减小体积。

从make dist到.orig.tar.gz

仓库根 Makefile 的dist目标展示了上游发布 tarball 的生成方式：make reallyclean后把DISTFILES中列出的目录拷贝进dist/mosquitto-${VERSION}/再打包成mosquitto-${VERSION}.tar.gz。这就是自打包流程中mosquitto_1.1.2.orig.tar.gz的来源——你既可以从官方下载页获取，也可以自己执行make dist现场生成。

构建体系的演进

README-compiling.md 明确说明：到 2.1 版本为止，官方推荐在 Windows/Mac 上用 CMake、其他平台用纯 Makefile；而 2.1 之后官方推荐全面转向 CMake，纯 Makefile 将在 3.0 版本移除。因此如果你要打包的是 2.1.x 及更新版本，也可以基于CMakeLists.txt使用cmake+cpack或 debhelper 的 cmake 支持来构建；本文介绍的 debuild 流程（套用 Debian 官方元数据）对两种构建后端都适用，因为debian/rules本身可以调用任意构建工具。

后续演进：从自打包到官方仓库

自打包只是权宜之计，Mosquitto 的 Debian 分发此后经历了几个阶段，仓库中的历史博文记录了完整脉络：

1. 手工二进制包（2010-09）：作者最初手工编译发布 i386/amd64 的 Debian 包，见 debian-packages.md；
2. 进入 Debian/Ubuntu 官方源（2011-07）：mosquitto 0.10 被打包进 Debian testing 与 Ubuntu，见 debian-and-ubuntu-packaging.md；
3. 官方实验性 apt 仓库（2013-01）：自打包"turned out to be a bit problematic"（有些麻烦），作者随后搭建了官方实验性 Debian 仓库，提供 i386、amd64、armel 与树莓派 armhf 架构的包，用户只需导入签名密钥、添加 sources.list 条目后apt-get install mosquitto即可，完整步骤见 mosquitto-debian-repository.md；
4. 正式进入 Debian（当前）：如今 Mosquitto 已进入 Debian 官方源（见 www/pages/download.md），新版本发布后经正常 Debian 流程即可进入发行版。

即便如此，自打包仍有不可替代的场景：需要比发行版源更新的版本、需要定制编译选项、或在无网络/内网环境中离线部署。此时本文的 debuild 流程依然是最直接的手段。

常见问题与注意事项

• orig 包命名：务必使用下划线mosquitto_1.1.2.orig.tar.gz格式，否则dpkg-buildpackage无法识别上游源码，构建会报 "native package" 相关的错误。
• quilt 补丁未应用：如果构建日志中出现 patch 应用失败，通常是因为.debian.tar.xz版本与源码版本不匹配，应获取与目标源码版本对应的打包元数据。
• 缺少构建依赖：debuild早期失败多数源于依赖缺失，按报错补齐即可；若裁剪了WITH_*特性，对应的-dev包可以不装。
• 版本选择：原文档以 1.1.2 为例，当前仓库为 2.1.2；自打包时从官方下载页或make dist获取与你需要的功能版本一致的源码，打包元数据也应尽量匹配。
• 架构产物：生成的 .deb 文件名中的架构字段（如amd64）由构建机架构决定，跨架构部署需在对应架构的机器或 chroot/容器中构建。

• 后端
• 消息队列
• 消息路由