GeekIt

NATS命令速查

服务端启停、监控诊断、上下文与认证、发布订阅、JetStream 流与消费者、KV 与对象存储、集群灰度与报错排查等 157 条命令

共 157 条命令 · 11 类场景 · 点击右侧图标可复制

命令 / 配置说明复制
nats-server前台启动,默认监听 4222
nats-server -c /etc/nats/nats.conf指定配置文件启动,生产统一配置入口
nats-server -js -sd /data/nats开启 JetStream 并指定存储目录
nats-server -m 8222开启 HTTP 监控端口 8222
nats-server -p 4222 -m 8222 -js常用组合:客户端端口 + 监控 + JetStream
nats-server -t -c /etc/nats/nats.conf只校验配置语法,不启动服务
nats-server -DV开启 debug 与 trace 日志,排查协议问题
nats-server --signal reload热加载配置,修改账号或权限后无需重启
nats-server --signal ldm进入 lame duck 模式,逐步断开连接,滚动升级用
nats-server --signal stop优雅停止
systemctl restart nats-serversystemd 环境重启服务
ss -lntp | grep -E "4222|8222|6222"确认客户端、监控、集群端口监听
journalctl -u nats-server -fsystemd 环境查看实时日志
nats server list启动后验证节点是否可连接
nats-server -v查看服务端版本,JetStream 特性与版本强相关
命令 / 配置说明复制
nats server list列出可连接的服务器与版本、连接数
nats server info --json查看服务器详细信息
nats server ping --count 3测试服务端连通性与往返延迟
nats server report connections按连接汇总流量与消息数
nats server report jetstreamJetStream 资源使用报告
nats server report subscriptions订阅关系汇总
nats server check connection连接健康检查,适合监控探针
nats server check jetstreamJetStream 健康检查
curl -s http://127.0.0.1:8222/varz | jq服务端总体指标:连接数、消息进出、内存
curl -s http://127.0.0.1:8222/connz | jq连接明细,定位异常客户端
curl -s http://127.0.0.1:8222/subsz | jq订阅数与订阅分布
curl -s http://127.0.0.1:8222/jsz?streams=true&consumers=true | jqJetStream 流与消费者状态
curl -s http://127.0.0.1:8222/healthz健康检查接口,返回 ok 表示可用
curl -s http://127.0.0.1:8222/routez | jq集群路由状态
nats sub '$SYS.>'订阅系统事件,观察连接、慢消费者与集群变化
命令 / 配置说明复制
nats context save prod --server nats://10.0.0.11:4222保存连接上下文,避免每次带地址
nats context save prod --creds /etc/nats/app.creds上下文绑定凭据文件(NKey/JWT 认证)
nats context select prod切换当前上下文
nats context ls列出所有上下文
nats context show查看当前生效的连接参数
nats context rm prod删除上下文
nats context validate prod校验上下文配置是否可用
nats --server nats://10.0.0.11:4222 pub test.hello "hi"临时指定服务器,不依赖上下文
nats --user app --password "P@ss" sub test.>用户名密码认证连接
nats --token "s3cr3t" sub test.>Token 认证连接
export NATS_CONTEXT=prod用环境变量固定上下文,脚本中更稳定
默认端口 4222,TLS 场景用 tls:// 前缀地址前缀决定是否加密连接
命令 / 配置说明复制
nats account info查看当前账号的 JetStream 与连接限额
nats nkeys generate生成 NKey 密钥对,用于免密认证
nats nkeys list列出本地已保存的 NKey
nats-server --signal reload修改 nats.conf 的账号与权限后热加载
accounts { APP: { users: [ { user: app, password: pass } ] } }配置账号与用户,多租户隔离的基础
authorization { users: [ { user: app, password: pass, permissions: { publish: "orders.>", subscribe: "orders.>" } } ] }按 subject 限制发布与订阅权限
nats sub 'orders.>' --user app用受限账号验证订阅权限
nats pub orders.new "x" --user app验证发布权限是否放通
system_account: SYS指定系统账号后才能查看 $SYS 事件与服务器指标
nats server list确认账号配置生效且能正常认证
TLS 配置 tls { cert_file, key_file }生产必须开启 TLS,客户端用 tls:// 连接
命令 / 配置说明复制
nats pub orders.new "hello"发布一条消息到指定 subject
nats pub orders.new "hello" --count 10连续发布 10 条,快速验证链路
nats pub orders.new "hello" --sleep 500ms按间隔发布,模拟稳定流量
nats pub orders.new "payload" --header "trace-id:abc"带 Header 发布(2.2+)
nats sub orders.new订阅指定 subject
nats sub 'orders.>'通配订阅:> 匹配多级,* 匹配单级
nats sub 'orders.*.created'单级通配符,匹配 orders.{id}.created
nats sub orders.new --queue workers队列组订阅,同组内消息只投递给一个成员
nats sub orders.new --count 5收到 5 条后退出,脚本中常用
nats sub orders.new --raw只输出消息体,便于管道处理
nats req orders.lookup "id=1"请求-响应模式,超时未响应会报 no responders
nats req orders.lookup "id=1" --timeout 2s指定请求超时时间
nats reply orders.lookup "status=ok"模拟服务端响应请求,调试用
nats sub orders.new --trace显示消息元信息(subject、大小、回复地址)
nats sub '$SYS.>' --count 20观察系统事件流
nats events订阅 NATS 内部事件(连接、订阅变化等)
命令 / 配置说明复制
nats stream add ORDERS --subjects "orders.>" --storage file --retention limits --max-msgs=-1 --max-bytes=-1 --max-age=72h --replicas 3建流:文件存储、按时间与容量限制、3 副本
nats stream add EVENTS --subjects "events.*" --storage memory --retention interest内存流 + interest 保留(有消费者才保留)
nats stream add WORK --subjects "work.>" --retention workqueue --max-age=24h工作队列流,消息被确认后删除
nats stream ls列出所有流
nats stream report全部流的消息数、字节数与消费者汇总
nats stream info ORDERS查看流配置、状态与消费者
nats stream state ORDERS查看流当前消息数、首末序号与副本状态
nats stream edit ORDERS --max-age=168h修改流配置(如延长保留时间)
nats stream purge ORDERS清空流内消息,保留流定义
nats stream purge ORDERS --keep 1000只保留最近 1000 条
nats stream purge ORDERS --subject "orders.test"按 subject 精准清理
nats stream get ORDERS 1按序号取消息,排查内容
nats stream view ORDERS持续查看流内消息
nats stream rm ORDERS删除流及其消息
nats stream rm ORDERS --force强制删除(流有消费者时)
nats stream seal ORDERS封存流,只读不可再写入
nats stream backup ORDERS /backup/orders备份流到目录,含元数据与消息
nats stream restore /backup/orders从备份目录恢复流
命令 / 配置说明复制
nats consumer add ORDERS worker --pull --deliver all --ack explicit --replay instant --filter ""拉模式消费者:从最早开始、显式 ack、即时回放
nats consumer add ORDERS tail --pull --deliver new --ack explicit只消费新消息
nats consumer add ORDERS push_c --push --deliver all --ack explicit推模式消费者,由服务端主动推送
nats consumer add ORDERS c1 --pull --filter "orders.cn.>" --max-deliver 5按 subject 过滤并限制最大投递次数
nats consumer ls ORDERS列出流上的消费者
nats consumer info ORDERS worker查看消费者配置、待处理与未确认数量
nats consumer next ORDERS worker拉取下一条消息(拉模式)
nats consumer next ORDERS worker --count 10批量拉取 10 条
nats consumer next ORDERS worker --no-ack拉取但不确认,用于排查
nats consumer rm ORDERS worker删除消费者
nats consumer report ORDERS消费者指标报告:积压、投递速率
num_pending 持续增长说明消费跟不上num_ack_pending 高则是 ack 慢或未确认
nats sub "orders.>" --queue workers以队列组订阅流绑定的 subject,快速验证消息是否正常
命令 / 配置说明复制
nats kv add CONFIG创建 KV 桶,底层是 JetStream 流
nats kv ls列出所有 KV 桶
nats kv put CONFIG db.host "10.0.0.5"写入键值
nats kv get CONFIG db.host读取键值
nats kv del CONFIG db.host删除键(保留历史)
nats kv purge CONFIG db.host彻底清除键及其历史
nats kv history CONFIG db.host查看键的变更历史
nats kv watch CONFIG监听桶内变更,实时刷新配置
nats kv watch CONFIG --history从历史版本开始监听
nats kv rm CONFIG删除 KV 桶
nats object add FILES创建对象存储桶,用于大文件
nats object put FILES /tmp/report.pdf上传文件
nats object ls FILES列出对象
nats object get FILES report.pdf下载对象
nats object info FILES report.pdf查看对象大小、分块与校验信息
nats object rm FILES report.pdf删除对象
命令 / 配置说明复制
nats-server -cluster nats://0.0.0.0:6222 -routes nats://node1:6222加入集群:指定集群监听与路由地址
nats-server -cluster_name prod-cluster -cluster nats://0.0.0.0:6222显式指定集群名,避免误连其他集群
curl -s http://127.0.0.1:8222/routez | jq查看路由连接与集群拓扑
nats server list --json | jq以 JSON 查看各节点状态与版本
nats server info查看当前连接节点的详细信息
nats server raft step-down让 JetStream 集群 leader 主动退位,测试切换
nats server raft peer-remove移除失效的 Raft 成员(3.0+ 需按提示选择 peer)
nats-server --signal ldm灰度下线:lame duck 模式逐步迁移客户端
gateways { A: { gateways: [ { name: B, url: "nats://b:7222" } ] } }跨集群网关,做多地域消息互通
leafnodes { port: 7422 }叶节点模式,边缘节点就近接入
JetStream 副本数不能超过集群节点数3 副本需要至少 3 个节点,否则建流失败
curl -s http://127.0.0.1:8222/jsz | jq .meta查看 JetStream 集群元数据与 leader
命令 / 配置说明复制
nats bench pub test.bench --msgs 100000 --size 128发布压测:10 万条、128 字节
nats bench sub test.bench --msgs 100000订阅压测,测消费吞吐
nats bench service test.svc --msgs 10000请求-响应压测,测端到端延迟
nats bench pub test.bench --msgs 100000 --clients 10多客户端并发压测
nats server report connections压测中观察连接与消息速率
curl -s http://127.0.0.1:8222/varz | jq '.slow_consumers'检查慢消费者数量,慢消费者会拖累服务端
curl -s http://127.0.0.1:8222/connz?subs=1 | jq按连接查看订阅与待发送数据
nats sub test.bench --trace查看消息元信息,确认 subject 与大小
nats server report jetstreamJetStream 存储与流指标
nats stream state ORDERS --json | jq脚本化提取流积压与副本状态
nats consumer info ORDERS worker --json | jq .num_pending提取待消费数量做监控报警
客户端重连日志出现 slow consumer减少单连接订阅数或提高客户端处理能力
命令 / 配置说明复制
nats: no servers available for connection地址错误、服务未启动或 TLS 端口前缀不对
Authorization Violation账号密码、Token 或 NKey 不正确,检查上下文配置
Permissions Violation for Publish to "orders.new"账号缺少该 subject 的发布权限
Permissions Violation for Subscription to "orders.>"账号缺少订阅权限,注意通配符也要覆盖
nats: no responders available for request请求无服务方响应:服务未订阅该 subject 或已下线
nats: maximum payload exceeded超过最大消息体(默认 1MB),调 max_payload 或改用对象存储
nats: timeout请求超时:检查服务处理耗时与 --timeout 设置
nats: connection closed连接被服务端关闭:鉴权失败、心跳超时或服务重启
JetStream not enabled服务端未加 -js,或账号未开启 JetStream 权限
stream name already in use同名流已存在,先 stream info 确认或改名
consumer already exists同名消费者已存在,删除重建或直接复用
no stream matches subject发布的 subject 没有匹配的流绑定,先 stream info 看 subjects
insufficient resources / replicas > cluster size副本数超过节点数或存储空间不足
slow consumer detected客户端消费慢导致服务端积压,需扩容消费者或限流
nats: secure connection required服务端要求 TLS,客户端需用 tls:// 连接
JetStream 消息堆积但消费者显示 pending 为 0检查 filter subject 是否匹配,以及 ack 是否被提前确认
集群节点反复断开重连检查 6222 端口、集群名与 routes 配置是否一致

