Ubuntu 22.04 安装 NSQ 1.3.0 指南

目标：在 Ubuntu 22.04 服务器上安装 NSQ 1.3.0（官方最新稳定版），提供「官方二进制在线安装 / 源码编译 / 离线包」三种方案，并用 systemd 托管 nsqd、nsqlookupd、nsqadmin 三个守护进程。以下所有命令与回显均在 Ubuntu 22.04 环境逐条实测。

一、环境信息

1.1 端口清单

💡 说明：NSQ 三个守护进程各自监听独立端口，安装后用 ss -ltn 应看到 4150/4151/4160/4161/4171 中的对应监听。若与其他服务冲突，全部端口都可用命令行参数改绑。

二、前置条件

安装基础工具（用于下载、校验与解压）：

apt-get update && apt-get install -y curl wget

实测回显（节选）：Reading package lists ... Building dependency tree ... 0 newly installed（本实验环境已预装 curl/wget，显示无需新装；全新机器会各下载安装一个包）。

确认系统架构，选择正确的发布包（NSQ 1.3.0 官方提供 amd64/arm64 等）：

uname -m
# x86_64

三、版本选型说明

• NSQ 遵循 主.次.修订 语义化版本。截至 2026-10-20，官方 GitHub Releases 的最新稳定版为 v1.3.0（2023-12-27 发布），此后无更新版本；本文即以 1.3.0 为准。
• 查询最新版本的官方途径（无需访问 api.github.com）：

curl -s https://github.com/nsqio/nsq/releases.atom | grep -oE '<title>[^<]+' | sed -n '2p' | cut -d'>' -f2
# 1.3.0

• v1.3.0 的 linux-amd64 发布包名为 nsq-1.3.0.linux-amd64.go1.21.5.tar.gz（尾缀是官方构建时用的 Go 工具链版本，与 NSQ 版本无关），sha256 为 eeeb62e003ca7c514b6cb6ef1bbe9d3754f14657ef276e3ebb54b5d57bd7988a（本文下载后 sha256sum 实测）。

⚠️ 提示：NSQ 未提供 Ubuntu 官方 apt 仓库与 snap 包，二进制 tarball 与源码编译是官方支持的两条安装路径。

四、方案 A：官方二进制在线安装（推荐）

4.1 方案说明

从 GitHub Releases 直接下载官方编译好的静态二进制，解压即用，零运行时依赖（官方 README 口径「compiled binaries have no runtime dependencies」），是最快、最可控的方式。

4.2 下载与校验

cd /tmp
wget https://github.com/nsqio/nsq/releases/download/v1.3.0/nsq-1.3.0.linux-amd64.go1.21.5.tar.gz

实测回显（节选）：

--2026-10-19 17:16:14--  https://github.com/nsqio/nsq/releases/download/v1.3.0/nsq-1.3.0.linux-amd64.go1.21.5.tar.gz
HTTP request sent, awaiting response... 200 OK
Length: 23042962 (22M)
Saving to: 'nsq-1.3.0.linux-amd64.go1.21.5.tar.gz'
nsq-1.3.0.linux-amd64.go1.21.5.tar.gz     100%[=====================>]  21.97M  --.-KB/s    in 2.0s

校验哈希并确认文件属性：

sha256sum nsq-1.3.0.linux-amd64.go1.21.5.tar.gz
# eeeb62e003ca7c514b6cb6ef1bbe9d3754f14657ef276e3ebb54b5d57bd7988a  nsq-1.3.0.linux-amd64.go1.21.5.tar.gz
ls -l nsq-1.3.0.linux-amd64.go1.21.5.tar.gz
# -rw-r--r-- 1 root root 23042962 Dec 27  2023 nsq-1.3.0.linux-amd64.go1.21.5.tar.gz

4.3 解压与安装

tar xzf nsq-1.3.0.linux-amd64.go1.21.5.tar.gz

查看包内清单（9 个二进制）：

