natsio/nats-box

nats-box

镜像概述与主要用途

nats-box 是一个轻量级 Docker 容器，内置 NATS 和 NATS Streaming 相关工具集，用于与 NATS 服务器交互、管理账户与用户、监控服务器状态及进行性能测试。适用于快速部署并使用 NATS 生态工具，简化 NATS 消息系统的开发、测试与运维流程。

核心功能与特性

容器包含以下核心工具，支持 NATS 及 NATS Streaming 的全生命周期管理：

• nats：NATS 管理工具，用于发布/订阅消息、管理服务器配置等（https://github.com/nats-io/natscli#readme%EF%BC%89
• nsc：NATS 账户与用户管理工具，用于创建、配置 NATS 账户及用户
• nats-top：类 top 工具，用于实时监控 NATS 服务器状态
• stan-pub：向 NATS Streaming 集群发布消息
• stan-sub：从 NATS Streaming 集群订阅消息
• stan-bench：NATS Streaming 性能基准测试工具

使用场景与适用范围

• 本地开发/测试：快速与 NATS 服务器（如公共 demo 服务器或私有服务器）进行消息发布订阅
• Kubernetes 集群：在容器编排环境中管理 NATS 资源、调试消息流
• NATS 账户管理：通过 NSC 工具创建和维护 NATS 账户、用户及权限配置
• 性能评估：使用 stan-bench 测试 NATS Streaming 集群的消息处理能力
• 服务器监控：通过 nats-top 实时查看 NATS 服务器的连接数、消息吞吐量等指标

使用方法与配置说明

Docker 环境使用

基础交互示例

通过 Docker 运行容器，直接使用工具与 NATS 服务器交互：

sh
# 启动交互式容器
docker run --rm -it synadia/nats-box:latest

# 在容器内发布消息到公共 NATS 服务器（示例）
~ # nats pub -s demo.nats.io test 'Hello World'
16:33:27 已向 "test" 主题发布 11 字节消息

参数说明

• --rm：容器退出后自动删除
• -it：启用交互式终端
• -v <本地路径>:/nsc：挂载本地目录到容器内 /nsc，用于持久化 NSC 配置（如账户、密钥文件）

Kubernetes 环境使用

交互式模式

直接在 Kubernetes 集群中启动临时交互容器：

sh
# 创建并进入交互式容器
kubectl run -i --rm --tty nats-box --image=natsio/nats-box --restart=Never

# 在容器内订阅消息（后台运行）
nats-box:~# nats sub -s nats hello &

# 发布消息到同一主题
nats-box:~# nats pub -s nats hello world

非交互式模式

部署持久化容器并通过 exec 进入：

sh
# 应用 nats-box 部署配置
kubectl apply -f https://nats-io.github.io/k8s/tools/nats-box.yml

# 进入容器终端
kubectl exec -it nats-box -- /bin/sh

使用 NSC 管理 NATS 账户与用户

NSC（NATS 账户服务器命令行工具）用于管理 NATS 账户、用户及密钥。通过挂载本地卷可持久化配置文件。

步骤示例

1. 启动容器并挂载卷：

   sh
   docker run --rm -it -v $(pwd)/nsc:/nsc natsio/nats-box:latest
   

2. 初始化 NSC（首次使用时）：

   sh
   nats-box:~# nsc init -d /nsc
   

3. 验证配置文件：
   本地 nsc 目录将生成账户、密钥等配置文件，结构如下：

   nsc/
   ├── accounts          # 账户配置
   │   ├── nats
   │   └── nsc.json
   └── nkeys             # 密钥文件
       ├── creds
       └── keys