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-server | systemd 环境重启服务 | |
ss -lntp | grep -E "4222|8222|6222" | 确认客户端、监控、集群端口监听 | |
journalctl -u nats-server -f | systemd 环境查看实时日志 | |
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 jetstream | JetStream 资源使用报告 | |
nats server report subscriptions | 订阅关系汇总 | |
nats server check connection | 连接健康检查,适合监控探针 | |
nats server check jetstream | JetStream 健康检查 | |
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 | jq | JetStream 流与消费者状态 | |
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 jetstream | JetStream 存储与流指标 | |
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 jetstreamnats context save → nats pub/sub 验证 → nats stream add → nats consumer add → nats consumer nextnats stream state → nats consumer info 看 num_pending/num_ack_pending → 扩消费者或调 max ack pendingnats 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
相关工具
Linux命令速查
文件、文本、权限、进程、网络、磁盘、systemd与防火墙等 Linux 常用命令速查手册
Docker命令速查
镜像、容器、网络、数据卷、Compose、Swarm、清理与排障等 Docker 常用命令速查手册
Nginx命令速查
服务管理、配置指令、反向代理、HTTPS、限流缓存、日志排查等 Nginx 常用命令速查手册
K8S命令速查
集群上下文、Pod调试、工作负载、Service与Ingress、存储、权限、排障等 kubectl 常用命令速查手册
Windows CMD命令速查
文件目录、网络诊断、进程服务、系统信息、用户权限、注册表、批处理等 Windows CMD 常用命令速查手册
systemctl服务管理速查
服务启停、开机自启、unit文件编写、日志查看、定时器、依赖分析与排障等 systemctl 命令速查手册
关于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 加固、集群扩容与灰度升级、消息积压与慢消费者治理,以及中间件运维与面试复习。