企业官网建设流程全解析

• 后端
• 企业应用
• 运维

在蓝鲸智云配置平台（BlueKing CMDB）中，集群模板（Set Template）是标准化集群资源建模的核心工具：它允许用户在指定业务（bk_biz_id）下创建一个具名集群模板，并通过服务模板 ID 列表将一组服务模板挂载到该集群模板上，从而实现"集群—服务模板—服务实例"的标准化拓扑管控。本文以官方 API 文档 docs/apidoc/cc/zh_hans/create_set_template.md 为主体，完整讲解该接口的请求参数、请求/响应示例、字段含义，并结合 bk-cmdb 源码深入剖析接口背后的调用链、参数校验规则与数据落库逻辑，帮助读者既"会用"接口，也"懂"其实现原理。

一、接口功能与适用场景

该接口的官方定义为：在指定业务 ID 下创建指定名称的集群模板，创建的集群模板通过指定的服务模板 ID 去包含服务模板。调用该接口需要具备"集群模板新建"权限。

在 CMDB 的模板化运维体系中，集群模板承载如下职责：

• 将一组服务模板（Service Template）组织到同一个集群模板（Set Template）下，形成可复用的"集群标准结构"；
• 后续可通过"用集群模板同步集群"能力，把集群模板批量实例化为具体集群（Set），并把服务模板实例化为集群下的模块（Module），实现从模板到实例的自动化批量生成。

因此，创建集群模板是"服务模板 → 集群模板 → 集群实例"这条标准化链路的第一步，也是后续sync_set_template_to_set（用集群模板同步集群）等操作的前提。

二、请求参数详解

2.1 公共参数（common args）

请求中首先需要携带蓝鲸 API 网关（APIGW/ESB）统一要求的公共鉴权参数。以官方示例与 docs/apidoc/apigw/definition.yaml 中体现的字段为准，典型公共参数如下：

说明：公共参数的"必选"程度取决于接入方使用的鉴权方式（应用鉴权或登录态鉴权），实际以蓝鲸 API 网关接入规范为准；bk_supplier_account在请求示例中固定为"0"，用于多租户/开发商隔离场景。

2.2 接口专属参数

接口参数定义如下（与源码 src/common/metadata/set_template_request.go 中CreateSetTemplateOption结构体的 JSON 字段一一对应）：

其中CreateSetTemplateOption的 Go 定义为：

type CreateSetTemplateOption struct { Name string `field:"name" json:"name" bson:"name" mapstructure:"name"` ServiceTemplateIDs []int64 `field:"service_template_ids" json:"service_template_ids" bson:"service_template_ids" mapstructure:"service_template_ids"` }

可以看到name与service_template_ids同时被声明了 JSON、BSON 与 mapstructure 标签，说明该结构体既用于 HTTP 请求体解码，也用于 MongoDB 文档映射与配置转换，是贯穿"请求解析—数据落库"的统一数据载体。

三、完整请求与响应示例

3.1 请求参数示例

{ "bk_app_code": "esb_test", "bk_app_secret": "xxx", "bk_username": "xxx", "bk_token": "xxx", "bk_supplier_account": "0", "name": "test", "bk_biz_id": 20, "service_template_ids": [59] }

要点提示：

• bk_biz_id为 20，即业务 20 下创建集群模板；
• name为test，即集群模板名称；
• service_template_ids为[59]，即该集群模板关联 1 个服务模板（ID 为 59）；
• 请求示例同时演示了如何将业务 ID 放在请求体里，而真实的 REST 接口实现中，bk_biz_id也可通过 URL 路径/create/topo/set_template/bk_biz_id/{bk_biz_id}/传入（详见下文"接口实现"）。

3.2 返回结果示例

