后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读delete_inst是蓝鲸智云配置平台BlueKing CMDB即 bk-cmdb开放平台ESB/API 网关提供的「删除实例」接口用于按照模型 IDbk_obj_id与实例 IDbk_inst_id删除指定模型下的对象实例。本文以官方接口文档 docs/apidoc/cc/en/delete_inst.md中文版见 docs/apidoc/cc/zh_hans/delete_inst.md为主体结合 topo_server 与 coreservice 的真实源码、路由注册和单测用例讲清接口的适用范围、请求参数、鉴权细节、返回结构以及删除动作在底层是如何一步步执行的。读完本文你可以正确调用该接口完成自定义模型实例的删除并理解为什么不能删除业务/主机等内置模型实例为什么被关联的实例删不掉这类常见问题。一、接口能力与适用范围根据官方文档该接口的核心能力为指定模型 ID 和实例 ID删除指定模型下的对象实例操作需要具备模型实例删除权限。使用前必须明确其适用范围适用于自定义层级模型、通用模型普通自定义模型的实例。不适用于业务biz、集群set、模块module、主机host等内置模型实例。这一限制在源码中有直接体现。topo_server 的删除实例路由处理函数位于 src/scene_server/topo_server/service/inst.go其中首先执行// forbidden delete inner model instance with common api if common.IsInnerModel(objID) { blog.Errorf(delete %s instance with common delete api forbidden, rid: %s, objID, ctx.Kit.Rid) ctx.RespAutoError(ctx.Kit.CCError.CCError(common.CCErrCommForbiddenOperateInnerModelInstanceWithCommonAPI)) return }也就是说当bk_obj_id命中内置模型Inner Model时接口会直接拒绝并返回错误码CCErrCommForbiddenOperateInnerModelInstanceWithCommonAPI对应 src/common/errInfo.go 中的1199084。内置模型实例的删除应改用各模块专用接口例如主机删除走 host_server、业务删除走 topo_server 的业务专用逻辑如 src/scene_server/topo_server/logics/inst/del_business.go。二、请求参数详解2.1 公共参数该接口属于开放平台通用cc组件见 docs/apidoc/cc/cc.yaml调用时需携带 ESB 公共参数文档中以{{ common_args_desc }}占位符表示实际请求中至少包含字段类型必选说明bk_app_codestring是应用 ID接入 ESB 时分配的标识bk_app_secretstring是应用密钥用于鉴权签名bk_usernamestring是操作者用户名bk_tokenstring是登录态 Token2.2 接口参数字段类型必选描述bk_obj_idstring是模型 IDbk_inst_idint是实例 IDbk_biz_idint否业务 ID当删除的是自定义主线层级模型实例时必传2.3 自定义主线层级模型与 metadata 参数低版本注意文档特别强调当操作对象是自定义主线层级模型实例且系统启用了权限中心时对于 CMDB 小于 3.9 的版本还需要额外传入包含实例所在业务 ID 的metadata参数否则权限中心鉴权会失败。格式如下metadata: { label: { bk_biz_id: 64 } }其作用是让权限中心能够感知该实例所属业务从而正确匹配业务 ID 模型实例删除这条权限策略。从源码结构看bk-cmdb 的权限动作Action会按模型动态生成删除实例动作参见 src/ac/iam/adaptor.go 中的genDynamicDeleteAction其动作名称为模型名实例删除/模型ID delete instance因此权限判定依赖模型与业务上下文低版本通过 metadata 传递业务上下文是必须的。三、完整请求示例与返回说明3.1 请求参数示例文档给出的标准请求体如下删除模型test下bk_inst_id44的实例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_obj_id: test, bk_inst_id: 44 }3.2 返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: null }3.3 返回结果参数说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败时返回的错误信息permissionobject权限信息鉴权失败或需要申请权限时返回request_idstring请求链 ID用于全链路日志追踪dataobject请求返回的数据删除成功时为 null四、接口在开放平台中的路由与调用形态4.1 ESB 组件配置在 docs/apidoc/cc/cc.yaml 中该接口被注册为- path: /v2/cc/delete_inst/ name: delete_inst label: 删除实例 label_en: delete a inst suggest_method: POST api_type: operate comp_codename: generic.v2.cc.cc_component dest_path: /api/v3/delete/instance/object/{bk_obj_id}/inst/{bk_inst_id} dest_http_method: DELETE可见从用户侧调用/v2/cc/delete_inst/建议方法 POST请求体带参数ESB 组件会将其转发为对 bk-cmdb 内部的DELETE /api/v3/delete/instance/object/{bk_obj_id}/inst/{bk_inst_id}请求。4.2 内部路由注册在 src/scene_server/topo_server/service/service_business_initfunc.go 中可以看到 topo_server 实际注册了两条删除路由utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: /delete/instance/object/{bk_obj_id}/inst/{inst_id}, Handler: s.DeleteInst}) utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: /deletemany/instance/object/{bk_obj_id}, Handler: s.DeleteInsts})其中DeleteInst对应单实例删除即本文接口DeleteInsts对应批量删除对应 ESB 侧/v2/cc/batch_delete_inst/见 docs/apidoc/cc/cc.yaml。4.3 底层调用的关键链路DeleteInst处理函数src/scene_server/topo_server/service/inst.go会校验bk_obj_id非内置模型解析路径参数inst_id若等于batch则转交DeleteInsts批量处理否则按十进制解析为 int64通过AssociationOperation().IsMainlineObject判断该模型是否为自定义主线模型后续用于业务维度校验在AutoRunTxn事务中调用InstOperation().DeleteInstByInstID(kit, objID, []int64{instID}, true)执行删除。DeleteInstByInstIDsrc/scene_server/topo_server/logics/inst/inst.go构造条件{实例ID字段: {$in: [instID]}}通用模型额外带bk_obj_id然后进入commonInst.DeleteInst同文件 L626-L674。五、删除动作的内部执行流程源码级commonInst.DeleteInst是整个删除动作的编排核心其流程如下查询待删实例以实例 ID 条件查询实例若不存在则直接返回幂等。主机占用检查调用hasHost(kit, instRsp.Info, objectID, needCheckHost)若待删实例上仍挂有主机返回错误码CCErrTopoHasHostCheckFailed1101030见 src/common/errInfo.go。生成审计日志通过auditlog.NewInstanceAudit(...).GenerateAuditLog(kit, metadata.AuditDelete, objID, delInsts)为每个待删实例生成删除类型的审计日志定义见 src/common/auditlog/instance.go。执行物理删除调用c.deleteInsts(kit, delInsts, objID)其中先调用asst.CheckAssociations(kit, objID, delInstIDs)src/scene_server/topo_server/logics/inst/association.go检查实例的关联关系——查询该实例作为源或目标的所有实例关联若仍存在指向存在中实例的关联则删除失败避免产生脏数据再调用 coreservice 的CoreService().Instance().DeleteInstance(...)src/apimachinery/coreservice/instance/api.go。保存审计日志audit.SaveAuditLog若失败返回CCErrAuditSaveLogFailed。5.1 coreservice 中的数据层删除coreservice 侧的DeleteModelInstancesrc/source_controller/coreservice/core/instances/instance.go完成最终数据操作按供应商SupplierAccount补齐条件并设置实例表名common.GetInstTableName(objID, ...)与实例 ID 字段名先查询出符合条件的实例 ID 列表对每个实例调用dependent.IsInstAsstExist若仍存在实例关联返回错误码CCErrorInstHasAsst1101075见 src/common/errInfo.go调用mongodb.Client().Table(tableName).Delete(...)删除实例数据行对通用模型metadata.IsCommon(objID)同步删除实例映射instance mapping调用dependent.DeleteQuotedInst清理该实例被引用的引用关系见 src/source_controller/coreservice/core/instances/dependences.go。5.2 级联删除的对照同一文件还提供CascadeDeleteModelInstanceinstance.go L632-L680它在删除前调用dependent.DeleteInstAsst先清理实例关联实现级联删除语义。本文的普通delete_inst接口属于非级联删除因此文档中实例存在关联时删除会失败的行为是有意设计避免误删关联数据。六、单元测试验证coreservice 的实例管理单测直接验证了删除行为见 src/source_controller/coreservice/core/instances/instance_test.goTestSearchAndDeleteInstanceL117-L147先创建bk_switch模型实例查询命中后再调用DeleteModelInstance断言删除计数Count ! 0覆盖建—查—删完整闭环。TestCascadeDeleteInstanceL149-L170验证级联删除接口同样可以正常删除实例。这两条用例证明了删除逻辑在模型实例上的可用性也印证了普通删除与级联删除是两条独立的执行路径。七、API 网关APIGW侧定义除 ESB 组件外bk-cmdb 还以 OpenAPI 形式暴露该资源。在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中/api/v3/delete/instance/object/{bk_obj_id}/inst/{bk_inst_id}: delete: operationId: delete_inst description: 删除实例 ... backend: type: HTTP method: delete path: /api/v3/delete/instance/object/{bk_obj_id}/inst/{bk_inst_id} pluginConfigs: - type: bk-rate-limit yaml: | rates: __default: - period: 1 tokens: 100 authConfig: userVerifiedRequired: false可见网关侧对每个实例 ID 的删除请求默认做了限流默认每周期 100 个 token且该资源允许申请权限allowApplyPermission: true与文档中模型实例删除权限的要求相互呼应。八、常见错误与排查建议结合文档与源码调用失败时优先排查以下几点误删内置模型实例bk_obj_id为biz/set/module/host等内置模型时接口返回1199084禁止使用通用删除 API 操作内置模型实例。此时应改用对应模块的专用删除接口。实例 ID 解析失败bk_inst_id无法解析为整数时返回1199009CCErrCommParamsNeedInt或1199006CCErrCommParamsInvalid请确认传参为纯数字。实例仍被关联待删实例存在有效实例关联时删除会被CCErrorInstHasAsst1101075拦截若实例上挂有主机则返回CCErrTopoHasHostCheckFailed1101030。此时应先解除关联/主机绑定或改用级联删除能力。低版本权限中心鉴权失败CMDB 3.9 且启用了权限中心时删除自定义主线层级模型实例必须携带metadata.label.bk_biz_id。审计日志保存失败删除动作是先删除、后审计若审计日志落库失败整个操作会回滚并返回CCErrAuditSaveLogFailed需检查审计服务状态。总结delete_inst是 bk-cmdb 面向自定义模型实例的标准化删除入口ESB 侧由/v2/cc/delete_inst/暴露内部映射为 topo_server 的DELETE /api/v3/delete/instance/object/{bk_obj_id}/inst/{bk_inst_id}经事务包裹后由 coreservice 完成实例数据、实例映射与引用关系的清理。整个链路同时受内置模型禁止主机占用检查实例关联检查和权限中心鉴权四重约束理解这些约束是安全、正确地使用该接口的前提。如需进一步了解接口的批量形态可对照 batch_delete_inst 文档与DeleteInsts实现继续深入。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台bk-cmdb删除模型实例接口delete_inst实战指南蓝鲸配置平台bk cmdb删除模型实例接口delete_inst实战指南 本文面向蓝鲸智云配置平台BlueKing CMDB下称 bk cmdb的后端企业应用运维bk-cmdb 服务实例批量删除接口delete_service_instance实战指南参数、权限与底层实现bk cmdb 服务实例批量删除接口delete_service_instance实战指南参数、权限与底层实现 本指南以蓝鲸智云配置平台bk cmdb后端企业应用运维bk-cmdb 删除管控区域接口delete_cloud_area实战指南参数、响应与源码级删除流程解析bk cmdb 删除管控区域接口delete_cloud_area实战指南参数、响应与源码级删除流程解析 本指南基于蓝鲸智云配置平台bk cmdb开放后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考