后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读本文基于蓝鲸智云配置平台BlueKing CMDB官方 API 文档与仓库源码系统讲解如何通过POST /api/v3/hosts/modules/recycle接口将业务下的主机上交至待回收模块。读完本文你将掌握该接口的完整请求参数与返回结构、待回收模块在 CMDB 数据模型中的定位default3以及从 host_server 到 coreservice 的底层调用链与校验逻辑可直接用于业务代码集成与排障。一、功能概述什么是待回收模块在 bk-cmdb 的拓扑模型中每个业务默认会内置一个由系统创建的空闲机、故障机、待回收模块集合Set。其中空闲机模块idle hostdefault 1故障机模块fault hostdefault 2待回收模块recycle hostdefault 3这三个模块类型标识在源码中有明确定义见 src/common/definitions.goconst ( // DefaultResModuleFlag the default resource module flag DefaultResModuleFlag int 1 // DefaultFaultModuleFlag the default fault module flag DefaultFaultModuleFlag int 2 // NormalModuleFlag create module by user , default 0 NormalModuleFlag int 0 // DefaultRecycleModuleFlag default recycle module flag DefaultRecycleModuleFlag int 3 )上交主机到待回收模块的含义是将某业务下仍然挂载在业务模块中的主机统一移动到该业务自带的待回收模块中从而标记这些主机进入回收前的待处置状态。该操作通常用于主机下线、资源回收的前置流程。可以通过 get_biz_internal_module 接口文档 查询某业务下的待回收模块 ID响应中default: 3、bk_module_name: recycle host的模块即为待回收模块。二、接口基本信息项目说明接口路径/api/v3/hosts/modules/recycleHTTP 方法POST功能上交主机到业务的待回收模块权限要求服务实例编辑权限Service Instance Edit Permission该路由在 host_server 服务中的注册位置见 src/scene_server/host_server/service/service_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /hosts/modules/recycle, Handler: s.MoveHost2RecycleModule})API 网关侧的资源定义含限流配置默认每秒 100 token见 docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml。三、请求参数详解3.1 公共参数调用蓝鲸 API 时需携带统一的公共参数common_args_desc用于身份认证与链路追踪通常包括字段类型必选描述bk_app_codestring是应用标识ESB 应用 IDbk_app_secretstring是应用密钥bk_usernamestring是操作用户名bk_tokenstring是登录票据token当通过 API 网关ESB调用时网关会根据应用鉴权信息自动补充这些字段直接调用 CMDB 原生接口时则需要显式携带。3.2 接口参数字段类型必选描述bk_biz_idint是业务 ID主机所属业务bk_set_idint与 bk_module_id 至少填一个集群 ID用于定位主机当前所在模块bk_module_idint与 bk_set_id 至少填一个模块 IDbk_host_idarray是主机 ID 数组需上交的主机集合参数约定说明bk_set_id与bk_module_id属于至少填一个的互斥组合约束用于定位主机当前在业务拓扑中的位置bk_host_id支持批量操作可一次上交多台主机最终真正生效的目标模块是业务内置的待回收模块而非请求中填写的模块请求中的bk_set_id/bk_module_id仅用于确定主机来源范围源码中对应结构体见 src/common/metadata/common.go// DefaultModuleHostConfigParams TODO type DefaultModuleHostConfigParams struct { ApplicationID int64 json:bk_biz_id HostIDs []int64 json:bk_host_id ModuleID int64 json:bk_module_id }四、请求参数示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, bk_biz_id: 1, bk_set_id: 1, bk_module_id: 1, bk_host_id: [ 9, 10 ] }上例表示将业务 ID 为 1 的主机 9、10 上交至该业务的待回收模块。五、返回结果示例与字段说明5.1 返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: null }5.2 返回字段说明response字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息无权限时携带跳转链接等request_idstring请求链 ID用于全链路日志追踪dataobject请求返回的数据本接口成功时为 null调用方应以result与code作为成功判定依据resulttrue且code0表示操作成功否则需读取message并结合request_id在 CMDB 日志中定位失败原因。六、底层实现与调用链解析源码级6.1 入口MoveHost2RecycleModulehost_server 服务层收到请求后进入处理函数 MoveHost2RecycleModule其内部复用了统一的moveHostToDefaultModule逻辑仅传入不同的默认模块标志// MoveHost2RecycleModule TODO func (s *Service) MoveHost2RecycleModule(ctx *rest.Contexts) { s.moveHostToDefaultModule(ctx, common.DefaultRecycleModuleFlag) }同样的机制也被上交故障机模块MoveHost2FaultModule复用见 module.go。6.2 关键流程moveHostToDefaultModule核心实现位于 module.go流程如下解析请求体将 JSON 反序列化为DefaultModuleHostConfigParams构造模块过滤条件根据defaultModuleFlag设置moduleFilter[bk_default] DefaultRecycleModuleFlag(3)并叠加moduleFilter[bk_biz_id] bizID通过GetResourcePoolModuleID查询该业务对应的待回收模块 ID而非使用请求中的bk_module_id审计准备调用auditlog.NewHostModuleLog与audit.WithPrevious记录操作前的主机-模块关系快照事务执行在AutoRunTxn事务中构造TransferHostToInnerModule包含bk_biz_id、目标module_id、bk_host_id调用 coreservice 的TransferToInnerModule完成转移落库审计转移成功后保存审计日志任一环节失败则整体回滚事务。6.3 coreservice 侧校验与转移coreservice 的TransferToInnerModule实现见 src/source_controller/coreservice/core/host/transfer/manager.go其核心校验点是目标模块必须是默认内置模块通过HasInnerModule校验请求中的目标模块是否为空闲机/故障机/待回收模块若否直接返回错误码CCErrCoreServiceModuleNotDefaultModuleErr值 1113008moduleID 不属于 default module定义见 src/common/errInfo.go参数与主机归属校验通过genericTransfer.ValidParameter完成包括校验主机是否存在、主机是否属于当前业务validHostsBelongBiz等见 transfer.go关系转移删除原有主机-模块关系并建立新关系相关实现见 transfer.go。可以推断由于校验目标模块必须是默认模块业务自定义普通模块default0无法直接作为该接口的落点这正是上交到待回收模块语义的硬性保证。七、使用注意事项与常见问题权限前置调用方需要具备服务实例编辑权限否则会被权限中心拦截返回 403 及permission字段业务一致性bk_biz_id必须与主机实际所属业务一致bk_host_id不能跨业务混传否则会在 coreservice 的validHostsBelongBiz校验处失败目标模块自动推导接口实际将主机移入业务内置的待回收模块default3请求体中的bk_set_id/bk_module_id仅用于来源定位请勿误解为可指定任意目标模块批量操作bk_host_id为数组可一次上交多台部分主机校验失败时返回结构中的异常明细会通过RespEntityWithError携带建议对部分失败结果做单独处理待回收模块查询如需在调用前获取业务待回收模块 ID可先调用 get_biz_internal_module 接口确认响应data.module中default3的bk_module_id即待回收模块审计追踪每次上交操作都会生成主机-模块关系变更审计日志可通过request_id关联操作上下文便于后续溯源。八、结语上交主机到待回收模块是 CMDB 主机生命周期管理中的关键一环。通过本文你可以看到接口层host_server只负责参数解析与模块推导真正的校验与数据落库在 coreservice 的 transfer 模块中完成并通过事务保证一致性。掌握这一调用链无论是二次开发、问题排查还是权限设计都能事半功倍。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云 CMDB 上交主机到待回收模块接口transfer_host_to_recyclemodule详解蓝鲸智云 CMDB 上交主机到待回收模块接口transfer_host_to_recyclemodule详解 导读 transfer_host_to_rec后端企业应用运维蓝鲸智云配置平台 bk-cmdb 主机身份查询接口 search_hostidentifier 实战指南蓝鲸智云配置平台 bk cmdb 主机身份查询接口 search_hostidentifier 实战指南 本指南以蓝鲸智云配置平台bk cmdb对外 API后端企业应用运维蓝鲸配置平台bk-cmdb空闲机/故障机/待回收模块查询接口get_biz_internal_module完整解析蓝鲸配置平台bk cmdb空闲机/故障机/待回收模块查询接口get_biz_internal_module完整解析 本文以蓝鲸智云配置平台bk cmd后端企业应用运维上一篇企业级硬件测试方案基于stressapptest的服务器稳定性验证流程下一篇TensorFlow张量操作终极指南掌握多维数组的10个核心技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考