Ubuntu 22.04 安装 ZeroMQ 4.3.5 指南

Ubuntu 22.04 安装 ZeroMQ(libzmq)完整指南:apt 安装 4.3.4 与源码编译安装最新稳定版 4.3.5 两条路线、CURVE/libsodium 安全构建变体、ipc/tcp 本地连通实测、升级降级与卸载清理,全部命令逐条实测(2026-10-20)。

ZeroMQZeroMQ2026/10/20

Ubuntu 22.04 安装 ZeroMQ 4.3.5 指南

目标:在 Ubuntu 22.04 服务器上从零完成 ZeroMQ(libzmq)的安装与验证,覆盖「apt 在线仓库安装 4.3.4」与「源码编译安装最新稳定版 4.3.5」两种方案、CURVE 安全构建变体、ipc/tcp 本地连通实测、升级降级与卸载清理。本文全部命令与输出均在 Ubuntu 22.04.5 LTS (x86_64) 环境逐条实测通过,实测日期 2026-10-20。

一、环境信息

  • 操作系统:Ubuntu 22.04.5 LTS(jammy),x86_64(cat /etc/os-release 实测:PRETTY_NAME="Ubuntu 22.04.5 LTS"、VERSION_CODENAME=jammy;uname -m 实测:x86_64)
  • 编译工具链:gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0、GNU Make 4.3
  • 目标组件:ZeroMQ 核心库 libzmq
    • Ubuntu 22.04 官方仓库版本:libzmq 4.3.4(libzmq5 4.3.4-2,apt-cache policy 实查 Candidate: 4.3.4-2)
    • 官方最新稳定版:libzmq 4.3.5(2023-10-09 发布,GitHub Releases Atom 源实查,查询日期 2026-10-20)
  • 官方仓库:https://github.com/zeromq/libzmq
  • 安装方式:方案 A 为 apt 在线仓库安装;方案 B 为官方源码包编译安装(另附 CURVE 安全构建变体)
  • 默认安装路径:apt 方案装至 /usr(动态库在 /lib/x86_64-linux-gnu/);源码方案装至 /usr/local(动态库在 /usr/local/lib/,头文件在 /usr/local/include/)

二、前置条件

安装前需要确认系统基础条件,逐项执行验证:

  1. 具备 root 或 sudo 权限(本文以 root 演示;普通用户在命令前加 sudo)。
  2. 能访问 Ubuntu 软件源(内网环境请先配置内部镜像源)。
  3. 方案 B 需要能访问 GitHub 下载源码包(约 2.5 MB;受限网络见「九、常见问题」Q1 的代理方案)。
sudo apt-get update

实测回显(输出节选,实测末尾):

Get:18 http://archive.ubuntu.com/ubuntu jammy-backports/universe amd64 Packages [35.6 kB]
Fetched 49.0 MB in 6s (7817 kB/s)
Reading package lists...

三、版本选型说明

ZeroMQ 是一个 C/C++ 消息库,Ubuntu 22.04 官方仓库中的包名为 libzmq5(运行库)、libzmq3-dev(开发头文件与 pkg-config 描述)。两种安装路线的版本与适用性对比如下:

方案版本包/产物是否需联网编译适用场景
A:apt 在线仓库4.3.4(仓库版本)libzmq5 / libzmq3-dev否(纯下载安装)快速上手、通用开发、随系统升级维护
B:源码编译4.3.5(最新稳定版)/usr/local 下的 libzmq.so 等是需要最新版修复/新选项、需要自定义构建(如 --with-libsodium)

关键差异与如何选型:apt 方案胜在「一条命令、系统托管、升级省心」,但版本停在 4.3.4;源码方案能拿到 4.3.5 并自由定制构建选项(例如启用 libsodium 支持 CURVE),代价是要自己负责后续升级。两方案的动态库 soname 相同(libzmq.so.5),不产生冲突,先装 apt 版再编译 4.3.5 会自然「升级」到新库(见 5.6 节实测)。

四、方案 A:apt 在线仓库安装(libzmq 4.3.4)

4.1 方案说明

Ubuntu 22.04 官方仓库(main/universe)直接提供 libzmq 运行库与开发包,一条命令即可装齐,并由 APT 负责后续升级与卸载。适合绝大多数开发与生产场景,唯一遗憾是版本为 4.3.4 而非最新的 4.3.5。

