# 启动参数与配置文件

EMQX Neuron 支持通过`命令行`、`环境变量`、`配置文件`的方式，对 EMQX Neuron 的配置参数进行修改，可以提供更加灵活的启动和运行方式。
如果同时配置了`命令行`、`环境变量`、`配置文件`，三者的优先级关系为：命令行 > 环境变量 > 配置文件 

## 命令行

EMQX Neuron 的命令行位于 `/opt/neuronex/bin/neuronex`，它提供了以下的常用选项：

### `run` 命令

`run`  命令用于在控制台上运行 EMQX Neuron。该命令将 EMQX Neuron 作为一个进程启动，并在终端中显示其输出。

```shell
-c, --config 配置文件路径, 默认为 "etc/neuronex.yaml"
-k, --disable_kuiper 选择是否停用规则引擎应用，默认为 false，即启用
```

例如：
```sh
./bin/neuronex run -c etc/neuronex.yaml -k true
```

该命令将 EMQX Neuron 作为进程启动，并在终端中显示其输出, EMQX Neuron 不会启动规则引擎应用

### `start` 命令

`start ` 命令用于在守护进程模式下启动 EMQX Neuron，该命令将 EMQX Neuron 作为守护进程启动并在后台运行。

### `stop` 命令

`stop` 命令用于停止运行 EMQX Neuron。该命令将杀死 EMQX Neuron 进程。

```sh
./bin/neuronex stop
```

### `install` 命令

`install` 命令用于在 /etc/systemd/system path 中注册 EMQX Neuron 服务配置文件。

```sh
./bin/neuronex install
```

### `uninstall` 命令

`uninstall` 命令用于在 /etc/systemd/system path 中取消注册 EMQX Neuron 服务配置文件。

```sh
./bin/neuronex uninstall
```

### `reset-password` 命令

`reset-password` 命令用于将默认用户 admin 的密码修改为默认密码 0000。

```sh
./bin/neuronex reset-password
```

## 环境变量

EMQX Neuron 支持在启动过程中读取环境变量来配置启动参数，目前支持的环境变量如下:

| 配置名                                | 配置作用                                                     |
|------------------------------------|----------------------------------------------------------|
| NEURONEX_DISABLE_AUTH              | 设置为 1，EMQX Neuron 关闭 Token 鉴权认证；设置为0，EMQX Neuron 开启 Token 鉴权认证 |
| NEURONEX__SERVER__ADMIN__PASSWORD  | 修改 admin 用户默认密码                                          |
| NEURONEX__SERVER__VIEWER__USERNAME | 新添加 viewer 用户的用户名                                        |
| NEURONEX__SERVER__VIEWER__PASSWORD | 新添加 viewer 用户的密码                                         |
| NEURONEX__LOG__MODE                | 设置为 console, EMQX Neuron 会把日志打印到标准输出                        |
| KUIPER__BASIC__CONSOLELOG          | 设置为 true，规则引擎应用会把日志打印到标准输出                            |
| NEURON__LOG__MODE                  | 设置为 console, EMQX Neuron 会把日志打印到标准输出                          |


### 环境变量映射为配置文件

EMQX Neuron 支持通过环境变量覆盖配置文件中的配置，当通过环境变量修改配置时，环境变量需要按照规定的格式设置。映射关系如下：

  ```
  NEURONEX__SERVER__DISABLEAUTH => server.disableAuth in etc/neuronex.yaml
  NEURONEX__LOG__MODE => log.mode in etc/neuronex.yaml
  ```

环境变量之间用“__”分隔，分隔后第一部分的内容匹配配置文件的文件名，其余内容匹配不同级别的配置项。

EMQX Neuron 支持通过环境变量配置规则引擎应用的 yaml 配置文件，映射关系和 EMQX Neuron 相同，如下：

```
KUIPER__BASIC__DEBUG => basic.debug in share/ekuiper/etc/kuiper.yaml
MQTT_SOURCE__DEMO_CONF__QOS => demo_conf.qos in share/ekuiper/etc/mqtt_source.yaml
EDGEX__DEFAULT__PORT => default.port in share/ekuiper/etc/sources/edgex.yaml
CONNECTION__EDGEX__REDISMSGBUS__PORT => edgex.redismsgbus.port in data/ekuiper/connections/connection.yaml
```
举例，如要调大调用外部算法函数的超时时间（默认为5s），可以设置如下环境变量`KUIPER__PORTABLE__RECVTIMEOUT => recvTimeout in share/ekuiper/etc/kuiper.yaml`：
```
# Docker 部署方式
docker run -d --name neuronex -p 8085:8085 -e KUIPER__PORTABLE__RECVTIMEOUT=20s --privileged=true emqx/neuronex:latest

```


### 规则引擎应用配置项

规则引擎应用的主配置文件是 `/opt/neuronex/share/ekuiper/etc/kuiper.yaml`，文件内每一项都带有注释。常用配置项按分组列在下面，配置文件与环境变量二选一即可，环境变量优先。

