夜莺监控配置文件讲解

中心端 n9e 的配置文件是 etc/config.toml，边缘告警引擎 n9e-edge 的配置文件是 etc/edge/edge.toml。这里我们先分块讲解 n9e 的配置文件，n9e-edge 的配置绝大部分与 n9e 相同，最后单独说明差异。

配置加载机制

开始之前，先了解几个配置加载的基础知识：

• n9e 启动时通过 -configs 参数指定配置目录（默认是 etc，也可以用环境变量 N9E_CONFIGS 指定），目录下所有 .toml 文件都会被合并加载，所以你可以把配置拆成多个 toml 文件分类管理
• 配置修改后需要重启 n9e 进程才能生效，n9e 不会热加载配置文件
• 很多可选参数并没有出现在发行包默认的 config.toml 中，不配置时使用代码内置的默认值，下文会逐一说明

n9e 支持的命令行参数：

敏感字段加密

如果不想在配置文件里写明文密码，可以把敏感字段加密后写成 {{cipher}}xxxx 的形式（xxxx 是 AES-CBC 加密后再做 base64 编码的密文），然后启动时通过 -crypto-key your-secret-key 传入密钥，n9e 会自动解密。支持加密的字段有：

• DB.DSN
• Redis.Password
• HTTP.APIForAgent.BasicAuth 中的密码
• HTTP.APIForService.BasicAuth 中的密码
• Pushgw.Writers 中的 BasicAuthPass

Global

[Global]
RunMode = "release"

这是夜莺研发人员用的配置项，普通用户不需要关心，永远保持 release 即可。

Log

[Log]
# stdout, stderr, file
Output = "stdout"
# log write dir
Dir = "logs"
# log level: DEBUG INFO WARNING ERROR
Level = "DEBUG"
# # rotate by time
# KeepHours = 4
# # rotate by size
# RotateNum = 3
# # unit: MB
# RotateSize = 256

注意：file 模式下，KeepHours（按时间切分）和 RotateNum（按大小切分）必须二选一配置，两个都是 0 的话进程会启动失败。

HTTP

[HTTP]
# http listening address
Host = "0.0.0.0"
# http listening port
Port = 17000
# https cert file path
CertFile = ""
# https key file path
KeyFile = ""
# whether print access log
PrintAccessLog = false
# whether enable pprof
PProf = true
# expose prometheus /metrics?
ExposeMetrics = true
# http graceful shutdown timeout, unit: s
ShutdownTimeout = 30
# max content length: 64M
MaxContentLength = 67108864
# http server read timeout, unit: s
ReadTimeout = 20
# http server write timeout, unit: s
WriteTimeout = 40
# http server idle timeout, unit: s
IdleTimeout = 120

HTTP.ShowCaptcha

[HTTP.ShowCaptcha]
Enable = false

• Enable：登录页是否开启验证码功能

HTTP.APIForAgent

[HTTP.APIForAgent]
Enable = true
# [HTTP.APIForAgent.BasicAuth]
# user001 = "ccc26da7b9aba533cbb263a36c07dcc5"

• Enable：是否开启面向 Agent（如 categraf）的 API 接口，正常来讲必然是要开启的，所以这个配置项一般都是 true
• BasicAuth：Agent 的 API 接口支持 BasicAuth，这里配置 BasicAuth 用户名和密码。一般内网通信不需要配置，如果是公网通信，建议配置，而且密码一定不要使用默认的，容易被攻击

上例中 user001 是 BasicAuth 的用户名，ccc26da7b9aba533cbb263a36c07dcc5 是 BasicAuth 的密码，如果想要配置多个用户，可以继续添加：

[HTTP.APIForAgent.BasicAuth]
user001 = "ccc26da7b9aba533cbb263a36c07dcc5"
user002 = "d4f5e6a7b8c9d0e1f2g3h4i5j6k7l8m9"

注意：如果你配置了 BasicAuth，那么 Agent 端的配置文件中也需要配置相应的用户名和密码，否则 Agent 无法连接到中心 n9e。

