企业官网建设流程全解析

• 后端
• 企业应用
• 运维

本篇文章基于 bk-cmdb（蓝鲸智云配置平台，BlueKing CMDB）开源仓库中的 v3.12.3 版本变更记录（docs/support-file/changelog_user/en/v3.12.3_2023-11-06.md），结合仓库源码逐项解析该版本的核心能力：首页主机搜索新增「IP」与「BK-Network Area:IP」两种检索模式、创建模型时自动注入四个内置审计字段、动态分组交互优化与模型分组拖拽排序，以及权限中心重复注册问题的修复。读完本文，你将理解这些变更背后的数据模型与写入链路实现，并能据此规划升级与使用方式。

版本概览与升级入口

v3.12.3 是一个聚焦「检索体验」与「模型内置能力」的迭代版本，其变更集中在三类：Feature（新增特性）、Improved（体验优化）、Fixed（问题修复）。其中最具长期影响的变化是：新建模型时会自动附带四个内置字段，从而让每个模型实例天然具备"谁在何时创建/更新"的审计信息，无需业务方自行建模。

与本次发布对应的数据库升级逻辑，记录在升级器目录 src/scene_server/admin_server/upgrader/y3.12.202310301633 中。该目录下的 pkg.go 通过upgrader.RegistUpgrader("y3.12.202310301633", upgrade)注册了本次升级任务，核心动作是 add_recorded_fields.go 中的addRecordedFields——遍历存量模型对象表，为每个模型补齐这四个内置字段的属性定义，保证升级后新旧模型行为一致。

Feature 一：首页主机搜索支持两种检索模式

本版本为主页的主机搜索入口新增两种模式：

• IP：直接输入主机 IP 进行检索；
• BK-Network Area:IP：以「网络区域（管控区域）+ IP」的组合形式进行精确定位检索。

从数据模型角度看，这种组合检索之所以可行，是因为管控区域（Cloud Area）是主机模型的内置固有属性。仓库中主机实例与管控区域的关系可见于多处：在 src/scene_server/host_server/logics/host.go 中，主机数据会携带bk_cloud_id字段并参与归属区域的组织逻辑；在 src/scene_server/host_server/logics/hostsearch.go 的主机搜索逻辑中，bk_cloud_id同样被纳入属性解析与返回（attributeMap[common.BKCloudIDField] = common.FieldTypeInt）。也就是说，同一 IP 在不同管控区域中可以视为不同主机，因此用「区域:IP」定位比单独用 IP 更精确，尤其适合多区域（多云、多机房）纳管场景。

实际检索时，IP 匹配支持 IPv4/IPv6，前端已有对应的 IP 解析与粘贴自动切分能力（见 src/ui/src/components/filters/filter-fast-search.vue 中的splitIP/parseIP工具，能够同时解析 IPv4、IPv6 以及带管控区域的 IP 列表）。结合后端 src/apiserver 提供的检索服务，用户可在首页一次性完成跨区域的按 IP 模糊检索，或按「区域:IP」的精确检索。

Feature 二：模型初始化自动注入四个内置字段

这是本版本最值得关注的模型层能力。在初始化（创建）模型时，系统会自动为该模型添加四个内置字段：

四个字段的 ID 常量统一定义在 src/common/definitions.go 的inst record's logging information常量块中（BKCreatedAt/BKCreatedBy/BKUpdatedAt/BKUpdatedBy），与原有的create_time/last_time/creator/modifier等内部字段并存，共同构成实例的完整审计信息。

字段的属性设计：系统托管、不可编辑

这四个字段的属性定义集中体现在 src/scene_server/topo_server/logics/model/object.go 的recordedAttrs变量中，其设计要点为：

• IsOnly: false：不参与唯一性校验，避免与业务自定义唯一索引冲突；
• IsEditable: false：对用户不可编辑，确保审计信息不被业务侧篡改；
• IsRequired: false：非必填，写入由系统自动完成；
• IsPre: true：标识为系统预置属性；
• PropertyType：bk_created_at/bk_updated_at为FieldTypeTime，bk_created_by/bk_updated_by为FieldTypeUser；
• Creator: common.CCSystemOperatorUserName：属性的创建者标记为系统运营用户，即这类属性属于平台托管。

而在升级脚本 add_recorded_fields.go 中，同样的四个属性还额外声明了PropertyGroup: mCommon.BaseInfo（归入"基础信息"属性分组），并声明IsMultiple: false。

模型创建链路：属性如何被自动挂载

新建模型的完整链路位于 src/scene_server/topo_server/logics/model/object.go 的CreateObject：

1. createObjectParamCheck完成模型参数校验；
2. 调用CoreService().Model().CreateModel创建模型本身（底层实现在 src/source_controller/coreservice/core/model/model.go 的CreateModel，通过lock.GetLockKey(lock.CreateModelFormat, ...)保证模型创建的并发安全）；
3. 创建默认属性分组（GroupName 为 "Default"，GroupIndex: -1）；
4. 调用createDefaultAttrs写入默认属性——该函数（object.go）除了注入实例名称属性（PropertyID为该模型的实例名字段、IsRequired: true）外，还会逐个遍历recordedAttrs并附加到新建模型；若为模型主线（mainline）模型，还会额外增加父实例字段bk_inst_parent；
5. 创建唯一索引与审计日志。

