蓝鲸配置平台（bk-cmdb）四大核心使用场景：事件推送、模型管理、拓扑管理与主机管理实战解析-平芜编程栈

后端
企业应用
运维

【免费下载链接】bk-cmdb

蓝鲸智云配置平台(BlueKing CMDB)

项目地址：https://gitcode.com/gh_mirrors/bk/bk-cmdb

导读

本文基于蓝鲸智云配置平台（BlueKing CMDB，下称 bk-cmdb）官方文档使用场景展开，深入解析平台最核心的四个能力面：事件推送、模型管理、拓扑管理与主机管理。你将了解到：如何通过订阅与 Watch 两种机制实时获取配置数据变更事件；如何自定义企业架构与 IT 基础设施模型；如何用主线关联描述业务拓扑；以及如何通过集群/模块划分与云区域实现主机的精细管理和跨云管理。全文结合仓库源码（事件服务、CoreService、TopoServer、HostServer 等模块）给出实现层面的印证，方便你在实际集成与二次开发中直接落地。

一、事件推送：把 CMDB 的每一次变更实时送达

1.1 什么是事件推送

当 CMDB 管理的资源（主机、业务、集群、模块、进程、模型实例等）发生变化时，系统会产生相应的事件。这些事件可以由 CMDB 主动推送给订阅方，使下游系统（如监控、变更管理、自动化运维平台）无需轮询数据库即可感知配置变化。

从事件服务模块说明可以看到，bk-cmdb 提供了两种事件获取方式：

基于回调模式的事件订阅与推送（Subscribe / Push）；
基于 Watch 模式的事件监听（长轮询 / 游标回溯）。

两种方式对应的 API 文档分别位于订阅事件与监听资源变化事件（Watch）。

1.2 方式一：回调式事件订阅（Subscribe）

订阅模式的核心思想是：业务方先在 CMDB 登记一个回调地址，CMDB 在资源产生事件后主动向该地址推送。订阅接口的核心参数如下（字段定义来源于订阅事件 API）：

字段	类型	必选	描述
subscription_name	string	是	订阅的名字
system_name	string	是	订阅事件的系统的名字
callback_url	string	是	回调地址
confirm_mode	string	是	事件发送成功校验模式，可选`1-httpstatus`、`2-regular`
confirm_pattern	string	是	callback 的 httpstatus（如 200）或正则表达式
subscription_form	string	是	订阅的事件类型，多个以逗号分隔
timeout	int	是	发送事件超时时间

一个完整的订阅请求示例如下：

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "subscription_name": "mysubscribe", "system_name": "SystemName", "callback_url": "http://127.0.0.1:8080/callback", "confirm_mode": "httpstatus", "confirm_pattern": "200", "subscription_form": "hostcreate", "timeout": 10 }

订阅成功后返回subscription_id，后续可通过更新订阅事件、查询订阅信息与取消订阅事件对订阅进行生命周期管理。

参数说明：confirm_mode决定了推送方如何判断回调是否成功——httpstatus模式按 HTTP 状态码判断（如confirm_pattern填200），regular模式则用正则匹配回调响应体内容。subscription_form支持的事件类型（如hostcreate、hostupdate等）以逗号分隔组合，可同时订阅多种事件。

1.3 方式二：Watch 模式事件监听

Watch 模式面向需要主动拉取、支持断点续传的集成场景，v3.8 以上版本提供，其设计特性（见 resource_watch.md）：

在有限时间内（目前为 3 小时，勿依赖该时长）提供高可用的数据变更 watch 服务；
支持按游标（cursor）回溯事件，适用于异常数据回溯或系统变更后的数据补录；
支持按时间点回溯、按游标回溯、从当前时间点开始监听三种起始方式；
支持按事件类型（增/删/改）过滤，事件中携带全量数据；
支持主机与主机关系两类资源的事件 watch；
采用短长链设计：游标 watch 时若无新事件则保持连接，20 秒内有变更立即推回，既避免频繁请求又保证时效；
支持批量事件 watch 与按需定制返回字段。

