夜莺 Nightingale —— 兼容 Prometheus 生态、集告警与可视化于一体的国产开源观测平台

分类：03 一体化监控平台 适用：物理机、虚机、云主机、容器与 K8s、网络设备、数据库/中间件/日志；几十台到数万时间线规模 一句话：不绑定存储、只做「数据源接入 + 告警判定 + 事件路由 + 可视化」，Categraf 采集、Prometheus/VictoriaMetrics 存储 官方：https://github.com/ccfos/nightingale ｜ https://n9e.github.io/ ｜ https://flashcat.cloud/ 授权：Apache-2.0，完全开源；商业支持/增值功能由快猫星云提供

1. 它解决什么问题

不擅长：并非时序数据库（须外接 TSDB）；SNMP 自动发现弱于 Zabbix；纯日志检索需接 Loki/Elasticsearch。

⚠️ 版本差异务必先看 2.3：v5 与 v6+ 架构完全不同，配置文件名、模块名、数据库 schema 均不通用；跨大版本升级先读官方 Upgrade 文档。

2. 核心概念与架构

2.1 术语表

2.2 组件与数据流

 被监控机/容器/应用 ─▶ Categraf（input.* 插件）／exporter／Telegraf／Prometheus
   │ remote write :17000/prometheus/v1/write          ▲ 心跳 :17000/v1/n9e/heartbeat
   ▼
 ┌──────────────────── n9e Server（v6+ 单进程） ────────────────────┐
 │ Web/API ─▶ MySQL/PostgreSQL（规则/用户/事件）                       │
 │ Pushgw ─▶ [[Pushgw.Writers]] ─▶ 时序库                              │
 │ 告警引擎 ─ PromQL 查时序库 ─▶ 判定 ─▶ 事件 ─▶ 通知规则 ─▶ 通知媒介   │
 │      ▲ 从 DB 同步规则          └─▶ 自愈 ─▶ ibex(20090)/Webhook      │
 └──────────┬──────────────────────────┬─────────────────────────────┘
            ▼                          ▼
 VictoriaMetrics:8428 / Prometheus:9090 / Thanos / ES / Loki
 通知：邮件 / 企业微信 / 钉钉 / 飞书 / Webhook / 自愈回调

• 链路：Categraf → n9e Server →（Pushgw.Writers 转发）时序库；告警引擎按周期从 DB 同步规则 → 查时序库 → 判定生成事件 → 通知规则路由到媒介。
• 与 Prometheus 生态关系：夜莺不存储指标，是「兼容层 + 告警/可视化中心」。直接接已有 Prometheus/VictoriaMetrics 作数据源、用原生 PromQL，也可让 Categraf 直接 remote write 到 VM，因此 Grafana 大盘可原样保留；[[Pushgw.Writers]] 支持多 Writer 双写用于迁移（以官方文档为准）。

2.3 版本架构差异（选型/升级前必读）

当前主线为 v8 / v9，且 v9 与 v6 配置项已有增减。本文命令按 v6+ 通用形态书写，凡涉及 [EmbeddedTSDB]、[HTTP.TokenAuth]、AI/MCP 等只属于特定版本的项，一律以对应版本官方文档/Release Notes 为准。

3. 安装与部署

版本号、镜像 tag、包名一律 以官方最新稳定版为准（https://github.com/ccfos/nightingale/releases）；`<xxx>` 为占位符。Docker Compose 的 host-network 套件仅 Linux 可用。

3.1 环境准备

3.2 多种安装方式

方式 A：官方 Docker Compose（最快，含全套依赖）

git clone https://github.com/ccfos/nightingale.git
cd nightingale/docker/compose-bridge && docker compose up -d && docker compose ps
# 打开 http://localhost:17000 ，默认 root / root.2020

