企业官网建设流程全解析

• 后端
• 企业应用
• 运维

一、接口概览与适用场景

list_host_service_template_id是蓝鲸配置平台（BlueKing CMDB，仓库路径gh_mirrors/bk/bk-cmdb）中用于根据主机 ID 反查其所属服务模板 ID（service_template_id）列表的专用查询接口。该接口承载的是"主机 → 模块 → 服务模板"的链路查询能力，常见于节点管理（NodeMan）等场景：当需要判断一台主机是否纳管了某项服务、或者依据模板维度批量梳理主机归属时，无需逐台拉取主机详情，只需提交一批bk_host_id即可一次拿到对应的模板 ID 集合。

需要特别留意的是，该接口在官方文档中明确标注为节点管理专用接口，可能会随时调整，其他服务请勿使用，且存在版本与权限前提：

• 版本要求：v3.10.11+；
• 权限要求：主机池主机查看权限（Host pool host view permission）；
• 适用范围：单次最多查询200 台主机，超出会被拒绝。

从接口能力上看，它与仓库内 find_host_by_service_template.md（按服务模板查主机）互为逆向操作：一个是"模板 → 主机"，一个是"主机 → 模板"。阅读本文后，读者将掌握该接口的完整调用姿势、参数约束、返回结构，以及其背后的数据链路与实现原理。

二、请求方式与参数说明

2.1 请求路径与调用方式

该接口在 ESB（企业服务总线）侧暴露的映射地址为/v2/cc/find_host_service_template/，内部转发至 CMDB 的dest_path: /api/v3/findmany/hosts/service_template，请求方法为 POST。该映射关系定义在 docs/apidoc/cc/cc.yaml 中（第 1237–1246 行），并在其中标记了is_hidden: true，说明它可以通过 ESB 调用，但不会在 ESB 的接口文档页面中展示——这与"节点管理专用"的定位一致。

在 CMDB 侧，该路由由 host_server 服务注册，见 src/scene_server/host_server/service/service_initfunc.go：

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/findmany/hosts/service_template", Handler: s.ListServiceTemplateIDsByHost})

同时，src/ac/parser/host.go 中将其登记为权限解析规则findHostsServiceTemplatesPattern，参与后续的鉴权匹配。

2.2 公共参数与接口参数

调用该接口需要两类参数：

（1）公共参数（common_args_desc）：即 ESB 级别的认证参数，通常包括：

实际必选组合以部署环境为准，通常为bk_app_code + bk_app_secret（应用级）或bk_username / bk_token（用户级）中的一组。

（2）接口参数（Interface Parameters）：

bk_host_id无默认值，必须显式传入；若传入空数组或超过 200 个，接口会直接报错（详见下文参数校验）。

2.3 请求参数示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_host_id": [ 258, 259 ] }

三、返回结果结构与字段说明

3.1 返回结果示例

{ "result": true, "code": 0, "message": "success", "permission": null, "request_id": "e43da4ef221746868dc4c837d36f3807", "data": [ { "bk_host_id": 258, "service_template_id": [ 3 ] }, { "bk_host_id": 259, "service_template_id": [ 1, 2 ] } ] }

3.2 通用返回字段（response）

3.3 data 明细字段

返回语义上需要注意几点：

• service_template_id是数组而非单个标量。原因是同一台主机可能同时挂载在多个模块下（例如同时存在于多个业务模块），而这些模块分别关联不同的服务模板，因此一台主机可对应多个模板 ID；
• 结果中的service_template_id列表已做去重，同一台主机关联同一模板多次时只保留一个；
• 主机所在的模块如果没有绑定任何服务模板（即service_template_id为 0 的普通模块），则该模块对应的模板 ID 不会出现在结果中；
• 返回的data中每个元素只包含请求过的主机 ID，未请求的主机不会出现。

四、源码级实现原理：主机与服务模板的关联链路

该接口虽然参数简单，但其内部数据链路涉及 CMDB 多个模块的协作。对应核心实现位于 src/scene_server/host_server/service/findhost.go 的ListServiceTemplateIDsByHost，以及 src/scene_server/host_server/logics/host.go 的ListServiceTemplateHostIDMap。

4.1 参数校验：最多 200 台主机

在进入业务逻辑前，ListServiceTemplateIDsByHost首先将请求体解码到input结构体，其中bk_host_id被映射为[]int64：

input := struct { ID []int64 `json:"bk_host_id"` }{} if err := ctx.DecodeInto(&input); err != nil { ... } if len(input.ID) > 200 { ctx.RespAutoError(ctx.Kit.CCError.CCErrorf(common.CCErrCommValExceedMaxFailed, common.BKHostIDField, 200)) return }