tar tzf nsq-1.3.0.linux-amd64.go1.21.5.tar.gz
# nsq-1.3.0.linux-amd64.go1.21.5/
# nsq-1.3.0.linux-amd64.go1.21.5/bin/
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsq_to_file
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsqlookupd
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsq_tail
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsqadmin
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsq_to_http
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsq_stat
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsqd
# nsq-1.3.0.linux-amd64.go1.21.5/bin/to_nsq
# nsq-1.3.0.linux-amd64.go1.21.5/bin/nsq_to_nsq

安装到版本化目录并建立软链接（便于后续多版本管理）：

mkdir -p /usr/local/nsq-1.3.0
mv nsq-1.3.0.linux-amd64.go1.21.5/bin /usr/local/nsq-1.3.0/
ln -sfn /usr/local/nsq-1.3.0 /usr/local/nsq

⚠️ 排障实录：软链接必须指向「包含 bin 的父目录」/usr/local/nsq-1.3.0，而不是 /usr/local/nsq-1.3.0/bin。实测中曾把链接指向 bin 自身，结果 $PATH 里的 /usr/local/nsq/bin 解析成了 .../bin/bin，报 command not found。判别方法：ls /usr/local/nsq/ 应直接列出 nsqd 等 9 个二进制。

将命令加入 PATH（全局生效）：

echo 'export PATH=$PATH:/usr/local/nsq/bin' > /etc/profile.d/nsq.sh
source /etc/profile.d/nsq.sh

4.4 验证安装

nsqd --version
# nsqd v1.3.0 (built w/go1.21.5)
nsqlookupd --version
# nsqlookupd v1.3.0 (built w/go1.21.5)
nsqadmin --version
# nsqadmin v1.3.0 (built w/go1.21.5)
nsq_tail --version
# nsq_tail v1.3.0

⚠️ 注意：to_nsq 工具没有 -version 参数（实测报 flag provided but not defined: -version），其余工具均支持。

五、方案 B：源码编译安装

5.1 方案说明

适合内网镜像源受控、需要自定义构建或审计源码的场景。NSQ 1.3.0 模块声明使用 Go 1.21（go.mod 口径），本文实测采用与官方构建一致的 Go 1.21.5 工具链。

5.2 安装编译工具与 Go 工具链

apt-get install -y make

下载并安装 Go 1.21.5：

cd /tmp
curl -sL -o go1.21.5.linux-amd64.tar.gz https://dl.google.com/go/go1.21.5.linux-amd64.tar.gz
tar xzf go1.21.5.linux-amd64.tar.gz -C /usr/local
/usr/local/go/bin/go version
# go version go1.21.5 linux/amd64

⚠️ 排障实录：国内网络直连 go.dev 下载常失败，实测改用 https://dl.google.com/go/go1.21.5.linux-amd64.tar.gz 可直连成功；同理，Go 拉取依赖默认走 proxy.golang.org（实测 connection refused），需切换国内模块代理，见 5.4。

5.3 获取源码

官方 tag 源码包（约 0.8MB）：

cd /tmp
curl -sL -o nsq-1.3.0-src.tar.gz https://codeload.github.com/nsqio/nsq/tar.gz/refs/tags/v1.3.0
tar xzf nsq-1.3.0-src.tar.gz
cd nsq-1.3.0
ls
# AUTHORS  CODE_OF_CONDUCT.md  CONTRIBUTING.md  ChangeLog.md  Dockerfile  LICENSE  Makefile  README.md  apps  bench  contrib  dist.sh  fmt.sh  go.mod  go.sum  internal  nsqadmin  nsqd  nsqlookupd  test.sh

5.4 编译

export PATH=/usr/local/go/bin:$PATH
export GOPROXY=https://goproxy.cn,direct
make

实测回显（节选，编译过程逐包下载依赖并输出构建命令）：

go: downloading github.com/bitly/go-hostpool v0.1.0
go build  -o build/nsq_to_file ./apps/nsq_to_file
go build  -o build/nsq_to_http ./apps/nsq_to_http
go build  -o build/nsq_tail ./apps/nsq_tail
go build  -o build/nsq_stat ./apps/nsq_stat
go build  -o build/to_nsq ./apps/to_nsq

