企业官网建设流程全解析

• 后端
• 企业应用
• 运维

导读

本文以蓝鲸配置平台（bk-cmdb）开放 API 文档中「创建容器集群」（create_kube_cluster）接口为核心，完整讲解其请求参数、请求/响应报文、权限与版本约束，并深入仓库源码，从拓扑服务（topo_server）到核心服务（coreservice）再到 MongoDB 存储，还原一次容器集群创建请求的完整调用链与底层校验逻辑。读完本文，你将掌握该接口的完整用法，并能根据源码确认各字段的必填性与可编辑性约束，为容器资源（集群、命名空间、工作负载等）的纳管与二次开发提供可靠依据。

接口概览：创建容器集群

「创建容器集群」是 bk-cmdb 容器资源管理（kube 模块）对外提供的核心写接口，用于在指定业务（business）下登记一个 Kubernetes 集群。接口基本信息如下：

• 接口版本：v3.12.1 及以上
• 权限要求：容器集群（Kube Cluster）的创建权限
• HTTP 方法：POST
• API 路径：/api/v3/create/kube/cluster

从网关资源定义文件 bk_apigw_resources_bk-cmdb.yaml 可以看到该资源在 API 网关侧的完整配置：

/api/v3/create/kube/cluster: post: operationId: create_kube_cluster description: 创建容器集群 x-bk-apigateway-resource: isPublic: false allowApplyPermission: true matchSubpath: false backend: type: HTTP method: post path: /api/v3/create/kube/cluster matchSubpath: false timeout: 0 upstreams: {} transformHeaders: {} pluginConfigs: - type: bk-rate-limit yaml: | rates: __default: - period: 1 tokens: 100 authConfig: userVerifiedRequired: false disabledStages: [] descriptionEn:

从配置可以看出：该接口默认不公开（isPublic: false），支持申请权限（allowApplyPermission: true），并挂载了bk-rate-limit限流插件（默认每 1 秒 100 个令牌），可用于管控调用频率。

请求参数详解

创建容器集群请求体为 JSON，参数定义如下：

字段约束的源码级验证

以上字段的「必填」「是否可编辑」约束并非仅停留在文档层面，在 cluster.go 中通过字段描述符（ClusterSpecFieldsDescriptor）做了显式声明：

var ClusterSpecFieldsDescriptor = table.FieldsDescriptors{ {Field: KubeNameField, Type: enumor.String, IsRequired: true, IsEditable: true}, {Field: SchedulingEngineField, Type: enumor.String, IsRequired: false, IsEditable: false}, {Field: UidField, Type: enumor.String, IsRequired: true, IsEditable: false}, {Field: XidField, Type: enumor.String, IsRequired: false, IsEditable: false}, {Field: VersionField, Type: enumor.String, IsRequired: false, IsEditable: true}, {Field: ClusterEnvironmentField, Type: enumor.String, IsRequired: false, IsEditable: true}, {Field: NetworkTypeField, Type: enumor.Enum, IsRequired: false, IsEditable: true}, {Field: RegionField, Type: enumor.String, IsRequired: false, IsEditable: true}, {Field: VpcField, Type: enumor.String, IsRequired: false, IsEditable: false}, {Field: NetworkField, Type: enumor.String, IsRequired: false, IsEditable: true}, {Field: TypeField, Type: enumor.String, IsRequired: true, IsEditable: true}, {Field: ProjectNameField, Type: enumor.String, IsRequired: false, IsEditable: true}, {Field: ProjectIDField, Type: enumor.String, IsRequired: false, IsEditable: true}, {Field: ProjectCodeField, Type: enumor.String, IsRequired: false, IsEditable: true}, }

从源码结构可以推断出几个对调用方重要的细节：

• name、uid、type为创建必填字段，其中uid是第三方平台侧集群唯一标识（如 BCS 集群 ID），scheduling_engine、xid、vpc创建后不可编辑；
• scheduling_engine虽是可选字段，但建议明确传入（如k8s），源码注释指出其含义是调度引擎（如 k8s、tke 等），见 cluster.go；
• network为数组，对应结构体中的NetWork *[]string，描述全局路由网络地址（容器 overlay 网络），如["1.1.1.0/21"]，见 cluster.go；
• 字段常量定义集中在 types.go，如KubeNameField = "name"、UidField = "uid"、TypeField = "type"等，可作为字段名的权威参考。

集群类型枚举

type字段仅接受两个枚举值，由ClusterType类型及校验逻辑强制约束（见 cluster.go）：

const ( SharedClusterType ClusterType = "SHARE_CLUSTER" IndependentClusterType ClusterType = "INDEPENDENT_CLUSTER" )

ClusterType.Validate()会校验传入值，若不属于上述两个枚举则返回CCErrCommParamsIsInvalid（参数非法）错误。其中SHARE_CLUSTER对应共享集群，INDEPENDENT_CLUSTER对应独立集群，共享集群与业务的关联通过命名空间维度的关系表cc_NsSharedClusterRelation维护（见 cluster.go）。

请求示例

