企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本文介绍蓝鲸智云配置平台（BlueKing CMDB，简称 bk-cmdb）开放 API 中「批量更新进程信息」接口的完整用法。该接口用于在业务下一次性批量修改多个进程实例的启动命令、PID 文件、进程别名、绑定端口等属性，是自动化运维平台、CI/CD 系统与 CMDB 集成的常用能力。读完本文，你将掌握接口的权限要求、请求/响应结构、全部字段含义，以及其背后「服务实例编辑权限」校验、模板字段约束与批量上限的底层实现。

接口概述

「批量更新进程信息」接口对应操作 IDupdate_process_instance，其能力是在指定业务（bk_biz_id）下批量更新进程实例的属性，调用者必须具备「服务实例编辑权限」。该接口在网关配置中位于 bk_apigw_resources_bk-cmdb.yaml（/api/v3/update/proc/process_instance一节），后端路由注册于 service.go：

• 请求方法：PUT
• 后端路径：/api/v3/update/proc/process_instance
• 网关映射路径：/update/proc/process_instance
• 接口性质：非公开资源（isPublic: false），允许申请调用权限（allowApplyPermission: true），并配置了默认限流（每周期 100 个令牌）

在 service.go 中，该路径与POST /create/proc/process_instance（创建进程实例）、DELETE /delete/proc/process_instance（删除进程实例）、POST /findmany/proc/process_instance（查询进程实例）一起构成完整的进程实例生命周期 API。

权限说明

从权限模型看，该接口在 processinstance.go 中被定义为 IAM 资源ProcessInstanceIAMResourceType上的meta.Update动作，对应配置如下：

调用前请确保调用方账号在对应业务下已获得进程实例的编辑（update）权限；若无权限，接口会返回 permission 相关的错误信息。

输入参数

顶层请求体包含两个必选参数：

其中processes最大数量为 100，对应后端常量BKMaxUpdateOrCreatePageSize = 100（定义于 definitions.go）。超过上限时，processinstance.go 中的UpdateProcessInstances处理器会返回「超出数量上限」的错误（CCErrCommXXExceedLimit）。

processes 字段说明

processes数组中的每个元素为一条进程更新数据，其字段如下（除bk_process_id外均为可选字段，未传的字段默认不更新）：

这些字段与 process.go 中metadata.Process结构体的 JSON tag 一一对应，例如bk_process_id（ProcessID）、bk_func_name（FuncName）、bk_process_name（ProcessName）、face_stop_cmd（ForceStopCmd）、timeout（TimeoutSeconds）、work_path（WorkPath）等。

bind_info 补充说明

在调用示例中可以看到processes元素还支持bind_info（进程端口绑定信息）数组，其内部字段为：

后端校验（见 processinstance.go 的validateProcessInstance）要求绑定信息的 IP 必须是合法 IPv4 地址，端口与协议不能为空，否则会返回参数校验错误。

调用示例