4.2 安装步骤

安装运行库、开发包与 Python 绑定(Python 绑定用于后续验证与开发,可选):

apt-get install -y libzmq5 libzmq3-dev python3-zmq pkg-config

实测回显(输出节选,实测末尾):

Setting up libnorm-dev:amd64 (1.5.9+dfsg-2) ...
Setting up libkrb5-dev:amd64 (1.19.2-2ubuntu0.10) ...
Setting up python3-zmq (22.3.0-1build1) ...
Setting up pkg-config (0.29.2-1ubuntu3) ...
Setting up libzmq3-dev:amd64 (4.3.4-2) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

💡 说明:libzmq3-dev 会连带安装 libsodium-dev、libnorm-dev、libkrb5-dev 等依赖——libzmq 把 libsodium(加密)、NORM(可靠组播)、GSSAPI(Kerberos 认证)作为可选能力编译进了发行版构建。

4.3 安装验证

逐项确认安装结果。先看包清单:

dpkg -l | grep -E 'zmq|libnorm|libsodium'

实测回显:

ii  libnorm-dev:amd64           1.5.9+dfsg-2                            amd64        NACK-Oriented Reliable Multicast (NORM) library (development files)
ii  libnorm1:amd64              1.5.9+dfsg-2                            amd64        NACK-Oriented Reliable Multicast (NORM) library
ii  libsodium-dev:amd64         1.0.18-1ubuntu0.22.04.1                 amd64        Network communication, cryptography and signaturing library - headers
ii  libsodium23:amd64           1.0.18-1ubuntu0.22.04.1                 amd64        Network communication, cryptography and signaturing library
ii  libzmq3-dev:amd64           4.3.4-2                                 amd64        lightweight messaging kernel (development files)
ii  libzmq5:amd64               4.3.4-2                                 amd64        lightweight messaging kernel (shared library)
ii  python3-zmq                 22.3.0-1build1                          amd64        Python3 bindings for 0MQ library

再验证开发元数据与动态库缓存:

pkg-config --modversion libzmq
ldconfig -p | grep libzmq

实测回显:

4.3.4
        libzmq.so.5 (libc6,x86-64) => /lib/x86_64-linux-gnu/libzmq.so.5
        libzmq.so (libc6,x86-64) => /lib/x86_64-linux-gnu/libzmq.so

最后用 Python 绑定打印运行时实际加载的库版本(这是最接近「应用程序视角」的验证):

python3 -c "import zmq; print(zmq.zmq_version()); print(zmq.pyzmq_version())"

实测回显:

4.3.4
22.3.0

zmq.zmq_version() 返回的是 C 库 libzmq 的版本(4.3.4),zmq.pyzmq_version() 返回 Python 绑定自身的版本(22.3.0)——两个版本号独立演进,属正常现象。

五、方案 B:源码编译安装 libzmq 4.3.5

5.1 方案说明

从官方 GitHub Releases 下载 4.3.5 源码包,走 autotools 流程(configure → make → make install)编译安装到 /usr/local。本方案同样覆盖 CMake 构建路径的等价性说明。为演示「升级生效」,本节先在装有 apt 版 4.3.4 的机器上进行(与多数读者现状一致),编译完成后运行时版本将从 4.3.4 升到 4.3.5。

5.2 安装编译依赖

apt-get install -y build-essential wget pkg-config python3-zmq

实测回显(输出节选,实测末尾):

0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

确认工具链版本:

gcc --version | head -1
make --version | head -1

实测回显:

gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0
GNU Make 4.3

安装后的基线运行时版本(当前仍是 apt 的 4.3.4):

python3 -c "import zmq; print(zmq.zmq_version())"

实测回显:

4.3.4

5.3 下载源码包并校验

官方 4.3.5 源码包约 2.5 MB,从 GitHub Releases 下载:

cd /usr/local/src
wget https://github.com/zeromq/libzmq/releases/download/v4.3.5/zeromq-4.3.5.tar.gz

校验文件与 SHA-256(实测值,可用于内部校验基线):

ls -lh zeromq-4.3.5.tar.gz
sha256sum zeromq-4.3.5.tar.gz

