★ FEATURED ARTICLE 后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文以蓝鲸智云配置平台BlueKing CMDBbk-cmdb开放接口clone_host_property为主线系统讲解如何通过 ESB 网关调用该接口将源主机的属性一键克隆到目标主机。文中完整覆盖请求参数含义、两种主机指定方式内网 IP 与主机 ID的互斥规则、请求与返回示例并结合仓库源码深入剖析参数校验、鉴权链路、事务执行与字段过滤规则。读完本文你将能独立构造正确的克隆请求、排查常见调用失败原因并理解该功能在 hostserver 模块内部的完整实现。一、功能概述与适用场景克隆主机属性接口用于将源主机的可编辑属性批量复制到目标主机例如批量初始化一批同规格新主机的资产编号、责任人、备注等属性时非常实用。调用该接口需要具备业务主机编辑权限。该接口对外暴露在 ESB企业服务总线上映射关系定义在 docs/apidoc/cc/cc.yaml 第 318-326 行- path: /v2/cc/clone_host_property/ name: clone_host_property label: 克隆主机属性 label_en: clone host property suggest_method: POST api_type: operate comp_codename: generic.v2.cc.cc_component dest_path: /api/v3/hosts/property/clone dest_http_method: PUT即ESB 侧路径为/v2/cc/clone_host_property/POST内部转发到 CMDB 的PUT /api/v3/hosts/property/clone。CMDB 侧路由在 src/scene_server/host_server/service/service_initfunc.go 中注册utility.AddHandler(rest.Action{Verb: http.MethodPut, Path: /hosts/property/clone, Handler: s.CloneHostProperty})二、请求参数详解调用该接口除需携带bk_app_code、bk_app_secret、bk_username、bk_token等通用鉴权参数外接口参数如下表所示字段类型必选描述bk_org_ipstring是源主机内网 ipbk_dst_ipstring是目标主机内网 ipbk_org_idint是源主机 IDbk_dst_idint是目标主机 IDbk_biz_idint是业务 IDbk_cloud_idint否管控区域 ID对应的 Go 参数结构体定义在 src/common/metadata/hostserver.go可确认各字段的 JSON 键名与含义// CloneHostPropertyParams TODO type CloneHostPropertyParams struct { AppID int64 json:bk_biz_id // source and destination host inner ip OrgIP string json:bk_org_ip DstIP string json:bk_dst_ip // source and destination host id OrgID int64 json:bk_org_id DstID int64 json:bk_dst_id CloudID int64 json:bk_cloud_id }重要约束使用主机内网 IPbk_org_ip/bk_dst_ip进行克隆与使用主机身份 IDbk_org_id/bk_dst_id进行克隆这两种方式只能使用其中的一种不能混用。三、两种主机指定方式与校验规则1. 按主机内网 IP 指定IP 方式同时提供bk_org_ip源主机内网 IP与bk_dst_ip目标主机内网 IP接口内部会将 IP 解析为对应主机 ID 后再执行克隆。2. 按主机 ID 指定ID 方式同时提供bk_org_id源主机 ID与bk_dst_id目标主机 ID直接定位主机。3. 服务端参数互斥校验在 src/scene_server/host_server/service/host.go 的CloneHostProperty入口处代码对参数组合做了严格校验可归纳为以下规则bk_biz_id必须大于 0bk_cloud_id不能小于 0IP 与 ID 两种方式不能混用只要提供了任意一个 IP 参数且同时提供了任意一个 ID 参数即报参数非法必须成对提供IP 方式下bk_org_ip与bk_dst_ip必须同时提供ID 方式下bk_org_id与bk_dst_id必须同时大于 0源与目标不能是同一台主机若两者 IP 相同或 ID 相同接口直接返回成功无实际克隆动作。四、请求参数示例示例一按主机内网 IP 克隆{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 2, bk_org_ip: 127.0.0.1, bk_dst_ip: 127.0.0.2, bk_cloud_id: 0 }示例二按主机 ID 克隆{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 2, bk_org_id: 10, bk_dst_id: 11, bk_cloud_id: 0 }注意上述两个示例中携带了bk_cloud_id该参数可选在按 IP 方式指定主机时IP 需要结合管控区域云区域ID 唯一定位主机因此建议 IP 方式下同时携带bk_cloud_id。五、返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: null }返回结果参数说明response字段类型描述resultbool请求成功与否。true:请求成功false请求失败codeint错误编码。0表示success0表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息request_idstring请求链 iddataobject请求返回的数据该接口执行成功时data为空null克隆结果可通过查询主机属性接口确认。六、源码实现原理从请求到克隆落库1. IP 到主机 ID 的解析当采用 IP 方式时服务端通过 ip2hostID 将 IP 解析为主机 ID以bk_cloud_id与bk_host_innerip使用$in匹配源/目标 IP为条件查询主机逐一比对内网 IP支持逗号分隔的多 IP 场景后得到源、目标主机 ID任一 IP 无法解析到主机 ID 时返回“invalid org or dst data”错误。2. 鉴权链路业务主机编辑权限克隆属于敏感写操作服务端在真正执行前做了两层鉴权见 host.go对源主机执行authmeta.Find查询权限校验对目标主机执行authmeta.Update编辑/更新权限校验无权限时返回带 permission 信息的无权限响应供调用方申请权限。这与文档声明的“权限业务主机编辑权限”完全对应。3. 核心克隆逻辑真正的克隆动作在 src/scene_server/host_server/logics/host.go 的CloneHostProperty中完成关键步骤与字段过滤规则如下归属校验通过拓扑关系校验源主机与目标主机都归属于bk_biz_id对应的业务否则返回“主机不在当前业务”错误字段白名单过滤读取主机模型全部属性仅保留IsEditable可编辑字段并排除参与了主机唯一性校验unique rule的字段——这是防止克隆破坏唯一约束的关键设计读取源主机属性按过滤后的字段列表读取源主机数据同时剔除bk_host_id与创建时间字段避免覆盖目标主机主键生成审计日志克隆前先为目标主机生成更新类审计快照更新落库以目标主机 ID 为条件执行UpdateInstance将源主机属性写入目标主机并保存审计日志。此外整个克隆过程通过Txn().AutoRunTxn事务包装host.go保证参数校验、克隆更新、审计日志写入要么全部成功、要么整体回滚。4. 客户端调用封装CMDB 各服务间调用通过 apimachinery 封装src/apimachinery/hostserver/apis.go 提供了CloneHostProperty客户端方法PUT /hosts/property/clone集成方可在 Go 服务中直接复用。七、测试用例验证仓库内置了针对该接口的自动化测试可佐证上述行为src/test/host_server/host_test.go正常场景“clone host”以 IP 方式克隆后断言result为 truesrc/test/host_server/host_abnormal_test.go覆盖异常场景包括缺少bk_biz_id、缺少源/目标 IP、业务 ID 不存在、源/目标 IP 非法如127.0.1等均断言result为 false验证了参数校验的完备性。八、注意事项与排查建议IP 与 ID 互斥切勿混用两种指定方式否则接口直接返回参数非法主机归属源、目标主机都必须属于bk_biz_id指定的业务不可克隆字段参与唯一性校验的字段如某些自定义唯一属性不会被克隆需在克隆后手动补齐权限前置调用方需具备源主机查询与目标主机编辑权限无权限时返回permission信息可据此向蓝鲸权限中心申请错误排查返回code非 0 时结合message与request_id定位问题request_id可用于在 CMDB 日志中串联完整调用链。综上clone_host_property是 CMDB 主机管理体系中一个轻量而实用的批量属性初始化接口理解其参数约束与源码实现能帮助你在业务运维与二次开发中准确、安全地使用它。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台 bk-cmdb 克隆主机属性接口clone_host_property详解IP 与 ID 双模式调用与源码实现剖析蓝鲸智云配置平台 bk cmdb 克隆主机属性接口clone_host_property详解IP 与 ID 双模式调用与源码实现剖析 本文以蓝鲸智云配置平后端企业应用运维bk-cmdb 克隆主机属性接口clone_host_property详解从 ESB 网关映射到源码实现bk cmdb 克隆主机属性接口clone_host_property详解从 ESB 网关映射到源码实现 本篇围绕蓝鲸智云配置平台bk cmdb的「克后端企业应用运维蓝鲸 CMDB 更新主机属性接口update_host实战指南参数详解、调用示例与源码实现原理蓝鲸 CMDB 更新主机属性接口update_host实战指南参数详解、调用示例与源码实现原理 导读 本文围绕蓝鲸配置平台bk cmdb开放 API后端企业应用运维创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