{ "bk_biz_id": 2, "name": "cluster", "scheduling_engine": "k8s", "uid": "xxx", "xid": "xxx", "version": "1.1.0", "network_type": "underlay", "region": "xxx", "vpc": "xxx", "network": [ "127.0.0.0/21" ], "type": "INDEPENDENT_CLUSTER", "environment": "xxx", "bk_project_id": "21bf9ef9be7c4d38a1d1f2uc0b44a8f2", "bk_project_name": "test", "bk_project_code": "test" }

要点说明：

• bk_biz_id必须为当前业务内有效 ID，ValidateCreate()中若BizID == 0会直接返回CCErrCommParamsNeedSet（参数缺失）错误（见 cluster.go）；
• bk_project_id/bk_project_name/bk_project_code用于关联蓝鲸容器平台（BCS）项目信息，均为可选；
• network_type常见取值为overlay或underlay，源码注释中以 overlay/underlay 为例（见 cluster.go）。

响应示例与响应参数

成功创建后接口返回：

{ "result": true, "code": 0, "message": "success", "permission": null, "data": { "id": 1 } }

响应参数说明：

data.id对应结构体RspID（见 object_controller.go），即 CMDB 侧集群自增主键bk_cluster_id的来源；而uid才是第三方平台侧的集群唯一标识，二者需要区分。对外响应类型CreateClusterRsp的定义见 cluster.go。

源码级实现原理：一次创建请求的完整调用链

从网关层到数据落库，「创建容器集群」经历了多级服务的协作，关键调用链如下：

1. API 网关 / 业务接入层：请求经网关转发至拓扑服务（topo_server），路由注册见 service.go：POST /create/kube/cluster -> CreateCluster；
2. 拓扑服务（topo_server）入口：处理函数 cluster.go 依次执行：
   • ctx.DecodeInto(data)解析请求体到types.Cluster结构体；
   • data.ValidateCreate()做参数合法性校验；
   • 权限校验：构造acmeta.ResourceAttribute{Type: acmeta.KubeCluster, Action: acmeta.Create}进行鉴权，无权限则返回RespNoAuth，对应文档所述「容器集群创建权限」；
   • 事务执行：通过AutoRunTxn包裹「创建集群 + 生成审计日志」两个操作，保证一致性；
   • 调用CoreService().Kube().CreateCluster()下发到核心服务，并返回metadata.RspID{ID: id}。
3. 核心服务（coreservice）落库：处理函数 cluster.go 完成：
   • 再次执行ValidateCreate()校验；
   • 通过mongodb.Client().NextSequence(...)基于cc_ClusterBase表生成自增 ID；
   • 填充Revision（creator、modifier、create_time、last_time）与SupplierAccount；
   • 写入 MongoDB 表cc_ClusterBase（常量BKTableNameBaseCluster，见 types.go）。
4. 审计日志：拓扑服务在事务内调用auditlog.NewKubeAudit(...).GenerateClusterAuditLog(...)生成并保存集群创建审计日志，便于后续追溯。

客户端 SDK 封装

若在 Go 服务中调用该接口，可使用 apimachinery 提供的客户端封装。拓扑服务客户端CreateCluster位于 kube.go，核心服务客户端位于 api.go，二者均以POST /create/kube/cluster为子路径，通过 REST 客户端发起请求并解析CreateClusterRsp，最终返回data.id。

测试用例验证

仓库集成测试 cluster_test.go 对该接口进行了端到端验证，可作为调用参考与行为佐证：

• 正常创建：构造types.Cluster（含 name、scheduling_engine=k8s、uid、xid、version、network_type=underlay、region、vpc、network、type=INDEPENDENT_CLUSTER）调用kubeClient.CreateCluster，断言成功且返回集群 ID；
• 必填字段校验：不传name时调用创建，断言错误信息包含"name"，验证name必填约束生效；
• 创建后更新与删除：测试随后验证了版本字段可更新、uid等非可编辑字段更新被拒绝（错误信息包含"uid"）、以及按 ID 删除集群的流程；
• 查询验证：通过SearchCluster按name精确过滤，验证集群数据落库且可被检索。

常见问题与调用建议

• 报「参数非法」：检查type是否严格等于INDEPENDENT_CLUSTER或SHARE_CLUSTER；检查bk_biz_id是否缺失或为 0；
• 报「缺少必填参数」：重点核对name、uid、type三个必填项；
• uid与xid的区别：uid是集群自身在第三方平台的唯一 ID（创建后不可修改），xid是它依赖的底层集群 ID，仅在存在嵌套关系时填写；
• 限流与权限：网关侧默认限流 100 次/秒，且接口需申请容器集群创建权限，调用前请确认已完成权限申请；
• 网络规划字段：network建议按 CIDR 数组传入容器网络地址，与network_type（overlay/underlay）配合描述集群网络拓扑。

相关资源路径速览

• 接口文档原文：create_kube_cluster.md
• 网关资源定义（含限流、鉴权配置）：bk_apigw_resources_bk-cmdb.yaml
• 集群数据模型与校验逻辑：cluster.go
• 字段名常量定义：types.go
• 拓扑服务实现：cluster.go
• 核心服务落库实现：cluster.go
• 客户端封装：kube.go
• 集成测试用例：cluster_test.go

• 后端
• 企业应用
• 运维