配置#

虽然 NATS 服务器有许多命令行标志可以用于简单测试功能，但配置 NATS 服务器产品的标准方式是通过配置文件。 我们使用一种简单的配置格式，它结合了传统格式和较新风格（如 JSON 和 YAML）的优点。

nats-server -config my-server.conf

NATS 配置支持以下语法：

• 行可以用 # 和 // 注释
• 值可以通过以下分隔符分配给属性：
  • 等号：foo = 2
  • 冒号：foo: 2
  • 空格：foo 2
• 数组用方括号括起来：["a", "b", "c"]
• 映射用花括号括起来：{foo: 2}
• 映射可以不使用分隔符赋值：accounts { SYS {...}, cloud-user {...} }
• 分号可选用作终止符：host: 127.0.0.1; port: 4222;

NATS 配置文件使用 UTF-8 编码解析。

{% hint style="info" %} 我们强烈建议对名称和值仅使用 ASCII，将非 ASCII 文本的使用限制在注释中。 {% endhint %}

注意#

NATS 配置文件也可以渲染为 JSON 对象（带注释！），但要与变量结合使用，变量仍然必须不加引号。

{% hint style="info" %} JSON 配置文件应仅限于机器生成的配置文件 {% endhint %}

字符串和数字#

配置解析器非常宽容，正如你所见：

• 值可以是原始类型、列表或映射
• 字符串和数字通常会做正确的事情
• 数字支持单位，例如 1K 表示 1000，1KB 表示 1024

以数字开头的字符串值 可能 会产生问题。要将此类值强制为字符串，请用引号括起来。

错误的配置：

listen: 127.0.0.1:4222
authorization: {
    # Bad - Number parsing error
    token: 3secret
}

修复后的配置：

listen: 127.0.0.1:4222
authorization: {
    # Good
    token: "3secret"
}

变量#

服务器配置可以指定变量。变量允许你从配置中的一个或多个部分引用值。

变量语法：

• 块作用域
• 使用 $ 前缀引用。引号块中的变量会被忽略。例如，像 foo = "$VAR1" 这样的用法将导致 foo 成为字面字符串 "$VAR1"。
• 变量必须被使用才能被识别。配置解析器将通过查找对变量的引用来区分 unknown field 和变量。
• 未定义的变量引用将从环境变量中解析。

变量解析顺序：

• 在同一作用域中查找变量
• 在父作用域中查找变量
• 在环境变量中查找变量
• 如果未找到，停止启动服务器并显示以下错误

nats-server: variable reference for 'PORT' on line 5 can not be found

{% hint style="warning" %} 如果环境变量值以数字开头，根据你运行的服务器版本，解析时可能会遇到问题。 {% endhint %}

# 在配置中定义变量
TOKEN: "secret"

# 引用变量
authorization {
    token: $TOKEN
}

# 在配置中定义变量
# 但 TOKEN 从未使用，导致配置解析错误
TOKEN: "secret"

# 引用变量
authorization {
    token: "another secret"
}

unknown field "TOKEN"

类似的配置，但这次变量从环境中解析：

export TOKEN="hello"
nats-server -c /config/file

# TOKEN 在环境中定义
authorization {
    token: $TOKEN
}

包含指令#

include 指令允许你将服务器配置拆分为多个文件。这对于将配置分成可以在不同服务器之间轻松重用的块非常有用。

包含 必须 使用相对路径，并且相对于主配置（通过 -c 选项指定的配置）：

server.conf：

listen: 127.0.0.1:4222
include ./auth.conf

注意 include 后面不跟 = 或 :，因为它是一个 指令。

auth.conf：

authorization: {
    token: "f0oBar"
}

> nats-server -c server.conf

配置重新加载#

配置文件在服务器启动时被读取，不会重新扫描更改，也不会被锁定。

通过向 nats-server 发送信号，服务器可以重新加载大多数配置更改，而无需重新启动服务器或断开客户端连接：

nats-server --signal reload

从 NATS v2.10.0 开始，可以使用系统账户用户向 NATS 服务发送重新加载信号，其中 <server-id> 是要定位的服务器的唯一 ID。

nats --user sys --password sys request '$SYS.REQ.SERVER.<server-id>.RELOAD' ""