也就是说，四个内置字段在模型落库的同一创建事务流程中被一次性写入，新建即自带，业务方无需感知。需要说明的是：从源码结构看，这一自动注入发生在模型创建服务（topo_server 的 model 逻辑）中，因此后续通过模型导入（如 CreateObjectByImport）等其他创建入口的行为，需以对应入口实现为准。

实例写入链路：字段值由系统自动填充

这四个字段不仅自动建模，其值也完全由系统在实例写入时自动生成，业务侧无需也不能手动维护：

• 创建实例时：单条创建入口 instance_crud.go 的save与批量创建入口 instance_crud.go 中，都会统一执行inputParam.Set(common.BKCreatedBy, kit.User)、Set(common.BKCreatedAt, ts)、Set(common.BKUpdatedAt, ts)——创建人取自当前请求用户kit.User，时间取time.Now()，同时也会写入原有的create_time/last_time字段，保证新旧字段双写一致；
• 更新实例时：instance_crud.go 的update在落库前会执行data.Set(common.LastTimeField, ts)、data.Set(common.BKUpdatedBy, kit.User)、data.Set(common.BKUpdatedAt, ts)，确保每次修改都刷新"更新时间/更新人"；完整的更新流程（含唯一字段校验、实例校验器校验、进程绑定 IP 联动更新等）见 instance.go 的UpdateModelInstance；
• 时间类型处理时：在 instance_validate.go 的changeStringToTime中，bk_created_at/bk_updated_at会被显式跳过字符串转时间处理，避免被业务传入参数覆盖。

老数据兼容：与 create_time/last_time 的无缝衔接

升级前存量实例并没有bk_created_at/bk_updated_at值。为保证检索与展示的一致性，查询链路做了专门的兼容处理（instance.go 的FindInst）：

• 当查询字段包含bk_created_at但实例中该值为空时，自动回填为旧字段create_time的值；
• 当查询字段包含bk_updated_at但为空时，自动回填为last_time的值；
• 同时按需补充查询旧字段，并在返回前剔除不必要字段，保证 API 输出与升级前保持一致。

此外，在时间条件查询构造处（src/common/metadata/common.go），bk_created_at与bk_updated_at会被映射到create_time与last_time参与底层过滤，确保以新字段 ID 发起的查询也能命中历史数据。

使用建议

• 升级到 v3.12.3 后，存量模型会通过升级器自动补齐四个字段定义，无需手工建字段；
• 由于IsEditable: false，不要在业务侧尝试通过更新接口修改这些字段的值——系统会在写入链路统一覆盖；
• 做实例审计、变更追溯时，可直接基于bk_created_by/bk_updated_by/bk_created_at/bk_updated_at构建报表，或利用模型字段组合条件进行时间范围检索。

Improved：动态分组与模型分组操作体验优化

本版本还包含两项交互层面的优化：

• 动态分组（Dynamic Grouping）创建、预览、编辑流程的交互优化。动态分组是主机检索的高阶能力，其服务端实现位于 src/scene_server/host_server/logics/dynamic_grouping.go，其中主机条件组合会涉及bk_cloud_id等主机内置字段（见 dynamic_grouping.go 对BKCloudIDField的使用）。本版本的优化重点在创建、预览与编辑三者的衔接体验，具体交互细节以前端实际表现为准。
• 模型分组下支持通过拖拽修改模型顺序。该能力属于模型分组展示层的排序交互，用于调整分组内模型列表的展示次序，便于按业务习惯组织模型视图。

Fixed：修复创建模型时权限中心偶发重复注册

本次版本修复了一个稳定性问题：创建模型时，权限中心（IAM）偶尔会出现重复注册的情况。由于创建模型属于高频管理操作，偶发的重复注册会带来多余的权限资源冗余。修复后，模型创建与权限资源注册的幂等性得到保障，避免重复资源对权限模型管理造成干扰。相关权限接入可参见 src/ac/iam 目录下的权限资源初始化与注册逻辑。

升级与验证要点

1. 升级路径：升级至 v3.12.3 时，admin_server 会按升级器注册顺序执行y3.12.202310301633任务，为存量模型补齐内置审计字段（pkg.go）；
2. 验证字段注入：升级后新建任意自定义模型，在模型属性列表中应能看到"创建时间/创建人/更新时间/更新人"四个不可编辑字段；创建实例后查看实例详情，四个字段应已由系统自动填充；
3. 验证搜索模式：在首页主机搜索框分别使用「IP」与「BK-Network Area:IP」两种模式检索，确认多管控区域场景下区域+IP 组合能够精确返回目标主机；
4. 回归检查：确认历史实例查询结果中bk_created_at/bk_updated_at能正确回填旧值，时间范围查询行为与升级前一致。

• 后端
• 企业应用
• 运维