启动参数与配置文件

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

命令行

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

`run` 命令

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

shell

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

例如：

./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 进程。

./bin/neuronex stop

`install` 命令

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

./bin/neuronex install

`uninstall` 命令

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

./bin/neuronex uninstall

`reset-password` 命令

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

./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 etc/kuiper.yaml
MQTT_SOURCE__DEMO_CONF__QOS => demo_conf.qos in etc/mqtt_source.yaml
EDGEX__DEFAULT__PORT => default.port in etc/sources/edgex.yaml
CONNECTION__EDGEX__REDISMSGBUS__PORT => edgex.redismsgbus.port int etc/connections/connection.yaml

举例，如要调大调用外部算法函数的超时时间（默认为5s），可以设置如下环境变量KUIPER__PORTABLE__RECVTIMEOUT => recvTimeout in etc/kuiper.yaml：

# Docker 部署方式
docker run -d --name neuronex -p 8085:8085 -e KUIPER__PORTABLE__RECVTIMEOUT=20s --privileged=true emqx/neuronex:latest

规则引擎应用配置项

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

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`	是否把追踪数据落盘

链路追踪的开启方式见系统配置 · 链路追踪。

配置文件

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.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 功能

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

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 支持用户将认证公钥放置在 EMQX Neuron 安装目录下的 etc 文件夹下，以实现 JWT Token 认证。

如果 EMQX Neuron 采用 Docker 部署的方式，则需要将本地目录映射进容器内 EMQX Neuron 的 etc 目录。注意首次映射时本地目录不能为空, 必须具有 neuronex.yaml 配置文件以及公钥文件。

在 EMQX Neuron 软件升级或者迁移时，需要考虑到 etc 目录的备份和恢复。

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

驱动转换工具

MQTT

EMQX Cloud

AWS IoT

Azure IoT

Sparkplug B

OPC UA Server

Modbus RTU

Modbus TCP

Inovance Modbus TCP

Mitsubishi 3E

Siemens S7 ISO TCP

Siemens MPI

Omron FINS TCP

Omron FINS UDP

Beckhoff ADS

Panasonic Mewtocol

CODESYS V3

OPC UA

IEC60870-5-104

IEC61850

DL/T645-2007

Brother CNC

Mazak CNC

MTConnect

BACnet/IP

SECS GEM HSMS

NeuronHUB

数据表

函数

驱动开发 SDK 教程

启动参数与配置文件 ​

命令行 ​

run 命令 ​

start 命令 ​

stop 命令 ​

install 命令 ​

uninstall 命令 ​

reset-password 命令 ​

环境变量 ​

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

规则引擎应用配置项 ​

basic —— 日志与服务 ​

rule —— 规则的默认选项 ​

sink —— 动作的断网缓存 ​

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

store —— 状态存储 ​

portable —— Python 插件 ​

openTelemetry —— 链路追踪 ​

配置文件 ​

server ​

neuron ​

规则引擎应用 ​

log ​

official ​

HTTPS 功能使用 ​

开启 HTTPS 功能 ​

访问方式 ​

客户端配置 ​

JWT Token 认证公钥 ​

Dump文件 ​