企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本文是一篇围绕蓝鲸配置平台（BlueKing CMDB / bk-cmdb）add_host_to_business_idle接口展开的实战技术指南。该接口用于将主机资源一次性添加进入指定业务（bk_biz_id）的空闲机模块，是业务初始化、主机纳管阶段最常用的写入类接口之一。读完本文，你将完整掌握该接口的请求参数语义、批量上限约束、事务性保证（要么全部成功、要么全部失败）、权限要求（主机池主机分配至业务权限）、真实调用示例、响应字段解析，以及从路由注册到主机实例落库的底层实现链路。

接口概览：功能与适用场景

add_host_to_business_idle（添加主机到业务空闲机）是 CMDB 主机场景服务（host_server）对外暴露的一个写入型接口。它的核心职责是：将请求中携带的主机列表（bk_host_list）创建为主机实例，并挂载到指定业务（bk_biz_id）的空闲机模块下，随后返回这批新主机的bk_host_ids。

典型的适用场景包括：

• 业务初始化时，将一批新采购或新发现的服务器批量录入 CMDB 并归入业务空闲机；
• 通过自动化平台/作业平台调用 ESB 或 API 网关，把从资源池分配出来的主机落入指定业务；
• 批量导入主机并希望接口具备"全部成功或全部失败"的原子性保证。

该接口在仓库中的对外形态可以在 docs/apidoc/cc/cc.yaml 中看到：ESB 组件路径为/v2/cc/add_host_to_business_idle/，内部转发到 CMDB 的POST /api/v3/hosts/add/business_idle；同时它也在 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml 中被声明为蓝鲸 API 网关资源，支持权限申请与限流等网关插件配置。

前置条件与权限说明

根据接口定义（见 docs/apidoc/cc/en/add_host_to_business_idle.md），调用该接口需要满足以下前提：

• 版本要求：接口自v3.10.25起提供；
• 权限要求：调用方需要具备"主机池主机分配至业务权限"（Host pool host allocation to business permission）；
• 该权限校验相关问题曾在 v3.11.3 版本中有过修复记录，见 docs/support-file/changelog_user/ch/v3.11.3_2023-12-18.md，说明在实际升级时需要注意该接口权限策略的历史变更。

请求参数详解

公共参数（common args）

接口文档以{{ common_args_desc }}占位符引用公共参数模板，结合接口请求示例可以确认，调用时需要携带蓝鲸应用与用户身份信息，典型字段如下：

接口专属参数

其中bk_host_list内每个元素（主机对象）支持的字段如下：

关于字段取值的硬性约束，可以从源码常量中得到印证：BKAddressingStatic = "static"、BKAddressingDynamic = "dynamic"，以及单次批量写入上限BKMaxWriteOpLimit = 200，定义见 src/common/definitions.go。

请求示例（Python 数据结构）

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_biz_id": 3, "bk_host_list": [ { "bk_host_innerip": "10.0.0.1", "bk_cloud_id": 0, "bk_addressing": "dynamic", "operator": "admin" }, { "bk_host_innerip": "10.0.0.2", "bk_cloud_id": 0, "bk_addressing": "dynamic", "operator": "admin" } ] }

响应示例与参数说明

成功调用后，接口返回新创建主机的 ID 列表：

{ "result": true, "code": 0, "message": "", "permission": null, "request_id": "e43da4ef221746868dc4c837d36f3807", "data": { "bk_host_ids": [ 1, 2 ] } }

response 顶层字段

data 字段

源码级实现原理：接口背后发生了什么

路由注册与请求入口

该接口由 host_server 服务对外提供。路由注册位于 src/scene_server/host_server/service/service_initfunc.go：

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/hosts/add/business_idle", Handler: s.AddHostToBusinessIdle})

对应的处理器实现位于 src/scene_server/host_server/service/host.go，处理流程如下：