{ "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 } ] } ] }

请求使用PUT方法发送到/api/v3/update/proc/process_instance。示例中通过bk_process_id: 43精确定位待更新的进程实例，同时更新其进程别名、进程名称、工作路径、自动拉起开关、超时时长、拉起间隔、启动数量、启动优先级等属性，并重新设置一条绑定信息。

响应示例

{ "result": true, "code": 0, "message": "success", "permission": null, "data": [43] }

响应参数说明

其中data为本次成功更新的进程实例 id 数组（如[43]），即processes中各个bk_process_id的集合。

源码级实现解析

1. 请求链路

从调用方视角看，请求依次经过：

1. 网关/开放 API 层：PUT /api/v3/update/proc/process_instance，由 bk_apigw_resources_bk-cmdb.yaml 定义，并在此完成鉴权与限流；
2. proc_server 路由层：路由注册于 service.go，分发到ps.UpdateProcessInstances处理器（见 processinstance.go）；
3. 逻辑层：ps.updateProcessInstances逐进程构造更新数据，并通过ps.Logic.UpdateProcessInstance下发到 coreservice；
4. coreservice 实例层：最终调用CoreService().Instance().UpdateInstance（见 processinstance.go），按bk_process_id条件更新proc对象下的实例数据。

Go SDK 侧的封装位于 instance.go 的UpdateProcessInstance方法，它内部使用PUT方法请求子路径/update/proc/process_instance。

2. 模板实例与非模板实例的差异处理

后端在更新时会先通过ListProcessInstanceRelation查询进程实例与服务实例的关系，然后分两种情况处理（见 processinstance.go）：

• 非模板创建（ProcessTemplateID == ServiceTemplateIDNotSet）：请求中的字段会整体映射为进程数据，直接更新（bk_process_id、bk_supplier_account、last_time、create_time等系统字段会被剔除，不可修改）；
• 由服务模板/进程模板创建：调用ProcessTemplate.ExtractInstanceUpdateData（process.go）仅提取模板中允许编辑的字段，且再经过GetEditableFields过滤。因此模板实例上被模板锁定的字段（如start_cmd、auto_start、work_path等）即使传入也不会被更新，体现了「模板锁定」的约束逻辑。

从 process.go 的ExtractEditableFields实现可见，模板实例可编辑字段为bk_func_name、bk_process_name、bk_start_param_regex、bk_start_check_secs、user、stop_cmd、proc_num、description、timeout、auto_start、pid_file、reload_cmd、restart_cmd、face_stop_cmd、work_path、priority、start_cmd以及bind_info，且前提是模板中这些字段未被设置为「默认值（AsDefaultValue）」。

3. 字段置空与校验

该接口支持将字段更新为 null 以清空原值：处理器会遍历processes元素中值为null的字段，经metadata.FilterValidFields过滤出合法字段后，在更新数据中将其显式置为nil。对于模板实例，还会先经过GetEditableFields过滤，确保不会越权清空模板锁定的字段。

此外，bk_process_id必须存在且不为 0；后端会校验所有传入的进程 id 都能在业务下找到对应的进程实例关系，否则返回参数无效错误（CCErrCommParamsInvalid），未找到的进程 id 会拼接到错误信息中。

4. 事务、审计与并发

更新过程在AutoRunTxn事务中执行：更新前会先基于更新前的进程数据与服务实例关系生成审计日志（generateUpdateProcessAudit），更新成功后统一落库；任一进程更新失败则整个事务回滚。具体更新时采用并发管道（channel 容量为 10）批量执行UpdateProcessInstance，以提升大批量更新效率，同时通过waitgroup等待全部完成后统一返回更新成功的进程 id 数组。

5. 测试验证

仓库的集成测试 no_service_template_test.go 完整覆盖了该接口：

• 构造包含bk_func_name、bk_process_name、bk_start_param_regex、bk_process_id与bind_info的请求，调用processClient.UpdateProcessInstance后断言result为 true，并再次查询进程实例确认字段已更新为p3；
• 覆盖了「更新为与已有进程同名」的场景，断言返回失败，说明同名进程存在唯一性约束。

使用建议与注意事项

1. 权限前置：调用前确保调用方账号已获得对应业务下进程实例的编辑权限（服务实例编辑权限），否则请求会被 IAM 拒绝；
2. 批量上限：单次processes数组最多 100 条，超限会返回错误；大规模更新请分批调用；
3. 模板实例约束：对由服务模板生成的进程实例，只能更新模板允许编辑的字段，其余字段会被忽略，避免与模板配置冲突；
4. 精确定位：每条更新数据必须携带bk_process_id，否则后端无法定位进程，将返回参数错误；
5. 字段清空：将某个字段设为null可清空原值，但需注意只对合法字段生效（模板实例还需该字段可编辑）；
6. 响应判断：以result与code判断整体成败；data返回成功更新的进程 id 列表，可据此做后续联动。

相关文档与源码索引

• 接口定义：docs/apidoc/apigw/open/bk_apigw_resources_bk-cmdb.yaml
• 路由注册：src/scene_server/proc_server/service/service.go
• 处理器实现：src/scene_server/proc_server/service/processinstance.go
• 逻辑层封装：src/scene_server/proc_server/logics/processinstance.go
• 数据结构定义：src/common/metadata/process.go
• 批量上限常量：src/common/definitions.go
• 权限配置：src/ac/parser/processinstance.go
• 集成测试：src/test/proc_server/no_service_template_test.go

• 后端
• 企业应用
• 运维