蓝鲸 CMDB 查询业务内置模块（空闲机/故障机/待回收）接口全解析

• 后端
• 企业应用
• 运维

导读

本文围绕蓝鲸智云配置平台（bk-cmdb）的开放 APIget_biz_internal_module展开，它用于根据业务 ID（bk_biz_id）查询该业务下的空闲机、故障机和待回收模块，是 CMDB 业务拓扑中最基础也最高频的只读接口之一。读完本文，你将掌握该接口的请求参数与响应结构、default字段与三类内置模块的对应关系、接口背后的源码查询链路，以及它在主机资源流转场景中的典型用法。

接口概述

每个蓝鲸 CMDB 业务在创建时都会自动初始化一套"内置拓扑"：一个默认集群（默认集群名为空闲机池，源码常量DefaultResSetName定义于 src/common/definitions.go）下挂三个内置模块——空闲机（idle host）、故障机（fault host）、待回收（recycle host）。

这些内置模块承担着主机生命周期管理的关键职责：

• 新录入的主机先进入空闲机模块；
• 发生故障的主机可移入故障机模块；
• 需要回收或即将下线的主机进入待回收模块。

外部系统（如作业平台、监控平台、PaaS 平台等）在集成 CMDB 时，通常需要先通过本接口拿到这三个内置模块的实例 ID，再据此发起主机查询、转移等后续操作。get_biz_internal_module即为此设计：只返回内置的默认集群及其内置模块，不返回业务自定义的集群与模块。

在网关侧，该接口被定义为 APIGW 资源，路径为GET /api/v3/topo/internal/{bk_supplier_account}/{bk_biz_id}，对应配置见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml；同时它也被列为需要申请资源权限的网关资源之一（见 docs/apidoc/apigw/definition.yaml），调用方需先在蓝鲸 API 网关完成鉴权与权限申请。

请求说明

HTTP 方法

GET

请求路径

• 网关开放路径（对外）：/api/v3/topo/internal/{bk_supplier_account}/{bk_biz_id}
• CMDB 内部路径（对内）：/topo/internal/{owner_id}/{app_id}，其中owner_id即开发商账号（bk_supplier_account），app_id即业务 ID

输入参数

业务 ID 可通过查询业务列表接口（如search_business）获得。

调用示例

{ "bk_supplier_account": "0", "bk_biz_id": 2 }

响应示例与参数说明

响应示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": { "bk_set_id": 2, "bk_set_name": "空闲机池", "module": [ { "bk_module_id": 3, "bk_module_name": "idle host", "default": 1, "host_apply_enabled": false }, { "bk_module_id": 4, "bk_module_name": "fault host", "default": 2, "host_apply_enabled": false }, { "bk_module_id": 5, "bk_module_name": "recycle host", "default": 3, "host_apply_enabled": false } ] } }

说明：响应中的bk_module_name实际取值以部署环境为准（通常为"空闲机 / 故障机 / 待回收"），源码中内置模块的 key 分别对应SystemIdleModuleKey="idle"、SystemFaultModuleKey="fault"、SystemRecycleModuleKey="recycle"（见 src/common/definitions.go）。请以default字段而非模块名作为判定模块类型的依据，因为模块名在本地化部署下可能不同。

响应参数说明

data 说明

module 元素说明

default字段取值与模块类型的对应关系，可在 src/common/definitions.go 中确认：

其中"空闲机池"集群本身由DefaultResSetFlag = 1（src/common/definitions.go）标识，业务自定义集群的default字段则为NormalSetDefaultFlag = 0。

源码实现解析

1. 路由注册与处理器

该接口在拓扑服务（topo_server）中注册为两个 GET 路由（见 src/scene_server/topo_server/service/service_initfunc.go）：

utility.AddHandler(rest.Action{Verb: http.MethodGet, Path: "/topo/internal/{owner_id}/{app_id}", Handler: s.GetInternalModule}) utility.AddHandler(rest.Action{Verb: http.MethodGet, Path: "/topo/internal/{owner_id}/{app_id}/with_statistics", Handler: s.GetInternalModuleWithStatistics})