{ "result": true, "code": 0, "message": "success", "permission": null, "request_id": "e43da4ef221746868dc4c837d36f3807", "data": { "id": 6, "name": "test", "bk_biz_id": 20, "creator": "admin", "modifier": "admin", "create_time": "2019-11-27T17:24:10.671658+08:00", "last_time": "2019-11-27T17:24:10.671658+08:00", "bk_supplier_account": "0" } }

返回体中的data即为新创建的集群模板完整信息，其中id: 6是系统生成的集群模板唯一 ID。

四、返回结果参数说明

4.1 response 通用字段

所有 CMDB 接口统一遵循如下响应外壳（定义于 src/common/metadata/result.go 的BaseResp体系）：

4.2 data 字段说明

data对应集群模板实体SetTemplate（源码定义见 src/common/metadata/set_template.go）：

源码中的实体定义为：

type SetTemplate struct { ID int64 `field:"id" json:"id" bson:"id"` Name string `field:"name" json:"name" bson:"name"` BizID int64 `field:"bk_biz_id" json:"bk_biz_id" bson:"bk_biz_id"` Creator string `field:"creator" json:"creator" bson:"creator"` Modifier string `field:"modifier" json:"modifier" bson:"modifier"` CreateTime time.Time `field:"create_time" json:"create_time" bson:"create_time"` LastTime time.Time `field:"last_time" json:"last_time" bson:"last_time"` SupplierAccount string `field:"bk_supplier_account" json:"bk_supplier_account" bson:"bk_supplier_account"` }

五、接口调用链与源码实现剖析

5.1 REST 路由注册

该接口的真实访问路径由拓扑服务（topo_server）注册（见 src/scene_server/topo_server/service/service_settemplate_initfunc.go）：

utility.AddHandler(rest.Action{Verb: http.MethodPost, Path: "/create/topo/set_template/bk_biz_id/{bk_biz_id}/", Handler: s.CreateSetTemplate})

即 HTTP 方法为POST，完整网关路径为/api/v3/create/topo/set_template/bk_biz_id/{bk_biz_id}/。业务 ID 从 URL 路径中解析（src/scene_server/topo_server/service/set_template.go），请求体解码到metadata.CreateSetTemplateOption{}后进入业务逻辑。

5.2 服务端处理流程（topo_server → coreservice）

拓扑服务层的CreateSetTemplate（src/scene_server/topo_server/service/set_template.go）处理逻辑：

1. 从 URL 路径解析bk_biz_id，解析失败返回CCErrCommParamsInvalid；
2. 将请求体解码到CreateSetTemplateOption；
3. 校验service_template_ids非空，为空返回CCErrCommParamsNeedSet；
4. 在事务（AutoRunTxn）内调用 coreservice 的SetTemplate().CreateSetTemplate完成创建；
5. 若开启了权限中心鉴权（auth.EnableAuthorize()），将新集群模板注册为 IAM 资源创建者动作（RegisterResourceCreatorAction），类型为BizSetTemplate，详见 src/ac/iam/gen_id.go 的genSetTemplateResource与 src/ac/parser/settemplate.go 中"创建集群模板"的权限解析规则；
6. 返回创建的SetTemplate实体。

coreservice 层的CreateSetTemplate（src/source_controller/coreservice/service/set_template.go）进一步委托给核心操作类setTemplateOperation.CreateSetTemplate。

5.3 底层落库逻辑与校验规则（coreservice）

核心实现位于 src/source_controller/coreservice/core/settemplate/set_template.go，完整执行顺序如下：

