蓝鲸配置平台 bk-cmdb 集群模板同步接口 sync_set_template_to_set 实战指南

原创2026-10-13 23:57:422,185 阅读
文章标签:后端企业应用微服务

蓝鲸配置平台 bk-cmdb 集群模板同步接口 sync_set_template_to_set 实战指南

集群模板(Set Template)是蓝鲸配置平台(bk-cmdb)中用于批量规范化集群与模块结构的关键机制:通过先定义"模板",再将其批量同步到多个集群实例,即可在业务内快速复制一致的拓扑结构。本文以 sync_set_template_to_set 接口为核心,完整讲解其请求参数、返回结构、ESB 网关映射方式,并结合 topo_server 源码深入剖析"模板—集群差异计算、模块增删改、异步任务执行"的底层实现链路,帮助开发者正确调用该接口并理解其内部工作原理。

接口概述:将集群模板批量同步到指定集群

sync_set_template_to_set 的语义是:根据业务 ID、集群模板 ID 以及待同步集群 ID 列表,将指定业务下的集群模板同步到这些集群上。调用成功后,目标集群的集群属性、以及集群下挂载的模块(Module)会按照集群模板及其关联的服务模板(Service Template)重新对齐——缺失的模块被创建、多余的模块被删除、名称不一致的模块被更新。

  • 接口形态:ESB 网关接口,通过蓝鲸 API Gateway 转发到 bk-cmdb 内部接口;
  • 调用权限:集群编辑权限;
  • 适用场景:当调整了集群模板(如新增、删除或重命名某个服务模板)后,需要把模板的最新结构批量下发到一批已经存在的集群上;
  • 注意事项:本接口的同步操作会改变目标集群的模块结构,属于变更型(operate)操作,建议先在测试业务上验证。

该接口与"模板实例化集群"是配套的两种路径:实例化集群时以集群模板为基础新建集群,而本接口则是把已有集群向模板"对齐"。两者在 topo_server 内部共享同一套差异计算与同步执行逻辑。

请求参数详解

接口请求体包含三类公共鉴权参数(bk_app_code、bk_app_secret、bk_username/bk_token)与三个业务参数,业务参数定义如下:

字段 类型 必选 描述
bk_biz_id int 是 业务 ID
set_template_id int 是 集群模板 ID
bk_set_ids array 是 待同步集群 ID 列表

三个参数均必填,缺一不可:

  • bk_biz_id:目标业务。集群模板与集群均属于同一业务,跨业务同步不被允许;
  • set_template_id:作为同步基准的集群模板。模板内部维护了模板属性(cc_SetTemplateAttr)及其关联的服务模板列表(cc_SetServiceTemplateRelation),是本次同步的"期望态"来源;
  • bk_set_ids:本次要执行同步的集群实例 ID 数组。该列表可以为空数组以外的任意长度,但空数组会导致请求直接失败——源码中 len(option.SetIDs) == 0 时会返回参数错误(CCErrCommParamsNeedSet,见 set_template.go)。

从代码结构看,参数在服务端被解析为结构体 SyncSetTplToInstOption,其中仅包含 bk_set_ids 一个字段,而 bk_biz_id 与 set_template_id 则从 URL 路径参数中解析(见 set_template_request.go)。

请求参数示例

{
    "bk_app_code": "esb_test",
    "bk_app_secret": "xxx",
    "bk_username": "xxx",
    "bk_token": "xxx",
    "bk_biz_id": 20,
    "set_template_id": 6,
    "bk_set_ids": [46]
}

对应含义:将业务 20 下的集群模板 6,同步到集群 46 上。示例中仅同步一个集群,实际使用时 bk_set_ids 可传入多个集群 ID。

使用 curl 直接调用内部接口

若不经过 ESB,也可以直接调用 bk-cmdb 的内部 HTTP 接口(需具备网关或内网访问条件):

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'X-Bk-Username: admin' \
  -d '{"bk_set_ids":[46]}' \
  'http://<cmdb-server>/api/v3/updatemany/topo/set_template/6/bk_biz_id/20/sync_to_instances'

该内部路由与 ESB 接口的映射关系记录在 cc.yaml:ESB 地址 /v2/cc/sync_set_template_to_set/(POST)转发至内部地址 /api/v3/updatemany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/sync_to_instances(POST)。路由注册代码位于 service_settemplate_initfunc.go。

返回结果与字段说明

返回结果示例

{
    "result": true,
    "code": 0,
    "message": "success",
    "permission": null,
    "request_id": "e43da4ef221746868dc4c837d36f3807",
    "data": null
}

返回字段说明

字段 类型 描述
result bool 请求是否成功。true:成功;false:失败
code int 错误编码。0 表示 success,>0 表示失败错误码
message string 请求失败时返回的错误信息
permission object 权限信息
request_id string 请求链 ID,用于全链路日志追踪
data object 请求返回的数据,本接口同步任务异步执行,成功时返回 null

需要特别说明的是:该接口的 data 为 null 不代表同步已完成。从实现看,接口只负责"派发同步任务",任务本身由 task_server 异步执行。若需确认同步结果,应配合使用同步状态与历史查询接口(见下文"配套接口")。

内部实现链路:从请求到异步任务派发

1. 入口 Handler 与事务包裹

