yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: update config docs

This commit is contained in:
Zaiming (Stone) Shi 2023-04-18 18:23:21 +02:00
parent 3e72d6c4a3
commit 6c352fd525
2 changed files with 24 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
rel/emqx_conf.template.en.md
View File

@ -7,21 +7,27 @@ and a superset of JSON.
EMQX configuration consists of two layers. EMQX configuration consists of two layers.
From bottom up: From bottom up:
1. Immutable base: `emqx.conf` + `EMQX_` prefixed environment variables.<br/> 1. Cluster-synced configs: `$EMQX_NODE__DATA_DIR/configs/cluster.hocon`.
Changes in this layer require a full node restart to take effect. 2. Local node configs: `emqx.conf` + `EMQX_` prefixed environment variables.
1. Cluster overrides: `$EMQX_NODE__DATA_DIR/configs/cluster-override.conf`
:::tip Tip
Prior to v5.0.23 and e5.0.3, the cluster-synced configs are stored in
`cluster-override.conf` which is applied on top of the local configs.
If upgraded from an earlier version, as long as `cluster-override.conf` exists,
`cluster.hocon` will not be created, and `cluster-override.conf` will stay on
top of the overriding layers.
:::
When environment variable `$EMQX_NODE__DATA_DIR` is not set, config `node.data_dir` When environment variable `$EMQX_NODE__DATA_DIR` is not set, config `node.data_dir`
is used. is used.
The `cluster-override.conf` file is overwritten at runtime when changes The `cluster.hocon` file is overwritten at runtime when changes
are made from dashboard UI, management HTTP API, or CLI. When clustered, are made from Dashboard, management HTTP API, or CLI. When clustered,
after EMQX restarts, it copies the file from the node which has the greatest `uptime`. after EMQX restarts, it copies the file from the node which has the greatest `uptime`.
:::tip Tip :::tip Tip
Some of the configs (such as `node.name`) are boot-only configs and not overridable. To avoid confusion, don't add the same keys in both `cluster.hocon` and `emqx.conf`.
Config values from `*-override.conf` are **not** mapped to boot configs for
the config fields attributed with `mapping: path.to.boot.config.key`
::: :::
For detailed override rules, see [Config Overlay Rules](#config-overlay-rules). For detailed override rules, see [Config Overlay Rules](#config-overlay-rules).

16
rel/emqx_conf.template.zh.md
View File

@ -5,9 +5,15 @@ HOCON（Human-Optimized Config Object Notation）是一个JSON的超集，非常
EMQX的配置文件可分为二层，自底向上依次是： EMQX的配置文件可分为二层，自底向上依次是：
1. 不可变的基础层 `emqx.conf` 加上 `EMQX_` 前缀的环境变量。<br/> 1. 集群同步配置：`$EMQX_NODE__DATA_DIR/configs/cluster.hocon`。
修改这一层的配置之后，需要重启节点来使之生效。 2. 本地节点配置：`emqx.conf` 加上 `EMQX_` 前缀的环境变量。
1. 集群范围重载层：`$EMQX_NODE__DATA_DIR/configs/cluster-override.conf`
:::tip Tip
在 v5.0.23 或 e5.0.3 之前，集群同步配置保存在文件 `cluster-override.conf` 中，并且它覆盖在配置的最上层。
如果从之前的版本升级上来，只要 `cluster-override.conf` 文件存在，
EMQX 就不会创建 `cluster.hocon`，并且 `cluster-override.conf` 会继续覆盖在配置的最上层。
:::
如果环境变量 `$EMQX_NODE__DATA_DIR` 没有设置，那么该目录会从 `emqx.conf` 的 `node.data_dir` 配置中读取。 如果环境变量 `$EMQX_NODE__DATA_DIR` 没有设置，那么该目录会从 `emqx.conf` 的 `node.data_dir` 配置中读取。
@ -16,9 +22,7 @@ EMQX的配置文件可分为二层，自底向上依次是：
当EMQX运行在集群中时，一个EMQX节点重启之后，会从集群中其他节点复制该文件内容到本地。 当EMQX运行在集群中时，一个EMQX节点重启之后，会从集群中其他节点复制该文件内容到本地。
:::tip Tip :::tip Tip
有些配置项是不能被重载的（例如 `node.name`）。 为避免歧义，应尽量避免让 `cluster.hocon` 和 `emqx.conf` 出现配置交集。
配置项如果有 `mapping: path.to.boot.config.key` 这个属性，
则不能被添加到重载文件 `*-override.conf` 中。
::: :::
更多的重载规则，请参考下文 [配置重载规则](#配置重载规则)。 更多的重载规则，请参考下文 [配置重载规则](#配置重载规则)。