bk-cmdb 上交主机到业务的空闲机模块:接口全解析与源码级实现

原创2026-10-13 09:19:421,676 阅读
文章标签:后端企业应用微服务

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,执行步骤如下:

  1. 解析请求体:将请求 JSON 反序列化为 DefaultModuleHostConfigParams;
  2. 构造模块过滤条件:按 defaultModuleFlag 设置 moduleFilter[common.BKDefaultField](即 bk_default),并追加 moduleFilter[common.BKAppIDField] = bizID(即 bk_biz_id),从而把查询范围锁定在指定业务下的空闲机模块:
    moduleFilter[common.BKDefaultField] = common.DefaultResModuleFlag // 空闲机
    moduleFilter[common.BKAppIDField] = bizID
    
  3. 定位目标模块:调用 s.Logic.GetResourcePoolModuleID(ctx.Kit, moduleFilter) 按过滤条件查出该业务空闲机模块的 moduleID;若查不到,返回 CCErrAddHostToModuleFailStr("module not found") 错误;
  4. 审计前置快照:auditlog.NewHostModuleLog(...).WithPrevious(ctx.Kit) 记录转移前的主机-模块关系,用于审计追溯;
  5. 事务内执行转移:在 AutoRunTxn 事务中构造 TransferHostToInnerModule{ApplicationID, HostID, ModuleID},调用 CoreService 的 Host().TransferToInnerModule 真正落库;转移成功后 audit.SaveAudit(ctx.Kit) 写入审计日志;
  6. 返回结果:事务成功则 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 业务生命周期管理中最高频的接口之一。通过本文的请求参数、调用示例与源码调用链对照,你可以精确掌握其行为语义:自动定位默认模块、事务化批量转移、逐台异常隔离、审计可追溯,以及网关侧的限流与权限配置。结合故障机、待回收、资源池等姊妹接口,即可构建完整的主机状态流转能力。

登录后查看全文
bk-cmdb