内部接口 SyncSetTplToInst 是 topo_server 服务层入口,流程如下(见 set_template.go):

  1. 从 URL 路径解析 bk_biz_id、set_template_id,解析失败返回参数错误;
  2. 将请求体解码到 SyncSetTplToInstOption,并校验 bk_set_ids 非空;
  3. 在**数据库事务(AutoRunTxn)**内调用业务逻辑层 SetTemplateOperation().SyncSetTplToInst,事务失败则整体回滚;
  4. 事务成功即返回空 data 响应。

2. 业务逻辑:并发 Diff + 任务派发

逻辑层实现位于 settemplate.go,是理解本接口工作原理的关键:

  • 拉取模板关联的服务模板:调用 ListSetTplRelatedSvcTpl 获取集群模板下挂载的全部服务模板,作为期望态基准;
  • 并发计算差异:对 bk_set_ids 中的每个集群,启动 goroutine 并发执行 DiffSetTplWithInst(差异计算),通过带缓冲的 channel(容量 10)做并发限流,并收集每个集群的差异结果 SetDiff;
  • 逐集群派发同步任务:对每个集群,将其差异中的每个模块差异(ModuleDiffs)封装为 SyncModuleTask,调用 DispatchTask4ModuleSync 通过 task_server 的 Task().Create 创建异步同步任务(任务类型 SyncSetTaskFlag)。

3. 差异计算:Diff 规则

DiffSetTplWithInst(settemplate.go)会同时对比集群属性和模块结构;模块层面的对比由 DiffServiceTemplateWithModules(settemplate.go)完成,产生四类差异类型:

DiffType 触发条件 同步动作
add 服务模板存在于模板中,但集群下无对应模块 新建模块
remove 集群下存在模块,但其关联的服务模板不在模板中 删除模块
changed 模块关联的服务模板在模板中,但模块名称与模板名称不一致 更新模块名称
unchanged 模块名称与模板一致 无操作

同步动作的实际执行者 DoModuleSyncTask(见 worker.go)按 DiffType 分发:remove 删除模块,add 依据服务模板的名称、服务分类 ID 等信息新建模块,changed 仅更新模块名,unchanged 直接返回。同时每个集群在模块同步前都会先执行集群属性同步(syncSetAttributes),把模板属性(cc_SetTemplateAttr)中的值下发到集群实例上。

4. 数据模型支撑

与集群模板同步相关的核心存储表记录在 docs/db/set_template.md:

  • cc_SetTemplate:集群模板主表(模板 ID、名称、所属业务、创建/更新信息);
  • cc_SetTemplateAttr:集群模板的属性配置表(模板 ID → 属性 ID → 属性值),是集群属性同步的数据源;
  • cc_SetServiceTemplateRelation:集群模板与服务模板的关联表,决定了集群下应挂载哪些模块。

同步状态与配套接口

一次模板同步派发后,建议通过以下配套接口跟踪结果(均在 service_settemplate_initfunc.go 注册):

  • 查询单集群同步详情:POST /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/instances_sync_status(Handler:GetSetSyncDetails),返回指定集群与模板的最新差异状态;
  • 查询批量同步状态:POST /findmany/topo/set_template_sync_status/bk_biz_id/{bk_biz_id}(Handler:ListSetTemplateSyncStatus),返回业务下各集群模板是否"需要同步"的标记;
  • 查询同步历史:POST /findmany/topo/set_template_sync_history/bk_biz_id/{bk_biz_id}(Handler:ListSetTemplateSyncHistory),查看历史同步任务的执行情况;
  • 预检差异:POST /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/diff_with_instances(Handler:DiffSetTplWithInst),在执行同步前先预览将会产生哪些差异,是安全变更的重要前置步骤。

在 UI 侧,集群模板列表页会通过同步状态接口标记出"需要同步"的模板(见 src/ui/src/views/set-template/index.vue 中 need-sync 标记逻辑),与上述接口对应。差异预检与同步派发共用 DiffSetTplWithInst,保证"预览结果"与"实际执行结果"一致。

调用建议与注意事项

  1. 先预检再同步:批量变更前先调用 diff_with_instances 预览差异,确认新增/删除/修改的模块数量符合预期,避免误删模块;
  2. 区分同步范围:bk_set_ids 只作用于列出的集群,未列出的集群不受影响;若希望对模板下全部集群同步,需自行先查询模板关联集群列表再传入;
  3. 异步确认结果:接口返回 data: null 仅表示任务派发成功,请通过 instances_sync_status 或 set_template_sync_status 确认最终同步结果;
  4. 权限要求:调用方需具备目标业务的集群编辑权限,否则会被权限中心拦截并返回 permission 信息;
  5. 事务一致性:同步任务的派发过程在数据库事务内完成,若派发失败会自动回滚,不会产生"部分集群已派发"的中间状态;
  6. 并发上限:差异计算阶段采用容量为 10 的并发管道限流,大批量集群同步时会排队执行,属于预期行为。

综上,sync_set_template_to_set 是 bk-cmdb 集群模板体系中面向"存量集群对齐模板"的核心操作接口。理解其 Diff 计算、任务派发与异步执行机制后,开发者既可以安全地通过 ESB 网关调用,也能在需要时直接对接内部路由,实现集群结构的批量标准化治理。

登录后查看全文
bk-cmdb