1. 构造实体：以当前时间初始化SetTemplate，Creator/Modifier取请求用户，SupplierAccount取请求的开发商账号；
2. 名称合法性校验：调用SetTemplate.Validate（src/common/metadata/set_template.go），内部通过valid.ValidTopoNameField校验拓扑名称格式；
3. 业务 ID 校验：ValidateBusinessID（同文件 L42-L55）在cc_BaseApp表中按bk_biz_id计数，不存在则报参数非法；
4. 服务模板 ID 校验：ValidateServiceTemplateIDs（同文件 L57-L76）先对传入 ID 去重，再在cc_ServiceTemplate表中按bk_biz_id + id in (...)统计，数量不一致即返回CCErrCommParamsInvalid，确保传入的服务模板必须属于同一业务；
5. 名称唯一性校验：在cc_SetTemplate表中按name + bk_biz_id + bk_supplier_account过滤，同业务下重名返回CCErrCommDuplicateItem；
6. 生成 ID 并落库：通过mongodb.Client().NextSequence(cc_SetTemplate)生成自增 ID，插入cc_SetTemplate表；
7. 写入关联关系：将每个服务模板 ID 构造成SetServiceTemplateRelation（src/common/metadata/set_template.go），批量插入cc_SetServiceTemplateRelation表（多对多关系）。

对应的 MongoDB 表结构可参见 docs/db/set_template.md：cc_SetTemplate存放集群模板信息，cc_SetServiceTemplateRelation存放集群模板与服务模板的关联关系，cc_SetTemplateAttr存放集群模板属性配置（属性由"创建集群模板（全量信息）"接口create/topo/set_template/all_info一并写入）。

5.4 事务保证

整个创建过程在拓扑服务层包裹于事务中（AutoRunTxn，见 src/scene_server/topo_server/service/set_template.go）。若 coreservice 创建失败或 IAM 注册失败，事务回滚，避免出现"模板已创建但权限未注册"的中间态。

六、测试用例验证

仓库自带的集成测试 src/test/topo_server/set_template_test.go 完整覆盖了本接口的行为契约：

• "create empty set template test"（L25-L38）：传入空service_template_ids，断言返回CCErrCommParamsNeedSet，验证了"服务模板 ID 列表必填"的约束；
• "create normal set template test"（L40-L61）：使用合法的业务 ID 与service_template_ids: [serviceTemplateID]调用CreateSetTemplate，断言result == true、Name == "setTpl2"、ID != 0，随后依次覆盖更新、列表查询、关联服务模板查询、基于模板创建集群、模板与集群差异对比（Diff）等全流程。

读者可以以该测试文件为参照，编写自己的客户端调用代码（例如复用 src/apimachinery/toposerver/settemplate/settemplate.go 中的CreateSetTemplate客户端封装）。

七、常见问题与注意事项

1. service_template_ids不能为空：源码与测试均强制校验，空列表会返回参数必填错误；
2. 服务模板必须属于同一业务：传入的service_template_ids会在cc_ServiceTemplate表中按业务过滤并计数核对，跨业务传 ID 会失败；
3. 名称同业务唯一：同一业务下集群模板名称不可重复，重名报CCErrCommDuplicateItem；
4. 权限要求：调用需具备"集群模板新建"权限；启用权限中心时，创建动作还会同步注册到 IAM 资源实例（类型BizSetTemplate），便于后续细粒度授权；
5. ID 生成：id由 MongoDB 自增序列生成，返回响应中的id是后续更新、删除、同步等操作（如 update_set_template.md、sync_set_template_to_set.md）的关键入参；
6. 文档勘误提示：官方文档data字段说明中name的类型标注为array，从源码SetTemplate.Name（string 类型）与返回示例看，实际应为字符串类型。

八、小结

本文完整覆盖了 bk-cmdb"创建集群模板"接口的请求参数、请求/响应示例、返回字段说明，并通过 src/scene_server/topo_server/service/set_template.go 与 src/source_controller/coreservice/core/settemplate/set_template.go 两条源码路径还原了从 REST 入口到 MongoDB 落库的完整调用链：参数解析 → 权限注册 → 业务/服务模板/名称三重校验 → ID 生成 → 模板与关联关系双表写入 → 事务提交。掌握这一接口，即掌握了 CMDB 集群模板标准化的起点，也为后续集群模板同步、差异对比等高级能力打下基础。

• 后端
• 企业应用
• 运维