企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本篇围绕蓝鲸配置平台（BlueKing CMDB，下称 bk-cmdb）开放 API 中的transfer_host_to_resourcemodule（主机回收至资源池/主机归还主机池）接口展开。读完本文，你可以掌握该接口的请求路径、参数语义、默认目录回退规则与响应结构，并了解它从 API 网关、host_server 路由到 coreservice 跨业务转移的完整源码调用链，以及常见失败场景对应的错误码。

一、接口定位与网关定义

transfer_host_to_resourcemodule用于将某业务下的一台或多台主机归还（回收）到资源池（主机池）业务，对应的 IAM 动作名称为“主机归还主机池”，可在 动作定义（src/ac/iam/initial_actions.go#L50，BusinessHostTransferToResourcePool: "主机归还主机池"）中确认。

在 API 网关的资源定义 bk_apigw_resources_bk-cmdb.yaml 中，该接口的关键配置如下：

该接口属于 bk-cmdb 主机关系（host relation）API 家族，归档文档 host_relation.md 中以“主机回收至资源池”条目记录了同一接口，英文描述为transfer host to resource module。

二、输入参数详解

官方接口文档（transfer_host_to_resourcemodule.md）定义的输入参数如下：

结合源码对参数的补充说明：

• bk_biz_id：主机当前所属的业务 ID，作为跨业务转移的“源业务”。服务端参数结构定义在 DefaultModuleHostConfigParams（src/common/metadata/common.go#L355-L360）：

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

• bk_host_id：主机 ID 数组，一次可批量归还多台主机。注意 Service 层实现 中的特殊行为：若bk_host_id为空数组，接口会直接返回成功且 data 为 null，不做任何变更（“空操作即成功”）。
• bk_module_id：目标资源池目录（模块）ID。当取值为 0（缺省）时，逻辑层 会按“源业务为资源池业务 +bk_is_default为资源池默认目录标志（common.DefaultResModuleFlag）”的条件查找主机池的空闲机目录，这与文档中“默认转移到主机池的空闲机目录”的描述一致；显式指定时则按bk_module_id精确定位目录。
• bk_supplier_account：开发商账号。从源码结构看，该值并非从请求体读取，而是取自请求上下文（kit.SupplierAccount，由网关注入的请求头），用于在 GetResourcePoolModuleID 中按bk_supplier_account字段匹配资源池下对应开发商的模块，从而确定目标目录。

调用示例

{ "bk_biz_id": 1, "bk_module_id": 3, "bk_host_id": [ 9, 10 ] }

省略bk_module_id的等价调用：

{ "bk_biz_id": 269, "bk_host_id": [204] }

三、响应结构与参数说明

响应示例

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

响应参数说明

该接口的业务载荷data在成功时通常为null；失败时 Service 层 会把逻辑层收集的exceptionArr（[]metadata.ExceptionResult）通过RespEntityWithError随错误一并返回，便于调用方定位是哪些主机转移失败。

四、源码实现链路：一次调用发生了什么

以 bk-cmdb 后端源码为准，一次POST /api/v3/hosts/modules/resource请求经过以下链路：

1. 路由注册：host_server 在 service_initfunc.go 中把/hosts/modules/resource注册到MoveHostToResourcePool处理器。同组注册还包括/hosts/modules（业务内转移）、/hosts/modules/idle、/hosts/modules/fault、/hosts/modules/resource/idle（资源池主机分配给业务空闲机模块）等。
2. Service 层（事务边界）：MoveHostToResourcePool 将请求体解码为DefaultModuleHostConfigParams，在CoreService().Txn().AutoRunTxn事务闭包内调用逻辑层；事务失败或逻辑失败时返回异常列表与错误。
3. 逻辑层校验与目标目录定位：Logics.MoveHostToResourcePool 依次完成：
   • 通过 GetDefaultAppID 查询“默认业务”（即资源池/主机池业务）ID；
   • 若bk_biz_id为 0，返回错误码CCErrHostNotResourceFail（1110051，资源池未找到类错误）；
   • 若源业务 ID 与资源池业务 ID 相同（主机已经在资源池），返回CCErrHostBelongResourceFail（1110052，“The host is already in the resource pool”）；
   • 按第二节描述的规则解析出目标资源池目录模块 ID（按开发商账号匹配）；
   • 查询源业务下的非默认目录（bk_is_default != 0），再通过GetDistinctHostIDByTopology校验bk_host_id中的主机确实在这些目录里；若存在不属于的机器，按 IP 汇总后返回CCErrHostModuleConfigNotMatch（1110056，“hostID not belong to business”）。相关错误码定义见 errInfo.go。
   • 组装跨业务转移请求：

param := &metadata.TransferHostsCrossBusinessRequest{ SrcApplicationIDs: []int64{conf.ApplicationID}, // 源业务 HostIDArr: conf.HostIDs, DstApplicationID: ownerAppID, // 资源池业务 DstModuleIDArr: []int64{ownerModuleID}, // 资源池目标目录 }

4. 审计日志与落库：调用前先通过 NewHostModuleLog 记录转移前的主机-目录关系，再调用CoreService().Host().TransferToAnotherBusiness执行真正的拓扑关系变更，成功后audit.SaveAudit落审计日志。跨业务转移的核心实现在 coreservice 的 TransferManager.TransferToAnotherBusiness（src/source_controller/coreservice/core/host/transfer/manager.go#L239），它负责参数校验、清理遗留私有字段并更新主机与业务/集群/模块的关联。
5. 客户端 SDK：其他 Go 服务调用该能力时，可直接使用 hostServer.MoveHostToResourcePool（src/apimachinery/hostserver/apis.go#L300-L314），内部同样POST /hosts/modules/resource。前端页面的“归还主机池”操作也走同一后端接口（见 host-relation.js 中$http.post('hosts/modules/resource', ...)）。

五、典型失败场景与排查建议

结合上述逻辑层的校验顺序，实际调用时常见失败及对应错误码如下：

排查建议：先确认目标主机当前挂载的目录（可用主机-模块关系查询接口POST /api/v3/host/topo/relation/read，见 归档文档 中的说明），再核对bk_biz_id与开发商账号是否与资源池目录一致；批量调用时注意网关限流为默认 100 QPS。

六、与同族接口的关系（避免误用）

主机关系 API 家族中几个易混淆接口的方向不同，可对照理解：

即“归还主机池”与“从主机池分配主机到业务”是一对互逆操作，二者在 host_server 路由注册 中相邻出现，且共用同一套DefaultModuleHostConfigParams入参结构。

参考文件

• 接口文档：docs/apidoc/apigw/open/zh/transfer_host_to_resourcemodule.md
• 网关注册：docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml
• 归档 API 文档：docs/apidoc/archived/host/host_relation.md
• 路由注册：src/scene_server/host_server/service/service_initfunc.go
• 服务/事务层：src/scene_server/host_server/service/module.go
• 核心逻辑：src/scene_server/host_server/logics/module.go
• 入参结构：src/common/metadata/common.go
• 错误码：src/common/errInfo.go
• 客户端 SDK：src/apimachinery/hostserver/apis.go
• 跨业务转移实现：src/source_controller/coreservice/core/host/transfer/manager.go
• IAM 动作：src/ac/iam/initial_actions.go

• 后端
• 企业应用
• 运维