后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文以蓝鲸智云配置平台BlueKing CMDBbk-cmdb官方 API 文档 delete_host_lock.md 为主体完整讲解根据主机 ID 列表删除主机锁接口的请求参数、请求/返回示例、返回字段语义并结合仓库源码深入剖析其在 coreservice 中的路由注册、Service 层处理与 Mongo 存储层的真实实现帮助开发者掌握主机锁机制的完整调用链与批量解锁的最佳实践。一、接口概览什么是主机锁为什么要删除主机锁Host Lock是 bk-cmdb 提供的一种轻量级占用标记当某个运维流程或业务系统正在对一批主机执行变更如批量安装 Agent、下发配置、执行巡检时可以对这些主机加锁锁定记录会写明加锁用户与加锁时间从而提醒其他操作者该主机正处于被占用状态避免并发修改造成的冲突。本接口delete_host_lock的功能即根据主机 ID 列表id_list批量删除主机锁接口版本要求 v3.8.6 及以上调用者必须具备业务主机编辑权限。它通常与加锁和查询锁两个接口配套使用接口功能网关路径add_host_lock新加主机锁幂等/api/v3/host/lockPOSTdelete_host_lock删除主机锁/api/v3/host/lockDELETEsearch_host_lock查询主机锁/api/v3/host/lock/searchPOST上述三个接口在 cc.yamlESB API 网关配置中集中定义其中 delete_host_lock 的配置片段如下- path: /v2/cc/delete_host_lock/ name: delete_host_lock label: 删除主机锁 label_en: delete host lock suggest_method: POST api_type: operate comp_codename: generic.v2.cc.cc_component dest_path: /api/v3/host/lock dest_http_method: DELETE注意suggest_method为 POST 是 ESB 调用方式的建议实际对 CMDB 的转发方法由dest_http_method: DELETE决定——即最终落到 CMDB 侧的是 HTTP DELETE 请求。二、请求参数详解2.1 公共参数本接口文档中引用的{{ common_args_desc }}为 ESB 公共参数占位符实际调用时需在请求体中携带应用身份与用户身份信息。从官方请求示例可看到至少包含以下四项公共参数字段类型必选描述bk_app_codestring是应用编码即调用方在蓝鲸 ESB 上注册的应用标识bk_app_secretstring是应用密钥用于应用身份鉴权bk_usernamestring是操作用户名用于记录操作人与权限校验bk_tokenstring是登录态令牌通常为蓝鲸统一登录票据说明各字段的完整取值规则以蓝鲸 ESB 网关的实际鉴权配置为准上述四项在本文档的请求示例中均有出现属于本接口可复用的公共调用参数。2.2 接口参数字段类型必选描述id_listint array是主机 ID 列表即待删除锁的主机bk_host_id集合id_list为数组类型元素为整型主机 ID。一次调用可批量删除多台主机的锁。从元数据结构看请求体对应源码中的HostLockRequest见 src/common/metadata/hostlock.go// HostLockRequest TODO type HostLockRequest struct { IDS []int64 json:id_list }其中 JSON 标签json:id_list与文档参数名完全一致且字段类型为[]int64与文档int array类型一一对应。加锁、解锁接口复用同一个请求结构。三、请求示例{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, id_list: [1, 2, 3] }该示例表示以应用esb_test、用户xxx的身份一次性删除主机 ID 为 1、2、3 的三台主机的锁。实际使用时应替换为真实的bk_app_secret、bk_username、bk_token并将id_list换成待解锁的主机 ID。四、返回结果与字段说明4.1 返回结果示例{ result: true, code: 0, message: success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data: null }删除成功后result为true、code为0data为null本接口无额外返回数据。4.2 返回字段说明response字段类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败时返回的错误信息permissionobject权限信息当因权限不足失败时返回request_idstring请求链 id用于全链路日志追踪dataobject请求返回的数据本接口成功时为 null这一返回结构对应源码中统一的BaseResp基础响应模型HostLockResponse即内嵌BaseResp见 src/common/metadata/hostlock.go是 bk-cmdb 所有 API 的标准响应契约。五、源码级实现原理解锁请求在 CMDB 内部如何流转要深入理解本接口需要看清它从 ESB 网关到 coreservice 再到 MongoDB 的完整链路。以下依据仓库源码还原真实调用过程。5.1 路由注册DELETE /delete/host/lockcoreservice 的 REST 路由注册位于 src/source_controller/coreservice/service/service_initfunc.goutility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /find/host/lock, Handler: s.LockHost}) utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: /delete/host/lock, Handler: s.UnlockHost}) utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /findmany/host/lock/search, Handler: s.QueryLockHost})可以看到解锁删除锁对应的内部路由是DELETE /delete/host/lock处理器为UnlockHost加锁对应POST /find/host/lock查询对应POST /findmany/host/lock/searchESB 网关层cc.yaml暴露的/api/v3/host/lock与 coreservice 内部路径/delete/host/lock之间由 CMDB 开放 API 层做转发映射。5.2 Service 层参数解析与响应封装Service 层的UnlockHost位于 src/source_controller/coreservice/service/hostlock.go// UnlockHost TODO func (s *coreService) UnlockHost(ctx *rest.Contexts) { input : new(metadata.HostLockRequest) if err : ctx.DecodeInto(input); err ! nil { ctx.RespAutoError(err) return } err : s.core.HostOperation().UnlockHost(ctx.Kit, input) if err ! nil { blog.Errorf(UnlockHost failed, unlock host handle failed, err: %s, input:%v, rid:%s, err, input, ctx.Kit.Rid) ctx.RespAutoError(err) return } ctx.RespEntity(nil) }处理流程分三步参数反序列化通过ctx.DecodeInto(input)将请求体 JSON 解析为HostLockRequestid_list被解析到IDS字段解析失败立即返回错误。调用核心逻辑委托s.core.HostOperation().UnlockHost(ctx.Kit, input)执行实际解锁失败时记录错误日志含rid请求链 id并通过ctx.RespAutoError统一封装错误响应。成功响应ctx.RespEntity(nil)返回data: null的成功响应与文档返回示例一致。5.3 Core 层直接删除 cc_HostLock 集合记录真正的数据操作在 src/source_controller/coreservice/core/host/lock.go// UnlockHost TODO func (hm *hostManager) UnlockHost(kit *rest.Kit, input *metadata.HostLockRequest) errors.CCError { conds : mapstr.MapStr{ common.BKHostIDField: mapstr.MapStr{common.BKDBIN: input.IDS}, } conds util.SetModOwner(conds, kit.SupplierAccount) err : mongodb.Client().Table(common.BKTableNameHostLock).Delete(kit.Ctx, conds) if nil ! err { blog.Errorf(unlock host, delete host lock from db error, err: %v, rid:%s, err, kit.Rid) return kit.CCError.CCErrorf(common.CCErrCommDBDeleteFailed) } return nil }关键点解读查询条件构造bk_host_id使用$in操作符匹配id_list中的所有 ID一次 DELETE 批量删除多台主机的锁供应商账户隔离util.SetModOwner(conds, kit.SupplierAccount)在条件中附加bk_supplier_account确保只删除当前供应商账户租户范围内的锁记录多租户之间互不干扰存储表锁数据存放在 MongoDB 的cc_HostLock集合中该表名定义于 src/common/tablenames.goBKTableNameHostLock cc_HostLockbk_host_id字段名定义于 src/common/definitions.go幂等性直接对不存在的记录执行 Delete 不会报错因此即使某主机本就没有锁批量解锁也不会失败——这与加锁接口的幂等行为重复加锁仍提示成功形成对称设计方便业务方无脑解锁错误处理删除失败如数据库异常时返回CCErrCommDBDeleteFailed错误码并记录含rid的日志便于追踪。5.4 锁记录的存储结构cc_HostLock集合中的单条锁记录对应HostLockData结构见 src/common/metadata/hostlock.goJSON 字段bson 字段类型说明bk_userbk_userstring加锁用户bk_host_idbk_host_idint64被锁主机 IDcreate_timecreate_timetime.Time加锁时间UTC隐藏bk_supplier_accountstring供应商账户用于多租户隔离响应中不输出作为对照加锁接口LockHost同文件 lock.go在写入锁前会先校验主机是否真实存在于cc_BaseHost集合不存在的 ID 会报参数错误再逐台检查cc_HostLock是否已有锁记录仅对未加锁的主机插入新记录。由此可总结出主机锁的完整生命周期加锁校验主机存在 → 幂等写入→ 使用中可查询锁归属→ 解锁按主机 ID 批量删除。5.5 apimachinery 客户端封装对于在 Go 服务内直接调用 coreservice 的场景官方提供了 apimachinery 客户端封装见 src/apimachinery/coreservice/host/api.go// UnlockHost TODO func (h *host) UnlockHost(ctx context.Context, header http.Header, input *metadata.HostLockRequest) ( resp *metadata.HostLockResponse, err error) { resp new(metadata.HostLockResponse) subPath : /delete/host/lock err h.client.Delete(). Body(input). SubResourcef(subPath). WithHeaders(header). Do(). Into(resp) return resp, err }该封装通过h.client.Delete()发起DELETE /delete/host/lock请求Body(input)传入HostLockRequest返回HostLockResponse内嵌BaseResp。这也是源码层面对本接口HTTP DELETE JSON 请求体约定的直接印证。六、配套接口与典型使用流程主机锁三个接口在官方文档 docs/apidoc/cc/zh_hans/ 目录下均有对应文档add_host_lock.md 与 delete_host_lock.md英文版见 docs/apidoc/cc/en/delete_host_lock.md。三者配合可形成一套完整的锁管理操作闭环加锁任务开始时调用add_host_lock传入id_list锁定待操作主机即使主机已被锁重复加锁仍返回成功查询需要了解哪些主机被锁、被谁锁、锁了多久时调用search_host_lock查询锁明细返回info列表与count解锁任务结束成功或异常退出后调用delete_host_lock传入同样的id_list批量释放锁避免锁长期滞留。典型代码如下JSON 请求体{ bk_app_code: your_app, bk_app_secret: your_secret, bk_username: your_name, bk_token: your_token, id_list: [101, 102, 103] }建议在自动化脚本中加入defer式或等价的 try/finally解锁逻辑确保任务无论成败都能释放锁。七、常见问题与注意事项权限要求本接口需要业务主机编辑权限权限不足时返回result: false且permission字段携带所需权限信息调用方应据此发起权限申请。版本要求接口自 v3.8.6 起提供低于该版本的环境不保证可用。多租户隔离解锁操作受bk_supplier_account约束不会越租户删除锁记录。幂等语义对未加锁主机执行删除不会报错可放心批量调用。ID 合法性与加锁接口不同解锁接口不会校验id_list中的主机是否真实存在——这是删除操作的常见语义确保没有锁但调用方仍需保证id_list来源可靠避免误删有效锁。错误排查失败时可结合响应中的request_id请求链 id在 coreservice 日志中检索对应rid定位具体失败原因如数据库删除失败CCErrCommDBDeleteFailed。八、小结delete_host_lock是 bk-cmdb 主机锁机制中释放环节的标准接口。通过本文可以掌握接口的 ESB 公共参数与id_list接口参数、标准请求/响应格式、返回字段语义以及从 ESB 网关cc.yaml 的/api/v3/host/lockDELETE到 coreservice 路由DELETE /delete/host/lock再到 MongoDBcc_HostLock集合的完整调用链。结合 hostlock.go、lock.go 与 hostlock.go 三份源码即可在实际业务中安全、批量地完成主机锁的释放操作。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸 CMDB 删除主机锁接口详解delete_host_lock 的参数、响应与源码实现蓝鲸 CMDB 删除主机锁接口详解delete_host_lock 的参数、响应与源码实现 导读 主机锁Host Lock是 BlueKing CMDB后端企业应用运维bk-cmdb 蓝鲸配置平台删除主机锁接口delete_host_lock实战解析bk cmdb 蓝鲸配置平台删除主机锁接口delete_host_lock实战解析 导读 本文详细解析蓝鲸智云配置平台bk cmdb开放网关APIGW后端企业应用运维蓝鲸 CMDB 删除集群接口delete_set实战指南参数详解、调用示例与底层实现原理蓝鲸 CMDB 删除集群接口delete_set实战指南参数详解、调用示例与底层实现原理 本文围绕蓝鲸智云配置平台BlueKing CMDB简称 bk后端企业应用运维上一篇cleos system listproducers 命令详解查询与解读 EOSIO 链上生产者列表下一篇如何永久保存微信聊天记录WeChatMsg完整备份与导出终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
