后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文以蓝鲸智云配置平台BlueKing CMDBbk-cmdb开放 API 文档docs/apidoc/apigw/open/en/add_host_lock.md为核心系统讲解「锁定主机Lock hosts」接口的调用方式、参数约束、响应格式并结合开源仓库源码剖析其幂等实现、事务处理与权限校验链路。读者读完可准确调用该接口实现主机批量锁定并理解锁定数据在cc_HostLock表中的存储形态为上层运维流程如变更保护、故障隔离提供可靠依据。一、接口功能与适用场景锁定主机是 CMDB 对主机实例提供的一种保护性操作调用方传入一批主机 ID即可为这些主机添加锁定标记。被锁定的主机在业务层面通常意味着禁止变更、禁止回收、暂停操作常用于变更窗口期的主机保护防止自动化流程误操作故障主机隔离标记后避免被纳入正常调度资源生命周期管理锁定待下线/待回收资源。该接口的官方定义源自 add_host_lock.md明确指出Lock hosts based on a list of host IDs. For newly added hosts, if the host has already been locked, it will also indicate successful locking。即接口按主机 ID 列表锁定主机对于新加入列表的主机即使其此前已经被锁定接口依然返回锁定成功——这是理解该接口幂等语义的关键详见下文第六节。二、接口基本信息项目内容接口名称add_host_lock锁定主机引入版本v3.8.6所需权限业务主机编辑权限Business host editing permission请求方式POST请求路径/api/v3/host/lock从源码看该路径在 host_server 服务初始化 中注册utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /host/lock, Handler: s.LockHost}) utility.AddHandler(rest.Action{Verb: http.MethodDelete, Path: /host/lock, Handler: s.UnlockHost}) utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: /host/lock/search, Handler: s.QueryHostLock})权限控制方面ac/parser/host.go 中针对/api/v3/host/lockPOST 锁定、DELETE 解锁与/api/v3/host/lock/search查询均配置了主机实例资源的鉴权过滤而 service/hostlock.go 中通过AuthorizeByHostsIDs校验「编辑」动作权限无权限时返回ac.NoAuthorizeError及无权限提示信息对应文档所述的业务主机编辑权限。三、请求参数详解3.1 参数总览名称类型必填说明id_listint 数组是主机 ID 列表Host IDs3.2 参数约束源码级验证请求体在服务端被反序列化为metadata.HostLockRequest其定义见 src/common/metadata/hostlock.gotype HostLockRequest struct { IDS []int64 json:id_list }服务入口 LockHost 对参数做了第一层校验input : metadata.HostLockRequest{} if err : ctx.DecodeInto(input); nil ! err { ctx.RespAutoError(err) return } if 0 len(input.IDS) { blog.Errorf(lock host, id_list is empty,input:%v, rid:%s, input, ctx.Kit.Rid) ctx.RespAutoError(ctx.Kit.CCError.Errorf(common.CCErrCommParamsNeedSet, id_list)) return }由此可确认两个硬性约束id_list不能为空空数组会直接返回参数错误错误码CCErrCommParamsNeedSet提示字段为id_list元素类型为整数int64非整数会导致 JSON 反序列化失败同样走RespAutoError分支返回错误重复 ID 会被自动去重核心实现中首先执行input.IDS util.IntArrayUnique(input.IDS)见 core/host/lock.go因此传入[1, 1, 2]与[1, 2]效果等价。四、请求示例按照开放 API 文档请求体为一个包含id_list字段的 JSON 对象{ id_list:[1, 2, 3] }实际调用POST:POST /api/v3/host/lock Content-Type: application/json { id_list:[1, 2, 3] }五、响应示例与响应参数5.1 响应示例成功响应与文档一致{ result: true, code: 0, message: success, data: null, permission: null }5.2 响应参数说明名称类型说明resultbool请求是否成功。true成功false失败codeint错误码。0 表示成功0 表示失败的具体错误码messagestring请求失败时返回的错误信息dataobject请求返回的数据本接口成功时为 nullpermissionobject权限信息需要注意文档中的响应示例将data置为null这与服务端实现一致——LockHost 服务处理函数 在成功时调用ctx.RespEntity(nil)返回空数据核心层 coreservice 的 LockHost 同样以ctx.RespEntity(nil)结束因此data字段为空是正常预期业务方无需解析该字段。若请求失败code将返回非 0 错误码message携带具体错误描述。常见的失败场景包括id_list为空、主机 ID 不存在见第六节、鉴权失败无业务主机编辑权限等。六、底层实现原理幂等、存在性校验与事务6.1 调用链全景锁定主机请求在微服务架构中经历三层调用host_server 服务层service/hostlock.go解析参数、校验权限、开启事务host_server 逻辑层logics/hostlock.go通过CoreService().Host().LockHost发起对 coreservice 的 HTTP 调用coreservice 核心层core/host/lock.go直接操作 MongoDB完成实际的锁定写入。其中逻辑层封装如下func (lgc *Logics) LockHost(kit *rest.Kit, input *metadata.HostLockRequest) errors.CCError { hostLockResult, err : lgc.CoreAPI.CoreService().Host().LockHost(kit.Ctx, kit.Header, input) if nil ! err { ... return kit.CCError.Error(common.CCErrCommHTTPDoRequestFailed) } if !hostLockResult.Result { ... return kit.CCError.New(hostLockResult.Code, hostLockResult.ErrMsg) } return nil }6.2 幂等语义已锁定主机重复锁定仍返回成功文档强调if the host has already been locked, it will also indicate successful locking其实现位于 core/host/lock.go核心层先按主机 ID 查询cc_HostLock表中是否已存在锁定记录仅对未锁定的主机追加写入for _, id : range input.IDS { conds : mapstr.MapStr{ common.BKHostIDField: id, } conds util.SetQueryOwner(conds, kit.SupplierAccount) cnt, err : mongodb.Client().Table(common.BKTableNameHostLock).Find(conds).Count(kit.Ctx) ... if 0 cnt { insertDataArr append(insertDataArr, metadata.HostLockData{ User: user, ID: id, CreateTime: ts, OwnerID: httpheader.GetSupplierAccount(kit.Header), }) } }也就是说对已锁定主机跳过写入但不报错接口整体仍返回成功实现重复锁定幂等。6.3 主机存在性校验在写入锁定之前核心层会先校验主机是否真实存在core/host/lock.gocondition : mapstr.MapStr{ common.BKHostIDField: mapstr.MapStr{common.BKDBIN: input.IDS}, } condition util.SetQueryOwner(condition, kit.SupplierAccount) hostInfos : make([]metadata.HostMapStr, 0) err : mongodb.Client().Table(common.BKTableNameBaseHost).Find(condition). Fields(common.BKHostIDField).Limit(limit).All(kit.Ctx, hostInfos) ... diffID : diffHostLockID(input.IDS, hostInfos, kit.Rid) if 0 ! len(diffID) { blog.Errorf(lock host, not found, id: %v, rid: %s, diffID, kit.Rid) return kit.CCError.Errorf(common.CCErrCommParamsIsInvalid, fmt.Sprintf( id_list %v, diffID)) }diffHostLockID同文件 L121-L139将请求 ID 与基础主机表cc_HostBase中实际存在的主机 ID 求差集只要存在任意一个主机 ID 在 CMDB 中不存在整个请求即失败并在错误信息中明确指出不存在的主机 ID。因此调用方需确保传入的 ID 均为主机表内有效 ID。6.4 事务保证服务层将核心写入包在事务中执行service/hostlock.gotxnErr : s.Engine.CoreAPI.CoreService().Txn().AutoRunTxn(ctx.Kit.Ctx, ctx.Kit.Header, func() error { err : s.Logic.LockHost(ctx.Kit, input) if nil ! err { return err } return nil }) if txnErr ! nil { ctx.RespAutoError(txnErr) return } ctx.RespEntity(nil)任何一步失败都会触发事务回滚保证校验—写入过程的一致性。七、锁定数据的存储结构锁定记录存储在 MongoDB 集合cc_HostLock中表名常量定义见 src/common/tablenames.goBKTableNameHostLock cc_HostLock单条锁定记录metadata.HostLockData见 src/common/metadata/hostlock.go包含四个字段字段bson/json类型说明bk_host_idint64被锁定主机 IDbk_userstring发起锁定操作的用户create_timetime.Time锁定创建时间UTCbk_supplier_accountstring供应商账号多租户隔离字段存储层写入时core/host/lock.go用户信息取自请求 Headerhttpheader.GetUser时间统一取time.Now().UTC()并以SetQueryOwner/SetModOwner注入供应商账号实现多租户数据隔离。该表由升级脚本自动创建并维护索引。升级代码见 upgrader/y3.9.202010211805/add_host_lock_table.go若表不存在则创建并为bk_host_id建立名为bk_host_id_1的非唯一索引。索引的规范化注册见 src/common/index/collections/hostlock.go方便按主机 ID 快速查询锁定状态。八、配套接口解锁与锁定查询该接口同属主机锁定 API 组配套两个接口共同构成完整的锁定管理能力路由注册见 service_initfunc.go操作方法路径服务处理函数锁定主机本接口POST/api/v3/host/lockLockHost解锁主机DELETE/api/v3/host/lockUnlockHost查询主机锁定状态POST/api/v3/host/lock/searchQueryHostLock解锁同样接收id_list参数从cc_HostLock表批量删除锁定记录core/host/lock.go权限校验与事务机制与锁定一致查询返回每个主机 ID 的锁定状态map[int64]bool逻辑层 logics/hostlock.go 将未锁定主机置为false、已锁定主机置为true。这三者共享同一套鉴权业务主机编辑权限与数据模型cc_HostLock建议联动使用。九、调用注意事项必填且非空id_list为必填字段空数组会返回参数校验错误ID 必须真实存在任一主机 ID 不存在即整体失败且错误信息会列出不存在的 ID建议调用前先通过主机查询接口确认 ID 有效性幂等友好重复锁定已锁定主机不会报错可安全重试权限前置调用方需具备对应业务的主机编辑权限无权限时返回permission信息ac.NoAuthorizeError版本门槛该接口自 v3.8.6 起提供低版本环境不适用多租户隔离锁定记录按bk_supplier_account隔离跨供应商账号的 ID 校验与写入互不影响。综合来看add_host_lock 是 CMDB 主机保护机制的基础 API其幂等写入、存在性校验、事务封装与多租户隔离的实现均可在 src/scene_server/host_server/service/hostlock.go、src/source_controller/coreservice/core/host/lock.go 与 src/common/metadata/hostlock.go 中追溯验证是理解 CMDB 主机域写入类接口设计范式的良好范例。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸智云配置平台 bk-cmdb 主机身份查询接口 search_hostidentifier 实战指南蓝鲸智云配置平台 bk cmdb 主机身份查询接口 search_hostidentifier 实战指南 本指南以蓝鲸智云配置平台bk cmdb对外 API后端企业应用运维蓝鲸配置平台bk-cmdb主机身份下发push_host_identifier 接口原理与实战指南蓝鲸配置平台bk cmdb主机身份下发push_host_identifier 接口原理与实战指南 导读 主机身份host identifier是蓝鲸后端企业应用运维蓝鲸配置平台 BK-CMDB 主机身份推送结果查询接口 find_host_identifier_push_result 实战指南蓝鲸配置平台 BK CMDB 主机身份推送结果查询接口 find_host_identifier_push_result 实战指南 导读 find_host_i后端企业应用运维上一篇Hudi Notebooks 实战指南基于 Docker Compose 搭建 Spark Hudi MinIO Hive Metastore 数据湖开发环境下一篇缠论分析终极指南5分钟掌握ChanlunX通达信插件免费开源方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
