蓝鲸CMDB API详解：create_process_instance 创建进程实例接口原理与实战

• 后端
• 企业应用
• 运维

本篇围绕 bk-cmdb 配置中心（CC）的进程实例创建接口create_process_instance展开，完整讲解接口的权限要求、请求参数结构（含process_info与bind_info全量字段）、请求/响应示例；并结合开源仓库源码剖析该接口从路由注册、参数校验、事务落库到审计日志生成的完整处理链路，帮助读者掌握如何在服务实例上批量创建进程实例，并理解模板化服务实例为何禁止手工创建进程的底层原因。

功能描述与接口定位

create_process_instance的功能是：根据服务实例ID和进程实例属性值创建进程实例，调用方需要持有服务实例编辑权限。它属于蓝鲸 CMDB 配置中心（CC）模块的运维操作类（operate）API，是进程管理四件套（创建/更新/删除/查询）中的入口接口。

接口在不同入口的路径映射如下：

• 通过 ESB/API 网关（API Gateway）访问时，网关侧资源路径为/v2/cc/create_process_instance/，网关将其转发到后端实际路径/api/v3/create/proc/process_instance（POST 方法），映射关系定义在 API网关资源清单 中；
• 直接调用后端时，该路由由 proc_server 注册，见 路由注册：

// process instance utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/create/proc/process_instance", Handler: ps.CreateProcessInstances})

• 前端 UI 同样直接调用该后端路径（见 前端API封装）。

也就是说，网关 APIcreate_process_instance、后端接口POST /api/v3/create/proc/process_instance与源码中的CreateProcessInstances处理器是同一条链路的不同视角。

请求参数

公共参数

接口遵循 ESB 通用鉴权方式，公共参数即请求示例中的bk_app_code、bk_app_secret、bk_username、bk_token（四选二：使用 app_code/app_secret 或 username/bk_token 鉴权），以及业务归属参数bk_biz_id（业务ID，int 型，必选）。

接口参数

processes数组的每一项是一个process_template_id+process_info的组合结构，对应源码中的 ProcessInstanceDetail：

// ProcessInstanceDetail TODO type ProcessInstanceDetail struct { // ProcessTemplateID indicate which process to update if service instance bound with a template ProcessTemplateID int64 `json:"process_template_id"` ProcessData map[string]interface{} `json:"process_info"` }

其中process_info是一个自由字段 map（map[string]interface{}），可传入下文process_info字段表中定义的任何属性；而process_template_id用于服务实例绑定了模板的场景下指明目标进程（本接口的典型场景是未绑定模板的服务实例，见后文“限制条件”）。

整个请求体由 CreateRawProcessInstanceInput 反序列化：

type CreateRawProcessInstanceInput struct { BizID int64 `json:"bk_biz_id"` ServiceInstanceID int64 `json:"service_instance_Id"` Processes []ProcessInstanceDetail `json:"processes"` }

需要注意两点实现细节：

1. 数量上限 100：文档中“最大值为100”在源码中由 CreateProcessInstances 处理器 校验，空数组报CCErrCommParamsIsInvalid，超过上限报CCErrCommXXExceedLimit，上限常量BKMaxUpdateOrCreatePageSize定义在 definitions.go：

// BKMaxUpdateOrCreatePageSize maximum number of updates. BKMaxUpdateOrCreatePageSize = 100

2. 业务ID一致性校验：处理器会先通过Process().GetServiceInstance查出服务实例，并要求请求中的bk_biz_id与服务实例归属业务一致，否则返回CCErrCommParamsInvalid（见 校验代码）。

限制条件：模板初始化的服务实例不允许手工创建

从源码看，如果目标服务实例是由服务模板初始化的（serviceInstance.ServiceTemplateID != common.ServiceTemplateIDNotSet），接口会直接拒绝并返回CCErrProcEditProcessInstanceCreateByTemplateForbidden错误，见 判断逻辑。因此本接口适用于未绑定服务模板、进程为“raw”原始数据形态的服务实例；模板化实例的进程应通过模板同步机制维护。

process_info 字段说明

这些字段与后端落库用的 Process 结构体 一一对应（如face_stop_cmd→ForceStopCmd、bk_process_name→ProcessName、bk_func_name→FuncName）。除上表字段外，源码结构体还保留了description（描述）与bk_start_param_regex（启动参数正则）等属性，请求示例中也出现了这两个字段，实际传入同样会被接受。

bind_info 字段说明

bind_info用于描述进程监听的 IP/端口绑定关系，标准行结构定义在 stdProcBindInfo：

从源码结构看，ProcBindInfo由标准属性Std与自由扩展extra两部分组成，并实现了 IP 与 protocol 匹配校验、port 校验等 Validate 逻辑，即绑定的 IP 格式必须与协议匹配（如 IPv4/IPv6 与 protocol 的一致性），非法值会在入库前被拒绝。

