后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本指南以 bk-cmdb蓝鲸智云配置平台BlueKing CMDB开放 API 文档中的delete_set_template接口为线索完整讲解如何按业务 ID 与集群模板 ID 列表批量删除集群模板涵盖请求参数、请求示例、响应结构、权限要求并结合 topo_server / coreservice 源码剖析删除前的引用校验、关联数据清理与事务封装等底层机制。读完本文你可以直接基于该接口安全地上线集群模板回收能力也能看懂被引用集群模板为何删除失败。一、接口概述与适用场景delete_set_template用于删除指定业务下的一组集群模板调用依据是业务 ID 集群模板 ID 列表一次请求可批量删除多个集群模板。接口权限要求为集群模板删除权限Cluster template deletion permission即调用者需要具备对应业务的集群模板删除权限点。在 bk-cmdb 中集群模板Set Template是与服务模板-集群标准化管理配套的核心模型集群模板内聚合了若干服务模板业务侧再基于集群模板实例化出多个集群从而实现标准拓扑一键复制、批量扩容。因此删除集群模板属于高风险操作它直接影响后续基于该模板创建新集群的能力。该接口对应的英文 API 文档为 delete_set_template.md与其配套的还有创建接口 create_set_template.md、更新接口 update_set_template.md 与查询接口 list_set_template.md。二、请求参数请求方式为DELETE请求路径为/api/v3/deletemany/topo/set_template/bk_biz_id/{bk_biz_id}该路径在 bk_apigw_resources_bk-cmdb.yaml 中定义为operationId: delete_set_template中文描述删除集群模板。请求体参数如下名称类型必填说明bk_biz_idint是业务 IDset_template_idsarray是集群模板 ID 列表注意点bk_biz_id在 URL 路径中以{bk_biz_id}形式传递同时删除操作仍要求其存在且合法set_template_ids是数组允许一次传入多个集群模板 ID接口在 coreservice 层会以$in条件批量匹配见后文源码解析从 set_template_request.go 中可以看到DeleteSetTemplateOption结构体仅包含SetTemplateIDs一个字段json 标签为set_template_ids请求体中无需携带其他字段。请求示例{ bk_biz_id: 20, set_template_ids: [59] }该示例表示删除业务20下 ID 为59的集群模板。若需要批量删除将set_template_ids扩展为多个 ID 即可例如[59, 60, 61]。三、响应说明与响应示例响应示例{ result: true, code: 0, message: success, permission: null, data: null }响应参数名称类型说明resultbool请求是否成功。true 为成功false 为失败codeint错误码。0 表示成功大于 0 表示失败错误messagestring失败时返回的错误信息permissionobject权限信息dataobject请求返回的数据删除接口成功时 data 为 null从 topo_server 的 DeleteSetTemplate 实现 可以看到删除成功后ctx.RespEntity(nil)直接返回空 data这与响应示例中的data: null一致失败时则通过ctx.RespAutoError(txnErr)返回错误码与错误信息。四、删除的完整调用链与底层实现该接口虽由 open API 文档定义但实际处理链路为API 网关 → topo_server 的 DeleteSetTemplate 处理函数 → coreservice 的 setTemplateOperation.DeleteSetTemplate → MongoDB 数据操作。下面逐层剖析。4.1 topo_server 层参数解析与事务封装topo_server 的路由注册位于 service_settemplate_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: /deletemany/topo/set_template/bk_biz_id/{bk_biz_id}/, Handler: s.DeleteSetTemplate})对应的处理函数 DeleteSetTemplate 做了三件事从 URL 路径参数bk_biz_id解析业务 ID解析失败返回参数非法错误将请求体解码为metadata.DeleteSetTemplateOption通过s.Engine.CoreAPI.CoreService().Txn().AutoRunTxn(...)开启事务在事务内调用 coreservice 的SetTemplate().DeleteSetTemplate(ctx, header, bizID, option)完成实际删除。关键点删除操作被封装在事务中。事务内任一环节失败都会整体回滚避免模板删除成功但关联关系未清理等中间状态。4.2 coreservice 层引用校验 数据清理coreservice 侧的实际删除逻辑在 set_template.go 的DeleteSetTemplate方法共分三步第一步检查集群模板是否被集群引用reference checksetFilter : map[string]interface{}{ common.BKAppIDField: bizID, common.BKOwnerIDField: kit.SupplierAccount, common.BKSetTemplateIDField: map[string]interface{}{ common.BKDBIN: option.SetTemplateIDs, }, } referenceCount, err : mongodb.Client().Table(common.BKTableNameBaseSet).Find(setFilter).Count(kit.Ctx)该查询统计集群表BKTableNameBaseSet中set_template_id命中待删除 ID 列表的集群数量。只要referenceCount 0立即返回CCErrCommRemoveReferencedRecordForbidden被引用的记录禁止删除错误。这是该接口最核心的安全护栏被集群实例化的集群模板不允许删除必须先删除引用它的集群再删除模板。第二步删除集群模板本体setTplFilter : map[string]interface{}{ common.BKAppIDField: bizID, common.BKOwnerIDField: kit.SupplierAccount, common.BKFieldID: map[string]interface{}{ common.BKDBIN: option.SetTemplateIDs, }, } if err : mongodb.Client().Table(common.BKTableNameSetTemplate).Delete(kit.Ctx, setTplFilter); err ! nil { ... }在集群模板表BKTableNameSetTemplate中按bk_biz_id supplier_account id in set_template_ids批量删除。注意过滤条件中同时带上了bk_owner_id供应商账号即删除范围被限定在当前供应商账号与业务内防止越权删除其他供应商的数据。第三步清理模板与服务模板的关联关系relationFilter : map[string]interface{}{ common.BKAppIDField: bizID, common.BKOwnerIDField: kit.SupplierAccount, common.BKSetTemplateIDField: map[string]interface{}{ common.BKDBIN: option.SetTemplateIDs, }, } if err : mongodb.Client().Table(common.BKTableNameSetServiceTemplateRelation).Delete(kit.Ctx, relationFilter); err ! nil { ... }集群模板通过SetServiceTemplateRelation表与多个服务模板建立关联一张集群模板可关联多个服务模板。删除模板后若残留关联记录会在后续查询与同步时产生脏数据因此这里同步清理关系表BKTableNameSetServiceTemplateRelation保证删除的完整性。4.3 权限校验删除动作如何被识别bk-cmdb 的访问控制AC模块通过正则匹配请求路径来识别删除集群模板动作配置位于 settemplate.go{ Name: DeleteSetTemplateRegex, Description: 删除集群模板, Regex: regexp.MustCompile(^/api/v3/deletemany/topo/set_template/bk_biz_id/([0-9])/?$), HTTPMethod: http.MethodDelete, BizIDGetter: BizIDFromURLGetter, BizIndex: 6, ResourceType: meta.SetTemplate, ResourceAction: meta.Delete, ... }该配置将 DELETE 请求映射为SetTemplate资源上的Delete动作BizIDGetter从 URL 中提取bk_biz_id作为鉴权上下文InstanceIDGetter从请求体中解析set_template_ids作为资源实例 ID随后在权限系统中校验用户是否具备这些集群模板实例的删除权限。这就是文档中Permission: Cluster template deletion permission的落地实现。五、删除失败排查与典型场景结合源码逻辑以下场景会删除失败需要逐一排查集群模板被集群引用最常见任何bk_set实例的set_template_id指向该模板时coreservice 直接返回被引用记录禁止删除错误。测试用例 set_template_test.go 明确验证了这一点——先创建一个引用该模板的集群再尝试删除模板断言err不为 nil。正确操作顺序先删除引用集群再删除集群模板测试在删除集群后重新执行删除即成功见同一文件 L245-L252业务 ID 不存在或不属于当前供应商账号coreservice 的过滤条件严格绑定bk_biz_id与bk_owner_id匹配不到任何记录时按删除成功返回MongoDB 删除空集合不报错因此应先用查询接口确认模板真实存在且业务归属正确权限不足请求未通过 AC 层的资源删除动作鉴权时会返回权限相关错误需确认调用方已申请集群模板删除权限点。六、与其他集群模板接口的配合使用delete_set_template是集群模板生命周期管理的收尾环节建议与其配套接口协同使用形成完整闭环阶段接口说明创建create_set_template指定名称与服务模板 ID 列表创建集群模板见 create_set_template.md查询list_set_template按业务 ID 查询集群模板列表获取待删除的set_template_ids见 list_set_template.md更新update_set_template修改集群模板名称或服务模板关联见 update_set_template.md同步sync_set_template_to_set将模板变更同步到已实例化的集群见 sync_set_template_to_set.md删除delete_set_template删除未被引用的集群模板本文主题实战建议删除前先调用list_set_template确认目标模板 ID再通过查询集群模板关联的集群类接口确认无存量集群引用最后执行本接口若模板已被引用需要先完成集群的清理或解绑解除set_template_id引用再重试删除。七、小结delete_set_template是 bk-cmdb 开放 API 中面向集群模板回收的标准接口请求参数精简仅bk_biz_id与set_template_ids一次可批量删除底层由 topo_server 的事务封装与 coreservice 的引用校验 本体删除 关联清理三段式实现共同保障数据一致性并由 AC 模块按SetTemplate:Delete动作完成权限控制。使用本接口时只需牢记一条铁律先解引用再删除。相关可深入阅读的源码与文档包括接口文档delete_set_template.mdAPI 网关资源定义bk_apigw_resources_bk-cmdb.yamltopo_server 服务层service/set_template.gocoreservice 实现层core/settemplate/set_template.go请求体结构定义set_template_request.go权限动作配置ac/parser/settemplate.go集成测试用例test/topo_server/set_template_test.go赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 删除集群模板接口 delete_set_template 深度指南蓝鲸配置平台 bk cmdb 删除集群模板接口 delete_set_template 深度指南 导读 本文围绕蓝鲸智云配置平台BlueKing CMDB即后端企业应用运维蓝鲸配置平台bk-cmdbdelete_cloud_host_from_biz 接口详解从业务空闲机集群删除云主机蓝鲸配置平台bk cmdbdelete_cloud_host_from_biz 接口详解从业务空闲机集群删除云主机 导读 delete_cloud_hos后端企业应用运维蓝鲸智云配置平台bk-cmdb模型分类删除接口 delete_classification 实战指南蓝鲸智云配置平台bk cmdb模型分类删除接口 delete_classification 实战指南 delete_classification 是蓝鲸智云后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考