Watch 接口的核心请求参数：

字段	类型	必选	描述
bk_event_types	array string	否	关注的事件类型：`create`/`update`/`delete`，空为全部
bk_fields	array string	看情况	返回的事件字段列表；监听 host 资源时必填，主机关系可置空
bk_start_from	Int64	否	监听起始时间（Unix 秒）；与 bk_cursor 二选一
bk_cursor	string	否	游标，代表开始或继续监听的事件地址
bk_resource	string	是	资源类型枚举：host、host_relation、biz、set、module、process、object_instance、mainline_instance、biz_set、biz_set_relation、plat、project 等
bk_supplier_account	string	是	开发商账号
bk_filter	object	否	过滤条件，其中`bk_sub_resource`仅在资源为 object_instance / mainline_instance 时指定要监听的模型`bk_obj_id`

监听主机资源的请求示例：

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_event_types": ["create", "update", "delete"], "bk_fields": ["bk_host_innerip", "bk_mac"], "bk_start_from": 12345678999, "bk_cursor": "MQ0yDTE1ODkyMDcyODENMQ01ZWI3ZWZjNTBiOTA5ZTYyMGFmYWQzZGY=", "bk_resource": "host" }

返回结构示例：

{ "result": true, "code": 0, "message": "success", "request_id": "e43da4ef221746868dc4c837d36f3807", "data": { "bk_watched": true, "bk_events": [ { "bk_cursor": "MQ0yDTE1ODkyMDcyODENMQ01ZWI3ZWZjNTBiOTA5ZTYyMGFmYWQzZGY=", "bk_resource": "host", "bk_event_type": "update", "bk_detail": { "bk_cpu": 2 } } ] } }

Watch 的使用流程（官方使用说明）：

确定起始方式：从某一时间开始 / 从当前时间开始 / 从指定游标开始，然后发起请求；
处理返回：若bk_watched为 true，bk_events为事件详情列表，取数组中最后一个事件的 cursor作为下一次请求的bk_cursor继续 watch；若为 false，则用bk_events中唯一事件的 cursor 继续下一次 watch。

注意：事件有 3 小时过期时间，过期后事件释放、游标失效，需改用时间点或当前时间重新开始监听。

1.4 源码视角：事件服务的实现链路

从事件服务模块说明可以看清整体架构：

拉取数据源：基于资源控制层 CoreService 的事件机制，将底层数据库数据事件同步到全局缓存队列；事件服务基于游标进行 watch 拉取；
写入事件队列：事件服务整体为主从模式（除主机身份事件处理逻辑外），Master 节点的事件源 watcher 将事件同步到事件队列；
分发到订阅者事件队列：事件处理协程按订阅者关系把事件分发到各订阅者队列，再由 Pusher 协程发送到目标订阅者。

服务入口在 watch.go：WatchEvent从 URL 路径解析resource参数，将请求体解码为watch.WatchEventOptions，随后调用缓存服务（CacheService）的WatchEvent完成事件查询。

事件参数的校验逻辑见 watch.go 的Validate方法，关键约束包括：

bk_event_types中的事件类型必须合法；
监听host、biz、set、module资源时必须携带 bk_fields；
bk_start_from与bk_cursor不能同时使用；
只有object_instance、mainline_instance、inst_asst、kube_workload资源允许携带bk_sub_resource。

事件类型常量定义在 types.go：create（新增）、update（更新）、delete（删除）、unknown。资源类型（CursorType）的完整枚举定义在 cursor.go，除上述文档列出的 host、biz 等之外，还包括host_identifier、inst_asst、kube_cluster、kube_node、kube_namespace、kube_workload、kube_pod等容器相关资源——这意味着容器集群、节点、命名空间、工作负载、Pod 的变更同样纳入事件体系，可作为容器场景集成的依据。

二、模型管理：自由定义企业的 IT 资源模型

2.1 模型管理的定位

