蓝鲸配置平台 bk-cmdb 上交主机到空闲机模块:transfer_host_to_idlemodule 接口实战指南

原创2026-10-14 18:25:091,942 阅读
文章标签:后端企业应用微服务

蓝鲸配置平台 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):

  1. 解码请求:将请求体解析为 DefaultModuleHostConfigParams,取 bk_biz_id 与 bk_host_id;
  2. 构造模块过滤器:以 bk_default=1(空闲机标志)加 bk_biz_id 组合条件查询该业务下的空闲机模块 ID(GetResourcePoolModuleID);
  3. 记录审计日志:通过 auditlog.NewHostModuleLog 捕获转移前的主机模块关系(WithPrevious),以便留存操作前后对比;
  4. 开启事务:通过 CoreService().Txn().AutoRunTxn 将"转移主机到空闲机模块 + 保存审计日志"两步包在同一个分布式事务中执行,保证原子性——转移失败时审计与转移均回滚;
  5. 调用 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)执行三步校验与操作:

  1. 校验目标模块为默认模块:调用 HasInnerModule(见 src/source_controller/coreservice/core/host/transfer/transfer.go)确认目标模块确属该业务的空闲机/故障机等内部默认模块;否则返回 CCErrCoreServiceModuleNotDefaultModuleErr(目标模块不是默认模块错误);
  2. 参数校验:ValidParameter 检查主机与模块的合法性;
  3. 执行转移: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 注意事项

  1. bk_biz_id 必须为已存在的业务,且该业务下必须存在空闲机模块——这是 CMDB 初始化业务时的内置模块,若缺失会返回默认模块不存在的错误(CCErrCoreServiceDefaultModuleNotExist,见 transfer.go);
  2. 主机必须已属于该业务(处于业务内的某个模块中),否则转移会被判定为参数非法;
  3. 该接口仅作用于业务内部,跨业务转移请使用 TransferHostAcrossBusiness(/hosts/modules/across/biz);
  4. 接口调用需在 ESB 网关层配置应用鉴权(bk_app_code/bk_app_secret)与用户身份(bk_username/bk_token),并确保调用账号具备目标业务的服务实例编辑权限。

七、小结

transfer_host_to_idlemodule 是蓝鲸配置平台主机生命周期管理中"资源归位"环节的关键接口。通过本文的请求参数示例与源码链路分析可以看出:该接口在 hostserver 层完成默认模块定位与审计、在 coreservice 层通过事务和默认模块校验完成主机-模块关系的原子更新,配合"空闲机—故障机—待回收—资源池"的默认模块体系,为 CMDB 的业务主机资源管理提供了清晰、可控、可审计的闭环能力。读者可结合仓库中的 ESB 组件文档目录 与 hostserver 服务实现 进一步研读相邻接口与扩展场景。

登录后查看全文
bk-cmdb