• /topo/internal/{owner_id}/{app_id}：标准版本，返回上文所述的 data 结构；
• /topo/internal/{owner_id}/{app_id}/with_statistics：扩展版本，额外返回每个内置模块的主机属性自动应用规则数量host_apply_rule_count，并按照模块名拼音首字母排序（见 src/scene_server/topo_server/service/inst_module.go）。

处理器实现（见 src/scene_server/topo_server/service/inst_module.go）要点如下：

func (s *Service) GetInternalModule(ctx *rest.Contexts) { bizID, err := strconv.ParseInt(ctx.Request.PathParameter("app_id"), 10, 64) if nil != err { ctx.RespAutoError(ctx.Kit.CCError.New(common.CCErrTopoAppSearchFailed, err.Error())) return } // 从备库读取，降低主库压力 ctx.SetReadPreference(common.SecondaryPreferredMode) _, result, err := s.Logics.ModuleOperation().GetInternalModule(ctx.Kit, bizID) ... }

值得注意的两点：

• 业务 ID 从路径参数app_id解析，若解析失败返回CCErrTopoAppSearchFailed错误码；
• 查询时设置了SecondaryPreferredMode 读偏好（见 src/common/metadata/common.go 中SecondaryPreferredMode的定义），即优先读 MongoDB 从库、从库不可用时才读主库，以分摊主库读压力。

2. 核心查询逻辑

真正的数据查询逻辑位于module.GetInternalModule（见 src/scene_server/topo_server/logics/inst/module.go），分两步进行：

第一步：查询默认集群（空闲机池）

querySet := &metadata.QueryCondition{ Condition: map[string]interface{}{ common.BKAppIDField: bizID, common.BKDefaultField: common.DefaultResSetFlag, // default == 1 }, Fields: []string{common.BKSetIDField, common.BKSetNameField}, } querySet.Page.Limit = 1

条件为bk_biz_id = bizID 且 default = 1，只取bk_set_id与bk_set_name两个字段，且分页限制为 1 条（一个业务理论上只有一个空闲机池）。

第二步：查询全部内置模块

queryModule := &metadata.QueryCondition{ Condition: map[string]interface{}{ common.BKAppIDField: bizID, common.BKDefaultField: map[string]interface{}{ common.BKDBNE: 0, // default != 0 }, }, Fields: []string{common.BKModuleIDField, common.BKModuleNameField, common.BKDefaultField, common.HostApplyEnabledField}, } queryModule.Page.Limit = common.BKNoLimit

条件为bk_biz_id = bizID 且 default != 0，即只筛选default取值大于 0 的模块（1 空闲机、2 故障机、3 待回收，以及可能的 4、5 类平台内置模块），通过BKDBNE（not equal）运算符排除用户创建的自定义模块（default = 0）。返回字段限定为模块 ID、模块名、default 值与 host_apply_enabled，从而保证响应体精简且不包含自定义字段。

第三步：组装结果

查询结果组装为metadata.InnterAppTopo结构（见 src/common/metadata/object.go）：

type InnerModule struct { ModuleID int64 `field:"bk_module_id" ...` ModuleName string `field:"bk_module_name" ...` Default int64 `field:"default" ...` HostApplyEnabled bool `field:"host_apply_enabled" ...` } type InnterAppTopo struct { SetID int64 `json:"bk_set_id" field:"bk_set_id"` SetName string `json:"bk_set_name" field:"bk_set_name"` Module []InnerModule `json:"module" field:"module"` }

响应外层由SearchInnterAppTopoResult承载（见 src/common/metadata/toposerver.go），包含统一的BaseResp（result/code/message/permission）。

3. 底层调用链

GetInternalModule最终通过 coreservice 的实例读取接口获取数据，调用链如下：

topo_server: GetInternalModule (service/inst_module.go) └─ module.GetInternalModule (logics/inst/module.go) └─ CoreService().Instance().ReadInstanceStruct (apimachinery/coreservice/instance/api.go#L219) └─ POST /read/model/{objID}/instances → coreservice 查询 MongoDB

其中ReadInstanceStruct是"按结构体返回实例数据"的通用读取方法（见 src/apimachinery/coreservice/instance/api.go），对bk_set（集群）与bk_module（模块）两种内置对象各调用一次。

4. 客户端封装

若在 CMDB 内部（Go 服务间）调用该接口，可使用拓扑服务的实例客户端封装instanceClient.GetInternalModule（见 src/apimachinery/toposerver/inst/common.go）：

func (t *instanceClient) GetInternalModule(ctx context.Context, ownerID, appID string, h http.Header) (resp *metadata.SearchInnterAppTopoResult, err error) { resp = new(metadata.SearchInnterAppTopoResult) subPath := "/topo/internal/%s/%s" err = t.client.Get(). WithContext(ctx). Body(nil). SubResourcef(subPath, ownerID, appID). WithHeaders(h). Do(). Into(resp) ... }

该接口定义于InstanceInterface（见 src/apimachinery/toposerver/inst/api.go），是各服务间复用此能力（如主机转移、权限校验、资源统计）的统一入口。

典型应用场景：主机资源流转

本接口最常见的业务场景是配合主机转移接口使用。以"转移主机至空闲机"为例，前端 Web 端在 src/ui/src/views/host-operation/index.vue 中的实现逻辑是：

1. 先调用本接口（前端 dispatchobjectMainLineModule/getInternalTopo）获取内置拓扑；
2. 从返回的module数组中按module.default === 1找到空闲机模块；
3. 判断目标主机的final_modules是否已处于空闲机模块，再决定是否发起转移。

同样地，资源转移菜单（src/ui/src/views/resource/transfer/transfer-menu.vue）在将主机转移到空闲机模块时，会携带default_internal_module参数调用host/transfer_with_auto_clear_service_instance/bk_biz_id/{bk_biz_id}接口：

await this.$http.post(`host/transfer_with_auto_clear_service_instance/bk_biz_id/${bizId}`, { bk_host_ids: HostStore.getSelected().map(data => data.host.bk_host_id), default_internal_module: internalModule.data.bk_inst_id, is_remove_from_all: true }, ...)

可见，内置模块 ID 是主机转移类接口的关键入参，而获取这些 ID 正是本接口的核心价值。外部系统若需实现"主机上云后自动归入空闲机""故障机盘点"等自动化流程，建议按如下顺序编排：

1. 调用get_biz_internal_module拿到三个内置模块的bk_module_id；
2. 调用主机查询接口按bk_module_id过滤主机；
3. 按需调用主机转移接口在空闲机/故障机/待回收模块间流转主机。

注意事项与最佳实践

1. 用default字段识别模块类型：不要依赖bk_module_name做硬编码匹配，模块名可能因部署与本地化而不同，default才是稳定的类型标识（1=空闲机、2=故障机、3=待回收）。
2. 本接口只返回内置模块：若需要业务下全部集群/模块（含自定义），应使用拓扑查询类接口（如search_biz_inst_topo），本接口不适用。
3. 权限与网关：通过蓝鲸 API 网关调用时，该资源默认isPublic: false、允许申请权限（allowApplyPermission: true），并配置了默认限流（每 1 秒 100 个令牌，见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml）。调用前需在网关后台申请get_biz_internal_module资源权限。
4. 读取一致性：接口内部从备库读取（SecondaryPreferredMode），在写入后立即查询的场景下可能存在短暂的读延迟，如需强一致读取，请根据业务容忍度做适当重试或使用主库查询类接口。
5. 错误处理：关注返回体中的result与code字段；code = 0表示成功，非 0 时请结合message排查（如业务 ID 不存在、无权限等）。

• 后端
• 企业应用
• 运维