实测回显:

-rw-r--r-- 1 root root 2.5M Oct 20 01:59 zeromq-4.3.5.tar.gz
6653ef5910f17954861fe72332e68b03ca6e4d9c7160eb3a8de5a5a913bfab43  zeromq-4.3.5.tar.gz

⚠️ 注意:GitHub 在部分网络环境直连失败(实测曾出现 Connection refused)。若下载失败,为 wget 所在会话导出可达的 HTTP 代理环境变量(http_proxy/https_proxy,值形如 http://<代理主机>:<代理端口>,取你网络内实际可用的代理)后重试同一 wget 命令;完全断网的服务器可离线下载后传至服务器再校验 sha256。

5.4 配置与编译

解压并进入源码目录,执行 configure:

tar xf zeromq-4.3.5.tar.gz
cd zeromq-4.3.5
./configure --prefix=/usr/local

实测回显(configure 关键行节选):

configure: Using 'epoll' I/O thread polling system with CLOEXEC
configure: Using 'poll' zmq_poll(er)_* API polling system
configure: Using "64" bytes alignment for lock-free data structures
configure: Using "auto" condition variable implementation.
configure: Using built-in SHA1
configure: Using mtree implementation to manage subscriptions
configure: Building stable and legacy API (no draft API)
config.status: creating src/platform.hpp
config.status: creating src/libzmq.pc

💡 说明:默认 configure 使用 Linux 的 epoll I/O 多路复用;Using built-in SHA1 与未出现 libsodium 检查,表示 CURVE 加密采用内置 tweetnacl 实现(--with-libsodium 默认关闭,启用方法见 5.7 节);no draft API 表示仅编译稳定 API,RADIO/DISH 等 DRAFT 套接字不可用。

编译(-j$(nproc) 按核数并行,4 核虚机约 1~2 分钟):

make -j$(nproc)

实测回显(输出节选,实测末尾):

  CXXLD    perf/local_thr
  CXXLD    perf/proxy_thr
  CXXLD    perf/benchmark_radix_tree
make[1]: Leaving directory '/usr/local/src/zeromq-4.3.5'

编译产物中包含 8 个性能/基准工具(位于 perf/ 目录,make install 不会安装它们,用法见后文与《ZeroMQ 4.3.5 常用 CLI 命令与工具详解》):

ls -1 perf/ | grep -v -E '\.(o|cpp|d)$'

实测回显:

benchmark_radix_tree
inproc_lat
inproc_thr
local_lat
local_thr
proxy_thr
remote_lat
remote_thr

5.5 安装与动态库刷新

make install
ldconfig

实测回显(输出节选,实测末尾):

 /usr/bin/install -c -m 644 src/libzmq.pc '/usr/local/lib/pkgconfig'
make[2]: Leaving directory '/usr/local/src/zeromq-4.3.5'
make[1]: Leaving directory '/usr/local/src/zeromq-4.3.5'

安装内容:库文件至 /usr/local/lib/(含 libzmq.so.5.2.5、软链 libzmq.so.5、libzmq.so 与静态库 libzmq.a)、头文件至 /usr/local/include/(zmq.h、zmq_utils.h)、pkg-config 描述至 /usr/local/lib/pkgconfig/libzmq.pc。ldconfig 刷新动态库缓存后,/usr/local/lib 排在系统目录之前(Ubuntu 的 /etc/ld.so.conf.d/libc.conf 默认包含 /usr/local/lib,且排序先于 /lib/x86_64-linux-gnu),运行时将优先加载 4.3.5。

5.6 安装验证(4.3.4 → 4.3.5 升级生效)

pkg-config --modversion libzmq
ldconfig -p | grep libzmq
python3 -c "import zmq; print(zmq.zmq_version())"

实测回显:

4.3.5
        libzmq.so.5 (libc6,x86-64) => /usr/local/lib/libzmq.so.5
        libzmq.so.5 (libc6,x86-64) => /lib/x86_64-linux-gnu/libzmq.so.5
        libzmq.so (libc6,x86-64) => /usr/local/lib/libzmq.so
4.3.5

三项验证全部为 4.3.5:pkg-config 取到新库的元数据,动态库缓存 /usr/local/lib 优先,Python 运行时实际加载的 libzmq 从 4.3.4 变为 4.3.5——源码安装天然完成对 apt 版的升级覆盖,无需卸载旧包。

5.7 CURVE 安全构建变体(--with-libsodium)

libzmq 的 CURVE 加密默认用内置 tweetnacl 实现,此时源码树自带的密钥生成工具 curve_keygen 会拒绝工作(见「九、常见问题」Q2)。生产环境启用 CURVE 时,推荐用 libsodium 重建:

apt-get install -y libsodium-dev

实测回显(输出节选):

Setting up libsodium-dev:amd64 (1.0.18-1ubuntu0.22.04.1) ...

在全新解压的源码目录中带 --with-libsodium 重新配置、编译、安装(为什么必须全新目录见 Q3):

cd /usr/local/src
rm -rf zmq-libsodium && mkdir zmq-libsodium && cd zmq-libsodium
tar xf ../zeromq-4.3.5.tar.gz && cd zeromq-4.3.5
./configure --prefix=/usr/local --with-libsodium
make -j$(nproc)
make install
ldconfig

实测回显(configure 关键行):

checking for libsodium... yes
configure: Using libsodium for CURVE security

此时源码树 tools/curve_keygen 已被编译产出,可直接生成 CURVE 密钥对(Z85 编码):

./tools/curve_keygen

实测回显:

This tool generates a CurveZMQ keypair, as two printable strings you can
use in configuration files or source code. The encoding uses Z85, which
is a base-85 format that is described in 0MQ RFC 32, and which has an
implementation in the z85_codec.h source used by this tool. The keypair
always works with the secret key held by one party and the public key
distributed (securely!) to peers wishing to connect to it.

== CURVE PUBLIC KEY ==
mQdmh1=JuKj]rb$@:jrs:Efo:L$H3g+-FE{M$n#1

== CURVE SECRET KEY ==
[>}]%6&a(#Wmh9&wEHG*(Chd[m&Ra(=]EL-m/k*D

⚠️ 注意:以上密钥对仅为文档演示样本,请勿用于任何真实环境;生产密钥务必在目标服务器上现场生成并妥善保管私钥。

启用 libsodium 后,用 Python 绑定实测 CURVE 加密通联(REQ/REP 全程密文握手):

# curve_test.py —— CURVE 加密 REQ/REP 自测
import time
import zmq

ctx = zmq.Context()
server_pub, server_sec = zmq.curve_keypair()
client_pub, client_sec = zmq.curve_keypair()

rep = ctx.socket(zmq.REP)
rep.setsockopt(zmq.CURVE_SECRETKEY, server_sec)
rep.setsockopt(zmq.CURVE_SERVER, 1)
rep.bind("tcp://127.0.0.1:5570")

req = ctx.socket(zmq.REQ)
req.setsockopt(zmq.CURVE_PUBLICKEY, client_pub)
req.setsockopt(zmq.CURVE_SECRETKEY, client_sec)
req.setsockopt(zmq.CURVE_SERVERKEY, server_pub)
req.connect("tcp://127.0.0.1:5570")

time.sleep(0.5)
req.send_string("hello-curve")
print("REQ <- REP :", rep.recv_string())
rep.send_string("ok-curve")
print("REQ <- ACK :", req.recv_string())

实测回显:

REQ <- REP : hello-curve
REQ <- ACK : ok-curve

六、方案对比与选择建议

维度方案 A:apt 仓库方案 B:源码编译(默认)方案 B 变体:--with-libsodium
版本4.3.44.3.54.3.5
是否需联网是(软件源)是(GitHub + 软件源)是
安装方式apt 一条命令configure/make/make install同左,加 libsodium
systemd 服务无(库,无守护进程)无无
监听端口无无无
优点省心、随系统升级版本最新、构建可定制CURVE 用标准 libsodium,curve_keygen 可用
缺点版本滞后升级靠自己多一步重建

选择建议:内网快速落地、无 CURVE 定制需求 → 方案 A;需要 4.3.5 的新选项/修复或生产启用 CURVE → 方案 B(按需带 --with-libsodium)。两者可共存,源码版总是覆盖 apt 版的运行时加载(soname 相同、路径优先级更高)。

七、ipc/tcp 本地连通实测

libzmq 装好后无需任何服务启动动作,写一个最小收发程序即可验证「库可用、tcp/ipc 两传输皆通」。以下脚本同时覆盖三种链路:tcp REQ/REP 问答、tcp PUSH/PULL 队列、ipc PUSH/PULL 本机进程间队列。

cat > /root/zmq_local_test.py <<'EOF'
import time
import zmq

def push_pull(endpoint):
    ctx = zmq.Context()
    sender = ctx.socket(zmq.PUSH)
    sender.bind(endpoint)
    receiver = ctx.socket(zmq.PULL)
    receiver.connect(endpoint)
    time.sleep(0.2)  # 等待连接建立(慢加入者)
    for i in range(3):
        sender.send_string("msg-%d" % i)
    for i in range(3):
        print(receiver.recv_string())
    sender.close()
    receiver.close()
    ctx.term()

def req_rep(endpoint):
    ctx = zmq.Context()
    rep = ctx.socket(zmq.REP)
    rep.bind(endpoint)
    req = ctx.socket(zmq.REQ)
    req.connect(endpoint)
    time.sleep(0.2)
    req.send_string("ping")
    print("REP <-", rep.recv_string())
    rep.send_string("pong")
    print("REQ <-", req.recv_string())
    rep.close()
    req.close()
    ctx.term()

req_rep("tcp://127.0.0.1:5557")
push_pull("tcp://127.0.0.1:5556")
push_pull("ipc:///tmp/zmq-demo.ipc")
print("ALL OK")
EOF
python3 /root/zmq_local_test.py

实测回显:

REP <- ping
REQ <- pong
msg-0
msg-1
msg-2
msg-0
msg-1
msg-2
ALL OK

三段输出依次对应:tcp 上 REQ 发送 ping、REP 收到并回 pong;tcp 上 PUSH 推 3 条消息、PULL 依序收齐;ipc 端点 ipc:///tmp/zmq-demo.ipc 同样收发成功。最后一行 ALL OK 表示全部链路通过。

再用源码树自带的官方基准工具做一次 tcp 往返时延实测(两个终端分别执行,或在同一 shell 后台跑一端;工具的完整用法见《ZeroMQ 4.3.5 常用 CLI 命令与工具详解》):

# 终端 1:local_lat 作为反射端(绑定 tcp://127.0.0.1:5555)
cd /usr/local/src/zeromq-4.3.5/perf
./local_lat tcp://127.0.0.1:5555 1 10000
# 终端 2:remote_lat 打 1 万次往返并统计时延
./remote_lat tcp://127.0.0.1:5555 1 10000

remote_lat 侧实测回显:

message size: 1 [B]
roundtrip count: 10000
average latency: 53.402 [us]

验证通过:库正确安装、tcp/ipc 传输可用、性能工具能出数。

八、升级、降级与多版本管理

  • apt 版升级:Ubuntu 官方仓库的 libzmq 4.3.4 随系统安全更新走,apt-get update && apt-get upgrade 即可;apt-cache policy libzmq5 可查当前源内可用版本。
  • 升到最新稳定版:按第五节流程重编译安装新版本(如未来发布 4.3.6,将下载 URL 与目录名中的版本号替换为实际最新版,以 Releases 页实查为准),make install && ldconfig 后运行时即切到新库——第五节已实测 4.3.4 → 4.3.5 的覆盖升级。
  • 回退到 apt 版:删除 /usr/local 下的 libzmq 产物并刷新缓存(即「十、卸载与清理」中源码卸载步骤),运行时自动回落到 /lib/x86_64-linux-gnu/libzmq.so.5(4.3.4)。
  • 多版本共存:同一 soname(libzmq.so.5)在同一动态库搜索路径中只能有一个生效。需要并行使用多个版本时,把不同版本编译安装到不同前缀(如 ./configure --prefix=/opt/zmq-4.3.5、--prefix=/opt/zmq-4.3.6),编译应用时用 PKG_CONFIG_PATH=/opt/zmq-<版本>/lib/pkgconfig pkg-config --cflags --libs libzmq 指定链接目标,运行时用 LD_LIBRARY_PATH=/opt/zmq-<版本>/lib 指定加载目标。

九、常见问题(FAQ)

Q1:GitHub 下载源码包失败(Connection refused / 超时)怎么办? 实测环境中直连 GitHub 报 Connection refused,走 HTTP 代理后成功。解决方式见 5.3 节注意事项:给 wget/curl 配置 http_proxy/https_proxy 环境变量后重试;完全断网的服务器可离线下载后 scp 到服务器再校验 sha256。

Q2:运行 curve_keygen 提示「To use curve_keygen, please install libsodium and then rebuild libzmq」? 这是默认构建(tweetnacl)的预期行为——tools/curve_keygen 依赖 libsodium 构建的库。按 5.7 节安装 libsodium-dev 后在全新目录以 --with-libsodium 重建即可;重建后 curve_keygen 输出 Z85 密钥对(见 5.7 节实测回显)。

Q3:装了 libsodium 后在原目录重新 ./configure,CURVE 仍走 tweetnacl? 实测踩坑:第二次 configure 输出 config.status: src/platform.hpp is unchanged,构建系统复用了首次 configure 的 src/platform.hpp(tweetnacl 决定就固化在里面)。解决:先 make distclean,或在全新解压目录重新 configure(本文采用后者,实测生效)。

Q4:Python 报 AttributeError: Socket has no such option: SET_CURVE_SECRETKEY? 旧版 pyzmq(如 Ubuntu 22.04 仓库的 22.3.0)没有 set_curve_secretkey() 等便捷方法。改用底层 setsockopt(zmq.CURVE_SECRETKEY, <bytes>) 写法即可(见 5.7 节实测脚本);新版 pyzmq(≥25)才有便捷方法。

Q5:明明装了新版,程序运行时仍加载旧版 libzmq? 用 ldd /path/to/程序 | grep zmq 看实际链接路径。若指向 /lib/x86_64-linux-gnu/libzmq.so.5,先确认 /usr/local/lib/libzmq.so.5 存在、执行过 ldconfig,再用 ldconfig -p | grep libzmq 确认 /usr/local/lib 条目在前;临时切换可用 LD_LIBRARY_PATH=/usr/local/lib 强制指定。

十、卸载与清理

卸载 apt 版(实测):

apt-get remove --purge -y libzmq5 libzmq3-dev python3-zmq

实测回显(输出节选):

Removing libzmq3-dev:amd64 (4.3.4-2) ...
Removing python3-zmq (22.3.0-1build1) ...
Removing libzmq5:amd64 (4.3.4-2) ...
Processing triggers for libc-bin (2.35-0ubuntu3.15) ...

验证卸载干净:

pkg-config --modversion libzmq
ldconfig -p | grep libzmq

实测回显:

Package libzmq was not found in the pkg-config search path.
Perhaps you should add the directory containing `libzmq.pc'
to the PKG_CONFIG_PATH environment variable
No package 'libzmq' found

其中 ldconfig -p | grep libzmq 已无任何输出(动态库缓存中不再有 libzmq 条目),卸载干净。

卸载源码版(实测): 在保留的源码目录执行 make uninstall:

cd /usr/local/src/zeromq-4.3.5
make uninstall
ldconfig

实测回显(输出节选,实测末尾):

libtool: uninstall: rm -f /usr/local/lib/libzmq.la /usr/local/lib/libzmq.so.5.2.5 /usr/local/lib/libzmq.so.5 /usr/local/lib/libzmq.so /usr/local/lib/libzmq.a
 ( cd '/usr/local/lib/pkgconfig' && rm -f libzmq.pc )
make[1]: Leaving directory '/usr/local/src/zeromq-4.3.5'

随后确认头文件与库已移除(实测 ls /usr/local/include/zmq.h 返回 No such file or directory,ldconfig -p 中不再有 /usr/local/lib/libzmq.so.5 条目)。若源码目录已丢失,按下列清单手工清理:

rm -f /usr/local/lib/libzmq.so*
rm -f /usr/local/lib/libzmq.a
rm -f /usr/local/lib/libzmq.la
rm -f /usr/local/lib/pkgconfig/libzmq.pc
rm -f /usr/local/include/zmq.h /usr/local/include/zmq_utils.h
ldconfig

十一、参考链接