HTTP.APIForService

[HTTP.APIForService]
Enable = false
[HTTP.APIForService.BasicAuth]
user001 = "ccc26da7b9aba533cbb263a36c07dcc5"

• Enable：是否开启面向 Service 的 API 接口，边缘告警引擎 n9e-edge 和中心 n9e 通信就依赖这部分接口，所以如果你用到了 n9e-edge，就需要设置为 true
• BasicAuth：和 APIForAgent 的 BasicAuth 同理，公网通信务必启用并修改默认密码

注意：如果你配置了 BasicAuth，那么 n9e-edge 配置文件中的 CenterApi 部分也需要配置相应的用户名和密码，否则 n9e-edge 无法连接到中心 n9e。

HTTP.JWTAuth

[HTTP.JWTAuth]
# unit: min
AccessExpired = 1500
# unit: min
RefreshExpired = 10080
RedisKeyPrefix = "/jwt/"

夜莺页面登录的认证使用 JWT 方式。

JWT 的签名密钥（SigningKey）由夜莺自动生成并保存在数据库中，多个 n9e 实例会自动共享，不需要也不应该在配置文件中配置。

HTTP.ProxyAuth

[HTTP.ProxyAuth]
# if proxy auth enabled, jwt auth is disabled
Enable = false
# username key in http proxy header
HeaderUserNameKey = "X-User-Name"
DefaultRoles = ["Standard"]

如果你想把夜莺嵌入到你自己的系统中，可以考虑使用 ProxyAuth 方式，类似 Grafana 的 ProxyAuth。相当于用户在你自己的系统中登录，你可以拿到用户名，然后把用户名放到 X-User-Name 这个 Header 中传给夜莺，夜莺就会认为这个用户已经登录了。DefaultRoles 是默认角色，如果你不传角色，夜莺就会把这个用户当做 Standard 角色处理。

注意：开启 ProxyAuth 后 JWT 认证就不生效了，等于把认证完全托管给前置代理，一定要保证夜莺的端口只能通过你的代理访问。

HTTP.TokenAuth

[HTTP.TokenAuth]
Enable = true

• Enable：是否允许使用个人 Token（API Key）调用夜莺的 API。用户可以在个人中心创建 Token，调用 API 时通过 Header 携带
• HeaderUserTokenKey：可选参数，携带 Token 的 Header 名称，默认 X-User-Token

HTTP.RSA

[HTTP.RSA]
OpenRSA = false

夜莺在登录的时候，用户密码默认是明文传输的，如果夜莺站点是 HTTPS 的倒是还好，如果是 HTTP 的，就建议开启 RSA 加密，这样用户密码就不会明文传输了。

密钥对不是必须手工准备的：如果 RSAPublicKeyPath 和 RSAPrivateKeyPath 指向的文件都存在，就从文件加载；否则夜莺会自动生成一对密钥并持久化到数据库，多实例之间自动共享。

HTTP.A2A

v9 新增的可选配置，控制夜莺对外暴露的 AI 接口：A2A（Agent-to-Agent）和 MCP（Model Context Protocol）。两者默认都是开启的，外部的 AI Agent 或 MCP 客户端可以通过这些接口与夜莺的 AI 助手交互。

[HTTP.A2A]
# Disable = false
# DisableMCP = false
# BaseURL = ""

相关的 HTTP 路径：AgentCard 发现地址是 /.well-known/agent-card.json（无需认证），A2A 接口挂载在 /a2a，MCP 接口挂载在 /mcp。后两者的认证复用 TokenAuth（X-User-Token Header），所以使用 A2A/MCP 时需要保证 HTTP.TokenAuth.Enable = true。

DB

[DB]
# mysql postgres sqlite
DBType = "sqlite"
# postgres: DSN="host=127.0.0.1 port=5432 user=root dbname=n9e_v6 password=1234 sslmode=disable"
# mysql: DSN="root:1234@tcp(localhost:3306)/n9e_v6?charset=utf8mb4&parseTime=True&loc=Local"
DSN = "n9e.db"
# enable debug mode or not
Debug = false
# unit: s
MaxLifetime = 7200
# max open connections
MaxOpenConns = 150
# max idle connections
MaxIdleConns = 50

