bk-cmdb 接口深度解析:按点分五位查询进程实例相关信息(ListProcessRelatedInfo)
bk-cmdb 接口深度解析:按点分五位查询进程实例相关信息(ListProcessRelatedInfo)
导读
本文深入讲解蓝鲸智云配置平台(bk-cmdb)进程管理模块中的 ListProcessRelatedInfo 接口:如何按"业务 → 集群 → 模块 → 服务实例 → 进程"的点分五位维度组合过滤,一次请求同时拿到进程本身、所属集群、模块、主机、服务实例与进程模板的关联信息。该接口自 v3.9.13 引入,专供 GSEKit 使用,本文除给出完整可用的请求/响应示例与字段字典外,还结合 proc_server 源码逐段还原其内部五段式查询调用链,帮助读者理解接口的过滤语义、分页限制与字段裁剪机制,可直接用于接入、二次开发与排障。
接口概述与适用场景
ListProcessRelatedInfo 对应文档见 英文版 与 中文版,其功能是"点分五位查询进程实例的相关信息(v3.9.13)"。文档中明确说明:
- 该接口专供 GSEKit 使用,在 ESB 文档中为
hidden状态,不对外常规开放; - 用途是按集群(set)、模块(module)、服务实例(service instance)、进程(process)等维度组合条件,一次性查询满足条件的进程实例,并连带返回其所在集群、模块、主机、服务实例、进程模板等上下文信息。
与常规"按进程 ID 查详情"类接口相比,该接口的价值在于关联信息的聚合:响应中每个进程实例都带有 set、module、host、service_instance、process_template、process 六层嵌套结构,一次调用即可构建出进程在业务拓扑中的完整位置,非常适合 GSEKit 这类需要"按进程名/别名聚合管理多个主机上的进程"的场景。
请求路径与权限控制
路由与 HTTP 方法
接口的网关路径为 POST /api/v3/findmany/proc/process_related_info/biz/{bk_biz_id},bk_biz_id 以 URL 路径参数形式传入。路由注册代码位于 src/scene_server/proc_server/service/service.go:
utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/findmany/proc/process_related_info/biz/{bk_biz_id}",
Handler: ps.ListProcessRelatedInfo})
鉴权与资源模型
proc_server 的请求会经过鉴权解析。在 src/ac/parser/processinstance.go 中注册了该接口的 IAM 权限匹配规则:
{
Name: "listProcessRelatedInfo",
Description: "点分五位查询进程实例相关的信息",
Regex: regexp.MustCompile(`^/api/v3/findmany/proc/process_related_info/biz/([0-9]+)/?$`),
HTTPMethod: http.MethodPost,
BizIDGetter: BizIDFromURLGetter,
BizIndex: 6,
ResourceType: ProcessInstanceIAMResourceType,
ResourceAction: meta.Find,
}
即:调用方对目标业务下的进程实例资源需要具备 find(查看)权限,bk_biz_id 从 URL 第 6 段解析(BizIndex: 6),用于权限校验时的资源实例定位。
公共鉴权参数
文档中的请求参数以 {{ common_args_desc }} 占位公共参数,即 ESB 标准鉴权三要素。实际调用时需携带:
| 字段 | 类型 | 说明 |
|---|---|---|
| bk_app_code | string | 应用标识(蓝鲸智云 ESB 分配的 App Code) |
| bk_app_secret | string | 应用密钥(与 bk_app_code 配套) |
| bk_username | string | 操作者用户名,用于权限与审计 |
| bk_token | string | 登录态 Token(视接入方式二选一使用) |
请求参数详解
接口参数
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| bk_biz_id | int64 | 是 | 业务 ID |
| bk_set_ids | int64 array | 否 | 集群 ID 列表,若为空则代表任意集群 |
| bk_module_ids | int64 array | 否 | 模块 ID 列表,若为空则代表任意模块 |
| ids | int64 array | 否 | 服务实例 ID 列表,若为空则代表任意实例 |
| bk_process_names | string array | 否 | 进程名称列表,若为空则代表任意进程 |
| bk_process_ids | int64 array | 否 | 进程 ID 列表,若为空则代表任意进程 |
| fields | string array | 否 | 进程属性列表,控制返回结果中进程实例包含哪些字段,用于加速请求、减少网络流量;为空时返回进程所有字段,bk_process_id、bk_process_name 恒被返回 |
| page | dict | 是 | 分页条件 |
条件组合语义(AND)
这些字段的条件关系是与(AND):只会查询同时满足所填条件的进程实例。文档给出典型反例——如果同时填写了 bk_set_ids 与 bk_module_ids,而 bk_module_ids 都不属于 bk_set_ids,则查询结果为空。
在源码中,这一语义体现为过滤条件的层层收紧:提供集群 ID 时,先按其过滤出模块 ID 集合;再叠加服务实例条件过滤服务实例;再由服务实例关联出进程 ID;最终进程过滤条件同时叠加业务 ID 与(可选的)进程属性过滤条件(见下文"五段式查询调用链")。
page 分页条件
| 字段 | 类型 | 必选 | 描述 |
|---|---|---|---|
| start | int | 否 | 记录开始位置,默认 0 |
| limit | int | 是 | 每页限制条数,最大 500 |
| sort | string | 否 | 排序字段,- 前缀表示倒序;只能是进程的字段,默认按 bk_process_id 排序 |
limit 上限与源码校验逻辑一致:分页校验由 src/common/metadata/page.go 的 BasePage.IsIllegal() 完成——start < 0,或 limit > common.BKMaxPageSize(即 500)且不等于 BKNoLimit,或 limit <= 0,均视为非法分页参数,接口会返回参数校验错误。排序默认值为 bk_process_id,对应 processinstance.go 中 sort == "" 时回退到 common.BKProcessIDField 的逻辑。
五段式查询调用链:源码实现解析
接口入口为 src/scene_server/proc_server/service/processinstance.go 的 ListProcessRelatedInfo,其请求参数模型定义在 src/common/metadata/process.go:
type ListProcessRelatedInfoOption struct {
Set SetCondOfP `json:"set"`
Module ModuleCondOfP `json:"module"`
ServiceInstance ServiceInstanceCondOfP `json:"service_instance"`
ProcessPropertyFilter *querybuilder.QueryFilter `json:"process_property_filter"`
Fields []string `json:"fields"`
Page BasePage `json:"page"`
}
请求经 input.Validate() 校验(含 process_property_filter 的规则深度校验与 page 合法性校验,见 process.go)后,进入如下五段式查询流程:
- 集群 → 模块:若填写了
set.bk_set_ids,则以bk_biz_id + bk_set_id IN(...)(若同时填了bk_module_ids则再叠加bk_module_id IN(...))查询module对象,得到模块 ID 集合(processinstance.go); - 模块/服务实例 → 服务实例:若服务实例 ID 或模块 ID 非空,则在
cc_ServiceInstance表上以GetDistinctField去重取服务实例 ID(processinstance.go); - 服务实例 → 进程:若服务实例 ID 非空,则在
cc_ProcessInstanceRelation(进程实例关系表)上以GetDistinctField取出进程 ID 集合(processinstance.go),这是进程与主机/服务实例挂接关系的核心纽带表; - 进程属性过滤与详情查询:以
bk_biz_id(及进程 ID 集合)为基础条件,若传入process_property_filter则通过querybuilder规则引擎将其转换为 mongo 过滤条件并与基础条件做$and合并,最终调用 coreservice 的ReadInstance查询process对象(processinstance.go); - 关联信息组装:
listProcessRelatedInfo(processinstance.go)依据进程关系表数据与进程 ID 一一对应的映射,批量获取服务实例详情、主机详情(bk_host_id/bk_cloud_id/bk_host_innerip/bk_host_innerip_v6/bk_addressing/bk_agent_id)、模块详情(bk_module_id/bk_module_name)、集群详情(bk_set_id/bk_set_name/bk_set_env),最后按进程 ID 顺序组装成ListProcessRelatedInfoResult返回。
响应结构模型见 src/common/metadata/process.go:
type ListProcessRelatedInfoResult struct {
Set SetDetailOfP `json:"set"`
Module ModuleDetailOfP `json:"module"`
Host HostDetailOfP `json:"host"`
ServiceInstance ServiceInstanceDetailOfP `json:"service_instance"`
ProcessTemplate ProcessTemplateDetailOfP `json:"process_template"`
Process interface{} `json:"process"`
}
关于 fields 字段裁剪的一个实现细节
源码中当 fields 非空时,并不会原样透传:查询进程详情时会强制追加 bk_process_id、bk_process_name、bk_func_id 三个字段(processinstance.go),因为后续组装与结果展示依赖这三个关键标识。因此即使调用方只请求个别属性,响应中的 process.bk_process_id 与 bk_process_name 也始终存在,与文档"为空时返回进程所有字段,bk_process_id、bk_process_name"的说明互补。
请求参数示例
{
"bk_app_code": "esb_test",
"bk_app_secret": "xxx",
"bk_username": "xxx",
"bk_token": "xxx",
"bk_biz_id": 3,
"set": {
"bk_set_ids": [
11,
12
]
},
"module": {
"bk_module_ids": [
60,
61
]
},
"service_instance": {
"ids": [
4,
5
]
},
"process": {
"bk_process_names": [
"pr1",
"alias_pr2"
],
"bk_process_ids": [
45,
46,
47
]
},
"fields": [
"bk_process_id",
"bk_process_name",
"bk_func_name"
],
"page": {
"start": 0,
"limit": 100,
"sort": "bk_process_id"
}
}
说明:文档示例中 bk_process_names、bk_process_ids 位于 process 对象内;但从当前仓库元数据结构(process.go)看,ListProcessRelatedInfoOption 只包含 set、module、service_instance、process_property_filter、fields、page,并未定义进程名/进程 ID 的独立过滤字段,这属于文档与代码的版本差异。如需按进程名或进程 ID 过滤,可使用 process_property_filter(查询规则引擎,支持 bk_process_id、bk_process_name 等进程属性字段的组合条件)实现等价能力,例如 {"process_property_filter": {"condition": "AND", "rules": [{"field": "bk_process_id", "operator": "in", "value": [45, 46, 47]}]}}。
响应结构与字段说明
返回结果示例
{
"result": true,
"code": 0,
"message": "success",
"data": {
"count": 2,
"info": [
{
"set": {
"bk_set_id": 11,
"bk_set_name": "set1",
"bk_set_env": "3"
},
"module": {
"bk_module_id": 60,
"bk_module_name": "mm1"
},
"host": {
"bk_host_id": 4,
"bk_cloud_id": 0,
"bk_host_innerip": "127.0.0.1",
"bk_host_innerip_v6": "1::1",
"bk_addressing": "dynamic",
"bk_agent_id": "xxxxxx"
},
"service_instance": {
"id": 4,
"name": "127.0.0.1_pr1_3333"
},
"process_template": {
"id": 48
},
"process": {
"bk_func_name": "pr1",
"bk_process_id": 45,
"bk_process_name": "pr1"
}
},
{
"set": {
"bk_set_id": 11,
"bk_set_name": "set1",
"bk_set_env": "3"
},
"module": {
"bk_module_id": 60,
"bk_module_name": "mm1"
},
"host": {
"bk_host_id": 4,
"bk_cloud_id": 0,
"bk_host_innerip": "127.0.0.1"
},
"service_instance": {
"id": 4,
"name": "127.0.0.1_pr1_3333"
},
"process_template": {
"id": 49
},
"process": {
"bk_func_name": "pr2",
"bk_process_id": 46,
"bk_process_name": "alias_pr2"
}
}
]
}
}
顶层返回字段
| 字段 | 类型 | 描述 |
|---|---|---|
| result | bool | 请求是否成功。true:成功;false:失败 |
| code | int | 错误编码。0 表示 success,>0 表示失败错误码 |
| message | string | 请求失败时返回的错误信息 |
响应封装模型见 src/common/metadata/procserver.go,data 内包含 count(符合条件的进程实例总数)与 info(结果数组)。
data 各层级字段
data 顶层
| 字段 | 类型 | 描述 |
|---|---|---|
| count | int | 符合条件的进程实例总数量 |
| set | object | 进程所属的集群信息 |
| module | object | 进程所属的模块信息 |
| host | object | 进程所属的主机信息 |
| service_instance | object | 进程所属的服务实例信息 |
| process_template | object | 进程模板信息 |
| process | object | 进程自身的详细信息 |
data.set
| 字段 | 类型 | 描述 |
|---|---|---|
| bk_set_id | int | 集群 ID |
| bk_set_name | string | 集群名称 |
| bk_set_env | string | 环境类型 |
data.module
| 字段 | 类型 | 描述 |
|---|---|---|
| bk_module_id | int | 模块 ID |
| bk_module_name | string | 模块名称 |
data.host
| 字段 | 类型 | 描述 |
|---|---|---|
| bk_host_id | int | 主机 ID |
| bk_cloud_id | int | 管控区域 ID |
| bk_host_innerip | string | 主机内网 IP |
| bk_host_innerip_v6 | int | 主机内网 IPv6 |
| bk_addressing | string | 寻址方式 |
| bk_agent_id | string | Agent ID |
注:主机字段集合与源码
HostDetailOfP定义(process.go)一致,查询时仅取上述固定字段,不返回主机全量属性。
data.service_instance
| 字段 | 类型 | 描述 |
|---|---|---|
| id | int | 服务实例 ID |
| name | string | 服务实例名称 |
data.process_template
| 字段 | 类型 | 描述 |
|---|---|---|
| id | int | 进程模板 ID |
说明:文档原文此处描述为"集群模板 id / Cluster template ID",结合源码
ProcessTemplateDetailOfP{ID: procTemplateMap<a href="https://link.gitcode.com/i/f73471a531af4baaebe08a150ec983af" target="_blank">processID]}([processinstance.go)可以确认,该字段取自进程实例关系表中的process_template_id,本质是进程模板 ID,文档表述存在笔误,以源码为准。
data.process(进程自身属性,fields 为空时全部返回)
| 字段 | 类型 | 描述 |
|---|---|---|
| auto_start | bool | 是否自动拉起 |
| bk_biz_id | int | 业务 ID |
| bk_func_name | string | 进程名称 |
| bk_process_id | int | 进程 ID |
| bk_process_name | string | 进程别名 |
| bk_start_param_regex | string | 进程启动参数 |
| bk_supplier_account | string | 开发商账号 |
| create_time | string | 创建时间 |
| description | string | 描述 |
| face_stop_cmd | string | 强制停止命令 |
| last_time | string | 更新时间 |
| pid_file | string | PID 文件路径 |
| priority | int | 启动优先级 |
| proc_num | int | 启动数量 |
| reload_cmd | string | 进程重载命令 |
| restart_cmd | string | 重启命令 |
| start_cmd | string | 启动命令 |
| stop_cmd | string | 停止命令 |
| timeout | int | 操作超时时长 |
| user | string | 启动用户 |
| work_path | string | 工作路径 |
| bk_created_at | string | 创建时间 |
| bk_created_by | string | 创建人 |
| bk_updated_at | string | 更新时间 |
| bk_updated_by | string | 更新人 |
| bind_info | object | 绑定信息 |
上述进程字段与源码中的 Process 模型(src/common/metadata/process.go)一一对应,例如 bk_process_name 对应 ProcessName、face_stop_cmd 对应 ForceStopCmd、proc_num 对应 ProcNum。
工程实践与注意事项
- 善用 fields 裁剪响应体:GSEKit 等批量场景建议显式传入所需进程属性,可显著降低 coreservice 查询与网络传输开销;但需注意
bk_process_id、bk_process_name、bk_func_id会被强制保留,不可省略。 - 分页严格性:
limit必填且上限 500;start默认 0;sort仅支持进程字段,-前缀倒序,默认bk_process_id。非法分页会直接导致请求失败。 - 过滤条件的 AND 语义:集群、模块、服务实例、进程条件之间是严格与关系,越精确的过滤组合查询范围越小;若模块与集群不匹配(模块不属于所填集群),结果必为空。
- 进程属性高级过滤:仓库版接口还支持
process_property_filter(基于 querybuilder 规则引擎),可对进程属性做组合条件过滤,弥补了文档中bk_process_names/bk_process_ids在当前版本元数据中缺位的差异。 - 测试可参考:仓库中的集成测试覆盖了该接口的基础调用路径(src/test/proc_server/no_service_template_test.go),按服务实例 ID 过滤并断言
count非 0,可作为调用语义与返回值结构的验证参考;客户端封装见 src/apimachinery/procserver/process/instance.go。
综上,ListProcessRelatedInfo 是 bk-cmdb 进程实例查询接口中聚合度最高的一类:理解其五段式过滤调用链与字段组装规则,即可在 GSEKit 接入、进程批量巡检、主机进程拓扑盘点等场景中高效、精准地获取进程全链路上下文信息。