超过 200 个主机 ID 时会返回错误码CCErrCommValExceedMaxFailed（定义见 src/common/errInfo.go），错误信息形如bk_host_id field exceeds maximum value 200。

4.2 数据链路：主机关系 → 模块 → 服务模板

ListServiceTemplateHostIDMap是整个查询的核心，其执行链路分三步：

第一步：查询主机-模块关系。构造HostModuleRelationRequest，仅取出bk_module_id与bk_host_id两个字段，调用GetHostRelations获取主机挂载的模块列表（实现见 src/scene_server/host_server/logics/host.go，内部实际经由CoreAPI.CoreService().Host().GetHostModuleRelation访问 coreservice）。

第二步：按模块批量读取service_template_id。收集上一步得到的所有模块 ID，构造QueryCondition对模块实例（common.BKInnerObjIDModule）发起in条件查询，只取bk_module_id与service_template_id两个字段（DisableCounter: true表示不返回总条数），建立moduleID → serviceTemplateID的映射。

第三步：聚合为"主机 → 模板 ID 数组"。遍历主机-模块关系，将同一台主机的多个模块所对应的模板 ID 追加到同一个切片中；当模块的service_template_id为 0（普通模块、未绑定模板）时直接跳过；最终通过util.IntArrayUnique对模板 ID 去重，输出bk_host_id + service_template_id键值对集合：

result := make([]mapstr.MapStr, 0) for host, sv := range hostSvTmp { result = append(result, mapstr.MapStr{ common.BKHostIDField: host, common.BKServiceTemplateIDField: util.IntArrayUnique(sv), }) }

字段常量service_template_id定义在 src/common/definitions.go。该接口全程不直接读服务模板表，而是通过"主机-模块关系表 + 模块实例上的服务模板字段"间接推导，因此返回的是主机当前所处模块所关联的模板，属于实时快照查询。

五、调用注意事项与最佳实践

基于文档约束与源码实现，调用该接口时建议遵循以下实践：

1. 遵守专用接口约束：接口明确为节点管理专用且可能随时调整，业务系统不应将它的返回结构固化为长期依赖；上游 docs/apidoc/cc/cc.yaml 中is_hidden: true也印证了它不对外稳定承诺的特性。
2. 控制批量大小：单次bk_host_id最多 200 个，超出即报错；大批量主机请自行分批（如按 200 个一组切分）再并发或串行调用。
3. 理解去重与空值语义：返回的service_template_id已去重；普通模块（未绑定服务模板）不会产生模板 ID，若某台主机返回空数组，表示其当前模块均未关联任何服务模板。
4. 核对版本与权限：确认环境版本不低于 v3.10.11，且调用方持有主机池主机查看权限；权限规则由 src/ac/parser/host.go 登记，鉴权失败时permission字段会携带需要的权限信息，code对应权限错误码。
5. 善用 request_id 排查：返回的request_id是请求链 ID，可用于跨服务日志串联；CMDB 各服务日志（如 host_server 的blog.Errorf）均携带rid字段，排查超限、模块缺失等问题时可据此定位。

六、相关接口与延伸阅读

该接口属于 CMDB 服务模板（Service Template）接口体系的一员，仓库中与之配套的文档与代码还包括：

• 反向查询（按模板查主机）：find_host_by_service_template.md，对应 CMDB 侧实现FindHostsByServiceTemplates（src/scene_server/host_server/service/findhost.go）；
• 服务模板生命周期管理：create_service_template.md、update_service_template.md、delete_service_template.md、get_service_template.md；
• 服务模板的同步与差异：sync_service_template_to_service_instance.md、list_service_template_difference.md、list_service_template_sync_status.md；
• 接口文档与 ESB 映射关系的整体说明：docs/apidoc/cc/README.md。

如需在本地编译、运行 CMDB 以验证该接口，可参考 docs/overview/source_compile.md 与 docs/overview/installation.md 中的部署指引。

总结

list_host_service_template_id以极小的入参（仅bk_host_id数组）完成了"主机 → 服务模板"的批量反查，其内部通过"主机-模块关系 → 模块实例上的服务模板字段 → 去重聚合"三层链路实现，既体现了 CMDB 主机与模板之间多对多的真实数据模型，也暴露了 200 台上限、专用接口等使用约束。在节点管理及模板驱动的场景中，理解该接口的语义与边界，有助于准确、高效地完成主机模板归属梳理与批量判断。

• 后端
• 企业应用
• 运维