该套件拉起 5 个容器：mysql:3306（n9e_v6）、redis:6379、victoriametrics:8428、nightingale:17000/20090、categraf；配置目录挂载 ./etc-nightingale:/app/etc，改 config.toml 后 docker compose restart nightingale 生效。另有 compose-postgres（PG 元数据）、compose-host-network（MySQL+Prometheus，Linux host 网络）、compose-host-network-metric-log（含 Kafka/ES/Logstash）。

方式 B：二进制 + systemd（生产/信创常用）

mkdir -p /opt/monitor/n9e && tar zxvf n9e-v<版本>-linux-amd64.tar.gz -C /opt/monitor/n9e
mysql -uroot -p<密码> -e "CREATE DATABASE n9e_v6 DEFAULT CHARACTER SET utf8mb4;"
# 导入包内 initsql/ 初始化 SQL（以包内文件为准）；再编辑 etc/config.toml（见第 4 章）

# /etc/systemd/system/n9e.service
[Unit]
Description=Nightingale Monitoring Service
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/monitor/n9e
ExecStart=/opt/monitor/n9e/n9e
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target

systemctl daemon-reload && systemctl enable --now n9e && systemctl status n9e

方式 C：Categraf 采集器（每台被监控机）

mkdir -p /opt/categraf && cd /opt/categraf
tar xzf categraf-v<版本>-linux-amd64.tar.gz --strip-components=1
sudo ./categraf --install && sudo ./categraf --start   # 等价 --remove/--stop/--status

方式 D：Helm / K8s（社区 chart）

git clone https://github.com/flashcatcloud/n9e-helm.git
helm install nightingale ./n9e-helm -n n9e --create-namespace && kubectl get pod -n n9e

⚠️ 监控是 P0 系统，装进被监控的 K8s 会形成循环依赖；生产建议独立集群或集群外二进制部署。chart master 跟踪 v9，包仓库可能仍是 v8，以官方 chart 说明为准。

3.3 首次启动与验证

systemctl status n9e && ss -lntp | grep -E '17000|20090'   # 或 docker compose ps
curl -fsS http://127.0.0.1:8428/health                     # VM 探活
curl -G -fsS http://127.0.0.1:8428/api/v1/query --data-urlencode 'query=up'
# Web http://<主机>:17000  root/root.2020 登录后立即改密码
# 集成中心→数据源→新增「Prometheus Like」URL http://<VM_IP>:8428/ → 测试并保存
# 数据查询→即时查询选该源查 up；基础设施→设备列表看 Categraf 上线及 CPU/内存

4. 配置文件详解

4.1 主配置路径与关键项

4.2 完整可运行最小示例（config.toml）

# 以 MySQL + Redis + VictoriaMetrics 为例，密码与地址均为占位符
[DB]
DBType = "mysql"
DSN = "<user>:<pass>@tcp(127.0.0.1:3306)/n9e_v6?charset=utf8mb4&parseTime=True&loc=Local&allowNativePasswords=true"
[Redis]
RedisType = "standalone"
Address = "127.0.0.1:6379"
Password = "<redis_pass>"
[Pushgw]
LabelRewrite = true
[[Pushgw.Writers]]
Url = "http://127.0.0.1:8428/api/v1/write"
[HTTP.APIForAgent]
Enable = true
[HTTP.APIForAgent.BasicAuth]
<agent_user> = "<agent_pass>"

改后 systemctl restart n9e && journalctl -u n9e -f 校验。⚠️ compose 套件里 root:1234 同时写在 compose 与 config.toml 两处，上生产前必须改；开启 APIForAgent.BasicAuth 后未配凭证的 Categraf 会停心跳。

5. 核心使用方法（CLI / HTTP API / Web UI）

5.1 命令与操作速览（≥20 条）

5.2 Categraf 配置（conf/config.toml）

