螺旋式发现：从一个入口层层展开拓扑

概述

真实环境里，你要纳管的资产很少是"一张白纸"。更常见的起点是一个已知入口：一个 vCenter、一个 Kubernetes 集群、一台核心交换机。从这一个入口出发，平台能自动发现它背后的整张拓扑——虚拟机、宿主机、容器节点、邻居网络设备——并把这些新发现的对象自动变成配置齐全的采集点，而这些采集点又会发现更深一层的信息。

这种"发现一批 → 自动纳管 → 再发现更多 → 再纳管"的层层展开，就是本平台的螺旋式发现（spiral discovery）。它是 发现采集 与 CMDB 之间最省心的组合：你只手动配置一个入口，剩下的事交给模板和发现规则自动跑完。

一句话价值

从一个 vCenter 入口出发，几分钟后 CMDB 里自动长出"数据中心 → 集群 → ESXi → 虚拟机"的完整拓扑，每台虚拟机自动成为一个采集点并开始回传 OS / 硬件 / 已安装软件的详细信息——全程无需逐台配置。

前置阅读

本篇组合了多个模块。阅读前建议先熟悉：

• 发现采集总览 — 发现采集的整体概念
• 采集点 与 采集点详情 — 采集点是什么、怎么连设备
• 采集模板 — 模板的"一次定义、多处生效"
• 采集规则 — "找到设备后自动做什么"的自动纳管规则

为什么叫"螺旋"：两条链路，一个模板

理解螺旋式发现，关键是搞清每个"by API"类模板内部其实跑着两条独立的链路，它们协作但不重叠：

链路	对应的发现项	产出	落在哪
① CI 发现	*.ci.discovery	配置项（CI）+ 关联关系	CMDB（拓扑图谱）
② 采集点发现规则	*.vm.discovery / *.node.discovery / snmp.neighbor.discovery	子对象的标识（IP / UUID / OS 类型）	自动创建采集点 + 绑定模板

• CI 发现只管"把拓扑画进 CMDB"：发现到虚拟机、宿主机、交换机这些 CI，建立它们之间的从属 / 连接关系，但不创建采集点。
• 采集点发现规则只管“把子对象变成受管采集点”：它返回每个子对象的 IP / UUID 等标识，服务端据此按采集点原型（host prototype）自动创建采集点，并通过采集点原型上挂的模板链接，把对应的采集模板自动绑定上去。

新创建的采集点上线后，它绑定的模板往往自己也带着 CI 发现项——于是又触发一轮更深层的发现（OS、硬件、已安装软件……）。这就构成了螺旋的"第二圈"。

采集点原型是螺旋的"引擎"

"自动创建采集点 + 绑定模板"这件事，真正的驱动者是模板里的采集点原型。一个采集点原型预定义了"发现到什么样的子对象（按 OS、按 IP 规则）→ 建一个采集点 → 挂哪些模板"。你通常不需要手写采集点原型——平台预置模板里已经配好了。

场景一：VMware 拓扑发现与自动纳管

这是最典型的螺旋场景。目标：给一个 vCenter，自动拿到完整虚拟化拓扑，并把每台虚拟机纳管为采集点。

你要做的

只需手动配置一个顶层采集点：

1. 新建一个名为 vCenter 的采集点，关联预置模板 VMware by API，选择分组，先禁用该采集点
2. 配置连接鉴权信息（两处都要填）：
   • 在该采集点的宏中填写 vCenter 连接鉴权信息（见 各场景必填项速查中的 VMware 一行）。
   • 打开vCenter的采集点发现规则 VMware VM discovery 下的采集点原型，在每个原型各自的宏中填写该原型所需的连接鉴权信息（见 凭据配置中的"自动创建的采集点"部分）。
3. 启用采集点。

剩下的交给模板里的两条链路自动完成。

自动发生的事

• 第一圈：vmware.ci.discovery 自顶向下遍历 vCenter，把 vCenter、数据中心、集群、ESXi 宿主机、虚拟机、存储、资源池等 CI 及其从属关系写进 CMDB——你的虚拟化拓扑图就这样自动生成。
• 建采集点：vmware.vm.discovery 对每台虚拟机输出 IP / UUID / 客户机 OS 等标识，服务端按 OS 类型匹配采集点原型，为每台虚拟机自动创建一个采集点。
• 自动绑模板：Linux 虚拟机自动绑定 Linux and macOS by SSH；Windows 虚拟机自动绑定 Windows by WMI / Windows by PowerShell。
• 第二圈：这些新采集点上线后，它们绑定的 OS 模板自带 ssh.ci.discovery / wmi.ci.discovery，于是又把虚拟机内部的信息——硬件、磁盘、已安装软件 / 应用——作为 CI 写进 CMDB。

