企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本篇技术指南围绕蓝鲸智云配置平台（bk-cmdb）的集群模板同步接口sync_set_template_to_set展开，详细介绍该接口的功能语义、请求/响应参数、权限要求、底层实现链路与异常处理方式。读完本文，你将掌握如何通过该接口将指定业务下的集群模板一次性同步到多个集群实例，并能从源码层面理解同步任务的派发与执行机制，为二次开发与运维排障提供依据。

功能概述与适用场景

集群模板（Set Template）是 bk-cmdb 中用于统一定义一类集群的"标准答案"：它包含了集群自身的属性约定以及一组服务模板（Service Template），而集群实例（Set）则是模板在实际拓扑中的落地。当模板内容发生变更（如调整集群属性、新增或删除服务模板所对应的模块）后，需要把模板的最新状态"推送"到已关联的集群实例上。

sync_set_template_to_set接口正是完成这一动作的入口：根据业务 ID（bk_biz_id）、集群模板 ID（set_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_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），其处理流程为：

1. 从 URL 路径参数中解析bk_biz_id与set_template_id，解析失败返回参数非法错误；
2. 将请求体解码为metadata.SyncSetTplToInstOption；
3. 校验bk_set_ids非空（len(option.SetIDs) == 0时返回CCErrCommParamsNeedSet）；
4. 在事务（AutoRunTxn）中调用业务逻辑层SetTemplateOperation().SyncSetTplToInst，任一集群同步失败则整体回滚；
5. 成功后返回data: null的响应。

第三步：逻辑层并发比对与任务派发

业务逻辑核心位于 src/scene_server/topo_server/logics/settemplate/settemplate.go：

1. 先通过 CoreService 查询该集群模板关联的全部服务模板（ListSetTplRelatedSvcTpl）；
2. 对bk_set_ids中的每个集群，使用带缓冲管道（容量为 10）的并发池执行DiffSetTplWithInst，逐个计算集群实例与模板之间的差异（SetDiff），包括集群自身属性差异与模块差异（模块新增ModuleDiffAdd、删除ModuleDiffRemove、变更ModuleDiffChanged、未变化ModuleDiffUnchanged）；
3. 将每个集群的模块差异封装为SyncModuleTask，通过DispatchTask4ModuleSync调用 TaskServer 创建异步同步任务（任务类型为common.SyncSetTaskFlag），由任务系统在后台执行模块的增删改。

也就是说，接口返回成功仅代表同步任务已成功创建并派发，具体的模块增删与属性覆盖由后台任务异步完成，这也是官方配套提供"同步状态查询"接口的原因（见后文）。

第四步：后台任务执行

任务真正落地时由 src/scene_server/topo_server/logics/settemplate/worker.go 中的BackendWorker处理：

• 先执行syncSetAttributes（worker.go#L235-L257）：读取集群模板的属性及属性值，从属性定义表（cc_ObjAttDes）映射出bk_property_id，再批量更新目标集群上对应属性的取值；
• 再根据模块差异类型逐一处理：删除模板中已不存在的模块、按服务模板信息创建新增模块、更新变更模块的名称等。

返回结果示例

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

返回结果参数说明

response

调用方应优先根据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，用于判断集群实例是否落后于模板版本。

使用注意事项

1. 权限要求：调用者需具备目标集群的编辑权限（ModelSet资源的UpdateMany动作），权限不足时接口会返回权限相关信息（permission字段非空）；
2. bk_set_ids必须非空：空列表不会触发同步，且被服务端显式拒绝；
3. 异步语义：接口返回只代表同步任务派发成功，最终效果应以同步状态查询接口的结果为准；
4. 事务与回滚：同步整体运行在事务中，单个集群的同步失败会导致整个请求返回失败，需结合message与request_id排查具体原因；
5. 批量规模：逻辑层使用并发池（管道容量 10）逐集群执行差异比对，一次同步过多集群时请关注 topo_server 与 task_server 的资源占用，并留意 API 网关默认限流策略（1 秒 100 个令牌）。

通过以上"参数 — 源码 — 闭环操作"的完整梳理，你可以放心地将sync_set_template_to_set用于集群模板的批量下发场景，并在出现问题时依据request_id沿 topo_server、task_server 日志快速定位同步任务的实际执行结果。

• 后端
• 企业应用
• 运维