企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本文以 docs/db/built-in_model.md 为主体，系统讲解蓝鲸配置平台（BlueKing CMDB）中业务集、主机、项目这三类内置模型在 MongoDB 中的底层集合结构。你将掌握cc_BizSetBase中bk_scope范围过滤规则的三层嵌套结构、cc_HostBase中 IP 与 Agent ID 的唯一性约束实现，以及cc_ProjectBase的字段语义与索引设计，同时结合src/common下的源码厘清"内置模型表"与"用户自定义模型分表"之间的存储关系，为二次开发、数据巡检与运维排障提供直接依据。

一、前置认知：MongoDB 集合与"表结构"文档的关系

蓝鲸 CMDB 底层使用 MongoDB 进行数据存储。MongoDB 是面向文档的数据库，没有传统关系型数据库意义上的"表"，而是以**集合（Collection）和文档（Document）**组织数据。因此 docs/db/README.md 中明确说明：本目录下文档中涉及的"表结构和字段解释仅供参考，请以实际环境中的结构为准"。

内置模型是 CMDB 中最核心的一类模型，包括业务、业务集、集群、模块、主机、进程、管控区域、项目等。这些模型的实例数据并不存放在通用的实例分表中，而是存放在各自的内置集合中，集合名在源码中通过常量统一定义：

• BKTableNameBaseBizSet = "cc_BizSetBase"
• BKTableNameBaseHost = "cc_HostBase"
• BKTableNameBaseProject = "cc_ProjectBase"

参见 src/common/tablenames.go。同时，src/common/definitions.go 定义了这些内置模型的对象 ID：业务集为bk_biz_set_obj、主机为host、项目为bk_project，配合GetInstTableName将对象 ID 映射到对应集合（见 src/common/tablenames.go）。

一个关键设计是：内置集合仅保存模型内置的预定义字段，而用户在模型上扩展的自定义属性字段会动态叠加到同一文档中。下文每一节的"注意"都强调了这一点——表结构取决于用户在模型中定义的属性字段。

二、cc_BizSetBase：业务集信息集合

2.1 作用

cc_BizSetBase（BKTableNameBaseBizSet）用于存放业务集信息。业务集是 CMDB 中对多个业务（biz）进行聚合管理的逻辑单元，通过bk_scope描述其包含的业务范围。

2.2 集合结构

注意：此处仅对业务集内置的模型字段做说明，业务集表结构字段取决于用户在业务集模型中定义的属性字段。

这一结构与源码中的BizSetInst结构体一一对应（见 src/common/metadata/inst.go），其中Scope BizSetScope对应bk_scope，Default int64对应default字段。字段常量在 src/common/definitions.go 中定义（BKBizSetIDField、BKBizSetNameField、BKBizSetScopeField = "bk_scope"、BKBizSetMatchField = "match_all"）。

2.3 bk_scope 字段结构：业务集范围的过滤规则

bk_scope是业务集的核心字段，决定该业务集包含哪些业务。其结构分为三层：

第一层：bk_scope

第二层：bk_scope.filter

第三层：bk_scope.filter.rules

过滤规则为三元组field、operator、value：

2.4 源码级校验：bk_scope 的合法性约束

bk_scope并非自由拼装，而是经过严格校验后才允许入库。BizSetScope的校验逻辑定义在 src/common/metadata/toposerver.go，要点如下：

• match_all与filter互斥：当match_all为true时，filter必须为空；当match_all为false时，filter必须设置。二者同时存在或同时缺失都会报错。
• 条件深度固定为 2 层：scope.Filter.GetDeep()必须等于common.BizSetConditionMaxDeep，即过滤条件最多嵌套两层。
• 仅支持CombinedRule且组合条件必须为AND：filter.condition取值只能是AND，保证子条件之间是"与"的关系。
• 叶子规则（AtomRule）仅支持equal与in两个操作符：这意味着业务集范围规则只能用"等于某个值"或"属于某集合"来表达，不允许使用大小比较、模糊匹配等操作符。

从实现上看，filter的类型是*querybuilder.QueryFilter，其规则体系定义在 src/common/querybuilder/types.go：AtomRule{Field, Operator, Value}为叶子规则，CombinedRule{Condition, Rules}为组合规则，condition支持AND/OR，操作符枚举包括equal、not_equal、in、not_in、less、greater、contains、begins_with、is_empty、is_null、exist等。规则在落库前还会通过ToMgo()转换为 MongoDB 查询条件（如equal→$eq、in→$in、contains→ 正则$regex，见 src/common/querybuilder/types.go）。

创建业务集时，CreateBizSetRequest还会强制要求bk_biz_set_name必填（见 src/common/metadata/toposerver.go）。

2.5 集合索引

cc_BizSetBase的索引注册在 src/common/index/collections/business_set.go，包含：

• bk_biz_set_id上的唯一索引（CCLogicUniqueIdxNamePrefix + "biz_set_id"）；
• bk_biz_set_name上的唯一索引（业务集名称全局唯一）；
• bk_biz_set_id + bk_biz_set_name + bk_supplier_account上的普通组合索引。

三、cc_HostBase：主机信息集合

3.1 作用

cc_HostBase（BKTableNameBaseHost）是 CMDB 中最重要、数据量最大的集合之一，用于存放主机信息。主机是资产管理的核心对象，其上承载了 IP、Agent、云厂商、CPU/内存/磁盘等大量属性。

3.2 集合结构

注意：此处仅对主机内置的模型字段做说明，主机表结构字段取决于用户在主机模型中定义的属性字段。

3.3 关键字段语义补充

