企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

delete_module是蓝鲸配置平台（BlueKing CMDB，bk-cmdb）早期由 ESB 封装对外提供的 CMDB 组件接口之一，用于按业务（bk_biz_id）、集群（bk_set_id）、模块（bk_module_id）三个层级维度删除拓扑中的指定模块，调用方需具备业务拓扑删除权限。本文基于仓库内 docs/apidoc/esb-cc/en/delete_module.md 与 中文版文档 展开，并结合 topo_server 的模块删除实现源码，完整梳理接口请求参数、调用示例、响应结构、权限校验与底层删除链路，帮助开发者在对接 ESB 或自建自动化拓扑管理时正确、安全地使用该接口。

说明：docs/apidoc/esb-cc目录在仓库内被标注为“早期由 ESB 维护的组件文档，ESB 封装的 CMDB 组件，此文件夹里的内容需要保留，请勿往里面添加任何新的接口”，因此本文所讲接口属于历史 ESB 组件化封装的稳定契约，与当前 docs/apidoc/apigw 下的新一代 API 网关文档相互独立。

一、功能描述与适用场景

原文档对该接口的功能定义为：

Delete Module (Permission: Business Topology Deletion Permission) —— 删除模块（权限：业务拓扑删除权限）。

在 CMDB 的业务拓扑模型中，业务（Business）下包含集群（Set），集群下包含模块（Module）。模块是主机等资源实例挂载的最小组织单元，也是服务分类、服务模板、主机属性自动应用（host apply rule）等能力的承载对象。该接口用于在已明确业务、集群、模块三级定位的前提下，删除一个具体的模块实例。

典型的适用场景包括：

• 自动化运维平台通过 ESB 通道清理下线业务的空闲模块；
• 按模板驱动的批量拓扑初始化流程中，对废弃模块做回收清理；
• 在业务拓扑删除权限被授予后，由第三方系统完成合规的模块生命周期管理。

二、请求参数详解

2.1 公共参数（common_args）

原文档中公共参数部分以占位符{{ common_args_desc }}引用 ESB 通用参数说明。从文档自带请求示例可见，调用该接口时需要在请求体顶层携带 ESB 的通用认证与应用参数：

上述四个公共字段的具体取值规则由部署环境中的 ESB 组件决定，实际接入时应以所在环境的 ESB 网关配置为准。接口参数则继续沿用 CMDB 侧的参数契约。

2.2 接口参数（Interface Parameters）

原文档给出的接口参数如下：

各参数在请求体中以顶层字段形式携带，其中：

• bk_biz_id / bk_set_id / bk_module_id三者共同定位唯一模块实例，缺一不可。结合源码可知，它们最终会构成模块实例的完整查询条件：bk_biz_id、bk_set_id、bk_module_id（详见本文第四节）。
• bk_supplier_account为开发商账号，用于多开发商（多租户）场景下的账号区分，可选，默认场景可省略。

三、请求与响应示例

3.1 请求参数示例

原文档给出的请求体示例（Python 字典形式）为：

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_supplier_account": "123456789", "bk_biz_id": 1, "bk_set_id": 1, "bk_module_id": 1 }

即：删除业务 1、集群 1 下的模块 1。实际发起请求时，HTTP 方法为DELETE，请求体携带上述 JSON 参数（认证信息亦可按 ESB 通道约定放在 Header 中，取决于具体网关配置）。

3.2 响应示例

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

3.3 响应参数说明

该响应结构与 CMDB 全局统一响应格式一致：调用方应优先判断result与code，code == 0才表示操作成功；失败时结合message、request_id定位问题。

四、源码级实现原理：从 ESB 契约到底层删除链路

虽然delete_module是 ESB 组件化封装，但其在 CMDB 侧最终落地为 topo_server 的模块实例删除接口。以下依据仓库源码还原完整调用链。

4.1 路由注册：DELETE /module/{app_id}/{set_id}/{module_id}

在 src/scene_server/topo_server/service/service_initfunc.go 的initModule中注册了模块相关路由：

utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: "/module/{app_id}/{set_id}/{module_id}", Handler: s.DeleteModule})

即 ESB 侧将bk_biz_id、bk_set_id、bk_module_id映射到路径参数app_id、set_id、module_id，通过DELETE请求到达该处理器。与之对应的 apimachinery 客户端封装见 src/apimachinery/toposerver/inst/module.go，其子路径为/module/%d/%d/%d，分别填入 appID、setID、moduleID：

subPath := "/module/%d/%d/%d" err := t.client.Delete(). WithContext(ctx). Body(nil). SubResourcef(subPath, appID, setID, moduleID). ...

