蓝鲸配置平台 bk-cmdb 上交主机到空闲机模块:transfer_host_to_idlemodule 接口实战指南
蓝鲸配置平台 bk-cmdb 上交主机到空闲机模块:transfer_host_to_idlemodule 接口实战指南
导读
本文详解蓝鲸配置平台(BlueKing CMDB,bk-cmdb)中 上交主机到业务空闲机模块(transfer_host_to_idlemodule)这一 ESB 封装接口的完整调用方法:包括请求参数、请求/返回示例、返回字段语义,并深入其背后的源码实现——从 hostserver 的路由注册、coreservice 的事务化主机模块转移,到空闲机模块的查找与校验机制。读完本文,你将能直接调用该接口完成主机资源回收归位,并理解其与故障机、待回收、资源池等默认模块转移接口的差异与约束。
一、接口功能概述
transfer_host_to_idlemodule 是蓝鲸 ESB(企业服务总线)早期封装的 CMDB 组件接口之一,对应文档位于 docs/apidoc/esb-cc/zh_hans/transfer_host_to_idlemodule.md。根据目录 docs/apidoc/esb-cc/README.md 的说明,该目录是早期由 ESB 维护的组件文档,内容需保留且不再新增接口。
该接口的核心功能是:将指定的主机上交到指定业务的"空闲机"模块。在 CMDB 的拓扑模型中,每个业务(bk_biz_id)创建后都会自动生成若干默认模块,其中:
- 空闲机模块:存放已从业务模块中下架、待重新分配的主机(源码标记为
DefaultResModuleFlag = 1); - 故障机模块:存放故障待处理的主机(
DefaultFaultModuleFlag = 2); - 待回收模块:存放即将回收的主机(
DefaultRecycleModuleFlag = 3)。
这三个默认模块的定义见 src/common/definitions.go。本接口操作的对象就是上述"空闲机"默认模块。调用该接口需要具备 服务实例编辑权限。
二、请求参数详解
接口调用遵循 ESB 统一鉴权约定,公共参数({{ common_args_desc }} 模板占位符展开项)包含 bk_app_code(应用编码)、bk_app_secret(应用密钥)、bk_username(操作者用户名)、bk_token(用户登录票据)等。
2.1 接口参数
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| bk_supplier_account | string | 否 | 开发商账号 |
| bk_biz_id | int | 是 | 业务ID |
| bk_host_id | array | 是 | 主机ID |
参数说明:
- bk_biz_id(业务ID):必填,标识主机将要被转移到的目标业务。接口将在此业务下查找其空闲机模块;
- bk_host_id(主机ID):必填,数组类型,可一次批量上交多台主机;
- bk_supplier_account(开发商账号):可选,用于多租户/多开发商场景下标识数据归属;在源码中该账号会作为查询条件的 owner(
util.SetQueryOwner(cond, kit.SupplierAccount))注入所有数据库查询,见 src/source_controller/coreservice/core/host/transfer/transfer.go。
与后端数据结构对应:hostserver 服务解析请求时使用的 DefaultModuleHostConfigParams 结构体定义了 bk_biz_id、bk_host_id 与可选的 bk_module_id 三个 JSON 字段,见 src/common/metadata/common.go。
2.2 请求参数示例
{
"bk_app_code": "esb_test",
"bk_app_secret": "xxx",
"bk_username": "xxx",
"bk_token": "xxx",
"bk_supplier_account": "123456789",
"bk_biz_id": 1,
"bk_host_id": [
9,
10
]
}
上述示例表示:将业务 1(bk_biz_id=1)下的主机 9、主机 10 一次性上交到该业务的空闲机模块。若主机已存在于空闲机模块,则转移为幂等操作,不会产生额外影响。
三、返回结果与字段说明
3.1 返回结果示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"request_id": "e43da4ef221746868dc4c837d36f3807",
"data": null
}
成功时 result 为 true、code 为 0;失败时 code 为对应错误编码、message 携带错误信息。request_id 为请求链路 ID,可用于日志追踪与问题排查。
3.2 返回结果参数说明
| 名称 | 类型 | 描述 |
|---|---|---|
| result | bool | 请求成功与否。true:请求成功;false请求失败 |
| code | int | 错误编码。 0表示success,>0表示失败错误 |
| message | string | 请求失败返回的错误信息 |
| data | object | 请求返回的数据 |
| permission | object | 权限信息 |
| request_id | string | 请求链id |
值得注意的是,当请求失败时,data 字段可能返回部分成功的 ExceptionResult 列表(见下文源码分析),而 permission 字段在需要额外授权时携带权限申请信息。
四、接口背后的实现原理(源码级)
理解该接口的源码实现,有助于排查调用异常与评估批量操作的原子性边界。整个调用链路分为三层:
4.1 hostserver:路由注册与请求入口
在 hostserver 服务中,/hosts/modules/idle 路由被注册并绑定到 MoveHost2IdleModule 处理器,见 src/scene_server/host_server/service/service_initfunc.go:
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/idle",
Handler: s.MoveHost2IdleModule})
处理器实现见 src/scene_server/host_server/service/module.go,它直接透传给统一的默认模块转移逻辑 moveHostToDefaultModule(ctx, common.DefaultResModuleFlag),即以 DefaultResModuleFlag(1) 作为"空闲机"标志。
4.2 hostserver:空闲机模块查找与事务化转移
moveHostToDefaultModule 的核心流程(见 src/scene_server/host_server/service/module.go):
- 解码请求:将请求体解析为
DefaultModuleHostConfigParams,取bk_biz_id与bk_host_id; - 构造模块过滤器:以
bk_default=1(空闲机标志)加bk_biz_id组合条件查询该业务下的空闲机模块 ID(GetResourcePoolModuleID); - 记录审计日志:通过
auditlog.NewHostModuleLog捕获转移前的主机模块关系(WithPrevious),以便留存操作前后对比; - 开启事务:通过
CoreService().Txn().AutoRunTxn将"转移主机到空闲机模块 + 保存审计日志"两步包在同一个分布式事务中执行,保证原子性——转移失败时审计与转移均回滚; - 调用 coreservice 转移接口:构造
TransferHostToInnerModule(含业务 ID、主机 ID 数组、目标模块 ID),调用CoreService().Host().TransferToInnerModule完成实际转移。
若事务失败,接口返回 exceptionArr(ExceptionResult 列表)与错误信息,用于标识批量转移中各主机的具体失败情况。
4.3 coreservice:默认模块校验与关系转移
coreservice 是实际的转移执行者。其入口 TransferHostToInnerModule 在 src/source_controller/coreservice/service/host.go,路由为 POST /set/module/host/relation/inner/module(见 src/source_controller/coreservice/service/service_initfunc.go)。
转移管理器 TransferToInnerModule(见 src/source_controller/coreservice/core/host/transfer/manager.go)执行三步校验与操作:
- 校验目标模块为默认模块:调用
HasInnerModule(见 src/source_controller/coreservice/core/host/transfer/transfer.go)确认目标模块确属该业务的空闲机/故障机等内部默认模块;否则返回CCErrCoreServiceModuleNotDefaultModuleErr(目标模块不是默认模块错误); - 参数校验:
ValidParameter检查主机与模块的合法性; - 执行转移:
transfer.Transfer(kit, input.HostID, false)更新cc_ModuleHostConfig集合中的主机-模块关系,将主机从原模块摘除并挂到空闲机模块下。
当批量转移单台主机失败时,其余主机仍会继续处理,最终以 ExceptionResult 汇总反馈。因此调用方应针对 data 中的失败项做重试或补偿处理。
五、权限与同类接口对比
5.1 权限说明
文档明确标注该接口需要 服务实例编辑权限。ESB 网关在执行前会依据调用者的身份(bk_username 对应的平台账号体系)做权限校验;校验不通过时,返回结果的 permission 字段会携带权限申请所需的信息,供前端引导用户去权限中心申请授权。
5.2 与相邻接口的关系
仓库中同目录还提供了一组功能相近的 ESB 组件接口,调用时需按业务语义选择:
| 接口文档 | 功能 | 对应默认模块标志 |
|---|---|---|
| transfer_host_to_idlemodule.md | 上交主机到空闲机模块 | 空闲机(1) |
| transfer_host_to_faultmodule.md | 上交主机到故障机模块 | 故障机(2) |
| transfer_host_to_resourcemodule.md | 上交主机到资源池 | 资源池 |
| transfer_resourcehost_to_idlemodule.md | 资源池主机分配到空闲机模块 | 资源池→空闲机 |
| transfer_host_module.md | 主机跨模块转移(普通模块) | 非默认模块 |
它们共用 hostserver 中 moveHostToDefaultModule 的统一实现,仅传入不同的默认模块标志:MoveHost2FaultModule 传 DefaultFaultModuleFlag,MoveHost2RecycleModule 传 DefaultRecycleModuleFlag(见 src/scene_server/host_server/service/module.go)。而"上交主机到资源池"则走 MoveHostToResourcePool 的独立逻辑(见同文件 module.go)。
需要特别留意的是:空闲机、故障机、待回收三个默认模块之间存在互斥约束。coreservice 的 RemoveFromModule 实现中明确"如果主机属于空闲机模块或故障机模块,则移出操作失败"(见 src/source_controller/coreservice/core/host/transfer/manager.go),即默认模块中的主机不能通过普通移出模块操作被释放,只能通过默认模块间的转移或归还资源池来处理,从而保证主机生命周期状态机不被破坏。
六、常见使用场景与注意事项
6.1 典型场景
- 资源回收:业务下架、主机下线时,批量将主机从各业务模块上交到空闲机,等待重新分配或最终回收;
- 运维编排:配合 ESB 流程编排,在自动化作业中实现主机资源状态的统一归位;
- 批量转移:
bk_host_id支持数组,一次调用可处理多台主机,减少 API 调用次数。
6.2 注意事项
bk_biz_id必须为已存在的业务,且该业务下必须存在空闲机模块——这是 CMDB 初始化业务时的内置模块,若缺失会返回默认模块不存在的错误(CCErrCoreServiceDefaultModuleNotExist,见 transfer.go);- 主机必须已属于该业务(处于业务内的某个模块中),否则转移会被判定为参数非法;
- 该接口仅作用于业务内部,跨业务转移请使用
TransferHostAcrossBusiness(/hosts/modules/across/biz); - 接口调用需在 ESB 网关层配置应用鉴权(
bk_app_code/bk_app_secret)与用户身份(bk_username/bk_token),并确保调用账号具备目标业务的服务实例编辑权限。
七、小结
transfer_host_to_idlemodule 是蓝鲸配置平台主机生命周期管理中"资源归位"环节的关键接口。通过本文的请求参数示例与源码链路分析可以看出:该接口在 hostserver 层完成默认模块定位与审计、在 coreservice 层通过事务和默认模块校验完成主机-模块关系的原子更新,配合"空闲机—故障机—待回收—资源池"的默认模块体系,为 CMDB 的业务主机资源管理提供了清晰、可控、可审计的闭环能力。读者可结合仓库中的 ESB 组件文档目录 与 hostserver 服务实现 进一步研读相邻接口与扩展场景。