Nightingale 9.2.0 配置参数详解
目标：对 Nightingale（夜莺）v9.2.0 服务端唯一的配置文件 etc/config.toml 逐段拆解参数含义、默认值与生效方式，并对关键参数（日志级别、登录验证码、告警引擎名、Ibex 模块、匿名查询）给出「改动 → 重启 → 验证」的实测结果。全文基于官方 Release 包自带配置模板与真实运行环境实测。
| 项目 | 值 | 说明 |
|---|
| 服务端版本 | v9.2.0-01a8e22eb21d81f5cbe5c34e5a1511ff63e39983 | n9e --version 实测 |
| 配置文件 | /app/etc/config.toml（容器内），对应部署目录 etc-nightingale/config.toml | 启动日志确认加载路径 |
| 运行形态 | n9e 容器 + MySQL 8.0 + Redis 7.2 + VictoriaMetrics v1.153.0 + Categraf v0.5.15 | 见本专栏《Docker Compose 部署指南》 |
| 实测方式 | 修改配置 → 重启进程 → 观察日志/接口/数据库变化 | 每项均给出实测回显 |
- 唯一入口：n9e 启动时读取
etc/config.toml（可用 -c 参数指定其他路径），所有模块参数集中在该文件，官方 Release 包 etc/config.toml 即模板。
- 生效方式：普通参数在进程重启后生效，n9e 不支持配置文件热加载；配置存于文件而非数据库，多实例集群部署时需保证各实例文件一致。
- 结构：TOML 分段结构，顶层段为
Global/Log/HTTP/DB/Redis/Alert/Center/Pushgw/Ibex 九大段，其中 HTTP 下有 6 个子段（ShowCaptcha、APIForAgent、APIForService、JWTAuth、TokenAuth、ProxyAuth、RSA），Alert 下有 Heartbeat/Alerting 子段，Center 下有 AnonymousAccess 子段。
| 参数 | 默认值 | 说明 |
|---|
| RunMode | release | 运行模式，release/test；test 模式下框架日志更详细，生产保持 release |
| 参数 | 默认值 | 说明 |
|---|
| Dir | logs | 日志文件目录（Output=file 时使用） |
| Level | INFO | 日志级别：DEBUG / INFO / WARNING / ERROR |
| Output | stdout | 输出目标：stdout / stderr / file |
| KeepHours | （注释） | 按时间轮转保留小时数 |
| RotateNum / RotateSize | （注释）3 / 256 | 按大小轮转：单个文件数上限 / 单位 MB |
实测：Level="INFO" 改为 "DEBUG" 并重启，30 秒窗口内日志出现 78 条 DEBUG 行，例如：
DEBUG models/configs.go:95 Phone encryption config loaded: enabled=false
DEBUG memsto/notify_channel_cache.go:295 started 5 notify consumers for channel 2
| 参数 | 默认值 | 说明 |
|---|
| Host / Port | 0.0.0.0 / 17000 | 监听地址与端口，浏览器与 API 统一入口 |
| CertFile / KeyFile | 空 | HTTPS 证书路径，同时配置即启用 https |
| PrintAccessLog | false | 访问日志开关 |
| PProf | false | 性能分析端点开关（排障用，生产关闭） |
| ExposeMetrics | true | 暴露 /metrics 供 PromQL 抓取自身指标 |
| ShutdownTimeout | 30 | 优雅停机超时（秒） |
| MaxContentLength | 67108864 | 请求体上限（64MB） |
| ReadTimeout / WriteTimeout / IdleTimeout | 20 / 40 / 120 | HTTP 服务三超时（秒） |
实测：默认 ExposeMetrics=true 下 curl -I http://127.0.0.1:8130/metrics 返回 200（容器映射端口 8130 → 17000）。
| 参数 | 默认值 | 说明 |
|---|
| Enable | false | 登录页图形验证码开关；开启后登录必须携带 captchaid+verifyvalue |
实测：改为 true 重启后——
- 登录页状态查询接口
GET /api/n9e/auth/ifshowcaptcha 返回 {"dat":{"show":true}}；
- 不带验证码参数直接调登录接口返回
HTTP 500（源码 router_login.go：CaptchaVerify 校验失败即拒绝）；
- 配套接口：
POST /auth/captcha 生成图形验证码、POST /auth/captcha-verify 校验。
| 参数 | 默认值 | 说明 |
|---|
| APIForAgent.Enable | true | 采集器（Categraf 等）数据上报与心跳接口：/prometheus/v1/write、/v1/n9e/heartbeat 等 |
| APIForService.Enable | false | 面向「服务监控」类上报接口，默认关闭 |
| 子段 BasicAuth | （注释） | 上报接口摘要式口令保护，键值对形式 user = md5(password) |
💡 说明：Internet 暴露部署时建议为 Agent 接口开启 BasicAuth，防止任意人伪造心跳与写入数据。
| 参数 | 默认值 | 说明 |
|---|
| JWTAuth.AccessExpired | 1500 | 登录态有效期（分钟），约 25 小时 |
| JWTAuth.RefreshExpired | 10080 | 刷新令牌有效期（分钟），7 天 |
| JWTAuth.RedisKeyPrefix | /jwt/ | JWT 相关键在 Redis 中的前缀 |
| TokenAuth.Enable | false | 固定 Token 认证头开关（Header 名 X-User-Token） |
| ProxyAuth.Enable | false | 反向代理透传用户名认证（开启后 JWT 失效）；HeaderUserNameKey=X-User-Name，DefaultRoles=[Standard] |
| RSA.OpenRSA | false | 登录口令 RSA 加密传输开关 |
| 参数 | 默认值 | 说明 |
|---|
| DSN | （模板示例 1234） | 连接串；MySQL 与 PostgreSQL 两种写法，注释中给出 PG 示例 |
| Debug | false | SQL 调试日志（慢查询日志级别） |
| DBType | mysql | mysql 或 postgres |
| MaxLifetime | 7200 | 连接最大复用时间（秒） |
| MaxOpenConns / MaxIdleConns | 150 / 50 | 连接池上限；大规模集群（万级采集对象）可适当调大 |
本文实测栈 DSN：root:q1w2e3r4@tcp(mysql:3306)/n9e_v6?charset=utf8mb4&collation=utf8mb4_general_ci&parseTime=True&loc=Local&allowNativePasswords=true——库名 n9e_v6 由初始化 SQL 创建，即使 v9 版本库名仍沿用 n9e_v6 命名。
| 参数 | 默认值 | 说明 |
|---|
| Address | 127.0.0.1:6379 | 单机填 ip:port；cluster 类型填 ip1:port,ip2:port |
| Username / Password | （注释空） | 认证信息 |
| DB / UseTLS / TLSMinVersion | 0 / false / 1.2 | 逻辑库与 TLS |
| RedisType | standalone | standalone / cluster / sentinel |
| MasterName | （注释） | sentinel 模式主库名 |
| 参数 | 默认值 | 说明 |
|---|
| Heartbeat.IP | 空（自动探测） | 引擎心跳上报的 IP |
| Heartbeat.Interval | 1000 | 心跳间隔（毫秒） |
| Heartbeat.EngineName | default | 引擎集群名。多套引擎分组处理不同数据源时改名分组；数据源的 cluster_name 必须与该值一致才会被本组引擎评估（见 3.9 排障） |
| Alerting.NotifyConcurrency | 10（注释） | 通知发送并发数 |
实测：EngineName 由 default 改为 n9e-engine-01 并重启后，MySQL alerting_engines 表出现新的心跳行（节选）：
engine_cluster instance datasource_id
default 10.89.60.5:17000 0 <- 改名前遗留
n9e-engine-01 10.89.60.5:17000 0 <- 改名后新心跳
n9e-engine-01 10.89.60.5:17000 99999999
旧集群心跳行会在超时后被清理；改回 default 后数据源 1 的评估恢复。
| 参数 | 默认值 | 说明 |
|---|
| MetricsYamlFile | ./etc/metrics.yaml | 指标说明元数据（仪表盘联想提示用） |
| I18NHeaderKey | X-Language | 多语言请求头键名 |
| AnonymousAccess.PromQuerier | false | 匿名查询：开启后 /proxy/:id/*url、/ds-query 等查询接口免登录可访问 |
| AnonymousAccess.AlertDetail | false | 告警事件详情页免登录查看 |
实测：默认 false 时无 Token 调 POST /api/n9e/ds-query 返回 401；改为 true 重启后同一请求通过认证层（进入参数校验，返回参数错误而非 401）；改回 false 恢复 401。生产环境保持 false，仅内部分享看板时临时开启。
| 参数 | 默认值 | 说明 |
|---|
| LabelRewrite | true | 用库内（业务组/机器全局标签）改写时序标签 |
| ForceUseServerTS | true | 忽略上报数据自带时间戳、统一用服务端接收时间（避免采集端时钟漂移造成乱序） |
| DebugSample | （注释） | 调试用：按标签过滤打印样本 |
| WriterOpt.QueueMaxSize / QueuePopSize | 1000000 / 1000 | 内存队列长度与批量弹出条数，突发流量时防丢可调大 |
[[Pushgw.Writers]] 数组（可配多个后端，多写）：
| 参数 | 说明 |
|---|
| Url | Remote Write 端点，本文实测 http://victoriametrics:8428/api/v1/write |
| BasicAuthUser / BasicAuthPass | 后端认证 |
| Headers | 附加请求头，实测 ["X-From", "n9e"] |
| Timeout / DialTimeout | 请求/拨号超时（毫秒），10000 / 3000 |
| TLSHandshakeTimeout / ExpectContinueTimeout / IdleConnTimeout / KeepAlive | 连接池参数（毫秒） |
| MaxConnsPerHost / MaxIdleConns / MaxIdleConnsPerHost | 0 / 100 / 100，0 表示不限制总连接 |
| UseTLS/TLSCA/TLSCert/TLSKey/InsecureSkipVerify | 后端为 HTTPS 时的证书配置 |
| WriteRelabels | 写入前标签重写（Action=replace/keep/drop 等，语义同 Prometheus relabel） |
| 参数 | 默认值 | 说明 |
|---|
| Enable | true | 是否内置启动 Ibex 模块（告警自愈脚本调度、边缘数据转发） |
| RPCListen | 0.0.0.0:20090 | Ibex RPC 监听端口 |
实测：Enable=false 重启后进程日志不再出现 rpc.listening: 0.0.0.0:20090，/proc/net/tcp6 中 20090（十六进制 4E7A）监听为 0；恢复 true 后日志重现 rpc.listening: 0.0.0.0:20090 且监听计数为 2。不用自愈功能的生产环境可安全关闭，减少一个对外端口。
| 改动项 | 生效方式 | 验证手段 | 实测结果 |
|---|
| Log.Level | 重启进程 | 启动日志级别 | DEBUG 下 30s 出现 78 条 DEBUG 日志 |
| HTTP.ShowCaptcha.Enable | 重启进程 | /api/n9e/auth/ifshowcaptcha | {"show":true}，无验证码登录返回 500 |
| HTTP.ExposeMetrics | 重启进程 | curl /metrics | 200 |
| Alert.Heartbeat.EngineName | 重启进程 | alerting_engines 表 | 新集群名心跳行出现 |
| Ibex.Enable | 重启进程 | 启动日志 + 端口监听 | 20090 监听随开关出现/消失 |
| Center.AnonymousAccess.PromQuerier | 重启进程 | 无 Token 调 /ds-query | 401 ↔ 通过认证 |
| DB.DSN / Redis.Address | 重启进程 | 启动日志连接报错 | 配置错误时启动失败并打印连接错误 |
- 数据源 cluster_name 与 Alert.Heartbeat.EngineName 不一致：告警规则不评估（事件恒为 0），这是 v9 最隐蔽的坑，详见本专栏《Docker Compose 部署指南》排障实录。
- RunMode=release 别改：test 模式日志量极大，且部分校验行为不同。
- ForceUseServerTS=true 时：历史回灌数据时间戳会被改写，需要保留原始时间戳的迁移场景应设 false。
- MaxContentLength 64MB：通过 API 批量导入仪表盘/规则 JSON 超过 64MB 会被拒，需调大。
- 多实例部署：除 Heartbeat.IP 需各填本机 IP 外其余配置完全一致；JWT 依赖共享 Redis，多实例必须同 Redis。