后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本篇技术指南围绕蓝鲸智云配置平台bk-cmdb的集群模板同步接口sync_set_template_to_set展开详细介绍该接口的功能语义、请求/响应参数、权限要求、底层实现链路与异常处理方式。读完本文你将掌握如何通过该接口将指定业务下的集群模板一次性同步到多个集群实例并能从源码层面理解同步任务的派发与执行机制为二次开发与运维排障提供依据。功能概述与适用场景集群模板Set Template是 bk-cmdb 中用于统一定义一类集群的标准答案它包含了集群自身的属性约定以及一组服务模板Service Template而集群实例Set则是模板在实际拓扑中的落地。当模板内容发生变更如调整集群属性、新增或删除服务模板所对应的模块后需要把模板的最新状态推送到已关联的集群实例上。sync_set_template_to_set接口正是完成这一动作的入口根据业务 IDbk_biz_id、集群模板 IDset_template_id以及待同步集群 ID 列表bk_set_ids将指定业务下的集群模板同步到集群实例。调用该接口需要持有对应业务下集群的编辑权限权限点即集群编辑。该接口对应的完整请求路径为POST /api/v3/updatemany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/sync_to_instances该路径在 src/scene_server/topo_server/service/service_settemplate_initfunc.go 中注册属于 topo_server 的集群模板路由组同时也在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中作为 API 网关资源发布网关侧为其配置了默认限流bk-rate-limit默认 1 秒 100 个令牌等插件策略。请求参数说明接口请求由公共参数与接口参数两部分组成。公共参数common_args调用该接口时需在请求体中携带调用方身份信息包括bk_app_code应用编码、bk_app_secret应用密钥、bk_username操作人用户名、bk_token登录态令牌等。公共参数的具体字段以 docs/apidoc/cc/zh_hans 下的公共参数约定为准。接口参数字段类型必选描述bk_biz_idint是业务 IDset_template_idint是集群模板 IDbk_set_idsarray是待同步集群 ID 列表其中请求体bk_set_ids在源码中的结构化定义为// src/common/metadata/set_template_request.go#L272-L275 type SyncSetTplToInstOption struct { SetIDs []int64 field:bk_set_ids json:bk_set_ids bson:bk_set_ids mapstructure:bk_set_ids }从源码可以看到bk_set_ids为int64数组并且服务端在解析请求后会显式校验其非空若bk_set_ids为空列表接口会直接返回参数缺失类错误而不会进入同步流程见下文源码分析。请求参数示例以下是一个完整的请求示例参数含义业务 ID 为 20集群模板 ID 为 6待同步集群 ID 列表为[46]{ 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] }底层实现链路源码级理解接口参数后我们沿着源码追踪一次同步请求在 bk-cmdb 内部的完整流转这有助于你在调用失败或同步结果不符合预期时快速定位问题。第一步权限解析与鉴权请求进入 topo_server 后会先经过访问控制AC层的路由匹配与权限校验。在 src/ac/parser/settemplate.go 中该接口被注册为SyncSetTplToInstRegex正则匹配/api/v3/updatemany/topo/set_template/([0-9])/bk_biz_id/([0-9])/sync_to_instances/?资源类型为meta.ModelSet动作类型为meta.UpdateMany与文档所述集群编辑权限对应InstanceIDGetter会从请求体中反序列化bk_set_ids将其作为本次操作的实例 ID 集合参与鉴权即权限校验范围精确到具体集群实例。第二步服务端入口处理服务端处理函数为SyncSetTplToInst见 src/scene_server/topo_server/service/set_template.go其处理流程为从 URL 路径参数中解析bk_biz_id与set_template_id解析失败返回参数非法错误将请求体解码为metadata.SyncSetTplToInstOption校验bk_set_ids非空len(option.SetIDs) 0时返回CCErrCommParamsNeedSet在事务AutoRunTxn中调用业务逻辑层SetTemplateOperation().SyncSetTplToInst任一集群同步失败则整体回滚成功后返回data: null的响应。第三步逻辑层并发比对与任务派发业务逻辑核心位于 src/scene_server/topo_server/logics/settemplate/settemplate.go先通过 CoreService 查询该集群模板关联的全部服务模板ListSetTplRelatedSvcTpl对bk_set_ids中的每个集群使用带缓冲管道容量为 10的并发池执行DiffSetTplWithInst逐个计算集群实例与模板之间的差异SetDiff包括集群自身属性差异与模块差异模块新增ModuleDiffAdd、删除ModuleDiffRemove、变更ModuleDiffChanged、未变化ModuleDiffUnchanged将每个集群的模块差异封装为SyncModuleTask通过DispatchTask4ModuleSync调用 TaskServer 创建异步同步任务任务类型为common.SyncSetTaskFlag由任务系统在后台执行模块的增删改。也就是说接口返回成功仅代表同步任务已成功创建并派发具体的模块增删与属性覆盖由后台任务异步完成这也是官方配套提供同步状态查询接口的原因见后文。第四步后台任务执行任务真正落地时由 src/scene_server/topo_server/logics/settemplate/worker.go 中的BackendWorker处理先执行syncSetAttributesworker.go#L235-L257读取集群模板的属性及属性值从属性定义表cc_ObjAttDes映射出bk_property_id再批量更新目标集群上对应属性的取值再根据模块差异类型逐一处理删除模板中已不存在的模块、按服务模板信息创建新增模块、更新变更模块的名称等。返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: null }返回结果参数说明response字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息request_idstring请求链 ID用于日志追踪dataobject请求返回的数据本接口同步成功时返回 null调用方应优先根据result与code判断请求是否成功request_id可用于在 bk-cmdb 各服务日志中串联本次请求的全链路是排障的关键标识。配套接口同步前比对与同步后状态确认由于同步为异步执行建议在调用本接口前后配合以下接口形成完整的操作闭环均注册于 service_settemplate_initfunc.go同步前比对POST /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/diff_with_instances对应逻辑DiffSetTplWithInst先查看各集群与模板的差异清单SetDiff确认变更范围后再发起同步同步状态查询POST /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/instances_sync_status对应GetSetSyncDetails查询各集群实例是否已与模板一致同步历史与状态汇总POST /findmany/topo/set_template_sync_status/bk_biz_id/{bk_biz_id}与POST /findmany/topo/set_template_sync_history/bk_biz_id/{bk_biz_id}分别查看业务下集群模板的整体同步状态与历史同步记录未同步标记检查GET /findmany/topo/set_template/{set_template_id}/bk_biz_id/{bk_biz_id}/set_template_status用于判断集群实例是否落后于模板版本。使用注意事项权限要求调用者需具备目标集群的编辑权限ModelSet资源的UpdateMany动作权限不足时接口会返回权限相关信息permission字段非空bk_set_ids必须非空空列表不会触发同步且被服务端显式拒绝异步语义接口返回只代表同步任务派发成功最终效果应以同步状态查询接口的结果为准事务与回滚同步整体运行在事务中单个集群的同步失败会导致整个请求返回失败需结合message与request_id排查具体原因批量规模逻辑层使用并发池管道容量 10逐集群执行差异比对一次同步过多集群时请关注 topo_server 与 task_server 的资源占用并留意 API 网关默认限流策略1 秒 100 个令牌。通过以上参数 — 源码 — 闭环操作的完整梳理你可以放心地将sync_set_template_to_set用于集群模板的批量下发场景并在出现问题时依据request_id沿 topo_server、task_server 日志快速定位同步任务的实际执行结果。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 集群模板同步 API 实战指南sync_set_template_to_set 接口详解与源码级原理剖析蓝鲸 CMDB 集群模板同步 API 实战指南sync_set_template_to_set 接口详解与源码级原理剖析 导读 本文围绕蓝鲸智云配置平台Bl后端企业应用运维bk-cmdb 服务模板同步到服务实例接口sync_service_template_to_service_instance实战解析bk cmdb 服务模板同步到服务实例接口sync_service_template_to_service_instance实战解析 导读 服务模板Ser后端企业应用运维bk-cmdb 主机 Agent 解绑接口详解从 API 参数到源码实现bk cmdb 主机 Agent 解绑接口详解从 API 参数到源码实现 本指南以蓝鲸智云配置平台bk cmdb官方接口文档 unbind_host_ag后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