DBType 和 DSN 是最为关键的，两个配置联动。DBType 支持 mysql、postgres、sqlite 三种数据库，DSN 是数据库连接信息：如果是 sqlite，就是数据库文件路径；如果是 mysql 或 postgres，就是数据库连接串，写法参考注释中的例子。

夜莺从 v8 版本开始，默认 DBType 设置的是 sqlite，这样方便用户快速体验，不需要安装数据库。但是，生产环境中，还请使用 mysql 或 postgres。

Redis

[Redis]
# standalone cluster sentinel miniredis
RedisType = "miniredis"
# address, ip:port or ip1:port,ip2:port for cluster and sentinel(SentinelAddrs)
Address = "127.0.0.1:6379"
# Username = ""
# Password = ""
# DB = 0
# UseTLS = false
# TLSMinVersion = "1.2"
# Mastername for sentinel type
# MasterName = "mymaster"
# SentinelUsername = ""
# SentinelPassword = ""

Redis 除了用于存储 JWT 相关的登录认证信息，还用于存放机器心跳上报的 metadata。夜莺中支持的机器失联告警规则，就是根据 Redis 中机器的心跳时间来判断的，如果很长时间没有心跳了，就认为机器失联了。

如果 Redis 响应较慢，可能会导致失联告警的误判。即机器明明是存活的，但是 Redis 中的心跳信息没有及时更新，最终导致夜莺误判机器失联了。v8.beta11 版本开始，增加了 Redis 操作相关的监控指标，需要关注这些指标，及时发现 Redis 响应慢的问题。

RedisType 支持 standalone、cluster、sentinel、miniredis 四种，从夜莺 v8 版本开始，默认使用 miniredis（进程内嵌的内存 Redis），这样方便用户快速体验，不需要安装 Redis。但生产环境中，请使用其他模式部署真实的 Redis。

如果 Redis 启用了 TLS，还可以配置以下可选参数：

Alert

夜莺从某个版本开始，为了降低部署复杂度，把 webapi 和告警引擎模块合并在一起了，Alert 这里的配置项是告警引擎的配置项。

[Alert]
[Alert.Heartbeat]
# auto detect if blank
IP = ""
# unit ms
Interval = 1000
EngineName = "default"

[Alert] 下还有几个可选参数：

Alert.Heartbeat

Alert.Alerting

可选配置块，控制通知发送行为：

[Alert.Alerting]
# NotifyConcurrency = 10
# TemplatesDir = ""
# WebhookBatchSend = false

Alert.Alerting.GlobalWebhook

可选配置块，全局事件回调。开启后，所有告警事件除了走各自的通知规则之外，还会额外推送一份到这个全局地址，适合把事件统一接入自研系统或事件中心：

[Alert.Alerting.GlobalWebhook]
Enable = false
Url = "http://127.0.0.1:8999/webhook"
BasicAuthUser = ""
BasicAuthPass = ""
Timeout = 10
Headers = ["X-From", "n9e"]
SkipVerify = false

Center

中心端 n9e 的特有配置，边缘告警引擎 n9e-edge 没有这些配置项。即老版本的 n9e-webapi 相关的特有的配置。

[Center]
MetricsYamlFile = "./etc/metrics.yaml"
I18NHeaderKey = "X-Language"

[Center.AnonymousAccess]
PromQuerier = true
AlertDetail = true

Center.AnonymousAccess

匿名访问相关的配置项：

• PromQuerier：是否允许匿名查询各数据源的接口
• AlertDetail：是否允许匿名查看告警详情

内网环境可以开启，公网环境一定要关闭。

仪表盘有个公开访问的功能，甚至可以设置为不需要登录就可以访问，但前提是 PromQuerier 需要设置为 true。即如果 PromQuerier = false，那么即使设置了仪表盘为公开访问，也是需要登录的。

Center.RSA