`share/ekuiper/etc/` 属于程序资产，升级时会被新版本覆盖。需要长期保留的配置改动请使用环境变量，或在升级后重新应用。

#### basic —— 日志与服务

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `logLevel` | `info` | 日志级别，可选 debug、info、warn、error、fatal、panic |
| `debug` | `false` | 打开后按 debug 级别打印更多调试信息 |
| `consoleLog` | `false` | 日志输出到控制台 |
| `fileLog` | `true` | 日志输出到文件 |
| `rotateTime` | `24` | 日志切分间隔，单位小时 |
| `maxAge` | `72` | 日志保留时长，单位小时 |
| `rotateSize` | `10485760` | 单个日志文件大小上限，单位字节。设置后 `maxAge` 不再生效 |
| `rotateCount` | `3` | 保留的日志文件数量 |
| `restPort` | `9081` | REST 服务端口 |
| `timezone` | `Local` | 时区，取 IANA 时区数据库中的名称，`Local` 表示跟随系统 |
| `ignoreCase` | `false` | SQL 处理是否忽略大小写。插件自定义函数的名称始终区分大小写 |
| `pluginHosts` | `https://packages.emqx.net` | 预编译插件的下载地址 |
| `rulePatrolInterval` | `10s` | 规则巡检间隔 |
| `sql.maxConnections` | `0` | 同一数据库实例上各数据源与动作共享的最大连接数，0 表示不限 |
| `gracefulShutdownTimeout` | `10s` | 优雅退出的等待时长 |

#### rule —— 规则的默认选项

每条规则可以单独覆盖这里的取值。

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `qos` | `0` | 0 至多一次，1 至少一次，2 恰好一次。大于 0 时启用检查点机制，保存状态以便中断或重启后恢复，会影响性能 |
| `checkpointInterval` | `300s` | 检查点的执行间隔 |
| `sendError` | `false` | 是否把错误发送到动作 |

#### sink —— 动作的断网缓存

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `enableCache` | `false` | 是否启用缓存 |
| `memoryCacheThreshold` | `1024` | 内存中缓存的最大消息条数 |
| `maxDiskCache` | `1024000` | 磁盘上缓存的最大消息条数 |
| `bufferPageSize` | `256` | 批量读写磁盘的页大小，单位条，用于减少频繁 IO |
| `resendInterval` | `0s` | 重发缓存消息的间隔 |
| `cleanCacheAtStop` | `false` | 规则停止时是否清空缓存 |

#### source —— httppush 数据源的 HTTP 服务

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `httpServerIp` | `0.0.0.0` | HTTP 数据服务监听地址 |
| `httpServerPort` | `10081` | HTTP 数据服务端口 |

#### store —— 状态存储

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `type` | `sqlite` | 状态存储类型，可选 `sqlite`、`redis` |
| `extStateType` | `sqlite` | 外部状态的存储类型 |
| `sqlite.name` | 空 | SQLite 文件名，留空时使用 `sqliteKV.db` |
| `redis.host` | `localhost` | 使用 Redis 时的主机地址 |
| `redis.port` | `6379` | 使用 Redis 时的端口 |
| `redis.timeout` | `1s` | Redis 连接超时 |

#### portable —— Python 插件

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `pythonBin` | `python` | Python 可执行文件。系统中有多个 Python 时需要指定 |
| `initTimeout` | `60s` | 插件初始化超时，超过后插件被终止 |
| `sendTimeout` | `5s` | 发送超时 |
| `recvTimeout` | `5s` | 接收超时 |

#### openTelemetry —— 链路追踪

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `enableRemoteCollector` | `false` | 是否上报到远端采集器 |
| `remoteEndpoint` | `localhost:4318` | 远端采集器地址 |
| `localTraceCapacity` | `2048` | 本地保留的追踪条数 |
| `enableLocalStorage` | `false` | 是否把追踪数据落盘 |

