★ FEATURED ARTICLE 后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读本文以蓝鲸智云配置平台BlueKing CMDB仓库目录bk-cmdb官方 API 文档 add_cloud_host_to_biz 为骨架完整讲解新增云主机到业务空闲机模块这一云主机管理专用接口的请求参数、字段含义、请求/返回示例并结合 host_server 场景服务的 Go 源码cloud_host.go剖析其底层处理流程参数校验、云主机标识写入、新增/更新分类、事务化批量创建与空闲机转移。读完本文你将掌握该接口的完整调用姿势并理解一批主机同时成功或同时失败的原子性保证是如何在源码中实现的。一、接口概述定位、版本与权限该接口用于将云主机批量导入到指定业务的空闲机模块是云主机管理专用接口与普通主机导入接口相互独立。功能新增云主机到业务空闲机模块。版本要求v3.10.19自该版本起提供。所需权限业务主机编辑权限。接口路由源码在 service_initfunc.go 的initCloudHost中注册HTTP 方法为POST路径为/createmany/cloud_hosts。源码注释明确标注dedicated for cloud host management, do not use them for other use云主机管理专用请勿用于其他用途。该接口与配套的删除云主机接口DELETE /deletemany/cloud_hosts共同组成云主机生命周期管理闭环。二、请求参数详解接口请求同时包含通用鉴权参数bk_app_code、bk_app_secret、bk_username、bk_token与业务参数。2.1 接口参数字段类型必选描述bk_biz_idint是业务IDhost_infoarray是新增的云主机信息数组长度最多为 200一批主机仅可同时成功或同时失败数量上限 200对应源码常量BKWriteOpLimit 200定义于 definitions.go。参数结构体 AddCloudHostToBizParam 的Validate方法会对bk_biz_id 0、host_info为空、host_info超过 200 条分别返回校验错误。批次原子性一批主机仅可同时成功或同时失败由事务机制保证详见第四部分源码剖析。2.2 host_info 字段主机信息中管控区域ID、内网IP、云厂商、云主机实例ID为必填字段其余字段为主机模型中定义的属性按需填写。字段表如下字段类型必选描述bk_cloud_idint是管控区域IDbk_host_inneripstring是IPv4 格式的主机内网IP多个IP之间用逗号分隔bk_cloud_vendorarray是云厂商bk_cloud_inst_idarray是云主机实例IDbk_addressingstring否寻址方式云主机的寻址方式都是 staticbk_host_namestring否主机名也可以为其它属性operatorstring否主要维护人也可以为其它属性bk_commentstring否备注也可以为其它属性import_fromstring否主机导入来源以 api 方式导入为 3bk_asset_idstring否固资编号bk_created_atstring否创建时间bk_updated_atstring否更新时间bk_created_bystring否创建人bk_updated_bystring否更新人bk_cloud_host_statusstring否云主机状态bk_cpuint否CPU 逻辑核心数bk_cpu_architecturestring否CPU 架构bk_cpu_modulestring否CPU 型号bk_diskint否磁盘容量GBbk_host_outeripstring否主机外网IPbk_host_innerip_v6string否主机内网 IPv6bk_host_outerip_v6string否主机外网 IPv6bk_isp_namestring否所属运营商bk_macstring否主机内网 MAC 地址bk_memint否主机内存容量MBbk_os_bitstring否操作系统位数bk_os_namestring否操作系统名称bk_os_typestring否操作系统类型bk_os_versionstring否操作系统版本bk_outer_macstring否主机外网 MAC 地址bk_province_namestring否所在省份bk_service_termint否质保年限bk_slastring否SLA 级别bk_snstring否设备 SNbk_statestring否当前状态bk_state_namestring否所在国家bk_bak_operatorstring否备份维护人关于字段类型的小提示文档将bk_cloud_vendor与bk_cloud_inst_id标记为array但从实现看源码 cloud_host.go 的parseCloudHostInfo使用util.GetStrByInterface将其按字符串解析官方测试用例host_test.go中也是直接传字符串如1、000000001。实际调用时传入字符串即可。2.3 云主机属性模型说明bk_cloud_vendor、bk_cloud_inst_id、bk_cloud_host_status是随云主机管理能力一并内置的主机属性由升级脚本 add_cloud_host_attr.go 在升级时写入主机模型属性组为 baseInfo预置属性IsPre truebk_cloud_inst_id云主机实例ID单字符类型bk_cloud_vendor云厂商枚举类型bk_cloud_host_status云主机状态枚举取值包括1未知、2启动中、3运行中、4停止中、5已停止、6已销毁见同一文件中的cloudInstStatusEnum。三、请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 123, host_info: [ { bk_cloud_id: 0, bk_host_innerip: 127.0.0.1, bk_cloud_vendor: 2, bk_cloud_inst_id: 45515, bk_host_name: host1, operator: admin, bk_comment: comment }, { bk_cloud_id: 0, bk_host_innerip: 127.0.0.2, bk_cloud_vendor: 2, bk_cloud_inst_id: 45656, bk_host_name: host2, operator: admin, bk_comment: comment } ] }四、返回结果与参数说明4.1 返回结果示例{ result: true, code: 0, message: , permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: { ids: [ 1, 2 ] } }4.2 response 字段说明字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息dataobject请求返回的数据permissionobject权限信息request_idstring请求链 id4.3 data 字段说明字段类型描述idsarray创建成功的主机 ID 数组data.ids的顺序与请求参数host_info中的主机顺序一一对应对于本次新建的主机返回新生成的bk_host_id对于命中已有主机而执行更新逻辑的主机则返回其既有bk_host_id。该重排逻辑位于 cloud_host.go通过createIndexMap与updateParamMap将新建 ID 与更新 ID 按原始下标回填。五、源码级实现剖析一次调用背后发生了什么接口处理器为 cloud_host.go 中的AddCloudHostToBiz完整流程分为四步5.1 第一步参数预处理preprocessAddCloudHostParam对应源码 cloud_host.go调用input.Validate()做结构级校验业务ID合法、主机数组非空且不超过 200 条为每一台主机写入云主机标识字段bk_cloud_host_identifier true常量定义于 definitions.go其作用是标记该主机为不允许跨业务转移的云主机后续TransferHostAcrossBusiness等跨业务操作会据此拒绝汇总所有bk_cloud_id去重后查询bk_cc_base_plat表确认管控区域均真实存在否则报参数非法错误。5.2 第二步新增/更新分类classifyHosts对应源码 cloud_host.go以genExistHostParams构造查询条件按以下三组键判断主机是否已存在云厂商 云主机实例IDbk_cloud_vendorbk_cloud_inst_id唯一键格式vendor-instID管控区域 内网IPbk_cloud_idbk_host_innerip管控区域 内网 IPv6bk_cloud_idbk_host_innerip_v6。已存在的主机进入更新集合updateParamMap不存在的主机进入新建集合needCreateHosts。这正是该接口天然具备幂等性的原因重复导入同一批云主机不会产生重复数据而是转化为对既有主机的属性更新。5.3 第三步事务化执行AutoRunTxn对应源码 cloud_host.go通过CoreService().Txn().AutoRunTxn将两个写操作包裹在统一事务中updateCloudHost对更新集合中的主机逐台校验其确实属于目标业务调用GetDistinctHostIDByTopology再生成更新审计日志并执行UpdateInstanceaddCloudHostToBiz对新建集合中的主机执行创建与归属转移。这就是文档所述一批主机仅可同时成功或同时失败的实现根基——事务内任一环节失败整批写入回滚不会出现部分成功部分失败的数据状态。5.4 第四步新建主机 转移到空闲机模块addCloudHostToBiz对应源码 cloud_host.go内部依次执行定位空闲机模块按bk_biz_idbk_default 1DefaultResModuleFlag定义于 definitions.go查询该业务的空闲机模块 ID若结果不为 1 条则报参数错误批量创建主机实例调用CoreService().Instance().CreateManyInstance创建主机模型实例若返回结果中存在Repeated重复或Exceptions异常项则整体失败转移到空闲机模块构造TransferHostToInnerModule请求调用Host().TransferToInnerModule将新建主机挂入空闲机模块完成新增到业务空闲机的语义生成并保存审计日志调用auditlog.NewHostAudit生成AuditCreate类型的审计日志并落库保证每一步变更可追溯。5.5 客户端调用入口若在 bk-cmdb 内部以 Go 代码调用该接口可使用 apimachinery 客户端方法hostServer.AddCloudHostToBizapis.go其内部向/createmany/cloud_hosts发起POST请求并解析返回的CreateBatchResult。六、测试用例验证接口行为的边界保证官方集成测试 host_test.go 覆盖了该接口的主要行为是理解接口语义的最佳佐证测试场景预期结果说明正常导入两台云主机到空闲机返回 2 个 host ID可用SearchHostWithBiz按内网IP 查到对应主机新建路径再次导入同一台云主机同 vendorinstID不产生重复主机原主机属性如bk_host_name被更新更新路径 / 幂等性将云主机转移到资源池失败云主机不允许移入资源池跨业务转移云主机失败云主机不允许跨业务转移bk_cloud_host_identifier标识生效向不存在的业务导入失败业务校验部分主机缺少云厂商/实例ID整批失败必填字段校验 批次原子性同 vendorinstID 主机导入到另一业务失败云主机唯一性约束bk_cloud_inst_id字段建索引见 hostbase.go 的cloudInstID索引未传bk_biz_id或host_info失败参数结构校验七、使用注意事项小结必填字段bk_cloud_id、bk_host_innerip、bk_cloud_vendor、bk_cloud_inst_id四项缺一不可且内网IP与内网IPv6 至少填写其一批次上限单次host_info不超过 200 条超出会返回CCErrCommXXExceedLimit错误码 1199035见 errInfo.go幂等导入重复提交同一批云主机不会重复创建而是更新既有主机属性可放心用于定时同步场景专用接口该接口仅供云主机管理使用请勿将其用于普通物理机/虚拟机导入导入后主机带有bk_cloud_host_identifier标识无法移入资源池或跨业务转移版本与权限需要 v3.10.19 版本且调用方需具备对应业务的主机编辑权限。延伸阅读接口英文文档见 add_cloud_host_to_biz.md配套的删除云主机接口实现见 cloud_host.go 的DeleteCloudHostFromBiz云主机属性模型升级逻辑见 add_cloud_host_attr.go。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 新增云主机到业务空闲机模块接口实战add_cloud_host_to_biz蓝鲸 CMDB 新增云主机到业务空闲机模块接口实战add_cloud_host_to_biz 导读 本文围绕蓝鲸配置平台bk cmdb为云主机管理场景专后端企业应用运维蓝鲸配置平台bk-cmdb云主机管理专用接口新增云主机到业务空闲机模块蓝鲸配置平台bk cmdb云主机管理专用接口新增云主机到业务空闲机模块 导读 本文基于蓝鲸智云配置平台BlueKing CMDB仓库 bk cmdb后端企业应用运维蓝鲸 CMDBbk-cmdbadd_host_to_business_idle 接口实战批量添加主机到业务空闲机蓝鲸 CMDBbk cmdbadd_host_to_business_idle 接口实战批量添加主机到业务空闲机 本文是一篇围绕蓝鲸配置平台BlueKi后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