1. 参数解码与校验：将请求体解码为HostListParam结构体并执行Validate()；
2. 定位空闲机模块：以bk_biz_id+ 默认资源模块标志（DefaultResModuleFlag，其值为 1，见 src/common/definitions.go）为条件，通过GetResourcePoolModuleID查询目标业务的空闲机模块 ID；
3. 事务内写入主机：在AutoRunTxn事务中调用AddHosts，任一环节失败则整体回滚；
4. 返回主机 ID：成功后返回HostIDsResp（即data.bk_host_ids）。

参数校验的源码约束

请求参数结构体定义与校验逻辑位于 src/common/metadata/hostserver.go。校验规则可以归纳为：

• bk_host_list为空时报CCErrCommParamsNeedSet（参数必填缺失）；
• bk_host_list长度超过BKMaxWriteOpLimit（200）时报CCErrCommXXExceedLimit（超出批量上限）；
• bk_biz_id为 0 时报CCErrCommParamsNeedSet。

主机的字段级校验与落库链路

主机对象的逐字段校验在AddHosts内通过checkHostAttr完成，实现位于 src/scene_server/host_server/logics/import.go，关键校验点包括：

• IP 校验：bk_host_innerip与bk_host_innerip_v6至少填一个，否则报"至少设置一个值"错误（CCErrCommAtLeastSetOneVal）；
• 云区域校验：bk_cloud_id必须存在且为非负整数，并通过ValidHostCloudIDHook钩子校验，随后还会校验云区域是否真实存在（IsPlatAllExist）；
• 寻址方式校验：bk_addressing必须为"static"或"dynamic"，否则报参数无效错误。

校验通过后，AddHosts（见 src/scene_server/host_server/logics/import.go）会依次执行：

1. 通过CoreService().Instance().CreateManyInstance批量创建主机实例（内置对象BKInnerObjIDHost）；
2. 若存在重复主机数据（Repeated）则返回CCErrCommDuplicateItem错误；
3. 通过TransferToInnerModule建立主机与空闲机模块的挂载关系；
4. 生成并保存主机新增的审计日志（auditlog.NewHostAudit）。

空闲机模块的定位逻辑GetResourcePoolModuleID位于 src/scene_server/host_server/logics/module.go，它通过ReadInstance读取模块实例并按供应商账号（BkSupplierAccount）匹配返回模块 ID 与名称。

事务性保证：全部成功或全部失败

接口注释明确强调（v3.10.25+）：主机会被一起成功添加或一起失败。这一语义在 src/scene_server/host_server/service/host.go 中通过CoreService().Txn().AutoRunTxn事务包装AddHosts实现：只要创建主机实例、建立模块关系、生成审计日志任一环节出错，整个事务回滚，不会出现"部分主机入库"的中间状态。

调用注意事项与最佳实践

基于上述参数约束与实现细节，实际调用时建议注意以下几点：

1. 严格控制批量大小：单次bk_host_list最多 200 条，超限会直接报错；大批量场景应分批循环调用；
2. IP 必填其一：每条主机记录必须携带bk_host_innerip或bk_host_innerip_v6，否则整批失败；
3. 云区域必须先存在：bk_cloud_id必须指向已创建的管控区域，建议调用前先通过查询接口确认云区域 ID 有效；
4. 寻址方式二选一：bk_addressing只能传static或dynamic，与主机实际网络接入方式保持一致；
5. 权限前置检查：调用方需具备"主机池主机分配至业务"权限，鉴权失败时响应中的permission字段会携带权限申请信息，可据此引导用户完成权限申请；
6. 利用request_id排障：失败时可结合request_id与服务端日志（blog.Errorf中记录了rid）定位具体失败原因。

总结

add_host_to_business_idle是蓝鲸 CMDB 中面向业务空闲机批量写入主机的标准接口。它通过参数级校验（IP、云区域、寻址方式）、批量上限（200 条）与事务包装，保证了写入操作的规范性与原子性；其整体实现从路由注册、参数校验、空闲机模块定位到主机实例创建与审计日志落库，形成了完整闭环。本文涉及的接口文档、ESB/网关配置以及服务端源码，均可分别在 docs/apidoc/cc/en/add_host_to_business_idle.md、docs/apidoc/cc/cc.yaml 与 src/scene_server/host_server/service/host.go 中进一步查阅。

• 后端
• 企业应用
• 运维