bk-cmdb 接口深度解析:按点分五位查询进程实例相关信息(ListProcessRelatedInfo)

原创2026-10-13 17:10:321,905 阅读
文章标签:后端企业应用微服务

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)后,进入如下五段式查询流程:

  1. 集群 → 模块:若填写了 set.bk_set_ids,则以 bk_biz_id + bk_set_id IN(...)(若同时填了 bk_module_ids 则再叠加 bk_module_id IN(...))查询 module 对象,得到模块 ID 集合(processinstance.go);
  2. 模块/服务实例 → 服务实例:若服务实例 ID 或模块 ID 非空,则在 cc_ServiceInstance 表上以 GetDistinctField 去重取服务实例 ID(processinstance.go);
  3. 服务实例 → 进程:若服务实例 ID 非空,则在 cc_ProcessInstanceRelation(进程实例关系表)上以 GetDistinctField 取出进程 ID 集合(processinstance.go),这是进程与主机/服务实例挂接关系的核心纽带表;
  4. 进程属性过滤与详情查询:以 bk_biz_id(及进程 ID 集合)为基础条件,若传入 process_property_filter 则通过 querybuilder 规则引擎将其转换为 mongo 过滤条件并与基础条件做 $and 合并,最终调用 coreservice 的 ReadInstance 查询 process 对象(processinstance.go);
  5. 关联信息组装: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。

工程实践与注意事项

  1. 善用 fields 裁剪响应体:GSEKit 等批量场景建议显式传入所需进程属性,可显著降低 coreservice 查询与网络传输开销;但需注意 bk_process_id、bk_process_name、bk_func_id 会被强制保留,不可省略。
  2. 分页严格性:limit 必填且上限 500;start 默认 0;sort 仅支持进程字段,- 前缀倒序,默认 bk_process_id。非法分页会直接导致请求失败。
  3. 过滤条件的 AND 语义:集群、模块、服务实例、进程条件之间是严格与关系,越精确的过滤组合查询范围越小;若模块与集群不匹配(模块不属于所填集群),结果必为空。
  4. 进程属性高级过滤:仓库版接口还支持 process_property_filter(基于 querybuilder 规则引擎),可对进程属性做组合条件过滤,弥补了文档中 bk_process_names/bk_process_ids 在当前版本元数据中缺位的差异。
  5. 测试可参考:仓库中的集成测试覆盖了该接口的基础调用路径(src/test/proc_server/no_service_template_test.go),按服务实例 ID 过滤并断言 count 非 0,可作为调用语义与返回值结构的验证参考;客户端封装见 src/apimachinery/procserver/process/instance.go。

综上,ListProcessRelatedInfo 是 bk-cmdb 进程实例查询接口中聚合度最高的一类:理解其五段式过滤调用链与字段组装规则,即可在 GSEKit 接入、进程批量巡检、主机进程拓扑盘点等场景中高效、精准地获取进程全链路上下文信息。

登录后查看全文
bk-cmdb