后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本篇文章以 update_process_instance.md中文版见 update_process_instance.md为骨架结合 bk-cmdb 仓库中 proc_server、apimachinery、ac/parser、common/metadata 等源码与测试用例完整讲解批量更新进程实例这一开放接口的调用方式、字段约束、底层实现与排障要点。读完你将掌握如何构造合法的更新请求、进程实例与进程模板的关系如何影响可编辑字段、接口内部的事务与审计机制以及常见错误的定位方法。一、接口概览用途、路径与权限批量更新进程信息是 bk-cmdb 对外提供的进程实例Process Instance管理类接口用于在不经过服务实例模板同步流程的情况下直接对业务下已有的进程实例进行批量修改典型场景包括一次性调整某业务多个主机上进程的启动命令、工作目录、启动用户、优先级等属性修正进程别名bk_process_name、功能名bk_func_name等标识信息批量变更进程的绑定信息bind_info即 IP/端口/协议作为后续 GSE 进程托管配置的数据来源。该接口的核心定位与相关约束如下项说明开放网关资源路径PUT /api/v3/update/proc/process_instance见 bk_apigw_resources_bk-cmdb.yaml 中的update_process_instance定义内部服务路径proc_server 注册的PUT /update/proc/process_instance见 service.go所需权限服务实例编辑权限单次最大处理数processes数组最多 100 条幂等性按bk_process_id精确匹配更新未指定的字段保持不变权限说明在权限解析层该接口被注册为updateProcessInstances资源类型为ProcessServiceInstance服务实例动作Action为meta.Update业务 ID 通过DefaultBizIDGetter从请求参数中提取见 processinstance.go。也就是说调用者必须在蓝鲸权限中心拥有对应服务实例的编辑update权限否则请求会被拒绝并返回权限信息。二、请求参数详解1. 顶层参数参数名称参数类型必选描述processesarray是进程信息数组最大值为 100对应源码中BKMaxUpdateOrCreatePageSize 100的上限校验见 definitions.gobk_biz_idint是业务 ID更新请求必须显式声明所属业务在 Go 服务端顶层入参对应UpdateRawProcessInstanceInput结构体见 process.gotype UpdateRawProcessInstanceInput struct { BizID int64 json:bk_biz_id Processes []Process json:- Raw []map[string]interface{} json:processes }注意processes数组的每个元素是一个开放结构map[string]interface{}而不是强类型对象因此字段可按需传、可部分更新。2. processes 字段说明完整表下表完整继承自原文档并补充了字段取值范围来源于进程模型的属性定义 objAttDescData.go参数名称参数类型必选描述process_template_idint否进程模板 ID当进程实例由模板创建时用于定位模板auto_startbool否是否自动拉起auto_time_gapint否拉起间隔单位秒属性约束 1~10000见 update_process_property.gobk_biz_idint否业务 ID更新时以顶层 bk_biz_id 为准bk_func_idstring否功能 IDGSE Kit 功能标识bk_func_namestring否进程名称功能名称bk_process_idint否进程 ID实际更新时的定位键必须提供且有效bk_process_namestring否进程别名bk_supplier_accountstring否开发商账号face_stop_cmdstring否强制停止命令pid_filestring否PID 文件路径priorityint否启动优先级属性约束 1~100proc_numint否启动数量属性约束 1~1000000reload_cmdstring否进程重载命令restart_cmdstring否重启命令start_cmdstring否启动命令stop_cmdstring否停止命令timeoutint否操作超时时长属性约束 1~1000000userstring否启动用户work_pathstring否工作路径process_infoobject否进程信息嵌套对象形式可携带 bind_info 等复合结构bind_infoarray否进程绑定信息元素含enable、ip、port、protocol、template_row_id等关于必选字段的说明表格中bk_process_id标记为否仅表示它作为进程属性之一并非每次都必须变更但更新操作必须以bk_process_id作为目标定位键。服务端在 updateProcessInstances 中会校验process.ProcessID 0直接返回参数错误CCErrCommParamsInvalid并通过进程-服务实例关系表确认这些进程真实存在于该业务下不存在则报CCErrCommParamsIsInvalid并给出缺失的进程 ID 列表。3. bind_info 绑定信息的校验规则bind_info是进程实例较复杂的复合字段服务端在validateProcessInstance见 processinstance.go中对每个绑定项执行三重校验源码可佐证IP必须匹配 IPv4 格式正则^((1?\d{1,2}|2[0-4]\d|25[0-5])[.]){3}(1?\d{1,2}|2[0-4]\d|25[0-5])$为空则报CCErrCommParamsNeedSet格式非法报CCErrCommParamsInvalid端口通过PropertyPortValue.Validate()见 process.go支持逗号分隔多端口、start-end区间写法要求区间起点不大于终点、且各端口区间互不重叠协议ProtocolType枚举校验见 process.go取值1TCP、2UDP、3TCP6、4UDP6同时通过ValidateBindIPMatchProtocol校验绑定方式与协议族匹配IPv4 绑定不能配 TCP6/UDP6。三、调用示例可直接复制验证以下请求完整继承自原文档为便于对照已在行内补充关键字段注释{ bk_biz_id: 1, processes: [ { bk_process_id: 43, description: , start_cmd: , restart_cmd: , pid_file: , auto_start: false, timeout: 30, auto_time_gap: 60, reload_cmd: , bk_func_name: java, work_path: /data/bkee, stop_cmd: , face_stop_cmd: , bk_process_name: job_java, user: , proc_num: 1, priority: 1, bk_biz_id: 2, bk_func_id: , bind_info: [ { enable: false, ip: 127.0.0.1, port: 100, protocol: 1, template_row_id: 1 } ] } ] }几点实战提醒示例中processes[0].bk_biz_id为 2 与顶层bk_biz_id: 1不一致服务端以顶层业务 ID 为准进行数据归属校验条目内的bk_biz_id会被强制改写见 processinstance.goprocess.BusinessID bizID不打算修改的字段可以不出现在条目中服务端按bk_process_id读取旧值并仅对传入字段做覆盖若想把某字段清空可在条目中显式传入null服务端会提取这些置空字段并在更新数据中将其设为nil见 processinstance.go这适用于清空pid_file、user等可编辑文本属性。四、响应示例与参数说明{ result: true, code: 0, message: success, permission: null, data: [43] }响应参数完整说明如下继承自原文档参数名称参数类型描述resultbool请求成功与否。true请求成功false请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息dataobject请求返回的数据其中data是本次成功更新的进程 ID 数组[]int64即各条目中bk_process_id的去重集合由服务端ctx.RespEntity(result)返回见 processinstance.go。如果你的调用方需要记录哪些进程被更新直接取用该数组即可无需再次查询。五、源码级实现原理与调用链从调用方视角到数据落库该接口的完整链路如下网关层蓝鲸 API 网关将PUT /api/v3/update/proc/process_instance转发至 proc_server 内部路径网关资源定义见 bk_apigw_resources_bk-cmdb.yaml路由注册proc_server 在 service.go 中注册PUT /update/proc/process_instance - UpdateProcessInstances权限校验ac/parser 按 processinstance.go 的规则做服务实例 update 权限鉴权服务层处理UpdateProcessInstances见 processinstance.go先校验processes非空且不超过 100 条再生成更新前审计快照随后在数据库事务中执行updateProcessInstances并保存审计日志并发更新内部对每个进程 ID 并发执行更新通过容量为 10 的 channel 信号量pipeline : make(chan bool, 10)控制并发度见 processinstance.go任一条失败都会记录并整体返回首个错误逻辑层落库Logic.UpdateProcessInstance见 processinstance.go删除bk_supplier_account后构造UpdateOption{Data, Condition: {bk_process_id: procID}}调用 coreservice 的UpdateInstance最终写入 MongoDB 的process集合客户端封装调用方如测试或上层模块可通过 apimachinery 客户端UpdateProcessInstance见 instance.go发起请求内部使用 HTTP PUT 访问/update/proc/process_instance。值得关注的是审计日志更新前先通过generateUpdateProcessAudit见 processinstance.go读取进程更新前的快照、进程-服务实例关系与变更字段集合生成AuditUpdate类型日志与更新动作在同一事务中提交从而保证谁在何时改了什么、改前改后值均可追溯。六、模板进程与原生进程可编辑字段的差异这是使用本接口最容易踩坑的点。bk-cmdb 中进程实例分为两类来源模板进程由服务模板/进程模板同步创建ProcessTemplateID ! ServiceTemplateIDNotSet原生进程直接在服务实例下手动创建ProcessTemplateID ServiceTemplateIDNotSet。updateProcessInstances会根据进程-服务实例关系中的ProcessTemplateID走两条不同分支见 processinstance.go原生进程允许更新全部进程属性仅剔除bk_process_id、bk_supplier_account、create_time、last_time等系统字段模板进程必须通过processTemplate.ExtractInstanceUpdateData提取模板允许编辑的字段做增量更新模板不允许的字段会被忽略置空字段也需经processTemplate.GetEditableFields过滤防止把模板锁定的字段清掉。因此对模板进程调用本接口修改模板管控的属性如start_cmd通常不会生效正确做法是改进程模板并执行服务实例同步sync系列接口仓库错误码中也有对应的保护逻辑错误1108035 CCErrProcEditProcessInstanceCreateByTemplateForbidden见 errInfo.go即表示由模板创建的进程实例不允许直接编辑。七、常见错误与排障结合源码与测试用例no_service_template_test.go总结以下高频失败场景错误现象触发原因定位方法processes为空请求体缺少processes或为空数组服务端直接返回参数错误检查请求体超过 100 条数组长度 BKMaxUpdateOrCreatePageSize分批调用每批 ≤100bk_process_id缺失/为 0条目内未提供有效进程 ID该字段是更新定位键必须携带进程不存在bk_process_id不属于该业务服务端报CCErrCommParamsIsInvalid并列出缺失 ID更新同名进程失败进程别名/功能名启动参数与同模块其他进程冲突见测试update process instance with same name用例名称/功能名为空bk_process_name或bk_func_name传了空字符串服务端校验长度非空validateProcessInstancebind_info 校验失败IP 格式错误、端口区间非法/重叠、协议枚举非法参照上文bind_info 校验规则逐项核对模板进程编辑被拒对模板创建的进程实例直接改模板字段错误 1108035改走模板同步流程业务 ID 不一致条目内bk_biz_id与顶层不一致顶层为准条目内字段会被覆盖另外注意测试用例no_service_template_test.go还展示了同一路径族下的姊妹接口UpdateProcessInstancesByIDsPUT /update/proc/process_instance/by_ids它接收process_idsupdate_data结构适合对同一批进程统一改同一批属性的场景与本接口逐条精细更新形成互补可按需选用。八、小结批量更新进程实例update_process_instance是 bk-cmdb 进程实例管理体系中脱离模板、按 ID 直改的高频接口它支持最多 100 条进程的批量局部更新、按bk_process_id精确定位、内置字段置空与 bind_info 校验、事务化提交与更新审计同时对模板进程设置了可编辑字段边界。掌握本文的参数约束与源码行为即可在实际业务中安全、高效地完成进程属性的批量维护。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台bk-cmdb批量更新 Kubernetes Workload 接口实战指南蓝鲸配置平台bk cmdb批量更新 Kubernetes Workload 接口实战指南 导读 本文围绕 bk cmdb蓝鲸智云配置平台API 网关提供后端企业应用运维Elementor 编辑器通知系统elementor/editor-notifications 包版本演进与实现全解析Elementor 编辑器通知系统elementor/editor notifications 包版本演进与实现全解析 本文以 elementor/edi后端企业应用运维Matter 项目 Tracing 子系统详解运行时可配置的追踪与指标日志架构Matter 项目 Tracing 子系统详解运行时可配置的追踪与指标日志架构 Matter原 Project CHIP在 src/tracing htt后端企业应用运维上一篇Go Size Analyzer 使用教程下一篇终极Kubernetes中文教程从零开始的完整学习指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考