Nightingale 9.2.0 常用 CLI 命令详解

目标：整理 Nightingale（夜莺）v9.2.0 服务端 n9e 与配套采集器 Categraf v0.5.15 的全部命令行参数，并对高频 OpenAPI（curl）逐条给出实测命令与真实回显，覆盖「启动、排障、巡检、配置管理、告警运维」四类日常操作。

一、环境信息

项目	值	说明
服务端	`v9.2.0-01a8e22eb21d81f5cbe5c34e5a1511ff63e39983`	`n9e --version` 实测
采集器	`v0.5.15-3232630235e3602477778a4df6c6eb7d99839f7a`	`categraf --version` 实测
运行环境	n9e + MySQL 8.0 + Redis 7.2 + VictoriaMetrics v1.153.0 + Categraf（见本专栏部署篇）	API 实测基于容器映射端口 8130 → n9e 17000
API 认证	登录获取 JWT，请求头 `Authorization: Bearer <token>`	v9 API 统一前缀 `/api/n9e`

二、n9e 服务端命令行

n9e 是单二进制，命令行参数只有三个（n9e --help 实测输出）：

Usage of n9e:
  -configs string
        Specify configuration directory.(env:N9E_CONFIGS) (default "etc")
  -crypto-key string
        Specify the secret key for configuration file field encryption.
  -version
        Show version.

参数	说明	典型用法
`-configs`	指定配置目录（目录下必须含 `config.toml`），默认相对路径 `etc`；也支持环境变量 `N9E_CONFIGS`	多实例/多配置场景：`n9e -configs /opt/n9e/etc-2`；systemd 里推荐写绝对路径
`-crypto-key`	配置文件敏感字段（如 DB 口令）加密后的解密密钥	配合官方配置加密工具使用，密钥丢失则无法解密配置
`-version`	打印版本与 commit	升级前后比对：`n9e -version` → `v9.2.0-01a8e22...`

⚠️ 注意：-configs 的默认值 etc 是相对启动目录的路径，用 systemd 托管时务必写绝对路径或在 WorkingDirectory 固定目录，否则会报 configuration file etc/config.toml not found 类错误（Categraf 同理，实测见下文 4.2）。

启动与优雅停止（生产推荐 systemd 或容器编排）：

nohup ./n9e &> n9e.log &          # 前台裸跑（临时验证）
kill -HUP $(pidof n9e)           # 不支持热加载配置，重载请重启进程

三、curl OpenAPI 逐条实测

以下 API 均在本专栏部署栈上实测，$TOKEN 为登录返回的 access_token，请求头统一为 -H "Authorization: Bearer $TOKEN"。

3.1 认证与账号

登录获取 Token：

curl -s -X POST 'http://127.0.0.1:8130/api/n9e/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username":"root","password":"q1w2e3r4"}'

实测回显（截断）：

{"err":"","dat":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....","refresh_token":"...","user":{"id":1,"username":"root","role":"Admin"}}}

修改自己的口令：

curl -s -X PUT 'http://127.0.0.1:8130/api/n9e/self/password' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"oldpass":"root.2020","newpass":"q1w2e3r4"}'
# 实测回显：{"err":"","request_id":"31a7dcb6-..."}

查询登录验证码开关状态：

curl -s 'http://127.0.0.1:8130/api/n9e/auth/ifshowcaptcha'
# 实测回显：{"dat":{"show":false},"err":""}

3.2 采集对象与业务组

查询采集器目标（心跳自动注册）：

curl -s 'http://127.0.0.1:8130/api/n9e/targets?gids=0' -H "Authorization: Bearer $TOKEN"

实测回显关键字段（截断）：categraf01 已注册，agent_version: v0.5.15、host_ip、mem_util、cpu_num、target_up: 2（2=进程与插件均存活）。

查询业务组列表：

curl -s 'http://127.0.0.1:8130/api/n9e/busi-groups' -H "Authorization: Bearer $TOKEN"
# 实测回显：{"dat":[{"id":1,"name":"Default Busi Group",...}],"err":""}

3.3 数据源管理

创建/更新数据源（upsert 幂等）：

curl -s -X POST 'http://127.0.0.1:8130/api/n9e/datasource/upsert' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"victoria-metrics","identifier":"vm-01","plugin_type":"prometheus","plugin_type_name":"Prometheus Like","category":"timeseries","cluster_name":"default","settings":{},"http":{"url":"http://victoriametrics:8428","urls":["http://victoriametrics:8428"],"timeout":10000,"dial_timeout":3000,"tls":{},"max_idle_conns_per_host":100,"headers":{}},"auth":{"basic_auth":false,"basic_auth_user":"","basic_auth_password":""},"is_default":true,"weight":100}'
# 实测回显：{"err":"","dat":{"verification":"verified","id":1}}

