蓝鲸配置平台（bk-cmdb）推送主机身份接口详解：push_host

后端
企业应用
运维

【免费下载链接】bk-cmdb

蓝鲸智云配置平台(BlueKing CMDB)

项目地址：https://gitcode.com/gh_mirrors/bk/bk-cmdb

本文以蓝鲸智云配置平台（bk-cmdb）官方 API 文档 push_host_identifier 为主体，结合仓库源码与配置模板，系统讲解「向目标机器推送主机身份信息」这一能力的调用方式、返回结构、权限要求与底层实现链路。读完本文，你将掌握该接口的完整请求/响应契约、bk_host_ids数量限制与identification字段的取值规则，并理解其背后如何联动事件服务器（event_server）与 GSE 完成身份文件的下发与任务追踪。

一、接口能力与适用场景

push_host_identifier的核心能力是：把 CMDB 中一台（或多台）主机的身份信息推送到机器本机，并返回本次推送对应的 GSE 任务 ID（task_id）。调用方拿到这个 GSE 任务 ID 后，可以到 GSE 侧查询该推送任务的执行结果，也可以使用仓库中配套的 find_host_identifier_push_result 接口在 CMDB 内直接查询推送结果。

典型应用场景包括：

主机迁移、跨云区域调度后，需要及时把最新的主机身份同步到机器上，保证本机hostid文件与 CMDB 记录一致；
业务在初始化或故障恢复流程中，批量触发主机身份重推；
与 GSE 生态联动：推送动作本身由 GSE 的 taskServer / API 网关执行，CMDB 负责“组卷”与结果回收。

该接口在v3.10.18+版本提供。权限要求为：当目标主机位于业务内时，需要业务访问权限；当目标主机位于主机池（资源池）时，需要主机池主机编辑权限（实现上对应源码中的authByHostIDs分支，详见下文）。

二、请求参数与调用示例

1. 接口参数

字段	类型	必选	描述
`bk_host_ids`	array	是	主机 ID 数组，数量不能超过 200

单次最多推送 200 台主机，这是服务端强校验的硬性限制：在 sync.go 中，请求体被解析为metadata.HostIDArray后立即调用hostIDArray.Validate()校验，超限会直接返回参数非法错误。

2. 请求参数示例（ESB 网关风格）

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_host_ids": [1, 2] }

其中bk_app_code、bk_app_secret、bk_username、bk_token为公共鉴权参数（common_args_desc），bk_host_ids为接口专属参数。

3. 返回结果示例

{ "result": true, "code": 0, "msg": "success", "permission": null, "request_id": "c11aasdadadadsadasdadasd1111ds", "data": { "task_id": "GSETASK:F:202206222053523618521052:393", "host_infos": [ { "bk_host_id": 2, "identification": "0:127.0.0.1" } ] } }

4. 返回字段说明

response 通用结构

字段	类型	描述
`result`	bool	请求是否成功。`true`成功；`false`失败
`code`	int	错误编码。`0`表示 success，`>0`表示失败错误码
`message`	string	请求失败时返回的错误信息
`permission`	object	权限信息（鉴权失败时返回具体所需权限）
`request_id`	string	请求链 ID，用于全链路问题追踪
`data`	object	请求返回的数据

data 字段

字段	类型	描述
`task_id`	string	任务 ID，此 ID 即 GSE 侧的`task_id`
`host_infos`	array	本次任务中推送的主机信息，只包含成功推送的主机

host_infos 字段

字段	类型	描述
`bk_host_id`	int	主机 ID
`identification`	string	推送的主机在任务中对应的标识

identification的取值规则可在源码中找到依据：在 task.go 中，HostInfo的AgentID字段注释明确说明——对于 1.0 的 agent 为cloudID:innerIP格式，对于 2.0 的 agent 为bk_agent_id。上述示例中0:127.0.0.1即表示云区域 ID 为0、内网 IP 为127.0.0.1的 1.0 agent 主机；而在 sync.go 的PushHostIdentifier中，HostBriefInfo的Identification直接取hostidentifier.HostKey(cloudID, innerIP)，即"0:127.0.0.1"这种“云区域:IP”组合形式。

三、接口在 CMDB 中的路由与调用链

1. 服务注册位置

推送主机身份接口由**事件服务器（event_server）**提供，路由注册于 service.go：

POST /event/v3/sync/host_identifier→SyncHostIdentifier（同步并等待结果）
POST /event/v3/push/host_identifier→PushHostIdentifier（异步推送，返回 GSE 任务 ID，即本文主角）
POST /event/v3/find/host_identifier_push_result→GetHostIdentifierPushResult（查询推送结果）

2. 后端核心处理流程

PushHostIdentifier的完整链路（sync.go）大致分为四步：

校验与鉴权：解析HostIDArray并Validate()；若开启权限中心（auth.EnableAuthorize()），调用authByHostIDs校验权限——业务内主机走AuthorizeByBusinessID（业务访问权限），资源池主机走AuthorizeByHostsIDs（更新权限），与文档声明的权限要求一一对应；
拉取主机信息：getHostInfo通过ListHosts查询主机 ID、内网 IP、云区域 ID、寻址方式（bk_addressing）与bk_agent_id等字段；
批量推送：调用SyncData.BatchSyncHostIdentifier(hosts.Info, true, ...)构造推送任务并调用 GSE 下发，返回task_id；
缓存任务并返回：以host_identifier:task:为前缀、task_id为 Key，把任务写入 Redis（TTL 30 分钟），随后把成功推送的主机列表组装成SyncIdentifierResult（含task_id与host_infos）返回给调用方。

