Nightingale 主机接入失败排查指南用 host-onboard-diagnose 沿着 5 段接入链路定位问题【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale导读本文围绕 Nightingale 内置 AI 技能host-onboard-diagnose展开它是专门用于排查categraf 已安装、进程也在跑但主机就是不显示在主机列表里或显示为 unknown、没有任何指标这类接入失败问题的诊断方案。读者读完将掌握接入链路 5 段拆解法、probe_target_onboard_status探针工具的使用、按likely_segment分支的决策表、段 5 的三条变体 PromQL 查询以及一套可直接落地的修复命令与自验证方法。一、适用范围什么时候进入这个技能host-onboard-diagnose是 Nightingale AI 助手内置技能之一完整定义见 SKILL.md技能声明位于其 frontmattername: host-onboard-diagnosemax_iterations: 18内置probe_target_onboard_status、list_targets、get_target_detail、query_prometheus、query_host_metrics_window、list_datasources等工具。应当进入本技能的典型提问我新装的 categraf 主机没有出现在 Nightingale 里agent 装好了也在运行但主机列表里看不到这台机器列表里这台主机的 OS / CPU / 版本全部是 unknown我用 Helm 部署了 3 台 categraf平台只看到 1 台我在 Windows 上装了 agent 但注册不上改完 hostname 后主机立刻消失了categraf 还在运行的情况不应进入本技能的典型场景避免与相邻技能混淆之前一直可见、最近才失联 → 走 host-health-diagnose两者是互斥的host-health 处理曾经接入过、现在失联而 host-onboard 处理从头到尾就没接入成功ident 重复 / 改名后残留清理 → 走host-ident-cleanup规划中想改告警规则 / 屏蔽 → 走creation/create-alert-rule排查某条告警为何没触发 → 走alert-rule-troubleshoot。一句话原则缺失主机 ≠ 单一原因。只看heartbeat.enable就让人改 categraf 配置是最高频的坑——很多用户改了依然看不到主机因为问题其实出在omit_hostname/ ident 计算 shell / TLS / token / edge redis / 多集群路由上。二、核心模型接入链路 5 段拆解技能的核心心智模型是把主机接入拆成一条 5 段流水线每一段卡住的表现都不一样[1] categraf 本地进程 进程在不在 / 配置对不对 / heartbeat.enable 是否开启 │ [2] heartbeat 上报 HTTP 能否连通 /v1/n9e/heartbeat网络 / TLS / BasicAuth │ [3] server / edge 接收 token / 版本兼容性 / hostname 重复校验 │ [4] target 表持久化 该 ident 是否在 DB 中meta 是否进了 redis │ [5] Redis 指标流 时序库能否为该 ident 找到样本从源码结构看这条链路与 Nightingale 的实际数据流完全对应categraf 通过心跳接口上报安装脚本 install-categraf.sh.tmpl 中明确出现了${N9E_HOST}/v1/n9e/heartbeat这一地址脚本会校验配置中是否写入了该 URL中心侧收到心跳后把心跳时间与 meta 写入 Rediskey 形如n9e_meta_update_time_ident、n9e_meta_ident见host_health.go中readRedisHostState的读取逻辑同时把 target 行持久化到 DBcategraf 采集到的指标则通过[[writers]]写入时序库。只盯其中一段就让人改配置是常见误区。正确姿势是先收集证据再逐段定位最后给出修复命令。三、第一步强制调用probe_target_onboard_status这是本技能唯一的诊断入口工具一次调用就能返回 5 段的足迹。它的实现位于 host_onboard.go其设计出发点源码注释是与get_target_realtime_status的关键差异在于容忍 target 不在 DB 中——这正是 onboard 场景的常态机器没出现时 target 行往往根本就没落库老式 host_health 系列工具直接返回target not found就断了。关键返回字段与段位的对应关系返回字段对应段位含义in_target_dbtarget.ostarget.agent_version段 3/4DB 是否落库、元数据是否完整in_redis_beatredis_meta.hostnameredis_meta.remote_addr段 4Redis 心跳与 meta 是否存在in_prom_target_uptarget_up_lastprom_metrics_hit段 5时序库能否查到该 identlikely_segmentlikely_causes聚合诊断工具层已预聚合不要绕过它自己反推从 defs.go 中ProbeTargetOnboardStatus的定义可以看到完整的参数约定ident必填datasource_id可选不传时按 chat-level params 兜底仍取不到则跳过段 5不报错段 5 不是 fatal 的。权限上target 在 DB 且有业务组归属时按组交集鉴权target 不在 DB 或未归组时允许查询——因为接入排障必须能查还没归过组的机器否则用户会被自己的权限锁死源码host_onboard.go中有明确注释说明这一点与host_health.go的严格鉴权形成对照。实现细节见probeTargetOnboardStatus段 3/4 通过models.TargetGet(deps.DBCtx, ident?, ident)查 DB段 4 复用readRedisHostState读心跳时间与 meta段 5 用target_up{ident...}与system_load1{ident...}两条 instant 查询后者是兜底心跳挂着但用户不上报 target_up 的奇异情形也能识别escapePromLabel负责转义 ident 中的反斜杠与双引号。最后diagnoseOnboardSegment按最深一段有证据的位置折叠出likely_segment——规则按段位倒序判断一旦命中就返回避免把DB 有 redis 也有误判成段 3 问题。如果用户没提供 ident先调用list_targets让用户挑选或按 OSunknown / agent_version 为空过滤出候选即未归组 / 半接入视图。四、决策表按likely_segment分支拿到likely_segment后按表行动likely_causes已附带高频根因列表likely_segment含义首选修复动作segment_1_or_2DB / redis / prom 三处都没有这台主机到目标主机上systemctl status categraf→journalctl -u categraf --since 5 min ago看是否报connection refused/x509/401segment_3target 存在但 OS / agent_version 为空检查 categraf 的config.toml[heartbeat] enabletrue且omit_hostnamefalse版本 ≥ v0.2.35segment_4target 已落库但 redis 里没数据检查 n9e/edge 是否配置了 redisedge 模式下看edge.toml的[Redis]n9e 与 n9e-edge 版本是否一致segment_5redis 有 beat 但 prom 查不到检查 categraf[[writers]]是否配置多集群部署下数据源是否正确ident 是否含()[]*等特殊字符ok接入正常用户仍坚持看不到引导刷新页面 / 检查业务组过滤 / 浏览器缓存从源码看diagnoseOnboardSegment的判定逻辑host_onboard.go与上表一一对应且每条likely_causes都带 issue 编号作为证据链。例如segment_5的高频根因包括[[writers]]未配置或 url 错、omit_hostnametrue导致 ident 标签丢失、多集群下 categraf 与 server 走的数据源不一致redis 注册到了中心但时序写到了别处、ident 含特殊字符导致 PromQL 精确匹配失败。五、段 5 专用三条变体 PromQL 查询当likely_segmentsegment_5时必须用query_prometheus依次执行以下 3 条查询确认是 ident 标签问题还是真的没数据# 1. 标准 ident 精确匹配最常见 target_up{identident} # 2. 模糊匹配ident 带 IP 前缀 / 别名时用 target_up{ident~.*host.*} # 3. 极端兜底是否落到了 instance 标签上snmp / 自定义 tag 场景 {instance~.*host.*}判定逻辑三条全空 → 数据流确实从未到达 prom回头查 categraf writers / TLS / n9e ingest 队列仅 (2) 或 (3) 有数据 →ident 标签问题特殊字符 /global_labels覆盖 / snmpagent_host_tag误用引导用户走host-ident-cleanup规划中或修复 categraf 配置。六、输出模板强约束最终回答必须使用 Markdown、使用用户语言且严格四段结构## Conclusion 一句话卡在段 Xxxxx或接入正常你看不到的原因是 yyy ## Onboarding Pipeline Evidence - 段 1/2categraf 本地/HTTP未采集 / 推断异常xxx - 段 3server 接收target in_dbtrue, osunknown, agent_version → 心跳元数据未持久化 - 段 4target 持久化 redistarget update_at2026-05-14 10:23:11 但 redis 无心跳 - 段 5Promtarget_up 无数据 / prom_metrics_hit0 ## Fix Commands 1. 在目标主机上执行 grep -E heartbeat|omit_hostname /etc/categraf/conf/config.toml 期望heartbeat 段 enabletrue, omit_hostnamefalse。若不满足修改后 systemctl restart categraf。 2. ... 3. ... ## Self-Verification Steps 给用户 1-2 条想确认是否修好可以这样验证的命令例如 - 重启 categraf 后 30 秒内回到平台刷新主机列表OS/CPU 字段应不再是 unknown - curl -s http://n9e:17000/api/n9e/self-metrics | grep ident从源码角度输出模板里的证据字段与probe_target_onboard_status的 JSON 返回结构一一对应onboardTargetSnap/onboardRedisSnap/onboardProbeResult三个结构体也就是说最终回答里每一个证据项都应是探针返回的真实字段值而不是看起来正常这种模糊表述。七、反模式明确禁止的行为❌ 不调用probe_target_onboard_status就直接让用户改heartbeat.enable。先收集证据——很多用户早就开了 heartbeat问题在 omit_hostname / TLS / 版本。❌ 看到in_target_dbfalse就说categraf 没装。必须综合 redis 段与段 1/2 的原因整体判断是网络问题还是进程问题——两者的推荐动作完全不同。❌ 段 3 卡住时只让改 heartbeat 而不提 omit_hostname / 版本这两者同样常见。❌ 段 5 卡住时不跑 3 条变体 PromQL 就让用户改 writers——ident 标签问题同样会卡在段 5。❌ 输出不给具体命令只说检查一下 categraf 配置。每条建议都必须是用户能直接复制粘贴执行的。八、各段已知故障模式速查段 1/2categraf 连不上 centerconnection refused、TLS 未知证书颁发机构、自签证书、BasicAuth 无效、ams token 不匹配、Helm 多节点只见 1 台、Windows 场景、Win2008 不支持。段 3heartbeat enablefalse、未知字段 /omit_hostnametrue、categraf 版本过低v6 要求 v0.2.35、identity 计算 shell 拿不到 IP、hostname 重复。段 4edge redis 为 nil、n9e 与 n9e-edge 版本不匹配、CenterApi 缺失、edge 部署下中心看不到主机、redismaxmemory-policy把心跳 key 驱逐。段 5带括号的 ident 在 dashboard 里查不到、host* bug、snmp ident 冲突、omit_hostnametrue导致 ident 标签丢失、多集群下数据源选错、写入队列满 499、global.labels覆盖。九、输出风格与收尾判断结论放第一段第一行不卖关子。证据必须给具体字段值不写看起来正常。修复命令必须可直接粘贴执行。用用户的语言回答中文用户用中文英文用户用英文。如果likely_segmentok但用户坚持看不到提示依次检查业务组过滤主机其实在只是被前端业务组隐藏、浏览器缓存、登录用户的可见业务组权限。十、与相邻技能的协作关系本技能与 host-health-diagnose 是接入与健康两大诊断方向的分工前者回答为什么从没接进来后者回答为什么现在失联了。两者的工具族也有明确分工——onboard 用probe_target_onboard_status容忍 target 不在 DBhealth 用get_target_realtime_statustarget 不存在直接报 not found。两个技能在 actions.go 中被统一注册为可用动作形成互补。结合 defs.go 中的工具定义与 host_onboard.go、host_health.go 的实现读者可以完整追溯诊断结论 → 证据字段 → 底层数据源DB / Redis / Prometheus的整条链路将这套方法论复用到自己的接入排障实践中。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Nightingale 主机接入失败排查指南：用 host-onboard-diagnose 沿着 5 段接入链路定位问题
Nightingale 主机接入失败排查指南用 host-onboard-diagnose 沿着 5 段接入链路定位问题【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale导读本文围绕 Nightingale 内置 AI 技能host-onboard-diagnose展开它是专门用于排查categraf 已安装、进程也在跑但主机就是不显示在主机列表里或显示为 unknown、没有任何指标这类接入失败问题的诊断方案。读者读完将掌握接入链路 5 段拆解法、probe_target_onboard_status探针工具的使用、按likely_segment分支的决策表、段 5 的三条变体 PromQL 查询以及一套可直接落地的修复命令与自验证方法。一、适用范围什么时候进入这个技能host-onboard-diagnose是 Nightingale AI 助手内置技能之一完整定义见 SKILL.md技能声明位于其 frontmattername: host-onboard-diagnosemax_iterations: 18内置probe_target_onboard_status、list_targets、get_target_detail、query_prometheus、query_host_metrics_window、list_datasources等工具。应当进入本技能的典型提问我新装的 categraf 主机没有出现在 Nightingale 里agent 装好了也在运行但主机列表里看不到这台机器列表里这台主机的 OS / CPU / 版本全部是 unknown我用 Helm 部署了 3 台 categraf平台只看到 1 台我在 Windows 上装了 agent 但注册不上改完 hostname 后主机立刻消失了categraf 还在运行的情况不应进入本技能的典型场景避免与相邻技能混淆之前一直可见、最近才失联 → 走 host-health-diagnose两者是互斥的host-health 处理曾经接入过、现在失联而 host-onboard 处理从头到尾就没接入成功ident 重复 / 改名后残留清理 → 走host-ident-cleanup规划中想改告警规则 / 屏蔽 → 走creation/create-alert-rule排查某条告警为何没触发 → 走alert-rule-troubleshoot。一句话原则缺失主机 ≠ 单一原因。只看heartbeat.enable就让人改 categraf 配置是最高频的坑——很多用户改了依然看不到主机因为问题其实出在omit_hostname/ ident 计算 shell / TLS / token / edge redis / 多集群路由上。二、核心模型接入链路 5 段拆解技能的核心心智模型是把主机接入拆成一条 5 段流水线每一段卡住的表现都不一样[1] categraf 本地进程 进程在不在 / 配置对不对 / heartbeat.enable 是否开启 │ [2] heartbeat 上报 HTTP 能否连通 /v1/n9e/heartbeat网络 / TLS / BasicAuth │ [3] server / edge 接收 token / 版本兼容性 / hostname 重复校验 │ [4] target 表持久化 该 ident 是否在 DB 中meta 是否进了 redis │ [5] Redis 指标流 时序库能否为该 ident 找到样本从源码结构看这条链路与 Nightingale 的实际数据流完全对应categraf 通过心跳接口上报安装脚本 install-categraf.sh.tmpl 中明确出现了${N9E_HOST}/v1/n9e/heartbeat这一地址脚本会校验配置中是否写入了该 URL中心侧收到心跳后把心跳时间与 meta 写入 Rediskey 形如n9e_meta_update_time_ident、n9e_meta_ident见host_health.go中readRedisHostState的读取逻辑同时把 target 行持久化到 DBcategraf 采集到的指标则通过[[writers]]写入时序库。只盯其中一段就让人改配置是常见误区。正确姿势是先收集证据再逐段定位最后给出修复命令。三、第一步强制调用probe_target_onboard_status这是本技能唯一的诊断入口工具一次调用就能返回 5 段的足迹。它的实现位于 host_onboard.go其设计出发点源码注释是与get_target_realtime_status的关键差异在于容忍 target 不在 DB 中——这正是 onboard 场景的常态机器没出现时 target 行往往根本就没落库老式 host_health 系列工具直接返回target not found就断了。关键返回字段与段位的对应关系返回字段对应段位含义in_target_dbtarget.ostarget.agent_version段 3/4DB 是否落库、元数据是否完整in_redis_beatredis_meta.hostnameredis_meta.remote_addr段 4Redis 心跳与 meta 是否存在in_prom_target_uptarget_up_lastprom_metrics_hit段 5时序库能否查到该 identlikely_segmentlikely_causes聚合诊断工具层已预聚合不要绕过它自己反推从 defs.go 中ProbeTargetOnboardStatus的定义可以看到完整的参数约定ident必填datasource_id可选不传时按 chat-level params 兜底仍取不到则跳过段 5不报错段 5 不是 fatal 的。权限上target 在 DB 且有业务组归属时按组交集鉴权target 不在 DB 或未归组时允许查询——因为接入排障必须能查还没归过组的机器否则用户会被自己的权限锁死源码host_onboard.go中有明确注释说明这一点与host_health.go的严格鉴权形成对照。实现细节见probeTargetOnboardStatus段 3/4 通过models.TargetGet(deps.DBCtx, ident?, ident)查 DB段 4 复用readRedisHostState读心跳时间与 meta段 5 用target_up{ident...}与system_load1{ident...}两条 instant 查询后者是兜底心跳挂着但用户不上报 target_up 的奇异情形也能识别escapePromLabel负责转义 ident 中的反斜杠与双引号。最后diagnoseOnboardSegment按最深一段有证据的位置折叠出likely_segment——规则按段位倒序判断一旦命中就返回避免把DB 有 redis 也有误判成段 3 问题。如果用户没提供 ident先调用list_targets让用户挑选或按 OSunknown / agent_version 为空过滤出候选即未归组 / 半接入视图。四、决策表按likely_segment分支拿到likely_segment后按表行动likely_causes已附带高频根因列表likely_segment含义首选修复动作segment_1_or_2DB / redis / prom 三处都没有这台主机到目标主机上systemctl status categraf→journalctl -u categraf --since 5 min ago看是否报connection refused/x509/401segment_3target 存在但 OS / agent_version 为空检查 categraf 的config.toml[heartbeat] enabletrue且omit_hostnamefalse版本 ≥ v0.2.35segment_4target 已落库但 redis 里没数据检查 n9e/edge 是否配置了 redisedge 模式下看edge.toml的[Redis]n9e 与 n9e-edge 版本是否一致segment_5redis 有 beat 但 prom 查不到检查 categraf[[writers]]是否配置多集群部署下数据源是否正确ident 是否含()[]*等特殊字符ok接入正常用户仍坚持看不到引导刷新页面 / 检查业务组过滤 / 浏览器缓存从源码看diagnoseOnboardSegment的判定逻辑host_onboard.go与上表一一对应且每条likely_causes都带 issue 编号作为证据链。例如segment_5的高频根因包括[[writers]]未配置或 url 错、omit_hostnametrue导致 ident 标签丢失、多集群下 categraf 与 server 走的数据源不一致redis 注册到了中心但时序写到了别处、ident 含特殊字符导致 PromQL 精确匹配失败。五、段 5 专用三条变体 PromQL 查询当likely_segmentsegment_5时必须用query_prometheus依次执行以下 3 条查询确认是 ident 标签问题还是真的没数据# 1. 标准 ident 精确匹配最常见 target_up{identident} # 2. 模糊匹配ident 带 IP 前缀 / 别名时用 target_up{ident~.*host.*} # 3. 极端兜底是否落到了 instance 标签上snmp / 自定义 tag 场景 {instance~.*host.*}判定逻辑三条全空 → 数据流确实从未到达 prom回头查 categraf writers / TLS / n9e ingest 队列仅 (2) 或 (3) 有数据 →ident 标签问题特殊字符 /global_labels覆盖 / snmpagent_host_tag误用引导用户走host-ident-cleanup规划中或修复 categraf 配置。六、输出模板强约束最终回答必须使用 Markdown、使用用户语言且严格四段结构## Conclusion 一句话卡在段 Xxxxx或接入正常你看不到的原因是 yyy ## Onboarding Pipeline Evidence - 段 1/2categraf 本地/HTTP未采集 / 推断异常xxx - 段 3server 接收target in_dbtrue, osunknown, agent_version → 心跳元数据未持久化 - 段 4target 持久化 redistarget update_at2026-05-14 10:23:11 但 redis 无心跳 - 段 5Promtarget_up 无数据 / prom_metrics_hit0 ## Fix Commands 1. 在目标主机上执行 grep -E heartbeat|omit_hostname /etc/categraf/conf/config.toml 期望heartbeat 段 enabletrue, omit_hostnamefalse。若不满足修改后 systemctl restart categraf。 2. ... 3. ... ## Self-Verification Steps 给用户 1-2 条想确认是否修好可以这样验证的命令例如 - 重启 categraf 后 30 秒内回到平台刷新主机列表OS/CPU 字段应不再是 unknown - curl -s http://n9e:17000/api/n9e/self-metrics | grep ident从源码角度输出模板里的证据字段与probe_target_onboard_status的 JSON 返回结构一一对应onboardTargetSnap/onboardRedisSnap/onboardProbeResult三个结构体也就是说最终回答里每一个证据项都应是探针返回的真实字段值而不是看起来正常这种模糊表述。七、反模式明确禁止的行为❌ 不调用probe_target_onboard_status就直接让用户改heartbeat.enable。先收集证据——很多用户早就开了 heartbeat问题在 omit_hostname / TLS / 版本。❌ 看到in_target_dbfalse就说categraf 没装。必须综合 redis 段与段 1/2 的原因整体判断是网络问题还是进程问题——两者的推荐动作完全不同。❌ 段 3 卡住时只让改 heartbeat 而不提 omit_hostname / 版本这两者同样常见。❌ 段 5 卡住时不跑 3 条变体 PromQL 就让用户改 writers——ident 标签问题同样会卡在段 5。❌ 输出不给具体命令只说检查一下 categraf 配置。每条建议都必须是用户能直接复制粘贴执行的。八、各段已知故障模式速查段 1/2categraf 连不上 centerconnection refused、TLS 未知证书颁发机构、自签证书、BasicAuth 无效、ams token 不匹配、Helm 多节点只见 1 台、Windows 场景、Win2008 不支持。段 3heartbeat enablefalse、未知字段 /omit_hostnametrue、categraf 版本过低v6 要求 v0.2.35、identity 计算 shell 拿不到 IP、hostname 重复。段 4edge redis 为 nil、n9e 与 n9e-edge 版本不匹配、CenterApi 缺失、edge 部署下中心看不到主机、redismaxmemory-policy把心跳 key 驱逐。段 5带括号的 ident 在 dashboard 里查不到、host* bug、snmp ident 冲突、omit_hostnametrue导致 ident 标签丢失、多集群下数据源选错、写入队列满 499、global.labels覆盖。九、输出风格与收尾判断结论放第一段第一行不卖关子。证据必须给具体字段值不写看起来正常。修复命令必须可直接粘贴执行。用用户的语言回答中文用户用中文英文用户用英文。如果likely_segmentok但用户坚持看不到提示依次检查业务组过滤主机其实在只是被前端业务组隐藏、浏览器缓存、登录用户的可见业务组权限。十、与相邻技能的协作关系本技能与 host-health-diagnose 是接入与健康两大诊断方向的分工前者回答为什么从没接进来后者回答为什么现在失联了。两者的工具族也有明确分工——onboard 用probe_target_onboard_status容忍 target 不在 DBhealth 用get_target_realtime_statustarget 不存在直接报 not found。两个技能在 actions.go 中被统一注册为可用动作形成互补。结合 defs.go 中的工具定义与 host_onboard.go、host_health.go 的实现读者可以完整追溯诊断结论 → 证据字段 → 底层数据源DB / Redis / Prometheus的整条链路将这套方法论复用到自己的接入排障实践中。【免费下载链接】nightingaleNightingale is to monitoring and alerting what Grafana is to visualization.项目地址: https://gitcode.com/GitHub_Trending/ni/nightingale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考