可选配置块，和 HTTP.RSA（登录密码加密）不同，这里控制的是数据源密码在前后端之间传输时是否做 RSA 加密：

[Center.RSA]
OpenRSA = false

密钥对复用 HTTP.RSA 的密钥（自动生成或从文件加载）。

Center.FlashDuty

可选配置块，对接 FlashDuty（事件协作平台）时使用，包含 Api（FlashDuty 接口地址）、Headers（附加请求头）、Timeout（请求超时）三个参数。不使用 FlashDuty 集成则无需配置。

Center.AIAgent

v9 新增的可选配置块，AI 助手（Skill 体系）相关：

Pushgw

夜莺虽然不直接存储监控数据，但是提供了多种接收监控数据的接口，比如 Prometheus remote write 协议的接口、OpenTSDB 协议的接口、Datadog 协议的接口等。接收到数据之后，夜莺会把监控数据转发给后端时序库，所以这里夜莺就相当于一个 Pushgateway，相关的配置项都在 Pushgw 下面。

[Pushgw]
# use target labels in database instead of in series
LabelRewrite = true
ForceUseServerTS = true

常用参数：

以下是面向大规模场景的进阶调优参数，一般保持默认即可：

Pushgw.DebugSample

# [Pushgw.DebugSample]
# ident = "xx"
# __name__ = "cpu_usage_active"

这个配置是为了调试、排查问题用的。它是一个监控指标的过滤条件（标签名 = 标签值，需全部匹配），如果上报给夜莺的指标符合这个过滤条件，就会打印到日志中。一般不需要配置，注释掉即可。

Pushgw.DropSample

可选配置，丢弃规则。符合任意一组过滤条件（组内标签需全部匹配）的时序数据会被直接丢弃，不再转发给后端时序库，适合在网关层挡掉不想要的指标：

[[Pushgw.DropSample]]
__name__ = "go_gc_duration_seconds"

[[Pushgw.DropSample]]
ident = "test-host"
__name__ = "cpu_usage_idle"

被丢弃的样本数可以通过夜莺自身监控指标 n9e_pushgw_drop_sample_total 观察。

Pushgw.WriterOpt

# [Pushgw.WriterOpt]
# QueueMaxSize = 1000000
# QueuePopSize = 1000
# QueueNumber = 0

这部分配置默认是注释的，正常来讲用户不需要关注。如果夜莺接收到太多数据，在内存里拥塞了，最终丢了指标，此时需要考虑调整这里的配置。

夜莺会在内存里创建 QueueNumber 个队列，收到监控数据之后写入这些队列；每个队列对应一个 goroutine，按 QueuePopSize 的批次大小从队列取数写入后端时序库。所以 QueueNumber 本质上就是写入后端时序库的并发量。

Pushgw.Writers

这里配置后端时序库的 remote write 写入地址，所有支持 remote write 协议的时序库都可以配置在这里。一般来讲只需要配置一个，如果你想同时写入多个时序库做双写，可以配置多个 [[Pushgw.Writers]] 块。

[[Pushgw.Writers]]
Url = "http://127.0.0.1:9090/api/v1/write"
# Basic auth username
BasicAuthUser = ""
# Basic auth password
BasicAuthPass = ""
Headers = ["X-From", "n9e"]
# timeout settings, unit: ms
Timeout = 10000
DialTimeout = 3000
TLSHandshakeTimeout = 30000
ExpectContinueTimeout = 1000
IdleConnTimeout = 90000
KeepAlive = 30000
MaxConnsPerHost = 0
MaxIdleConns = 100
MaxIdleConnsPerHost = 100

如果时序库是 HTTPS 的，每个 writer 还支持一组可选的 TLS 参数：

# UseTLS = false
# TLSCA = "/etc/n9e/ca.pem"
# TLSCert = "/etc/n9e/cert.pem"
# TLSKey = "/etc/n9e/key.pem"
# InsecureSkipVerify = false

含义与 Redis 一节的 TLS 参数相同（还包括 TLSKeyPwd、ServerName、TLSMinVersion、TLSMaxVersion）。

