bk-cmdb API 详解:transfer_resourcehost_to_idlemodule —— 资源池主机分配至业务空闲机模块

原创2026-10-14 17:36:352,276 阅读
文章标签:后端企业应用微服务

bk-cmdb API 详解:transfer_resourcehost_to_idlemodule —— 资源池主机分配至业务空闲机模块

本文以 bk-cmdb(蓝鲸智云配置平台)开放接口 transfer_resourcehost_to_idlemodule 为核心,完整讲解该接口的请求参数、响应结构、鉴权模型,并结合 host_server 的源码实现,深入剖析"资源池主机 → 业务空闲机模块"这一跨业务拓扑变更背后的完整调用链:路由注册、事务封装、前置校验、跨业务转移与审计日志落盘。读完后,你可以直接调用该接口完成主机分配,也能在排查 result: false 类失败时快速定位到具体校验分支。

接口概览

该接口用于将位于资源池(默认业务下的资源目录)中的主机,批量分配到指定业务的空闲机模块(idle module),是蓝鲸 CMDB 主机生命周期管理中"采购/纳管 → 资源池 → 业务"流转的关键一步。

项目 说明
API 名称 transfer_resourcehost_to_idlemodule
请求路径 POST /api/v3/hosts/modules/resource/idle
功能 分配资源池主机到业务的空闲机模块
所需权限 资源池主机分配到业务权限(Allocate Hosts from Host Pool to Business)

在 API 网关侧的资源定义见 bk_apigw_resources_bk-cmdb.yaml,其中可以看到该资源:

  • isPublic: false、allowApplyPermission: true,即非公开资源,调用方需在蓝鲸开放平台申请权限后才能调用;
  • 后端以 HTTP 方式转发到同样的路径 /api/v3/hosts/modules/resource/idle;
  • 配置了 bk-rate-limit 插件,默认档位 __default 为每 1 秒 100 个令牌(tokens: 100, period: 1),用于限流保护。

请求参数

公共参数

与其他 esb-cc 接口一致,请求需携带蓝鲸开放平台通用参数(common_args_desc 定义的一组公共字段),请求示例中体现如下:

  • bk_app_code:调用方应用 ID(App Code)
  • bk_app_secret:应用密钥
  • bk_username:操作人账号
  • bk_token:蓝鲸 SSO 访问令牌

接口参数

字段 类型 必填 说明
bk_supplier_account string 否 开发机账号
bk_biz_id int 是 目标业务 ID
bk_host_id array 是 待分配的主机 ID 数组(资源池中的主机)

这些字段在 host_server 的服务端解码到了 DefaultModuleHostConfigParams 结构体:

type DefaultModuleHostConfigParams struct {
	ApplicationID int64   `json:"bk_biz_id"`
	HostIDs       []int64 `json:"bk_host_id"`
	ModuleID      int64   `json:"bk_module_id"`
}

从源码结构看,该结构体被多个"默认模块转移"接口共用(bk_module_id 在本接口中不需要传入,目标模块固定为业务空闲机模块,由逻辑层自动解析)。

请求参数示例

{
    "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
    ]
}

响应参数

响应示例

{
    "result": true,
    "code": 0,
    "message": "success",
    "permission": null,
    "request_id": "e43da4ef221746868dc4c837d36f3807",
    "data": null
}

响应字段说明

字段 类型 说明
result bool 请求成功与否。true: 成功;false: 失败
code int 错误编码。0 表示 success,>0 表示失败错误
message string 请求失败返回的错误信息
data object 请求返回的数据(本接口成功时为 null)
permission object 权限信息(鉴权失败时给出)
request_id string 请求链路 ID,排查日志的关键线索

服务端实现链路

路由注册与 HTTP 处理

该接口的路由在 host_server 的 service_initfunc.go 中注册:

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/modules/resource/idle",
	Handler: s.AssignHostToApp})

对应的 HTTP 处理器 AssignHostToApp 做了三件事:

  1. 用 ctx.DecodeInto 将请求体解码为 metadata.DefaultModuleHostConfigParams,解码失败直接返回参数错误;
  2. 通过 CoreAPI.CoreService().Txn().AutoRunTxn 把核心逻辑包在一个存储事务中执行,保证跨业务转移(删旧关系 + 建新关系)的原子性;
  3. 事务失败时调用 ctx.RespEntityWithError(exceptionArr, txnErr) 返回业务错误码与异常主机列表,成功则 ctx.RespEntity(nil),即 data: null。

同文件中还可以看到一组"默认模块"姊妹接口,它们复用同一套参数结构:

  • POST /hosts/modules/idle → MoveHost2IdleModule(业务内主机上交空闲机)
  • POST /hosts/modules/fault → MoveHost2FaultModule(上交故障机)
  • POST /hosts/modules/recycle → MoveHost2RecycleModule(上交回收站)
  • POST /hosts/modules/resource → MoveHostToResourcePool(业务主机移回资源池,本接口的反向操作)

核心业务逻辑:校验与跨业务转移