也就是说，响应中的host_infos来源于 GSE 实际接受下发的机器集合，因此“只包含成功推送的主机”，未成功下发（例如 agent 不在线）的主机不会出现在列表中。

3. 身份信息从哪来：coreservice 的 HostIdentifier

推送前需要先“生成主机身份”。事件服务器通过CoreService().Host().FindIdentifier调用 coreservice 的Identifier接口（注册见 host.go），其实现位于 identifier/identifier.go：

findHost：按bk_host_id从bkcc_host表查询主机基础字段（含bk_cloud_id、bk_host_innerip、bk_os_type、bk_agent_id、bk_addressing等）；
findModuleHostRelation：查询主机与模块的挂载关系（bkcc_module_host_config），进而得到业务、集群、模块归属；
findHostServiceInst：通过bkcc_process_instance_relation、bkcc_service_instance、bkcc_process关联出主机上运行的进程信息；
findHostTopoInfo/findHostLayerInfo：基于主线模型关联（bkcc_objasst）向上回溯自定义层级，构建Layer树；
build：把业务/集群/模块/自定义层级/进程组装进HostIdentifier结构并序列化，最终得到下发到机器上的身份文件内容。

最终下发的身份 JSON 结构由 metadata/inst.go 中的HostIdentifier定义：包含bk_host_id、bk_cloud_id、bk_host_innerip、bk_os_type、bk_supplier_account、associations（主机在各层级的归属与自定义层级layer链）、process（进程信息）、bk_agent_id与bk_addressing。

四、GSE 推送任务与结果回收机制

1. 两种 GSE 连接方式（v1 / v2）

事件服务器根据配置中的eventServer.hostIdentifier.version选择 GSE 交互方式（配置解析见 config.go）：

v1：使用 thrift 方式连接 GSE 的apiServer/taskServer，走push_file_forsyncdata通道；
v2：使用 GSE 2.0 的 API 网关（apigw）接口，如AsyncPushFile异步下发。

推送任务在 task.go 的pushFile中落地：调用 GSE 下发接口拿到task_id后，把Task{task_id, host_infos, expired_time}写入 Redis 的任务队列host_identifier:task_list，由后台协程持续跟进。

2. 任务结果的跟踪与失败重试

后台存在三个常驻循环（hostIdentifier.go）：

WatchToSyncHostIdentifier：监听主机事件（watch），增量推送身份；
FullSyncHostIdentifier：按batchSyncIntervalHours周期全量同步；
GetTaskExecutionStatus+LaunchTaskForFailedHost：轮询任务结果，超时（50 分钟）或失败的主机进入 Redis 失败队列host_identifier:fail_host_list，按最多retryTimes = 10次重试。

查询结果接口 find_host_identifier_push_result 正是利用 30 分钟 TTL 内缓存的Task，从 GSE 获取每个主机的下发结果，归类为success_list、failed_list与pending_list（GSE 已受理但尚未回执的主机）。

3. 下发文件形态：hostid 文件配置

身份信息通过“下发文件”的方式落到机器上，文件名为hostid，其落盘路径、属主与权限在 common.yaml 模板中配置：

eventServer: hostIdentifier: startUp: true # 是否开启下发主机身份功能 version: __BK_GSE_AGENT_VERSION__ # v1(thrift) 或 v2(apigw) batchSyncIntervalHours: 6 # 全量同步周期（小时） rateLimiter: qps: 200 # 每秒最多推送的主机数 burst: 200 # 突发容量 fileName: "hostid" # 下发文件名 linux: filePath: __BK_GSE_SYNCDATA_LINUX_HOSTID_DIR__ fileOwner: "root" filePrivilege: 644 windows: filePath: __BK_GSE_SYNCDATA_WINDOWS_HOSTID_DIR__ fileOwner: "SYSTEM" filePrivilege: 644

注意源码中的一处平台差异处理：在 hostIdentifier.go 中，若为 Windows 系统且通过cloudID:ip方式下发（即安装了 1.0 agent 的 Windows 机器），文件属主会被强制设置为root（v1AgentFileOwner），以保证 1.0 agent 能读取该文件。文件内容超过fileLimit限制时，API 调用会被拒绝（返回file exceed limit错误）。

五、使用建议与注意事项

控制批量大小：单次bk_host_ids最多 200 台，超限会直接报参数错误；大批量场景建议分批调用；
先确认 agent 在线：推送只对 agent 状态为on的主机生效（见 hostIdentifier.go 中getOnStatusAgent的状态过滤逻辑），离线主机会被跳过且不会出现在host_infos中，最终由失败重试机制兜底；
权限规划：业务内主机要求业务访问权限，主机池主机要求主机池主机编辑（更新）权限，权限中心开启时按此鉴权；
结果查询时效：任务缓存 TTL 为 30 分钟，查询推送结果请在此窗口内进行（find_host_identifier_push_result 也限定只能获取 30 分钟内推送的任务情况）；若需跨窗口追踪，可使用task_id直接到 GSE 侧查询；
版本前提：本接口自 v3.10.18 起提供，结果查询接口自 v3.10.23 起提供，使用前请确认部署版本。