Pushgw.Writers.WriteRelabels

写往时序库的数据，在写入之前可以做 relabel 操作。和 Prometheus 的 relabel 配置类似，只不过 Prometheus 用的 yaml 格式，夜莺用的 toml 格式：

[[Pushgw.Writers.WriteRelabels]]
Action = "replace"
SourceLabels = ["__address__"]
Regex = "([^:]+)(?::\\d+)?"
Replacement = "$1:80"
TargetLabel = "__address__"

Pushgw.KafkaWriters

可选配置，除了写时序库，夜莺还可以把接收到的监控数据转发到 Kafka：

[[Pushgw.KafkaWriters]]
Brokers = ["127.0.0.1:9092"]
Topic = "n9e-metrics"
[Pushgw.KafkaWriters.SASL]
Enable = true
User = "admin"
Password = "admin"
Mechanism = "PLAIN"
Version = 1
Handshake = true
AuthIdentity = ""

Ibex

故障自愈引擎 Ibex 的配置项，即远程执行脚本的那个功能。原本这个功能是单独拆开的一个模块叫 ibex，后来合并到 n9e 里了，所以这个配置项也在 n9e 里。

[Ibex]
Enable = true
RPCListen = "0.0.0.0:20090"

• Enable：是否开启 Ibex 服务端功能
• RPCListen：Ibex 的 RPC 服务监听地址，Agent（categraf 的 ibex 插件）通过这个端口与服务端通信

n9e-edge 的配置

边缘告警引擎 n9e-edge 的配置文件是 etc/edge/edge.toml，大部分配置和中心 n9e 的配置相同，差异主要有：

• n9e-edge 没有 [Center] 相关配置
• n9e-edge 必须配置 [CenterApi]，用于连接中心端 n9e：

[CenterApi]
Addrs = ["http://127.0.0.1:17000"]
BasicAuthUser = "user001"
BasicAuthPass = "ccc26da7b9aba533cbb263a36c07dcc5"
# unit: ms
Timeout = 9000

BasicAuthUser、BasicAuthPass 对应中心端 [HTTP.APIForService.BasicAuth] 里配置的用户名密码，同时中心端的 HTTP.APIForService.Enable 要设置为 true。

更多信息可以参考这篇文章：《夜莺架构中的边缘模式说明》。

常见问题

1. 修改了配置文件为什么不生效？

n9e 不支持配置热加载，任何配置修改后都需要重启 n9e 进程。另外注意 -configs 指定目录下的所有 toml 文件都会被加载，检查一下是否有其他 toml 文件覆盖了同名配置。

2. 生产环境最少需要修改哪些配置？

把 DB 从 sqlite 换成 mysql 或 postgres，把 Redis 从 miniredis 换成真实的 Redis（standalone/cluster/sentinel），配置 Pushgw.Writers 指向你的时序库。其余配置保持默认基本就能跑起来。

3. 时序数据偶尔丢点，如何排查是不是夜莺侧拥塞了？

观察夜莺自身的 /metrics 指标中队列相关的指标（如 n9e_pushgw_sample_queue_size），如果持续接近 QueueMaxSize，说明写后端时序库的速度跟不上接收速度，可以调大 Pushgw.WriterOpt 的 QueueNumber/QueueMaxSize，或检查后端时序库的写入性能。

4. 配置文件里的密码不想写明文怎么办？

用「敏感字段加密」机制：把密码用 AES 加密后写成 {{cipher}}xxx 形式，启动时通过 -crypto-key 传入密钥。支持 DB.DSN、Redis 密码、BasicAuth 密码、Writers 的 BasicAuthPass。

5. 想用自己编译的前端页面替换内置前端怎么办？

设置 Center.UseFileAssets = true，然后把前端构建产物放到 n9e 运行目录下的 pub 目录中即可。

参考资料

• 快速安装手册（二进制方式）
• 快速安装手册（docker-compose 方式）
• 夜莺架构中的边缘模式说明
• Prometheus relabel_config 官方文档