⚠️ cluster_name 必须与告警引擎集群名（config.toml 的 Alert.Heartbeat.EngineName，默认 default）一致，否则告警规则不会被评估（本专栏部署篇排障实录第一案）。

经 n9e 代理即时查询数据源（数据源 id=1）：

curl -s 'http://127.0.0.1:8130/api/n9e/proxy/1/api/v1/query?query=up' -H "Authorization: Bearer $TOKEN"

实测回显（截断）：

{"status":"success","data":{"resultType":"vector","result":[{"metric":{"__name__":"up","ident":"categraf01"},"value":[1792471788,"1"]}]}}

⚠️ 该接口用 GET + query 参数传查询语句；若用 POST JSON 会报 missing query arg（实测踩坑）。

3.4 告警规则

创建规则（业务组 1，请求体是数组，返回规则 id）：

curl -s -X POST 'http://127.0.0.1:8130/api/n9e/busi-group/1/alert-rules' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '[{"name":"memory-usage-over-20-percent","cate":"prometheus","prod":"metric","datasource_queries":[{"match_type":0,"op":"in","values":[1]}],"severity":2,"disabled":0,"rule_config":{"queries":[{"prom_ql":"100 - mem_available_percent","severity":2,"unit":"percent"}]},"prom_eval_interval":15,"prom_for_duration":0,"notify_recovered":1,"notify_channels":[],"notify_groups":[],"notify_repeat_step":60,"recover_duration":60,"callbacks":["http://10.89.60.1:18080/hook"],"enable_days_of_weeks":[["1","2","3","4","5","6","0"]],"enable_stimes":["00:00"],"enable_etimes":["23:59"]}]'
# 实测回显：{"err":"","dat":[1]}

更新规则（PUT，body 为完整对象且必带 id 与 group_id）：

curl -s -X PUT 'http://127.0.0.1:8130/api/n9e/busi-group/1/alert-rule/1' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"id":1,"group_id":1,"name":"memory-usage-over-20-percent-v2",...同创建字段...}'
# 实测回显：{"err":"","request_id":"..."}

查看规则：

curl -s 'http://127.0.0.1:8130/api/n9e/alert-rule/1' -H "Authorization: Bearer $TOKEN"   # 完整对象
curl -s 'http://127.0.0.1:8130/api/n9e/alert-rule/1/pure' -H "Authorization: Bearer $TOKEN"  # 仅业务字段

3.5 告警事件

查询当前触发中事件：

curl -s 'http://127.0.0.1:8130/api/n9e/alert-cur-events/list?limit=5&p=1' -H "Authorization: Bearer $TOKEN"

实测回显（截断）：

{"dat":{"total":1,"list":[{"id":1,"rule_id":1,"rule_name":"memory-usage-over-20-percent-v2",
 "severity":2,"tags":"tags=[ident=categraf01 rulename=memory-usage-over-20-percent-v2] ...","trigger_time":1792471221}]}}

删除（批量）当前事件：

curl -s -X DELETE 'http://127.0.0.1:8130/api/n9e/alert-cur-events' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{"ids":[1]}'
# 实测回显：{"err":"","request_id":"..."}

查询历史事件：GET /api/n9e/alert-his-events/list?limit=5&p=1（参数同上，用于复盘已恢复/已关闭事件）。

3.6 告警屏蔽（静默）

创建屏蔽规则（tags 是 TagFilter 数组，op 支持 ==、=~、in、!=、!~、not in）：

NOW=$(date +%s)
curl -s -X POST 'http://127.0.0.1:8130/api/n9e/busi-group/1/alert-mutes' \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d "{\"cause\":\"test-mute\",\"note\":\"api test\",\"cate\":\"prometheus\",\"prod\":\"metric\",
       \"tags\":[{\"key\":\"ident\",\"op\":\"=\",\"value\":[\"categraf01\"]}],
       \"btime\":$NOW,\"etime\":$((NOW+3600)),
       \"enable_days_of_weeks\":[[\"1\",\"2\",\"3\",\"4\",\"5\",\"6\",\"0\"]],
       \"enable_stimes\":[\"00:00\"],\"enable_etimes\":[\"23:59\"]}"
# 实测回显：{"dat":1,"err":"","request_id":"..."}

查询：GET /api/n9e/busi-group/1/alert-mutes，实测返回对象含 "activated":1（生效中）。

⚠️ 实测踩坑：tags 写成对象（{"ident":["categraf01"]}）会报 cannot unmarshal object into Go value of type []models.TagFilter，必须是数组结构；btime/etime 必填（时间戳），否则报 etime <= btime。

3.7 匿名查询相关