4.2 处理器校验链：模板约束与内置模块保护

核心处理器位于 src/scene_server/topo_server/service/inst_module.go，删除前依次执行以下校验：

1. 路径参数解析：分别从路径解析app_id、set_id、module_id，解析失败返回参数类型错误（CCErrCommParamsNeedInt）。
2. 集群模板约束检查：调用isSetInitializedByTemplate判断该集群是否由集群模板（set template）初始化。若由模板初始化，则禁止直接操作其下模块（错误码CCErrorTopoForbiddenOperateModuleOnSetInitializedByTemplate），只能通过集群模板同步流程维护——这与模板化拓扑的“声明式管理”设计一致。
3. 内置模块保护检查：调用checkIsBuiltInModule，通过统计default字段不在[0, 4]范围内的模块数量来判断是否内置模块。源码注释明确：当 default 值不等于 0 或 4 时为内置模块，其中 4 表示主机池中用户自定义创建的模块。若命中内置模块（如空闲机、故障机、待回收模块），返回错误码CCErrorTopoForbiddenDeleteOrUpdateBuiltInSetModule，禁止删除或修改。

4.3 事务化删除：模块实例 + 主机应用规则级联清理

校验通过后，删除动作被包裹在AutoRunTxn事务中执行，保证多步写操作的原子性：

txnErr := s.Engine.CoreAPI.CoreService().Txn().AutoRunTxn(ctx.Kit.Ctx, ctx.Kit.Header, func() error { err = s.Logics.ModuleOperation().DeleteModule(ctx.Kit, bizID, []int64{setID}, []int64{moduleID}) ... deleteRuleOption := metadata.DeleteHostApplyRuleOption{ ModuleIDs: []int64{moduleID}, } if err := s.Engine.CoreAPI.CoreService().HostApplyRule().DeleteHostApplyRule(ctx.Kit.Ctx, ctx.Kit.Header, bizID, deleteRuleOption); err != nil { ... } return nil })

事务内做两件事：

1. 删除模块实例：ModuleOperation().DeleteModule依据 src/scene_server/topo_server/logics/inst/module.go 组装删除条件——bk_biz_id精确匹配，bk_set_id、bk_module_id使用BKDBIN（IN 集合）匹配，最终调用DeleteInst删除模块对象实例（对象模型 ID 为common.BKInnerObjIDModule）。删除条件支持集合入参，意味着底层删除逻辑天然支持批量模块删除。
2. 级联清理主机应用规则：根据模块 ID 删除该模块关联的主机属性自动应用规则（host apply rule），避免删除模块后遗留悬空的规则数据。

事务提交成功后，处理器返回ctx.RespEntity(nil)，对应响应中data: null的语义；任一步失败则整个事务回滚并返回对应错误码。

五、使用注意事项与限制

结合原文档与源码实现，使用该接口时有以下几点需要特别留意：

• 权限前置：调用方必须具备业务拓扑删除权限，否则 ESB/CMDB 侧会返回权限相关错误（响应中的permission字段即用于承载权限信息）。
• 内置模块不可删除：空闲机、故障机等default字段为 1、2、3 的内置模块禁止删除；default == 4的主机池自定义模块属于用户可管理的范围。
• 模板化拓扑约束：由集群模板初始化生成的集群，其模块不允许直接删除，必须通过集群模板同步链路管理（源码中对应CCErrorTopoForbiddenOperateModuleOnSetInitializedByTemplate）。
• 删除具备级联副作用：删除模块的同时会清理其主机应用规则；若模块下仍挂载主机等资源实例，建议在删除前先完成主机转移（可参考同目录下的 transfer_host_module.md 等接口），避免拓扑数据异常。
• 历史文档契约：本接口属于docs/apidoc/esb-cc目录下的存量 ESB 组件文档，仓库明确要求不再向该目录新增接口；新接入方应优先参考 docs/apidoc/apigw 下的现行 API 文档。

六、常见失败场景与排查思路

七、总结

delete_module接口契约虽短小，但背后承载了蓝鲸 CMDB 对拓扑实例删除的一整套保护与级联机制：三级参数精确定位、内置模块与模板化集群双重防护、事务化删除保证数据一致性、主机应用规则级联清理。理解这些实现细节，能帮助开发者在使用该接口时规避常见误删与失败场景，也更利于理解 CMDB 拓扑实例管理（创建、查询、更新、删除）的统一设计范式。相关配套接口可继续阅读 create_module.md、search_module.md、update_module.md，以构建完整的模块生命周期管理视图。

• 后端
• 企业应用
• 运维