后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读push_host_identifier是蓝鲸智云配置平台bk-cmdb提供的推送主机身份信息到机器的 OpenAPI。调用该接口后平台会通过 GSE 将主机身份文件下发到目标机器的 agent 目录中并返回 GSE 侧的任务 ID供调用方后续到 GSE 查询推送结果。本文以官方 API 文档为骨架结合src/scene_server/event_server模块的源码实现与配置文件模板完整讲解接口的请求/响应协议、权限模型、数量限制、底层调用链路以及与之配套的任务结果查询与后台同步机制帮助你准确调用并深入理解主机身份下发的全流程。接口概述与适用场景主机身份Host Identifier是 CMDB 中主机在 GSE 侧的唯一标识文件。当主机初始化、agent 重建或需要重新对齐主机身份时需要将身份信息以文件形式下发到机器上供 GSE agent 读取从而建立CMDB 主机 ↔ GSE 托管机器的映射关系。接口路径POST /api/v3/event/push/host_identifier对应 OpenAPI 操作push_host_identifier该路由注册于 service.go版本要求v3.10.18返回内容本次推送任务在 GSE 侧的task_id调用方可凭该 ID 到 GSE 查询任务推送结果也可使用 CMDB 配套的find_host_identifier_push_result接口查询见下文权限要求对于业务内主机需要业务访问权限对于主机池资源池中的主机需要主机池主机编辑权限。从源码看该权限校验由 sync.go 中的authByHostIDs实现它先通过GetHostModuleRelation查询每个主机所属业务再调用 CMDB 权限中心区分处理——业务主机走AuthorizeByBusinessID业务访问权限资源池主机走AuthorizeByHostsIDs主机更新/编辑权限与文档描述完全一致。输入参数参数名称参数类型必选描述bk_host_idsarray是主机 id 数组数量不能超过 200该上限由常量BKMaxSyncIdentifierLimit 200定义见 definitions.go。对应的请求体结构体与校验逻辑位于 hostserver.go请求体被解析为metadata.HostIDArray字段名bk_host_idsValidate()校验两条规则bk_host_ids不能为空数组且长度不得超过 200否则分别返回参数无效CCErrCommParamsIsInvalid与超限CCErrCommXXExceedLimit错误见 hostserver.go。在接口处理器中该校验在参数解码后立即执行sync.go因此超量提交会在进入任何业务逻辑前被拦截。调用示例{ bk_host_ids: [1, 2] }响应示例与响应参数说明响应示例{ result: true, code: 0, msg: success, permission: null, data: { task_id: GSETASK:F:202206222053523618521052:393, host_infos: [ { bk_host_id: 2, identification: 0:127.0.0.1 } ] } }响应参数说明参数名称参数类型描述resultbool请求成功与否。true:请求成功false 请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据data 字段说明参数名称参数类型描述task_idstring任务 id此 id 为 GSE 侧的 task_idhost_infosarray任务中推送的主机信息只包含成功推送的信息host_infos 字段说明参数名称参数类型描述bk_host_idint主机 ididentificationstring推送的主机在任务中对应的标识响应结构对应源码中的metadata.SyncIdentifierResult与metadata.HostBriefInfo定义见 eventserver.go其中host_infos中的identification即主机标识格式为cloudID:innerIP例如0:127.0.0.1由HostKey(cloudID, hostIP)生成实现见 common.go。需要特别注意的是host_infos只包含成功推送的主机信息。因为处理器在执行推送前会先查询各主机的 agent 状态agent 处于 off 状态的主机会被过滤掉不会出现在返回列表中相关过滤逻辑见 hostIdentifier.go 的getV2OnStatusAgent/getV1OnStatusAgent。接口完整调用流程源码级push_host_identifier的 HTTP 处理函数为PushHostIdentifier完整实现见 sync.go。其处理链路依次为开关检查若 eventServer 未启用主机身份功能SyncData nil直接返回错误CCErrEventSyncHostIdentifierDisabled错误码 1103011见 errInfo.go参数解码与校验解析bk_host_ids并调用HostIDArray.Validate()权限校验在启用鉴权auth.EnableAuthorize()时执行authByHostIDs查询主机信息通过CoreService().Host().ListHosts批量拉取主机的bk_host_id、bk_host_innerip、bk_cloud_id、bk_addressing、bk_agent_id字段sync.go批量同步调用BatchSyncHostIdentifier(hosts, true, ...)其中第二个参数isApitrue表示本次调用来源于 API会以更严格的语义处理异常如身份文件超限时直接报错而非跳过缓存任务以host_identifier:task:taskID为 Key将任务写入 RedisTTL 为 30 分钟sync.go组装响应遍历任务中的主机构造identificationcloudID:innerIP并返回SyncIdentifierResult。说明该 30 分钟 Redis 缓存正是配套接口find_host_identifier_push_result能只能获取到 30 分钟内推送的任务情况的原因所在详见下文配套接口。底层实现BatchSyncHostIdentifier与 GSE 推送链路BatchSyncHostIdentifier是推送的核心方法位于 hostIdentifier.go分为三大步骤第一步查询主机 agent 状态。构造StatusReq含bk_agent_id、bk_cloud_id、bk_host_innerip、bk_addressing调用 GSE 查询 agent 在线状态。实现同时兼容两代 GSE 协议hostIdentifier.goV1 协议version: v1走 thrift 方式连接 GSE 的apiServer/taskServer按cloudID:innerIP查询V2 协议version: v2走 GSE 2.0 的 apigw 接口优先按bk_agent_id查询无 agentID 的静态寻址主机则退化为cloudID:innerIP构造 agentID 查询无论哪种协议失败均会重试最多retryTimes 10次每次重试前sleepForFail递增等待。第二步筛选在线主机。仅保留 agent 状态为 on 的主机V1 中bk_agent_alive 1V2 中状态码为2并建立hostID → agentID(或IP)的映射关系用于后续任务结果回查。第三步查询主机身份并推送。通过CoreService().Host().FindIdentifier查询主机身份 JSON然后按操作系统选择推送文件配置hostIdentifier.go身份文件内容为 JSON若序列化后超过fileLimit 102400字节100KBAPI 场景直接报错返回common.goV1 场景调用 GSE taskServer 的PushFileV2thrift 接口V2 场景调用 apigw 的AsyncPushFileAutoMkdir: true, TimeoutSeconds: 1000两者同样带 10 次重试task.go推送成功后将Task{TaskID, HostInfos, ExpiredTime}写入 Redis 的任务队列host_identifier:task_list任务的过期时间设置为 50 分钟task.go。支撑后台watch 增量同步、全量同步与失败重试除了 API 手动触发外eventServer 还内置了三个后台任务自动维护主机身份的一致性全部由 server.go 在服务启动时拉起后台任务入口方法职责增量监听WatchToSyncHostIdentifier监听主机事件新增/变更将身份变化实时推送到对应机器周期全量CycleSyncIdentifier→FullSyncHostIdentifier每隔batchSyncIntervalHours小时按每批 200 台全量重推一遍所有主机身份结果回查GetTaskExecutionStatus从 Redis 任务队列取出任务到 GSE 查询执行结果失败重推LaunchTaskForFailedHost将推送失败的主机从失败队列取出重新构造新任务推送几个值得注意的实现细节主从协调以上任务都先通过engine.Discovery().IsMaster()判断本节点是否为 master非 master 节点会跳过循环server.go避免多实例重复推送失败补偿任务结果回查时结果缺失或仍处于执行中Handling 115的主机会让任务重回队列继续等待直至超过 50 分钟过期最终失败的主机会写入 Redis 的host_identifier:fail_host_list失败队列最多重试 10 次retryTimes超过上限后不再处理task.go 与 task.go限流保护推送与查询均受RateLimiter{Qps, Burst}控制通过AcceptMany批量放行hostIdentifier.go可观测性整个链路注册了 Prometheus 指标包括cmdb_sync_data_get_agent_status_total、cmdb_sync_data_push_file_total、cmdb_sync_data_get_result_total、cmdb_sync_data_host_agent_status_total、cmdb_sync_data_host_result_total以及失败队列/任务队列长度的 GaugehostIdentifier.go。相关配置项eventServer.hostIdentifier推送功能的行为由配置文件中的eventServer.hostIdentifier段控制完整模板见 server#conf#common.yaml对应的解析代码见 config.go配置项类型说明startUpbool是否开启下发主机身份功能true 开启、false 关闭。关闭后调用本接口会返回同步主机身份功能未开启错误versionstring可选v1或v2。v1 用 thrift 方式连接 GSE需配置gse.apiServer与gse.taskServerv2 走 GSE 2.0 apigw 接口需配置 apiGW 地址batchSyncIntervalHoursint全量同步周期单位小时默认 6。服务启动后会等待一个完整周期再执行首次全量rateLimiter.qpsint推送限流 QPS默认 200代表每秒最多推送的主机数量rateLimiter.burstint限流突发容量默认 200fileNamestring下发主机身份的文件名默认hostidlinux.filePathstringLinux 主机身份文件路径模板占位符__BK_GSE_SYNCDATA_LINUX_HOSTID_DIR__由部署脚本替换linux.fileOwnerstringLinux 文件所有者默认rootlinux.filePrivilegeintLinux 文件权限值默认644windows.filePathstringWindows 主机身份文件路径模板占位符__BK_GSE_SYNCDATA_WINDOWS_HOSTID_DIR__windows.fileOwnerstringWindows 文件所有者windows.filePrivilegeintWindows 文件权限值源码中还有两个与文件下发相关的细节Windows 且使用 1.0 agent以cloudID:ip形式寻址的机器文件 owner 会被强制设为root常量v1AgentFileOwner见 hostIdentifier.go以兼容 1.0 agent 的文件路由V1 推送时会在文件名后追加.bak作为备份名MBackupName见 hostIdentifier.go。配套接口查询推送结果push_host_identifier返回的task_id可用于 GSE 侧查询在 CMDB 侧则使用配套接口find_host_identifier_push_resultPOST /api/v3/event/find/host_identifier_push_resultv3.10.23。输入task_id返回success_list、failed_list、pending_list三组主机 ID 列表详见 find_host_identifier_push_result.md。其实现为GetHostIdentifierPushResultsync.go先从 Redis 中按host_identifier:task:taskID读取 30 分钟内的任务快照——若缓存已过期即任务超过 30 分钟将无法查询到结果再到 GSE 拉取任务执行结果按 agentID或cloudID:innerIP匹配主机无结果或仍在执行中Handling 115的主机归入pending_listCCSuccess归入success_list其余归入failed_list。因此一次完整的主机身份推送通常遵循push 获取 task_id → find 轮询结果的组合用法推送后立即查询可能大量主机处于pending_list建议稍等片刻再次查询。注意事项与常见问题数量上限bk_host_ids最多 200 个超出将返回参数超限错误权限前置业务主机需业务访问权限资源池主机需主机编辑权限混合提交时两者都会被校验只返回成功主机agent 离线的主机不会出现在host_infos中不要将host_infos数量与bk_host_ids数量直接对比来判断失败结果查询时效CMDB 侧结果缓存 30 分钟GSE 侧任务过期时间为 50 分钟超出时效后结果不可用需重新触发推送功能开关若 eventServer 未开启hostIdentifier.startUp接口将直接返回错误码 1103011需在配置模板中确认该开关为true多 IP 主机实现会对多 IP 主机逐个 IP 查询 agent 状态只要其中一个 IP 在线即视为在线common.go。总结push_host_identifier是 CMDB 与 GSE 协同下发主机身份的标准化入口其背后由 eventServer 的 API 触发 watch 增量 周期全量 失败补偿四层机制共同保障。理解其请求/响应协议、200 台上限、双版本 GSE 协议差异以及 30 分钟结果缓存的时效约束即可在业务场景中准确使用该接口完成主机身份的批量下发与结果追踪。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台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后端企业应用运维蓝鲸智云配置平台bk-cmdb全量同步缓存条件查询接口list_full_sync_cond_for_cache深度解析蓝鲸智云配置平台bk cmdb全量同步缓存条件查询接口list_full_sync_cond_for_cache深度解析 导读 本文围绕蓝鲸智云配置平台后端企业应用运维上一篇终极指南如何使用 React Native Reanimated 实现流畅布局动画下一篇解决99%的问题WinApps常见错误与故障排除完全手册创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考