真正的业务规则在 Logics.AssignHostToApp,执行顺序为:

  1. 校验目标业务存在:按 bk_biz_id 查询业务详情(字段 bk_biz_id,bk_app_name),查不到时返回 CCErrCommNotFound。
  2. 确定资源池宿主业务:通过 GetDefaultAppID 获取资源池所属的默认业务 ID(ownerAppID)。若目标业务就是资源池本身(ownerAppID == conf.ApplicationID),则直接返回成功,不做任何转移。
  3. 校验主机确实在资源池资源目录中:在资源池业务下查询 bk_is_default 属于资源池标记(DefaultResModuleFlag)或资源自定义模块(DefaultResSelfDefinedModuleFlag)的模块,再用 notExistAppModuleHost 核对传入主机是否都挂在这些模块下。若有主机不满足,接口会把这些主机的 bk_host_id 转换为内网 IP(convertHostIDToHostIP 注释明确该容错方法"出现任何错误都会被忽略")并返回 CCErrHostModuleConfigNotMatch,错误信息中附带违规主机的 IP 列表,便于运维快速定位。
  4. 解析目标空闲机模块:在目标业务下按 bk_is_default = 资源池标记 条件查询空闲机模块 ID(GetResourcePoolModuleID),模块不存在时返回 CCErrHostModuleNotExist(携带模块名)。
  5. 构造跨业务转移请求并落库:
assignParams := &metadata.TransferHostsCrossBusinessRequest{
	SrcApplicationIDs: []int64{ownerAppID},
	DstApplicationID:  conf.ApplicationID,
	HostIDArr:         conf.HostIDs,
	DstModuleIDArr:    []int64{moduleID},
}

随后调用 CoreAPI.CoreService().Host().TransferToAnotherBusiness 完成"从资源池业务删除主机-模块关系、在目标业务空闲机模块下建立关系"的跨业务操作;失败时返回 CCErrHostEditRelationPoolFail,核心服务返回 result: false 时透传 result.Code / ErrMsg。

  1. 审计日志:转移前后通过 auditlog.NewHostModuleLog(...).WithPrevious 记录主机模块关系的前置快照,成功后 audit.SaveAudit 落库,使该操作可审计、可回溯;审计服务初始化失败返回 CCErrCommResourceInitFailed。

也就是说,接口文档中"data: null、result: true"的成功语义,对应源码中的"事务内 TransferToAnotherBusiness 成功且 result.Result 为真,审计保存成功"。

权限解析:资源池主机分配到业务

在 IAM 权限解析器中,host.go 将该路径定义为专门的模式常量:

moveResPoolHostToBizIdleModulePattern = "/api/v3/hosts/modules/resource/idle"

当请求命中该路径且为 POST 时(host.go),解析器会解码请求体中的 hostPool 参数,并调用 getRscPoolHostModuleRelation(opt.HostID) 反查这批主机在资源池中挂接的模块关系,再据此构造 meta.ResourceAttribute 参与鉴权。这与文档中"Permission: Allocate Hosts from Host Pool to Business Permission"的描述一致:权限点与主机在资源池中的实际归属绑定,而不是仅按 bk_biz_id 判断。

内部 SDK 调用示例

除通过 ESB/开放平台调用外,仓库内部也提供了 Go 客户端封装。hostserver.AssignHostToApp 即该接口的编程式客户端:

func (hs *hostServer) AssignHostToApp(ctx context.Context, h http.Header,
	dat *metadata.DefaultModuleHostConfigParams) (resp *metadata.Response, err error) {
	resp = new(metadata.Response)
	subPath := "/hosts/modules/resource/idle"

	err = hs.client.Post().
		WithContext(ctx).
		Body(dat).
		SubResourcef(subPath).
		WithHeaders(h).
		Do().
		Into(resp)
	return
}

在集群内部组件(如蓝鲸框架、其他中心)需要程序化分配主机时,可以直接复用 DefaultModuleHostConfigParams 结构与该客户端方法,而无需手工拼接 HTTP 请求。

常见失败场景对照

结合源码中的错误分支,调用失败时可按如下表快速定位:

现象 源码错误码 含义
返回"not found"类错误 CCErrCommNotFound bk_biz_id 对应的业务不存在
错误信息中带一串内网 IP CCErrHostModuleConfigNotMatch 部分主机不在资源池的资源目录模块下(如已被分配或不在资源池业务中)
提示某模块不存在 CCErrHostModuleNotExist 目标业务下未初始化空闲机模块
转移关系失败 CCErrHostEditRelationPoolFail 核心服务执行跨业务关系变更失败
result: false 且带核心服务错误码 透传 result.Code / ErrMsg 核心服务(拓扑/存储层)拒绝,需按 request_id 查日志

关联接口

该接口与一组主机-模块转移接口共同构成主机流转闭环,均注册在 service_initfunc.go:

路径 处理器 用途
POST /hosts/modules TransferHostModule 业务内主机转移到指定模块
POST /hosts/modules/resource/idle AssignHostToApp 资源池主机分配至业务空闲机模块(本文接口)
POST /hosts/modules/resource MoveHostToResourcePool 业务主机移回资源池
POST /hosts/modules/idle / fault / recycle MoveHost2*Module 业务内主机上交到默认模块
POST /hosts/modules/across/biz TransferHostAcrossBusiness 业务间转移主机
POST /hosts/resource/cross/biz TransferResourceHostsAcrossBusiness 资源池主机在多个业务间转移
POST /host/transfer/resource/directory TransferHostResourceDirectory 主机在资源池目录之间转移

历史接口文档(含入参出参说明)参见 host_relation.md。

小结

transfer_resourcehost_to_idlemodule 是 bk-cmdb 中资源池主机进入业务体系的唯一入口接口:参数上仅需 bk_biz_id 与 bk_host_id 两个核心字段;实现上则串联了业务存在性校验、资源池归属校验、目标空闲机模块解析、跨业务拓扑转移(事务保证原子性)与模块关系审计日志五个环节。理解这条调用链后,无论是编写自动化纳管脚本,还是排查"主机分配失败"类工单,都能直接在 host_server 的 service/logics 两层代码中定位到具体失败点。

登录后查看全文
bk-cmdb