配置属性#

配置文件具有以下结构（无特定顺序）。所有块和属性都是可选的（除了 host 和 port）。

请参阅下文，了解每个配置块的详细说明

# 常规设置
host: 0.0.0.0
port: 4222

# 各种服务器级别选项
# ...

# 以下部分是具有一组（嵌套）属性的映射

jetstream {
    # JetStream 存储位置、限制和加密
	store_dir: nats
}

tls { 
    # 用于客户端连接、路由和 https 监控连接的 tls 参数配置映射。
}

gateway {
    # 网关配置映射。网关用于连接集群。
}

leafnodes {
    # 叶子节点配置映射。LeafNodes 是轻量级集群。
}

mqtt {
    # mqtt 配置映射。允许客户端通过 mqtt 协议连接。
} 

websocket {
    # websocket 配置映射。允许客户端通过 websockets 连接。
} 

accounts {
    # 账户列表和账户内的用户
    # 用户可能有授权和认证部分
}

authorization { 
    # 用户可能有授权和认证部分
    # 仅当未定义账户时，此部分才有用
}

mappings {
    # 默认账户的主题映射
    # 当定义账户时，此部分必须在账户映射中
}

resolver {
    # 指向外部认证/授权解析器的指针
    # 有多种可能的解析器类型，在本文档的各自章节中解释
    # memory、nats-base、url ... 未来可能会添加更多
    # 此参数可以是简单配置的值 `MEMORY`
    # 或者是用于连接到解析器的属性映射
}

resolver_tls {
    # 基于 URL 的解析器的 TLS 配置
}

resolver_preload {
    # 在服务器启动时要加载的 JWT 令牌列表。
}

连接性#

集群#

主题映射#

请注意，每个账户都形成自己的主题命名空间。因此 mappings 部分可以出现在服务器级别（应用于默认账户）或账户级别。

host: 0.0.0.0
port:4222

mappings: {
	foo: bar
}

accounts: {
    accountA: { 
	mappings: {
	    orders.acme.*: orders.$1
	}
        users: [
            {user: admin, password: admin},
            {user: user, password: user}
           ]
    },
}

连接超时#

限制#

JetStream 服务器设置#

你可以通过在服务器的配置中简单地添加 jetstream {} 映射来启用 JetStream。 默认情况下，JetStream 子系统会将数据存储在 /tmp 目录中，但你可以通过 store_dir 指定要使用的目录，以及 JetStream 存储的限制（值为 0 表示无限制）。

通常 JetStream 将在集群模式下运行并复制数据，因此存储 JetStream 数据的最佳位置是本地快速 SSD。应特别避免将 NAS 或 NFS 存储用于 JetStream。

{% hint style="warning" %} 请注意，每个启用 JetStream 的服务器必须使用其自己独立的存储目录。JetStream 在集群节点之间复制数据（最多 5 个副本），通过这种方式实现冗余和可用性。

JetStream 不通过共享文件系统实现备用和容错。如果备用服务器与活动服务器共享存储目录，你必须确保任何时候只有一个处于活动状态。不会检测到访问冲突。我们不推荐这样的设置。 {% endhint %}

这是一个最小的示例文件，将在本地 "nats" 目录中存储数据，并设置一些限制。

$ nats-server -c js.conf

jetstream {
  store_dir: nats

  # 1GB
  max_memory_store: 1073741824

  # 10GB
  max_file_store: 10737418240
}

全局 JetStream 选项（服务器级别）

JetStream 账户设置#

JetStream 部分也可能出现在账户中。默认情况下 JetStream 是禁用的。最小配置将启用 JetStream。

accounts {
  A {}
    jetstream {
    }
  }

JetStream TPM 加密#

JetStream 服务器限制#

认证和授权#

集中式认证和授权#

默认的 NATS 服务器没有启用认证或授权。这仅对开发和简单的嵌入式用例有用。默认账户是 $G。

一旦在授权或账户部分配置了至少一个用户，默认的 $G 账户和无认证用户将被禁用。你可以通过设置 no_auth_user 来恢复无认证访问。

分布式认证和授权#

这里的配置选项指的是基于 JWT 的认证和授权。

运行时配置#

集群配置、监控和追踪#