运维常用组合

环境自检nats server list → nats server ping → curl :8222/healthz → nats server report jetstream
首次接入nats context save → nats pub/sub 验证 → nats stream add → nats consumer add → nats consumer next
积压排查nats stream state → nats consumer info 看 num_pending/num_ack_pending → 扩消费者或调 max ack pending
需求响应调试nats reply 模拟服务端 → nats req 发请求 → nats sub --trace 看链路 → 确认 no responders 原因
滚动升级nats server raft step-down → nats-server --signal ldm → 升级重启 → nats server list 复核
备份恢复nats stream backup ORDERS /backup/orders → nats stream restore /backup/orders → nats stream state 校验

常见问题排查

1. subject 设计要考虑通配

用 a.b.c 层级命名,消费端用 * 匹配单级、> 匹配多级,避免后期无法按层级订阅

2. 核心 NATS 不持久化

没有消费者在线时消息会丢;需要持久化就用 JetStream 建流

3. 副本数不超过节点数

3 副本流需要至少 3 个 JetStream 节点,否则建流直接失败

4. 拉模式更适合业务消费

pull consumer 由客户端控制节奏,配合 max ack pending 控制并发与重投

5. ack 策略要匹配业务语义

explicit 显式确认最常用,none 适合可丢场景,all 用于批量确认