[global]
hostname = ""            # 留空自动取系统 hostname；同名机器多时务必显式指定
interval = 15            # 全局采集频率（秒）
providers = ["local"]
[global.labels]          # 全局附加标签，用于分组/路由/检索
env = "prod"
[[writers]]
url = "http://<N9E_HOST>:17000/prometheus/v1/write"
basic_auth_user = ""     # 服务端开启 APIForAgent.BasicAuth 时填写
basic_auth_pass = ""
timeout = 5000
dial_timeout = 2500
max_idle_conns_per_host = 100
[heartbeat]
enable = true            # 必须开，否则设备列表无此机器/元信息 unknown
url = "http://<N9E_HOST>:17000/v1/n9e/heartbeat"
interval = 10

./categraf --test 校验指标输出；sudo ./categraf --start && --status 启动。只关心跳与只关心 writers 的差别：关 heartbeat → 元信息 unknown；关 writers → 无指标；都关 → 设备列表无此机器。input.* 目录改名（如 bak.input.xx）即停用该插件；另有 logs.toml、prometheus.toml、traces.yaml。

5.3 告警规则与自监控

• 告警规则：Web「告警规则」→ 选业务组与数据源 → 填 PromQL（如 100 - (avg by(instance)(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100) > 80）→ 设持续时间、附加标签、关联通知规则 → 保存。用 vector(1) > 0 可造必触发测试告警。
• 自监控：① 在 n9e / VM / MySQL / Redis 所在主机都部署 Categraf 采集系统指标；② 「模板中心」导入内置大盘与内置告警规则（含机器失联、时间偏移）；③ 用心跳端点 /v1/n9e/heartbeat 判采集器存活；④ 用 curl -G http://<VM_IP>:8428/api/v1/query --data-urlencode 'query=up' 验数据链路。具体自监控指标端点以对应版本官方文档为准。

6. 告警与通知

6.1 规则、静默与升级

6.2 通知媒介示例

Web 路径：通知媒介 → 新增；通知规则 → 绑定媒介与消息模板；消息模板用变量渲染事件字段。
邮件：SMTP 主机/端口/账号/密码/发件人；企业微信：企业 ID / Secret / AgentID / 部门
钉钉/飞书：机器人 Webhook + 加签密钥；Webhook：回调 URL + 自定义 Header/Body（模板变量）
Slack / PagerDuty / Telegram：官方媒介列表中选择并填 Token

具体媒介类型与字段随版本增加，以「通知媒介」页面当前可选项与官方文档为准；Webhook URL 与 Secret 属敏感信息，勿写入公开配置库。测试链路：新增媒介 → 通知规则绑定 → 临时告警规则 vector(1) > 0、for=0 → 观察告警事件与消息到达后 ⚠️ 立即禁用/删除该测试规则。

7. 实战场景

场景一：从零搭「Categraf + n9e + VictoriaMetrics」并跑通第一条告警

• 目标 / 步骤：10 分钟内机器上线、指标可查、告警可达；compose 起全家桶 → 配数据源 → 配媒介/规则 → 造测试告警。

git clone https://github.com/ccfos/nightingale.git
cd nightingale/docker/compose-bridge && docker compose up -d
curl -fsS http://localhost:8428/health
# Web http://localhost:17000 root/root.2020
# 集成中心→数据源→新增 Prometheus Like，URL http://victoriametrics:8428/ 并测试保存
# 数据查询→即时查询查 up；基础设施→设备列表看 categraf 上线
# 通知媒介→Webhook；通知规则→绑定；告警规则→vector(1) > 0、for=0

• 验证：即时查询返回指标、设备列表在线、告警事件产生且收到测试通知。
• 回滚：⚠️ 禁用并删除测试告警规则；docker compose down 停容器但保留卷，删数据需手动删 volume。

场景二：二进制部署 + 外部 VictoriaMetrics + 上报链路 BasicAuth 加固

• 目标 / 步骤：n9e 与 VM 分离、仅允许带凭证采集器上报；配 n9e 指向外部 VM → 开 APIForAgent.BasicAuth → Categraf 同步凭证。

# n9e：/opt/monitor/n9e/etc/config.toml
[DB]
DBType = "mysql"
DSN = "<user>:<pass>@tcp(127.0.0.1:3306)/n9e_v6?charset=utf8mb4&parseTime=True&loc=Local"
[Redis]
RedisType = "standalone"
Address = "127.0.0.1:6379"
[[Pushgw.Writers]]
Url = "http://<VM_IP>:8428/api/v1/write"
[HTTP.APIForAgent]
Enable = true
[HTTP.APIForAgent.BasicAuth]
<agent_user> = "<agent_pass>"

# 每台 Categraf：conf/config.toml（writers 与 heartbeat 都要带凭证）
[[writers]]
url = "http://<N9E_HOST>:17000/prometheus/v1/write"
basic_auth_user = "<agent_user>"
basic_auth_pass = "<agent_pass>"
[heartbeat]
enable = true
url = "http://<N9E_HOST>:17000/v1/n9e/heartbeat"
basic_auth_user = "<agent_user>"
basic_auth_pass = "<agent_pass>"

systemctl restart n9e && sudo ./categraf --stop && sudo ./categraf --start
curl -G -fsS http://<VM_IP>:8428/api/v1/query --data-urlencode 'query=up' | head -c 300

• 验证：即时查询有数据、设备列表心跳恢复；未配凭证的采集器停止更新（鉴权生效）。
• 回滚：[HTTP.APIForAgent] Enable = false 并去掉 Categraf 的 basic_auth_* 后重启两端；⚠️ 回滚短暂允许匿名上报，仅在隔离内网操作。

场景三：机器失联告警 + 告警自愈（自动拉起 Categraf）

• 目标 / 步骤：心跳中断即告警并自动恢复采集器；导入内置「机器失联」规则 → 配自愈回调 → 验证事件与回调。

# Web：模板中心 → 导入「机器失联 / 时间偏移」内置规则；告警规则 → 关联通知规则（企微+邮件）
# 告警自愈：规则中配 Webhook 回调运维执行器，或经 ibex(20090) 下发脚本
# 脚本示意（由执行器调用，勿在 n9e 主机以 root 裸跑）：
#   systemctl is-active categraf || systemctl start categraf
sudo ./categraf --stop     # 触发验证：Web 观察 CRITICAL + 通知 + 自愈回调
sudo ./categraf --start    # 恢复验证：事件自动清除

• 验证：告警事件出现且通知/回调成功，恢复后事件自动清除。
• 回滚：屏蔽规则加维护窗口或停用该规则；⚠️ 自愈脚本限制可执行命令白名单，避免告警触发任意命令执行风险。

8. 日常运维与故障排查

故障「现象 → 原因 → 处置」表

9. 性能、容量与高可用

10. 安全加固、备份与升级

11. 常见坑（现象 → 原因 → 解决）

12. 速查表

13. 选型建议与同类对比

何时选：已有或计划用 Prometheus/VictoriaMetrics，希望告警与事件管理页面化、按业务组分权、需要国产化/私有化与中文支持、想保留 Grafana 大盘只补一个告警中心。何时不选：只想装一个软件就完成采集+存储+绘图（选单机 Prometheus 或 Zabbix）、以 SNMP 网络设备与自动发现拓扑为核心（选 Zabbix）、不愿维护 MySQL+Redis+TSDB 三套外部依赖、团队已重度标准化在 Alertmanager YAML 流程上。

14. 参考链接

• GitHub 主仓库：https://github.com/ccfos/nightingale
• 官方文档（中/英）：https://n9e.github.io/ ｜ https://n9e.github.io/zh/docs/
• Docker Compose / Helm 安装文档：https://n9e.github.io/docs/install/compose ｜ https://n9e.github.io/docs/install/helm
• Categraf 仓库与安装文档：https://github.com/flashcatcloud/categraf ｜ https://n9e.github.io/zh/docs/agent/categraf
• v6 架构与升级说明：https://flashcat.cloud/blog/nightingale-v6-arch/ ｜ https://flashcat.cloud/blog/nightingale-v6-release
• Releases（版本号以官方最新稳定版为准）：https://github.com/ccfos/nightingale/releases