关于"资产清单（inventory）发现"

平台没有单独命名为 "inventory discovery" 的模板。你想要的"更深一层资产信息"（已安装软件、应用清单等），是由上面那些 OS 采集模板的 CI 发现规则承担的——在模板的 CI 发现规则里开启相应选项（如 收集已安装软件 / 收集应用）即可让螺旋第二圈带回更丰富的资产清单数据。

场景二：Kubernetes / ZStack / KVM —— 同一个套路

虚拟化 / 容器平台的发现机制同构：顶层入口挂对应模板，模板内部同样跑"CI 发现 + 采集点发现规则"两条链路。区别只在于为哪类子对象建采集点。

配置步骤与 VMware 场景一致：先创建顶层入口采集点并关联对应模板（先禁用），再按 各场景必填项速查与凭据配置在宏中填入连接鉴权信息，最后启用采集点。

顶层入口	关联模板	CI 发现写入 CMDB	自动建采集点的对象	自动绑定的模板
Kubernetes 集群	Kubernetes by API	集群 / Node / Namespace / Pod / Deployment / Service 等	每个 Node	Linux and macOS by SSH
ZStack 管理节点	ZStack by HTTP	KVM 宿主机 / 虚拟机 / 存储池	每台虚拟机	Linux and macOS by SSH / Windows by WMI / Windows by PowerShell
KVM 宿主机	KVM with libvirt by SSH	宿主机 / 虚拟机	每台虚拟机	Linux and macOS by SSH / Windows by WMI / Windows by PowerShell

注意 Kubernetes 的边界

Kubernetes 的发现规则只为 Node（节点）建采集点。Pod、Service、Container 这些对象会作为 CI 进入 CMDB（用于拓扑和关系），但不会各自变成采集点——它们数量庞大且生命周期短，逐个纳管既无必要也不现实。需要对节点做 SSH 采集时，平台已为每个 Node 自动建好了采集点。

场景三：网络邻居螺旋（CDP / LLDP / ARP / MAC）

网络侧的螺旋更纯粹：一台开了 SNMP 的核心交换机，就能带你发现整片网络。注意：螺旋只能经由开启了 SNMP 的设备继续向外扩散，创建新的采集点与 CI。

配置步骤：创建一个核心交换机的采集点，关联预置模板 Network Discovery by SNMP（先禁用），在宏中填入 SNMP 凭据（{$SNMP_COMMUNITY} 或 SNMPv3 参数，见 各场景必填项速查），最后启用采集点。自动创建的邻居采集点会复用顶层入口的 SNMP 凭据，无需逐个配置。

• 把预置模板 Network Discovery by SNMP 关联到一台已知交换机的采集点上。
• snmp.neighbor.discovery 通过 ARP 表、MAC 地址表（FDB）、CDP、LLDP 四种来源发现这台交换机的邻居设备。
• 每个有 IP 的邻居会按采集点原型自动创建采集点，并绑定回 Network Discovery by SNMP 模板本身。
• 因为新采集点挂的是同一个模板，下一轮它又会跑 snmp.neighbor.discovery 发现它的邻居——如此层层向外扩散，直到把整片可达网络收敛进来。

这是网络侧真正的"自递归"螺旋：模板绑回自身，靠周期性重扫一跳一跳地向外延伸。

UI 配置要点：每个场景必须填什么

螺旋能转起来，前提是顶层入口采集点配到位。采集点的配置表单分三块（详见 采集点详情 — 创建采集点）：

区块	填什么	在螺旋里的作用
概览	名称、接口（地址 / 端口 / 协议）、代理、关联模板、分组、状态	关联模板 = 选 by API 模板；分组 = 给这个入口归组
标签	（可选）键值对标签	标识 / 筛选
宏	模板声明所需的连接变量（每项一个独立宏，如 {$VMWARE.URL}、{$KUBE.API.TOKEN}）	填 API 地址、账号、密码 / Token 的地方——不同协议宏名不同，见下表

by API 场景：地址和凭据填在"宏"里，不是接口栏

对 VMware / Kubernetes / ZStack 这类 by API 入口，真正的 API 地址（如 vCenter SDK URL、k8s API Server）和账号 / Token 都填在宏区块；接口栏填管理端的地址和端口（用于判定采集点是否可达）。只有直连采集（Agent / SNMP / SSH / WMI）才把地址凭据主要落在接口。

各场景必填项速查

