启动参数与配置文件

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

命令行

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

run 命令

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

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

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

配置文件

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 官网服务器地址。

默认配置如下

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 目录内。

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/ 一并备份和恢复，见备份与恢复。

Dump文件

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

#!/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