请求参数示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_biz_id": 1, "service_instance_id": 48, "processes": [ { "process_info": { "bk_supplier_account": "0", "description": "", "start_cmd": "", "restart_cmd": "", "pid_file": "", "auto_start": false, "timeout": 30, "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_start_param_regex": "", "bk_process_id": 1, "bind_info": [ { "enable": false, "ip": "127.0.0.1", "port": "80", "protocol": "1", "template_row_id": 1234 } ] } } ] }

返回结果示例

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

返回结果参数说明

response

data的实际类型是新建进程实例的bk_process_id数组（int64 列表），如示例中的[64]。

源码级实现链路：一次创建请求发生了什么

理解上述参数后，再看 CreateProcessInstances 处理器 的完整实现，可以把接口行为归纳为以下调用链：

1. 解码与校验：ctx.DecodeInto反序列化请求体；processes为空或超过 100 条直接返回参数错误。
2. 开启事务：通过ps.Engine.CoreAPI.CoreService().Txn().AutoRunTxn包装整个创建过程，保证“写进程实例 + 写进程-服务实例关系 + 写审计日志”三者原子化。
3. 前置校验：Process().GetServiceInstance查询服务实例，校验bk_biz_id一致性与“非模板实例”约束。
4. 补齐系统字段：对每条进程数据强制写入/覆盖系统字段（见 字段填充代码）：

item.ProcessData[common.BKProcessIDField] = int64(0) // 进程ID由存储层生成 item.ProcessData[common.BKAppIDField] = input.BizID item.ProcessData[common.BkSupplierAccount] = ctx.Kit.SupplierAccount item.ProcessData[common.CreateTimeField] = now item.ProcessData[common.LastTimeField] = now item.ProcessData[common.BKServiceInstanceIDField] = input.ServiceInstanceID

也就是说，即使请求体里传了bk_biz_id、bk_process_id等值，业务ID与供应商账号也会以请求上下文为准，进程主键最终由存储层分配。 5.落库：ps.Logic.CreateProcessInstances将进程数据以原始数据（raw）形式批量写入进程表（内部对象 ID 为proc）。 6.建立关系：为每个新进程 ID 构造 ProcessInstanceRelation（含BizID、ProcessID、ServiceInstanceID、HostID，ProcessTemplateID置为ServiceTemplateIDNotSet），调用Process().CreateProcessInstanceRelations写入进程-服务实例关系表。这解释了为什么接口能“只凭服务实例ID”创建进程——宿主机的HostID是从服务实例反查得到的。 7.审计日志：事务内通过auditlog.NewSvcInstAudit生成审计记录（AuditCreate/AuditUpdate），记录操作人、业务、服务实例与进程明细，落库失败会触发事务回滚。 8.返回：ctx.RespEntity(processIDs)返回新建的进程实例 ID 列表。

权限控制

接口的 IAM 鉴权规则定义在 ProcessInstanceAuthConfigs：

{ Name: "createProcessInstances", Description: "创建进程实例", Pattern: "/api/v3/create/proc/process_instance", HTTPMethod: http.MethodPost, BizIDGetter: DefaultBizIDGetter, ResourceType: ProcessInstanceIAMResourceType, // meta.ProcessServiceInstance ResourceAction: meta.Update, },

从源码结构看，该接口对服务实例资源（ProcessServiceInstance）执行Update动作的校验——这正对应文档描述中的“权限：服务实例编辑权限”，BizIDGetter则从请求体中的bk_biz_id提取业务维度做鉴权。

内部复用视角

除了对外 HTTP 接口，该能力也以 client 方法形式封装在 apimachinery 中，供其他服务端内部复用：procserver 客户端 CreateProcessInstance 以 POST 方式请求同一子路径/create/proc/process_instance；coreservice 侧则提供了CreateProcessInstanceRelations等配套接口（见 coreservice process API），供 proc_server 在创建进程后维护关系数据。

小结

• create_process_instance面向未绑定服务模板的服务实例，一次性在其上批量创建进程实例，单次最多 100 条；
• 请求必须保证bk_biz_id与service_instance_id的归属一致，process_info可覆盖进程启动/停止命令、运行用户、超时、bind_info 端口绑定等完整属性；
• 后端在事务内完成进程实例写入、进程-服务实例关系写入与审计日志写入，返回新建的进程 ID 列表；
• 权限上对应服务实例资源的 Update（编辑）动作，网关路径/v2/cc/create_process_instance/映射到后端POST /api/v3/create/proc/process_instance。

配套接口文档位于 create_process_instance.md，同目录下的update_process_instance、delete_process_instance、list_process_instance等文档可作为进程实例全生命周期操作的进一步参考。

• 后端
• 企业应用
• 运维