产物落在 build/ 目录（实测 9 个二进制全部编译成功）：

ls build/
# nsq_stat  nsq_tail  nsq_to_file  nsq_to_http  nsq_to_nsq  nsqadmin  nsqd  nsqlookupd  to_nsq
build/nsqd --version
# nsqd v1.3.0 (built w/go1.21.5)

5.5 落位安装

把编译产物并入方案 A 的同一目录布局：

mv /tmp/nsq-1.3.0/build/bin /usr/local/nsq-1.3.0/bin-src 2>/dev/null || mkdir -p /usr/local/nsq-1.3.0 && cp /tmp/nsq-1.3.0/build/* /usr/local/nsq-1.3.0/bin/
nsqd --version
# nsqd v1.3.0 (built w/go1.21.5)

💡 说明：源码方案编译出的 9 个工具与官方发布包一致（官方 ChangeLog 明确 #1056 - Removed the nsq_pubsub utility，旧教程里的 nsq_pubsub 已于 1.0 前移除，1.3.0 中不存在）。

六、方案 C：离线包安装（断网服务器）

6.1 方案说明

先在能联网的机器上按方案 A 下载 tarball（或从内网制品库获取），校验后拷贝到目标服务器安装，全程不依赖外网。

6.2 操作步骤

在联网机器上获取并核对哈希（同 4.2，sha256 应为 eeeb62e003ca7c514b6cb6ef1bbe9d3754f14657ef276e3ebb54b5d57bd7988a），然后用任意安全通道传输（示例 scp 到目标机 /opt/pkg）：

scp nsq-1.3.0.linux-amd64.go1.21.5.tar.gz root@10.89.63.2:/opt/pkg/
# nsq-1.3.0.linux-amd64.go1.21.5.tar.gz   100%   22MB  48.6MB/s   00:00

在目标服务器（无需联网）上按方案 A 的 4.2～4.4 步骤执行：sha256sum 校验 → tar xzf → 安装到 /usr/local/nsq-1.3.0 → 建软链 → 配置 PATH → nsqd --version 验证。

七、方案对比与选择建议

选择建议：可联网机器一律用方案 A；需要审计或定制构建用方案 B；生产网隔离环境用方案 C（本质是方案 A 的离线搬运）。

八、配置说明与目录准备

8.1 创建专用系统账号与目录

NSQ 守护进程不建议以 root 长期运行，创建系统用户并准备目录：

useradd -r -s /usr/sbin/nologin nsq
mkdir -p /var/lib/nsq /etc/nsq
chown -R nsq:nsq /var/lib/nsq
id nsq
# uid=108(nsq) gid=116(nsq) groups=116(nsq)

8.2 关键运行参数（命令行参数即配置）

NSQ 所有配置都通过命令行参数指定（官方 README 口径），本指南三守护进程使用的核心参数：

单机体验可以直接 nsqd 裸跑（默认数据在内存）；生产建议按上表显式指定。九个工具的完整参数速查与实测见《NSQ 1.3.0 常用 CLI 命令与工具详解》，集群参数（-broadcast-address/-lookupd-tcp-address）的组网用法见《NSQ 1.3.0 集群部署指南》。

九、systemd 托管三守护进程

9.1 nsqd 服务单元

创建 /etc/systemd/system/nsqd.service：

[Unit]
Description=NSQ daemon (nsqd)
Documentation=https://nsq.io/components/nsqd.html
After=network.target

[Service]
Type=simple
User=nsq
Group=nsq
ExecStart=/usr/local/nsq/bin/nsqd -data-path=/var/lib/nsq
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

• User/Group=nsq：以专用低权账号运行；
• ExecReload：HUP 触发 nsqd 平滑重载（不中断连接）；
• LimitNOFILE=65536：NSQ 消费连接多，提高文件句柄上限。

9.2 nsqlookupd 服务单元

创建 /etc/systemd/system/nsqlookupd.service：

[Unit]
Description=NSQ lookup daemon (nsqlookupd)
Documentation=https://nsq.io/components/nsqlookupd.html
After=network.target

[Service]
Type=simple
User=nsq
Group=nsq
ExecStart=/usr/local/nsq/bin/nsqlookupd
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

9.3 nsqadmin 服务单元

创建 /etc/systemd/system/nsqadmin.service：

[Unit]
Description=NSQ web admin (nsqadmin)
Documentation=https://nsq.io/components/nsqadmin.html
After=network.target

[Service]
Type=simple
User=nsq
Group=nsq
ExecStart=/usr/local/nsq/bin/nsqadmin -lookupd-http-address=127.0.0.1:4161
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

9.4 逐个启用与启动

systemctl daemon-reload

回显：无输出（重载成功）。

systemctl enable nsqlookupd
# Created symlink /etc/systemd/system/multi-user.target.wants/nsqlookupd.service → /etc/systemd/system/nsqlookupd.service.
systemctl enable nsqadmin
# Created symlink /etc/systemd/system/multi-user.target.wants/nsqadmin.service → /etc/systemd/system/nsqadmin.service.
systemctl enable nsqd
# Created symlink /etc/systemd/system/multi-user.target.wants/nsqd.service → /etc/systemd/system/nsqd.service.

按依赖顺序启动（先发现服务，再数据节点，最后管理台）：

systemctl start nsqlookupd

确认状态：

systemctl status nsqlookupd --no-pager -l

实测回显（节选）：

● nsqlookupd.service - NSQ lookup daemon (nsqlookupd)
     Loaded: loaded (/etc/systemd/system/nsqlookupd.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-19 17:19:32 UTC; 3ms ago
       Docs: https://nsq.io/components/nsqlookupd.html
   Main PID: 133 (nsqlookupd)
     Tasks: 7 (limit: 5753)
    Memory: 2.2M

systemctl start nsqadmin
systemctl is-active nsqadmin
# active
systemctl start nsqd
systemctl status nsqd --no-pager -l

实测回显（节选）：

● nsqd.service - NSQ daemon (nsqd)
     Loaded: loaded (/etc/systemd/system/nsqd.service; enabled; vendor preset: enabled)
     Active: active (running) since Mon 2026-10-19 17:19:32 UTC; 3ms ago
   Main PID: 153 (nsqd)
     Tasks: 5 (limit: 5753)
    Memory: 1.7M

9.5 验证三服务连通

curl -s http://127.0.0.1:4151/ping
# OK
curl -s http://127.0.0.1:4161/ping
# OK
curl -s http://127.0.0.1:4151/info
# {"version":"1.3.0","broadcast_address":"nsq-inst","hostname":"nsq-inst","http_port":4151,"tcp_port":4150,"start_time":1792430229,...}

nsqadmin 已可访问（Web 界面为前端渲染，接口层验证）：

curl -s http://127.0.0.1:4171/api/nodes
# {"nodes":[{"remote_addresses":["127.0.0.1:xxxxx"],"hostname":"nsq-inst","broadcast_address":"nsq-inst","tcp_port":4150,"http_port":4151,"version":"1.3.0","topics":[],"out_of_date":false}]}

查看 nsqd 启动日志（journalctl）：

journalctl -u nsqd --no-pager -n 5 -o cat

实测回显（节选，单机首次启动）：

[nsqd] INFO: nsqd v1.3.0 (built w/go1.21.5)
[nsqd] INFO: ID: 208
[nsqd] INFO: NSQ: persisting topic/channel metadata to nsqd.dat
[nsqd] INFO: TCP: listening on [::]:4150
[nsqd] INFO: HTTP: listening on [::]:4151

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

• 多版本并存：本文按版本目录安装（/usr/local/nsq-1.3.0），新版本直接解压为 /usr/local/nsq-<新版本>，切换软链接即可回滚：

ln -sfn /usr/local/nsq-1.3.0 /usr/local/nsq
ls -l /usr/local/nsq
# lrwxrwxrwx 1 root root 20 Oct 19 17:16 /usr/local/nsq -> /usr/local/nsq-1.3.0

• 升级流程：systemctl stop nsqd → 切软链 → systemctl start nsqd → nsqd --version 与 curl 4151/info 验证版本与数据目录完好。
• 降级：反向切回旧版本软链接即可；nsqd 的磁盘队列格式向前兼容性以官方 Release Notes 为准，跨大版本降级前先备份 /var/lib/nsq。
• 查询最新版本：见第三章的 releases.atom 查询命令，不要硬编码猜测版本号。

十一、常见问题（FAQ）

Q1：nsqd 启动报 FATAL: failed to instantiate nsqd - failed to lock data-path: open /var/lib/nsq: no such file or directory？ 实测复现与结论：-data-path 指向的目录必须预先存在，nsqd 不会自建（实测日志：[nsqd] FATAL: failed to instantiate nsqd - failed to lock data-path: open /tmp/nsqdata2: no such file or directory）。先 mkdir -p /var/lib/nsq && chown nsq:nsq /var/lib/nsq 再启动。

Q2：systemd 以 User=nsq 启动报 Failed at step USER spawning /usr/local/nsq/bin/nsqd: No such process（status=217/USER）？ 实测结论：系统里不存在 nsq 用户。先执行 8.1 的 useradd -r -s /usr/sbin/nologin nsq 再 systemctl restart nsqd（实测修复后 is-active 返回 active）。

Q3：to_nsq --version 报 flag provided but not defined: -version？ 属正常现象：to_nsq 是标准输入转发工具，不提供版本参数；用 nsqd --version 等确认套件版本即可。

Q4：网上教程的 /empty、/pause HTTP 接口返回 {"message":"NOT_FOUND"}？ 1.0 起 nsqd 管理接口已改为资源化路径：/topic/empty、/topic/pause、/channel/empty、/channel/pause（v1.3.0 源码 http.go 路由表实查）。旧路径已不存在。

Q5：端口被占用如何迁移？ nsqd/nsqlookupd/nsqadmin 的所有监听都有对应参数（-tcp-address、-http-address、-https-address 等），改 systemd 单元里的 ExecStart 后 systemctl daemon-reload && systemctl restart <单元名> 即可；注意集群内同步更新 -broadcast-address 与各节点 lookupd 注册地址。

Q6：如何确认 nsqd 数据已落盘？ 往 topic 压入超过 -mem-queue-size（默认 10000）的消息后，ls /var/lib/nsq 会看到以 topic 命名的磁盘队列文件；元数据固定为 nsqd.dat（启动日志 NSQ: persisting topic/channel metadata to nsqd.dat）。

十二、卸载与清理

systemctl stop nsqadmin
systemctl disable nsqadmin
# Removed "/etc/systemd/system/multi-user.target.wants/nsqadmin.service".
systemctl stop nsqd
systemctl disable nsqd
# Removed "/etc/systemd/system/multi-user.target.wants/nsqd.service".
systemctl stop nsqlookupd
systemctl disable nsqlookupd
# Removed "/etc/systemd/system/multi-user.target.wants/nsqlookupd.service".
rm -f /etc/systemd/system/{nsqd,nsqlookupd,nsqadmin}.service
systemctl daemon-reload
rm -f /etc/profile.d/nsq.sh
rm -rf /usr/local/nsq /usr/local/nsq-1.3.0
rm -rf /var/lib/nsq /etc/nsq
userdel nsq

逐条验证残留已清除：

which nsqd || echo "nsqd 已卸载"
# nsqd 已卸载
ss -ltn | grep -E '4150|4151|4160|4161|4171' || echo "NSQ 端口已释放"
# NSQ 端口已释放

十三、参考链接

• 官方安装文档：https://nsq.io/deployment/installing.html
• 官方组件文档：https://nsq.io/components/nsqd.html
• v1.3.0 发行页：https://github.com/nsqio/nsq/releases/tag/v1.3.0
• 站内相关：《NSQ 1.3.0 介绍与选型指南》、《NSQ 1.3.0 集群部署指南》、《NSQ 1.3.0 常用 CLI 命令与工具详解》