通过模型管理，可以对企业架构、业务拓扑以及 IT 基础设施中的各种元素和元素的各种属性进行自定义，以满足生产管理需要。模型（Model / Object）是 bk-cmdb 一切数据组织的基石：主机是模型、业务是模型、集群和模块也是模型，甚至你可以自定义“交换机”“数据库实例”等任意新模型，并为它们补充属性字段。

2.2 模型体系中的几类核心操作

从源码看，模型管理覆盖的 API 分布在资源控制层（CoreService）与场景层（TopoServer）：

模型分类（Classification）管理：将模型按大类组织。CoreService 的 model.go 提供了CreateManyModelClassification、CreateOneModelClassification、SetOneModelClassification、SetManyModelClassification、UpdateModelClassification等接口，对应创建分类、查询分类、删除分类等 API；
模型（Object）管理：定义模型本身，即bk_obj_id、bk_obj_name、所属分类、图标等。TopoServer 的 object.go 中CreateObjectBatch支持批量创建模型，并且在写操作前会通过AuthManager.AuthorizeByObjectIDs做权限校验，随后在**事务（AutoRunTxn）**中完成属性与模型的创建，保证批量导入模型的数据一致性；
模型属性（Attribute）管理：为模型增删改属性字段，对应创建模型属性、查询模型属性、删除模型属性等 API；
模型实例（Instance）管理：定义好模型后即可创建实例数据，见本文第三部分的实例与拓扑接口。

从项目内置模型文档 built-in_model.md 可以看到，bk-cmdb 预置了业务、集群、模块、主机、进程、云区域等基础模型；在此基础上，用户可以按需扩展自定义模型与属性，从而把配置平台的抽象能力覆盖到企业内部任意资源对象上。

三、拓扑管理：用模型关系描绘业务拓扑

3.1 拓扑管理的定位

拓扑管理用于描述已定义的各种模型之间的关系。其中，**主线关联（Mainline）**用于描述业务的拓扑结构——最典型的即“业务 → 集群（Set）→ 模块（Module）”这样的层级主线，主机最终挂载在模块下，形成完整的业务视图。

3.2 主线模型与实例拓扑

CoreService 的 mainline.go 提供了两个核心能力：

SearchMainlineModelTopo：查询主线模型拓扑（以with_detail参数控制是否返回模型详情），对应 API 获取主线模型拓扑；
SearchMainlineInstanceTopo：按bk_biz_id查询某业务下的主线实例拓扑，即该业务下完整的层级实例树。

场景层 TopoServer 的 association.go 则负责主线对象的维护：CreateMainLineObject新增主线对象、DeleteMainLineObject删除主线对象、SearchMainLineObjectTopo查询主线拓扑；同时提供业务拓扑查询接口SearchBusinessTopo、SearchBusinessTopoWithStatistics（带主机数与服务实例数统计）以及GetTopoNodeHostAndSerInstCount等。

3.3 实例关联（Association）与实例操作

除了主线层级，模型之间还可以建立任意关联关系（如“服务器 → 部署 → 应用”）。实例层面的接口（见 inst.go）覆盖了完整 CRUD 链路：

创建/批量创建实例：CreateInst、CreateManyInstance、CreateInstsByImport（导入）；
删除/更新实例：DeleteInsts、DeleteInst、UpdateInsts、UpdateInst；
查询实例：SearchInsts、SearchObjectInstances、SearchInstTopo（查询实例拓扑）、SearchInstChildTopo（查询子拓扑节点）、SearchInstByObject、SearchInstByAssociation等；
关联查询：SearchInstAssociation、SearchInstAssociationUI、SearchInstAssociationWithOtherObject、SearchInstAndAssociationDetail。

关联类型（AssocKind）本身也是可管理的元数据：CreateAssociationType、UpdateAssociationType、DeleteAssociationType、SearchAssociationType（见 association.go）。对应 API 文档还包括新增实例关联、查询实例关联、查询对象关联等。