场景	关联模板（概览）	接口（概览）	必填宏（顶层入口·宏区块）	分组（概览）
VMware	VMware by API	vCenter 地址 · 443	{$VMWARE.URL} · {$VMWARE.USERNAME} · {$VMWARE.PASSWORD}	如"虚拟化"
Kubernetes	Kubernetes by API	API Server 地址 · 6443	{$KUBE.API.URL} · {$KUBE.API.TOKEN}（自签证书保持 {$KUBE.VERIFY_TLS} 为默认 false 即可，无需改）	如"容器"
ZStack	ZStack by HTTP	管理端地址 · 实际端口	{$KVM.API.URL} · {$KVM.API.USERNAME} · {$KVM.API.PASSWORD}	如"虚拟化"
KVM	KVM with libvirt by SSH	宿主机地址 · 22	{$SSH.USERNAME} · {$SSH.PASSWORD}（或公钥）· {$KVM.SUDO_PASSWORD}	如"虚拟化"
网络邻居	Network Discovery by SNMP	设备地址 · 161	{$SNMP_COMMUNITY}（SNMPv2c）或 SNMPv3 凭据	如"网络设备"

什么时候要改端口

设备用了非默认端口时，在接口里改：SSH 默认 22、SNMP 默认 161、HTTPS 默认 443、WinRM 默认 5985（HTTP）/ 5986（HTTPS）、k8s API 默认 6443。例如 SSH 改到 2222、SNMP 改到 1161，都要在接口端口里填。

凭据配置

螺旋里有两类采集点，凭据的位置不同——这是最容易配错的地方：

采集点	谁创建的	凭据配在哪
顶层入口采集点（vCenter / k8s / 核心交换机，只有 1 个）	你手动新建	该采集点自己的宏区块（即上表的必填宏）
自动创建的采集点（虚拟机 / 节点 / 邻居，一大批）	入口采集点所绑定模板里的采集点发现规则 + 采集点原型自动生成	该发现规则下的采集点原型——在原型上填 {$SSH.USERNAME} 等宏，每个自动建出的点都继承

你手动只建一个顶层入口，它的连接宏填在它自己的宏区块；而虚拟机 / 节点这些自动建出的采集点有成百上千个、不可能逐个手填，所以它们的凭据要配在采集点原型上——原型生成采集点时会把凭据一并带过去。例如 VMware 模板里"Linux 虚拟机"那个原型，填好 {$SSH.USERNAME} / {$SSH.PASSWORD}，之后每台自动纳管的 Linux 虚拟机都自带这套 SSH 凭据。

不要把凭据值写进模板

模板只声明 / 引用它需要哪些宏（如"Linux and macOS by SSH"模板引用了 {$SSH.USERNAME} / {$SSH.PASSWORD}），模板里固化的是采集项本身的配置（键值、OID、采集间隔）。凭据的值不要作为默认值写在模板里——那样一份模板一旦复用，凭据会跟着到处扩散，既不安全也不好维护。凭据值统一放在采集点原型（自动建点的场景）或顶层入口的宏里。

螺旋的边界与排查

理解以下边界，能避免对螺旋行为的误判：

• 没有"递归深度"参数。 螺旋的层层展开不是一段递归算法，而是模板层级组合 + 周期性重扫收敛：采集点原型天然只产一层（OS 模板不会再去发现 hypervisor），网络邻居靠每个发现周期逐步向外收敛。这意味着拓扑是渐进完整的，新接入的设备通常要等一两个发现周期才在 CMDB 里"长齐"。
• 没有 IP 的对象不会成为采集点。 虚拟机若没拿到 IP、邻居设备若无 IP，发现规则会过滤掉它们（建采集点必须要有 IP）。这些对象仍可能作为 CI 进入 CMDB，但不会自动纳管。
• 邻居关系是逐步收敛的。 邻居之间的 连接 关系要等邻居双方都成为 CI 后才建立；只发现了一侧时关系暂缺属正常现象，下个周期会补上。
• 凭据权限不足是静默失败的头号原因。 CI 发现往往"能连上但读不全"——例如 vCenter 账号缺数据中心权限，或 k8s token 缺 ClusterRole 绑定。症状是拓扑残缺或部分虚拟机没建采集点，排查先从入口采集点的宏（凭据）与账号权限入手。
• 别改动预置模板的发现项。 螺旋依赖模板里 CI 发现项与采集点发现规则项的配对关系；如需定制，优先用 采集规则 在自动纳管时追加动作（打标签、分组），而不是改预置模板本身。

小结

螺旋式发现的威力在于把"逐台手工纳管"变成"配一个入口、等拓扑自己长出来"。它的内核就两句话：

• CI 发现把拓扑画进 CMDB；
• 采集点发现规则 + 采集点原型把子对象自动变成采集点并绑模板，新采集点再触发更深一层的 CI 发现。

记住这个"两条链路、一个模板"的心智模型，VMware / Kubernetes / ZStack / KVM / 网络邻居这几类场景就都是同一个套路的变体。