6. 慢消费者是性能杀手

服务端会为每个连接缓存待发数据,消费慢会拖累内存,必要时限制 max_pending

共 157 条 NATS 命令 · 示例中的流名 ORDERS、subject 与服务器地址请替换为实际环境

关于NATS命令速查

在线 NATS 命令速查手册,按服务端部署与启停、服务端监控与诊断、上下文与连接配置、账号认证与权限、发布订阅与请求响应、JetStream 流管理、JetStream 消费者、KV 与 Object Store、集群网关与灰度、压测与问题定位、常见报错与排查等 11 类场景整理 160+ 条常用命令与配置,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 nats-server 的 -c/-js/-sd/-m/-p/-cluster/-routes/-DV/-t 与 --signal reload/ldm/stop、4222/8222/6222 端口与 journalctl 日志、nats server list/ping/info/report connections/jetstream/subscriptions/check connection/check jetstream 与 raft step-down/peer-remove、8222 的 /varz /connz /subsz /jsz /healthz /routez 监控接口、nats context save/select/ls/show/rm/validate 与 --server/--creds/--user/--token、nats nkeys generate 与 accounts/authorization 配置与 subject 级权限、nats pub 的 --count/--sleep/--header 与 nats sub 的 >/* 通配、--queue/--count/--raw/--trace 与 nats req/reply 请求响应、nats stream add 的 --subjects/--storage/--retention limits|interest|workqueue/--max-msgs/--max-bytes/--max-age/--replicas 与 stream ls/report/info/state/edit/purge --keep/--subject/get/view/rm --force/seal/backup/restore、nats consumer add 的 --pull/--push/--deliver all|new/--ack explicit/--replay instant/--filter/--max-deliver 与 consumer ls/info/next --count --no-ack/rm/report、nats kv add/ls/put/get/del/purge/history/watch/rm 与 nats object add/put/ls/get/info/rm、cluster_name/routez/gateways/leafnodes 与 lame duck 灰度、nats bench pub/sub/service 压测与 varz slow_consumers/connz subs=1 诊断、以及 no servers available、Authorization Violation、Permissions Violation、no responders、maximum payload exceeded、JetStream not enabled、stream name already in use、no stream matches subject、insufficient resources、slow consumer、secure connection required 等报错排查。适用于 NATS 消息队列日常运维、核心发布订阅与请求响应接入、JetStream 持久化流与消费者规划、KV 配置中心与对象存储使用、多租户账号权限与 TLS 加固、集群扩容与灰度升级、消息积压与慢消费者治理,以及中间件运维与面试复习。

核心能力

  • 涵盖 nats-server 的 -c/-js/-sd/-m/-p/-cluster/-routes/-DV/-t 与 --signal reload/ldm/stop、4222/8222/6222 端口与 journalctl 日志、nats server list/ping/info/report connections/jetstream/subscriptions/check connection/check jetstream 与 raft step-down/peer-remove、8222 的 /varz /connz /subsz /jsz /healthz /routez 监控接口、nats context save/select/ls/show/rm/validate 与 --server/--creds/--user/--token、nats nkeys generate 与 accounts/authorization 配置与 subject 级权限、nats pub 的 --count/--sleep/--header 与 nats sub 的 >/* 通配、--queue/--count/--raw/--trace 与 nats req/reply 请求响应、nats stream add 的 --subjects/--storage/--retention limits|interest|workqueue/--max-msgs/--max-bytes/--max-age/--replicas 与 stream ls/report/info/state/edit/purge --keep/--subject/get/view/rm --force/seal/backup/restore、nats consumer add 的 --pull/--push/--deliver all|new/--ack explicit/--replay instant/--filter/--max-deliver 与 consumer ls/info/next --count --no-ack/rm/report、nats kv add/ls/put/get/del/purge/history/watch/rm 与 nats object add/put/ls/get/info/rm、cluster_name/routez/gateways/leafnodes 与 lame duck 灰度、nats bench pub/sub/service 压测与 varz slow_consumers/connz subs=1 诊断、以及 no servers available、Authorization Violation、Permissions Violation、no responders、maximum payload exceeded、JetStream not enabled、stream name already in use、no stream matches subject、insufficient resources、slow consumer、secure connection required 等报错排查

适用场景

适用于 NATS 消息队列日常运维、核心发布订阅与请求响应接入、JetStream 持久化流与消费者规划、KV 配置中心与对象存储使用、多租户账号权限与 TLS 加固、集群扩容与灰度升级、消息积压与慢消费者治理,以及中间件运维与面试复习。NATS命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

NATS命令速查是免费的吗?需要注册或安装吗?
NATS命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
NATS命令速查支持哪些功能?
涵盖 nats-server 的 -c/-js/-sd/-m/-p/-cluster/-routes/-DV/-t 与 --signal reload/ldm/stop、4222/8222/6222 端口与 journalctl 日志、nats server list/ping/info/report connections/jetstream/subscriptions/check connection/check jetstream 与 raft step-down/peer-remove、8222 的 /varz /connz /subsz /jsz /healthz /routez 监控接口、nats context save/select/ls/show/rm/validate 与 --server/--creds/--user/--token、nats nkeys generate 与 accounts/authorization 配置与 subject 级权限、nats pub 的 --count/--sleep/--header 与 nats sub 的 >/* 通配、--queue/--count/--raw/--trace 与 nats req/reply 请求响应、nats stream add 的 --subjects/--storage/--retention limits|interest|workqueue/--max-msgs/--max-bytes/--max-age/--replicas 与 stream ls/report/info/state/edit/purge --keep/--subject/get/view/rm --force/seal/backup/restore、nats consumer add 的 --pull/--push/--deliver all|new/--ack explicit/--replay instant/--filter/--max-deliver 与 consumer ls/info/next --count --no-ack/rm/report、nats kv add/ls/put/get/del/purge/history/watch/rm 与 nats object add/put/ls/get/info/rm、cluster_name/routez/gateways/leafnodes 与 lame duck 灰度、nats bench pub/sub/service 压测与 varz slow_consumers/connz subs=1 诊断、以及 no servers available、Authorization Violation、Permissions Violation、no responders、maximum payload exceeded、JetStream not enabled、stream name already in use、no stream matches subject、insufficient resources、slow consumer、secure connection required 等报错排查。
NATS命令速查适合哪些场景使用?
适用于 NATS 消息队列日常运维、核心发布订阅与请求响应接入、JetStream 持久化流与消费者规划、KV 配置中心与对象存储使用、多租户账号权限与 TLS 加固、集群扩容与灰度升级、消息积压与慢消费者治理,以及中间件运维与面试复习。