小结：主线关联解决“业务纵向分层”的问题，实例关联解决“模型横向互连”的问题，两者共同构成 bk-cmdb 拓扑管理的能力底座。

四、主机管理：从资源池到业务的精细运维

4.1 主机管理的定位

通过模型管理功能定义主机及其属性，再结合拓扑管理功能对已定义的主机进行管理。典型做法是：在某个业务下划分集群和模块，将主机与对应模块关联，以此明确该业务下主机的分布情况；主机与云区域（Cloud Area）关联后，还能方便地实现跨云管理。

4.2 主机生命周期与模块流转

HostServer 的 module.go 提供了主机在业务内外的完整流转能力，关键接口包括：

TransferHostModule：主机转入/转出指定模块；
MoveHost2IdleModule：主机移至空闲机模块；
MoveHost2FaultModule：主机移至故障机模块；
MoveHost2RecycleModule：主机移至待回收模块；
MoveHostToResourcePool：主机移回资源池；
AssignHostToApp：主机分配至业务；
TransferHostAcrossBusiness：主机跨业务转移；
GetHostModuleRelation、GetHostRelationsWithMainlineTopoInstance：查询主机与模块、主线拓扑实例的关系。

此外，host.go 中的DeleteHostBatchFromResourcePool支持从资源池批量删除主机；主机搜索能力见 findhost.go，支持按拓扑、条件等多维度查询主机。

4.3 云区域与跨云管理

云区域（Cloud Area，即plat）用于抽象不同网络/云环境。HostServer 的 cloudarea.go 提供：

FindManyCloudArea：批量查询云区域；
CreatePlatBatch/CreatePlat：批量或单个创建云区域；
UpdatePlat、DeletePlat：更新与删除云区域；
UpdateHostCloudAreaField：更新主机的云区域字段（即调整主机所属云区域，实现主机在云区域间迁移）；
FindCloudAreaHostCount：统计云区域下主机数量。

对应 API 见创建云区域、查询云区域、更新主机云区域字段、删除云区域等。

主机属性中的bk_cloud_id即主机所属云区域标识（见主机资源 watch 事件详情示例中 host 的bk_cloud_id字段）。通过将主机关联到不同云区域，再结合业务下的集群/模块划分，即可在同一配置平台内实现多数据中心、多云环境下的统一主机视图与跨云调度管理。

4.4 主机与事件体系的联动

主机管理的每一次变更（新增、转移模块、改云区域等）都会产生事件，可通过第一部分介绍的事件推送机制实时获取。例如订阅hostcreate、hostupdate事件，或使用bk_resource=host、host_relation的 Watch 接口监听主机详情与主机-模块关系的变化（host_relation事件的bk_detail包含bk_biz_id、bk_host_id、bk_module_id、bk_set_id、bk_supplier_account等关键关系字段）。这一联动使“配置变更 → 事件通知 → 下游自动响应”成为可能，正是 CMDB 作为运维数据中枢的核心价值。

五、场景落地建议

事件同步类系统（监控、审计、自动化）：优先使用 Watch 模式，借助游标实现断点续传与数据补录，注意 3 小时事件有效期与单次返回 200 条上限（勿依赖该数值）；对时效要求不高、希望 CMDB 主动送达的场景，使用订阅模式并配置好confirm_mode与confirm_pattern以保障推送可靠性；
自定义资源建模：先规划模型分类，再定义模型与属性，最后通过实例关联与主线拓扑组织数据，善用批量创建与事务保障（见 object.go 中的AutoRunTxn）保证大规模建模的一致性与导入效率；
主机治理：按“资源池 → 业务 → 集群 → 模块”的路径设计主机归属，配合空闲机/故障机/待回收等默认模块规范主机状态流转，借助云区域抽象多云环境，最终通过事件订阅把主机变更同步给下游平台。

以上四大使用场景彼此联动：模型与拓扑定义数据的“形”，主机管理维护数据的“实”，事件推送则让数据的每一次变化“活”起来——这也是 bk-cmdb 支撑复杂运维体系的基础能力框架。