链路追踪的开启方式见[系统配置 · 链路追踪](./sys-configuration.md#链路追踪)。

## 配置文件

EMQX Neuron 提供 YAML 格式文件，位于`/opt/neuronex/etc/neuronex.yaml`，用于配置与 EMQX Neuron 相关的参数。

### server

` server`  部分定义了 EMQX Neuron 服务器的端口号。

- ` port`：EMQX Neuron 服务器的端口号，默认值为 8085。
- ` disableAuth`：EMQX Neuron 是否关闭 Token 认证。
- `disableKuiper`：EMQX Neuron 是否停用规则引擎应用
- `tls`: 开启 TLS 认证
  - `certFile`: 开启 TLS 认证后，证书文件位置
  - `keyFile`: 开启 TLS 认证后，密钥文件位置
- `admin`: 管理员账号
  - `password`: 管理员账户密码
- `viewer`: 添加查看者账号
  - `username`: 查看者账号用户名
  - `password`: 查看者账号密码

### neuron

` neuron ` 部分定义 EMQX Neuron 的版本号和反向代理配置。

- ` version`：EMQX Neuron 的版本号。
- ` reverseProxies`：EMQX Neuron 的反向代理配置列表。
  - ` location`： EMQX Neuron 的访问路径。
  - ` proxyPath` ：EMQX Neuron 后端服务器的路径。

### 规则引擎应用

`ekuiper` 配置段定义了规则引擎应用的版本号和反向代理配置。

- `version`：规则引擎应用的版本号。
- `reverseProxies`：规则引擎应用的反向代理配置列表。
  - `location`：规则引擎应用的路径。
  - `proxyPath`：规则引擎应用后端服务器的路径。
  - `location`：规则引擎应用的 ws 服务路径。
  - `proxyPath`：规则引擎应用 ws 服务的后端路径。

### log

日志 "部分定义了 EMQX Neuron 服务器的日志配置。

- ` mode` ：日志输出模式，选项为 console（输出到控制台）和 file（输出到文件）。
- ` level`：日志级别，选项包括 debug,info,warn,error ,fatal。
- ` file`：日志文件路径。
- `maxSize`：日志文件轮换前的最大容量（以 MB 为单位）。
- `maxAge`： 根据文件名中编码的时间戳保留旧日志文件的最长天数。
- `maxBackups`： 保留的旧日志文件的最大数量。

### official

- `offcial` 部分定义生态 license 官网服务器信息。
  - `url`：生态 license 官网服务器地址。

 默认配置如下

```yaml
server:
  port: 8085
  disableAuth: false
  disableKuiper: false
  # tls:
  #   certFile: "etc/certs/neuronex.crt"
  #   keyFile: "etc/certs/neuronex.key"
#  admin:
#    password: "0000"
#  viewer:
#    username: "test"
#    password: "0000"

neuron:
  reverseProxies:
    - location: /api/neuron
      proxyPath: http://127.0.0.1:7000/api/v2

ekuiper:
  reverseProxies:
    - location: /api/ekuiper
      proxyPath: http://127.0.0.1:9081
    - location: /ws/ekuiper
      proxyPath: ws://127.0.0.1:10081

log:
  mode: file
  level: error
  file: log/neuronex/neuronex.log
  maxSize: 20  # maximum size in megabytes of the log file before it gets rotated
  maxBackups: 5 # MaxBackups is the maximum number of old log files to retain

official:
  url: https://neuronex-licenses.emqx.com
```

## HTTPS 功能使用

EMQX Neuron现已支持HTTPS功能，提供了更安全的通信方式。此功能允许用户通过加密连接访问dashboard和API，增强了数据传输的安全性和隐私保护。EMQX Neuron 使用相同的端口（8085）同时支持HTTP和HTTPS。

### 开启 HTTPS 功能

在配置文件中取消注释以下字段，并在对应目录放入您的证书和私钥。

证书路径相对于安装根目录，默认放在 `etc/certs/`。该目录不随安装包创建，需要手工建立；Docker 部署时它位于挂载的 `etc` 目录内。

```yaml
tls:
  certFile: "etc/certs/neuronex.crt"
  keyFile: "etc/certs/neuronex.key"
```
### 访问方式
- Web Dashboard访问
  - HTTP访问：http://your-server:8085
  - HTTPS访问：https://your-server:8085
- API访问
  - HTTP访问：http://your-server:8085/api/endpoint
  - HTTPS访问：https://your-server:8085/api/endpoint

### 客户端配置

- 方式一：如使用自签名证书，将证书文件（neuronex.crt）添加到客户端的信任存储中
- 方式二：客户端禁用证书验证

## JWT Token 认证公钥

默认情况下 EMQX Neuron 对外暴露的 REST API 需要 JWT Token 认证。EMQX Neuron 支持将认证公钥放在安装目录下的 `etc/` 中，与 `neuronex.yaml` 同级。也可以通过 `POST /api/configuration/jwt/upload` 上传公钥，文件同样写入这个目录。

Docker 部署时，需要把宿主机目录映射进容器的 `/opt/neuronex/etc`，并保持可写。4.0 起，`etc` 为空时容器启动脚本会自动生成默认的 `neuronex.yaml`；公钥仍需预先放入，或在启动后通过接口上传。

升级或迁移时，`etc/` 与 `data/` 一并备份和恢复，见[备份与恢复](./backup-restore.md)。

## Dump文件

EMQX Neuron 默认安装启动后，发生 Crash 不生成 dump 文件。如需 dump 文件进行故障排查。需要生成dump文件的话，需要执行以下命令后开启dump文件存储。

```shell
#!/bin/sh

set -e

core_pattern_path="/proc/sys/kernel/core_pattern"
target_pattern="/tmp/core-%e-%s"
sudo echo $target_pattern | sudo tee $core_pattern_path

core_pid_path="/proc/sys/kernel/core_uses_pid"
target_pid="0"
sudo echo $target_pid | sudo tee $core_pid_path

core_pattern=$(cat $core_pattern_path)
core_pid=$(cat $core_pid_path)

if [ "$core_pattern" = "$target_pattern" ] && [ "$core_pid" = "$target_pid" ];then
  echo "setting success"
else
  echo "setting failed"
fi

```