bk-cmdb 上交主机到业务的空闲机模块:接口全解析与源码级实现
bk-cmdb 上交主机到业务的空闲机模块:接口全解析与源码级实现
导读
本文以蓝鲸智云配置平台(bk-cmdb)的 Open API 文档 transfer_host_to_idlemodule.md 为核心,深入讲解"上交主机到业务空闲机模块"这一经典主机运维操作:包括接口协议、请求/响应参数、调用示例,并追踪其在 host_server 服务中的完整调用链(MoveHost2IdleModule → moveHostToDefaultModule → CoreService TransferToInnerModule),同时梳理事务、审计日志与网关限流等底层机制。读完本文,你将能正确调用该接口实现主机回收、业务清理,并理解空闲机/故障机/待回收等内置模块的设计原理。
一、接口概述与业务背景
在 bk-cmdb 的拓扑模型中,每个业务(biz)创建时会自动生成若干"内置模块",用于承载特殊状态的主机。依据 src/common/definitions.go 中的常量定义:
| 默认模块 Flag | 常量名 | 含义 |
|---|---|---|
| 1 | DefaultResModuleFlag |
空闲机模块(空闲机) |
| 2 | DefaultFaultModuleFlag |
故障机模块 |
| 3 | DefaultRecycleModuleFlag |
待回收/待删除模块 |
模块的 bk_default 字段即用于标识模块是否属于默认模块及所属类型(0 表示普通模块,>0 表示空闲机等内置模块)。"上交主机"即把某业务下的主机从当前所属模块移除并挂载到该业务的空闲机模块,常见于主机下线、资源回收、故障处理等场景。
二、接口协议
- 请求地址:
POST /api/v3/hosts/modules/idle - 所需权限:服务实例编辑权限
- 网关资源定义:见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml,其
operationId为transfer_host_to_idlemodule,isPublic: false、allowApplyPermission: true,即该资源默认不公开、允许第三方申请权限后调用;网关侧还挂载了bk-rate-limit限流插件(默认 100 tokens/秒,周期 1 秒)。
三、请求参数详解
| 参数名称 | 参数类型 | 必选 | 描述 |
|---|---|---|---|
bk_supplier_account |
string | 否 | 开发商账号(多租户场景下用于指定开发商,单开发商环境可省略) |
bk_biz_id |
int | 是 | 业务 ID |
bk_host_id |
array | 是 | 主机 ID 数组 |
在服务端,请求体被解析为 src/common/metadata/common.go 中的 DefaultModuleHostConfigParams 结构体:
type DefaultModuleHostConfigParams struct {
ApplicationID int64 `json:"bk_biz_id"`
HostIDs []int64 `json:"bk_host_id"`
ModuleID int64 `json:"bk_module_id"`
}
即 bk_biz_id 对应 ApplicationID,bk_host_id 对应 HostIDs。注意 bk_host_id 必须为非空数组;ModuleID 字段在本接口中无需传入——目标模块(空闲机)由系统根据 bk_default 标志自动定位。
四、调用示例
{
"bk_biz_id": 1,
"bk_host_id": [
9,
10
]
}
五、响应示例与响应参数说明
5.1 响应示例
{
"result": true,
"code": 0,
"message": "success",
"permission": null,
"data": null
}
5.2 响应参数说明
| 参数名称 | 参数类型 | 描述 |
|---|---|---|
result |
bool | 请求成功与否。true 表示请求成功;false 表示请求失败 |
code |
int | 错误编码。0 表示 success,>0 表示失败错误码 |
message |
string | 请求失败时返回的错误信息 |
data |
object | 请求返回的数据,本接口成功后为 null |
permission |
object | 权限信息,鉴权未通过时返回所需申请的权限 |
需要留意的是:批量上交时若部分主机转移失败,result 将为 false 且 data 中会携带 ExceptionResult 类型的异常明细(见下文源码解析),上层系统应针对异常列表做补偿处理。
六、源码级实现解析
6.1 路由注册
接口在 host_server 服务中注册,见 src/scene_server/host_server/service/service_initfunc.go:
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/idle",
Handler: s.MoveHost2IdleModule})
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/fault",
Handler: s.MoveHost2FaultModule})
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/recycle",
Handler: s.MoveHost2RecycleModule})
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/resource",
Handler: s.MoveHostToResourcePool})
可以看到 /hosts/modules/idle、/fault、/recycle、/resource 四个"上交/回收"接口在同一代码块中统一注册,语义高度一致。
6.2 处理器实现
处理器定义于 src/scene_server/host_server/service/module.go:
// MoveHost2IdleModule TODO
func (s *Service) MoveHost2IdleModule(ctx *rest.Contexts) {
s.moveHostToDefaultModule(ctx, common.DefaultResModuleFlag)
}
// MoveHost2FaultModule TODO
func (s *Service) MoveHost2FaultModule(ctx *rest.Contexts) {
s.moveHostToDefaultModule(ctx, common.DefaultFaultModuleFlag)
}
// MoveHost2RecycleModule TODO
func (s *Service) MoveHost2RecycleModule(ctx *rest.Contexts) {
s.moveHostToDefaultModule(ctx, common.DefaultRecycleModuleFlag)
}
三个"上交到默认模块"的操作共享同一核心方法 moveHostToDefaultModule,仅通过 defaultModuleFlag 区分目标模块类型,从源码结构上印证了空闲机(flag=1)、故障机(flag=2)、待回收(flag=3)三种内置模块的同构设计。
6.3 moveHostToDefaultModule 核心流程
核心方法位于 src/scene_server/host_server/service/module.go,执行步骤如下:
- 解析请求体:将请求 JSON 反序列化为
DefaultModuleHostConfigParams; - 构造模块过滤条件:按
defaultModuleFlag设置moduleFilter[common.BKDefaultField](即bk_default),并追加moduleFilter[common.BKAppIDField] = bizID(即bk_biz_id),从而把查询范围锁定在指定业务下的空闲机模块:moduleFilter[common.BKDefaultField] = common.DefaultResModuleFlag // 空闲机 moduleFilter[common.BKAppIDField] = bizID - 定位目标模块:调用
s.Logic.GetResourcePoolModuleID(ctx.Kit, moduleFilter)按过滤条件查出该业务空闲机模块的moduleID;若查不到,返回CCErrAddHostToModuleFailStr("module not found")错误; - 审计前置快照:
auditlog.NewHostModuleLog(...).WithPrevious(ctx.Kit)记录转移前的主机-模块关系,用于审计追溯; - 事务内执行转移:在
AutoRunTxn事务中构造TransferHostToInnerModule{ApplicationID, HostID, ModuleID},调用 CoreService 的Host().TransferToInnerModule真正落库;转移成功后audit.SaveAudit(ctx.Kit)写入审计日志; - 返回结果:事务成功则
ctx.RespEntity(nil)(对应响应示例中的data: null);任一主机转移失败则返回ExceptionResult数组与事务错误。
6.4 异常处理与结果返回
TransferToInnerModule 返回 []metadata.ExceptionResult,批量上交时逐台主机独立处理——某台主机失败不会阻断其他主机的转移,失败明细会随 ctx.RespEntityWithError(result, txnErr) 返回给调用方。这一设计保证了批量回收大批量主机时的容错性。
七、前端调用形态(Web 控制台)
bk-cmdb 自带的前端管理界面也复用该接口,见 src/ui/src/store/modules/api/host-relation.js:
/**
* 主机上交至业务的空闲机模块
*/
transferHostToIdleModule({ commit, state, dispatch }, { params, config }) {
return $http.post('hosts/modules/idle', params, config)
},
用户在"业务资源池/主机管理"界面点击"上交至空闲机"时,即通过该 action 发起 POST hosts/modules/idle 请求,参数为 { bk_biz_id, bk_host_id }。
八、相似接口与使用边界
- 上交至故障机模块:
POST /api/v3/hosts/modules/fault(对应文档 transfer_host_to_faultmodule.md); - 上交至待回收模块:
POST /api/v3/hosts/modules/recycle; - 上交至资源池:
POST /api/v3/hosts/modules/resource(将主机从业务中移出、交回全局资源池); - 整集群上交:
POST /api/v3/hosts/modules/idle/set,operationId为transfer_sethost_to_idlemodule,按bk_set_id/bk_module_id批量上交; - 资源池主机分配至空闲机:
POST /api/v3/hosts/modules/resource/idle(与本文"上交"方向相反,是"分配/下发"),其operationId为transfer_resourcehost_to_idlemodule,文档见 transfer_resourcehost_to_idlemodule.md。
使用边界提示:
- 本接口仅支持同一业务内的主机转移,跨业务转移需使用
TransferHostAcrossBusiness(路由/hosts/modules/across/biz); - 目标模块由系统按
bk_default自动定位,无需也不应传bk_module_id; - 若传入的主机 ID 不属于
bk_biz_id对应业务,转移会以ExceptionResult形式返回失败,而不是整体报错。
九、验证与测试
仓库中已内置针对该能力的集成测试用例,可参考 src/test/host_server/host_test.go 与 src/test/host_server/host_abnormal_test.go 中 MoveSetHost2IdleModule 相关断言,了解正常与异常(业务 ID 缺失、模块不存在、主机越权等)场景下的期望返回,便于在二次开发时对齐行为。
结语
"上交主机到空闲机模块"是 bk-cmdb 业务生命周期管理中最高频的接口之一。通过本文的请求参数、调用示例与源码调用链对照,你可以精确掌握其行为语义:自动定位默认模块、事务化批量转移、逐台异常隔离、审计可追溯,以及网关侧的限流与权限配置。结合故障机、待回收、资源池等姊妹接口,即可构建完整的主机状态流转能力。