config.toml 中 Center.AnonymousAccess.PromQuerier=false（默认）时，无 Token 调用 POST /api/n9e/ds-query 返回 401；改为 true 后同请求通过认证层。该开关与 API 明细见本专栏《配置参数详解》3.7 节。

四、categraf 采集器命令行

categraf --help 实测完整输出：

Usage of categraf:
  -configs string
        Specify configuration directory.(env:CATEGRAF_CONFIGS) (default "conf")
  -debug
        Is debug mode?
  -debug-level int
        debug level
  -inputs string
        e.g. cpu:mem:system
  -install
        Install categraf service
  -interval int
        Global interval(unit:Second)
  -remove
        Remove categraf service
  -start
        Start categraf service
  -status
        Show categraf service status
  -stop
        Stop categraf service
  -test
        Is test mode? print metrics to stdout
  -update
        Update categraf binary
  -update_url string
        new version for categraf to download
  -user
        Install categraf service with user mode
  -version
        Show version.

4.1 参数分组说明

分组	参数	说明
配置定位	`--configs`	配置目录，默认相对路径 `conf`；也支持环境变量 `CATEGRAF_CONFIGS`
调试	`--debug` / `--debug-level`	调试模式与级别（打印每个插件的采集明细与心跳详情）
插件过滤	`--inputs`	只启用指定插件，冒号分隔：`--inputs cpu:mem:system`；不传则启用配置目录下全部 `input.*`
采集间隔	`--interval`	全局采集间隔（秒），覆盖 config.toml 中的 interval
服务管理	`--install` / `--start` / `--stop` / `--status` / `--remove` / `--user`	注册/管理 systemd 服务（`--user` 以用户级服务安装），物理机部署推荐此方式
自更新	`--update` / `--update_url`	从指定 URL 下载新版本二进制完成自更新
版本	`--version`	打印版本与 commit

4.2 高频命令实测

--test 模式（单插件，打印指标不推送）——改配置后验证采集是否正常的首选手段：

categraf --test --inputs mem --configs /opt/categraf/conf

实测回显（截断）：

I! runner.binarydir: /opt/categraf
I! runner.hostname: ops
I! runner.fd_limits: (soft=65535, hard=65535)
I! runner.vm_limits: (soft=unlimited, hard=unlimited)
I! use input provider: []
I! prometheus scraping disabled!
I! agent starting
I! input: local.mem started
I! agent started
1792471834 12:50:34 mem_used_percent agent_hostname= 28.45046263169101
1792471834 12:50:34 mem_active agent_hostname= 7492976640
1792471834 12:50:34 mem_cached agent_hostname= 23318061056
...

⚠️ 实测踩坑：--configs 若传相对路径且当前目录不含 config.toml，会报 failed to init config: configuration file(...) not found 后直接退出，务必使用绝对路径或先 cd 到二进制所在目录。

--debug 模式：前台持续运行并输出每个插件每轮采集的详细日志，用于定位某插件不产出数据的问题；--debug --inputs <插件> 可聚焦单插件。

服务管理（systemd 环境）：

categraf --install     # 注册系统服务（含开机自启）
categraf --start       # 启动
categraf --status      # 查看运行状态
categraf --stop        # 停止
categraf --remove      # 注销服务

版本确认：

categraf --version
# 实测回显：v0.5.15-3232630235e3602477778a4df6c6eb7d99839f7a

五、命令速查表

需求	命令
看服务端版本	`n9e -version`
指定配置目录启动	`n9e -configs /opt/n9e/etc`
登录拿 Token	`curl -X POST .../api/n9e/auth/login -d '{"username":"root","password":"..."}'`
看采集器是否注册	`curl .../api/n9e/targets?gids=0`
看数据源列表	`curl -X POST .../api/n9e/datasource/list`
经 n9e 查时序库	`curl '.../api/n9e/proxy/1/api/v1/query?query=up'`
建告警规则	`curl -X POST .../api/n9e/busi-group/1/alert-rules -d '[{...}]'`
看触发中事件	`curl '.../api/n9e/alert-cur-events/list?limit=5&p=1'`
看历史事件	`curl '.../api/n9e/alert-his-events/list?limit=5&p=1'`
创建静默	`curl -X POST .../api/n9e/busi-group/1/alert-mutes -d '{...}'`
采集器试跑	`categraf --test --inputs mem --configs /opt/categraf/conf`
采集器调试	`categraf --debug --inputs <插件>`
注册系统服务	`categraf --install && categraf --start`

六、参考链接

官方 OpenAPI 文档：https://n9e.docs.io
GitHub 仓库：https://github.com/ccfos/nightingale
本专栏相关：《Nightingale 9.2.0 介绍与选型指南》、《Nightingale 9.2.0 Docker Compose 部署指南》、《Nightingale 9.2.0 配置参数详解》