• bk_host_innerip/bk_host_outerip是数组类型（String Array）：一台主机可能拥有多个内网 IP 或外网 IP，因此字段以数组形式存储；IPv6 地址单独存放在bk_host_innerip_v6/bk_host_outerip_v6中。相关字段常量定义于 src/common/definitions.go 与 src/common/definitions.go。
• bk_agent_id（GSE Agent ID）：用于唯一标识一台已安装 GSE Agent 的主机，是 CMDB 与 GSE 管控体系对接的桥梁。
• bk_addressing（寻址方式）：取值定义在源码中，static表示静态寻址、dynamic表示动态寻址（见 src/common/definitions.go）。该字段直接参与主机唯一性约束（见下文索引说明）。
• bk_cloud_id（管控区域 id）：对应cc_PlatBase中的管控区域，主机必须归属某个管控区域。
• import_from（录入方式）：记录主机来源（如手动录入、Excel 导入、API 导入、云资源同步等）。

3.4 集合索引：IP 与 Agent ID 的唯一性约束

主机集合的索引定义在 src/common/index/collections/hostbase.go，是理解 CMDB 主机数据一致性的关键：

• bk_host_innerip + bk_cloud_id唯一索引：保证"同一管控区域内，静态寻址主机的内网 IP 不重复"。通过PartialFilterExpression（部分过滤索引）限定仅对bk_addressing = "static"的主机生效——即只有静态寻址主机才要求"内网 IP + 管控区域"唯一。
• bk_host_innerip_v6 + bk_cloud_id唯一索引：与上一条同理，针对 IPv6 地址，同样仅约束静态寻址主机。
• bk_agent_id唯一索引：保证一个 Agent ID 只能对应一台主机；部分过滤条件bk_agent_id > ""允许"未安装 Agent"的多台主机同时存在空 Agent ID。

此外还注册了一批历史兼容索引（bk_host_name_1、bk_host_innerip_1、idx_unique_hostID、bk_cloud_id_1等），见 src/common/index/collections/hostbase.go，初始化时通过registerIndexes统一注册（src/common/index/collections/hostbase.go）。

四、cc_ProjectBase：项目信息集合

4.1 作用

cc_ProjectBase（BKTableNameBaseProject）用于存放项目信息。项目是 CMDB 面向容器/云资源管理场景引入的一级组织单元（对象 ID 为bk_project），用于将资源按项目维度进行隔离与管理。

4.2 集合结构

注意：此处仅对项目内置的模型字段做说明，项目表结构字段取决于用户在项目模型中定义的属性字段。

字段常量在 src/common/definitions.go 中定义，包括bk_project_id、bk_project_name、bk_project_code、bk_project_desc、bk_project_type、bk_project_sec_lvl、bk_project_owner、bk_status等，此外还存在bk_project_team（项目团队）与bk_project_icon（项目图标）字段定义。

4.3 集合索引与写入限制

• 索引设计：cc_ProjectBase的索引注册在 src/common/index/collections/project.go，包括id、bk_project_id、bk_project_name、bk_project_code上的四个唯一索引（自增 ID、项目 ID、项目名称、项目英文名均全局唯一），以及bk_status上的普通索引。
• 批量写入限制：创建项目接口（CreateProjectOption）与更新项目接口（UpdateProjectOption）均将单次写入/更新的条数上限限制为common.BKWriteOpLimit（其值为 200，定义于 src/common/definitions.go），超出即返回"参数个数超出限制"错误，见 src/common/metadata/toposerver.go。

五、内置模型表与实例分表的关系

理解了上述三张集合后，还需要厘清它们在整个 CMDB 存储体系中的位置。CMDB 的模型实例数据分为两类存储路径（见 src/common/tablenames.go）：

1. 内置模型实例（业务、业务集、主机、模块、集群、进程、管控区域、项目等）：写入各自的固定集合，即本篇文章介绍的cc_BizSetBase、cc_HostBase、cc_ProjectBase，以及cc_ApplicationBase（业务）、cc_SetBase（集群）、cc_ModuleBase（模块）、cc_Process（进程）、cc_PlatBase（管控区域）等。映射关系由GetInstTableName统一完成。
2. 用户自定义模型实例：写入按开发商与对象 ID 动态生成的分表，命名格式为cc_ObjectBase_{supplierAccount}_pub_{objectID}（如cc_ObjectBase_0_pub_switch），对应GetObjectInstTableName的实现。

因此，业务集、主机、项目这三张表承载的只是内置预定义字段，用户在这些模型上新增的扩展属性虽然也物理存储在同一个文档中，但字段集合是动态、可变化的——这正是阅读本文各节"注意"提醒时需要牢记的核心规则。

六、实践建议：如何核对这三张集合

• 需要查看实际结构时，可以通过 MongoDB shell 连接 CMDB 的存储库，执行db.cc_BizSetBase.findOne()、db.cc_HostBase.findOne()、db.cc_ProjectBase.findOne()观察真实文档字段（参考 docs/db/README.md 中"以实际环境中的结构为准"的说明）。
• 排查主机重复录入问题时，重点检查cc_HostBase上bk_host_innerip + bk_cloud_id唯一索引与bk_agent_id唯一索引是否生效（源码入口在 src/common/index/collections/hostbase.go）。
• 业务集bk_scope的过滤规则若校验失败，可对照 src/common/metadata/toposerver.go 的BizSetScope.Validate()检查是否违反了"match_all 与 filter 互斥、深度为 2、仅 AND 组合、仅 equal/in 操作符"四条约束。

上述所有字段、约束与索引均可从当前仓库src/common目录下的常量定义、数据结构与索引注册代码中逐一溯源验证。

• 后端
• 企业应用
• 运维