• 后端
• 企业应用
• 运维

本文基于 bk-cmdb 官方发布说明 v3.10.16_2022-05-17.md 编写，结合当前仓库源码对每条变更进行实现级印证。v3.10.16 于 2022 年 5 月 17 日发布，共包含8 项新功能（Feature）、6 项缺陷修复（Bugfix）与 8 项升级优化（Upgrade），覆盖模型导入导出、业务集关联、主机自动应用、HTTP 超时机制、HTTPS 支持等核心方向。读完本文，你将掌握该版本每一项变更的业务价值、影响范围与对应的源码实现位置，并能据此规划升级与接口适配工作。

一、版本概览

本版本是 bk-cmdb 3.10 系列的一次功能型小版本迭代，变更集中在"配置模型管理"与"主机/拓扑查询体验"两大主题：

• 模型与拓扑：新增模型导入导出、业务集关联、主机+拓扑自定义层级查询条件；
• 主机管理：主机搜索支持模块/集群名称模糊匹配，主机自动应用支持按服务模板配置并限制不适用字段；
• 平台底座：各组件 HTTP 请求上下文引入超时机制，各服务支持 HTTPS；
• 接口兼容：procserver 部分无分页接口改为强制分页（见 issue #5651），调用方需适配。

二、新功能（Feature）详解

1. 服务与集群模板实例列表支持单实例删除入口

此前在服务模板（Service Template）与集群模板（Set Template）的实例列表页中，实例通常只能通过"同步差异对比"后批量处理。本版本为实例列表页新增单个实例删除入口，运维人员可以直接在列表中对某一具体实例发起删除，而无需进入批量操作流程，降低了单实例清理的操作成本。

2. 主机搜索支持模块、集群名称模糊搜索

在主机查询场景中，用户常通过模块名、集群名来缩小主机范围。本版本在主机查询链路中支持对模块名称、集群名称进行模糊搜索。

从源码实现看，该能力由主机服务端的ListBizHostsTopo流程承载，核心逻辑位于 findhost.go：当请求携带SetPropertyFilter（集群属性过滤）或ModulePropertyFilter（模块属性过滤）时，服务会先调用parseHostsTopoFilter分别解析出符合条件的集群 ID 集合与模块 ID 集合，再将其作为SetIDs、ModuleIDs传入底层ListHosts查询。任何一层过滤条件命中结果为空时，直接返回空集，避免全表扫描后再过滤的性能损耗：

// if set filter or module filter is set, search them first to get ids to filter hosts filteredSetIDs, setMap, err := s.parseHostsTopoFilter(ctx.Kit, common.BKInnerObjIDSet, bizID, parameter.SetPropertyFilter) filteredModuleIDs, moduleMap, err := s.parseHostsTopoFilter(ctx.Kit, common.BKInnerObjIDModule, bizID, parameter.ModulePropertyFilter)

3. 主机自动应用支持按服务模板配置与体验优化

主机自动应用（Host Auto-Apply）在本版本中支持依据服务模板（Service Template）的配置生成应用执行计划，并同步优化了使用体验。

源码侧的核心实现在 plan.go 的GenerateApplyPlan：该函数接收业务 ID、主机-模块关系（HostModules）与规则列表（Rules）后，先聚合出主机 ID 与属性 ID，再通过listHostAttributes拉取主机属性定义，最后仅查询计划所需的字段（如bk_host_id、bk_host_innerip、bk_host_innerip_v6、bk_cloud_id、bk_host_name及规则涉及的属性字段）来构造执行计划。这一"按需取字段"的实现方式，与发布说明中"体验优化"的表述一致——只读取必要字段，减少无关数据拉取。相关数据模型可进一步参考 host_apply_rule.go。

4. 新增模型导入导出功能

这是本版本最重要的功能之一：支持对自定义模型（及其字段、关联关系）进行整体导入导出，便于在多环境、多实例之间迁移配置模型。

从后端看，模型导入导出能力承载在 web_server 的 Excel/文件服务中，scene.go 定义了明确的导入类型与文件格式映射：

模型导出/导入的操作算子实现在 operator/model/operator.go，其中Export()负责将模型数据写入 Excel，Import()负责解析导入的属性字段并校验合法性（getImportAttr/getImportAttrVal完成逐字段的值转换与校验）。

前端方面，模型导入导出面板提供了完整的四步式向导：用户须知 → 上传模型包 → 确认导入数据（编辑）→ 展示导入结果，导入数据分为confirmedModels（模型）与confirmedRelationTypes（关联类型）两类，支持导入前的人工确认与修正，避免误导入脏数据。

5. 业务集支持关联

业务集（Business Set）在本版本中正式支持关联能力。业务集将多个业务按统一条件聚合为一个管理单元，此前的实现仅覆盖"创建/删除/查询"等基础操作，本版本补齐了关联相关的语义支持。

从源码看，业务集的操作接口已形成完整闭环：biz_set.go 定义了CreateBizSet、UpdateBizSet、DeleteBizSet、FindBizInBizSet（查询业务集中的业务）、FindBizSetTopo（查询业务集拓扑路径）与SearchBusinessSet等客户端接口；服务端实现在 inst_business_set.go，路由注册见 service_initfunc.go：

PUT /updatemany/biz_set 更新业务集 POST /deletemany/biz_set 删除业务集 POST /find/biz_set/biz_list 查询业务集下的业务列表 POST /find/biz_set/topo_path 查询业务集拓扑路径

业务集的权限模型也同步扩展，biz_set.go 为其提供了独立的访问控制扩展，使"业务集"成为 IAM 权限体系中的一类资源。前端业务集服务的调用封装可参考 src/ui/src/service/business-set/index.js，其中find/biz_set/biz_list接口同时支持分页与非分页两种调用方式。

6. 组件 HTTP 请求上下文新增超时机制

本版本为各组件间的 HTTP 请求上下文引入了统一的超时机制，目标是避免某个下游服务长时间无响应时，上游请求"悬挂不退出"拖垮整个调用链。相关实现集中在 httpclient/client.go 等公共 HTTP 客户端代码中：所有通过公共客户端发起的请求都纳入上下文超时管控，一旦超时即中止请求并返回错误。这是一项典型的"防呆"基础设施增强，对生产环境的稳定性有直接价值，建议升级后在监控中观察请求超时相关的错误计数。

7. 各服务支持 HTTPS

本版本支持为各服务启用 HTTPS 通信。公共 TLS 配置能力位于 common/ssl/ssl.go，提供三类配置入口：

• ClientTLSConfNoVerify()：客户端不校验服务端证书（内部链路常用）；
• ClientTLSConfVerity(caFile, certFile, keyFile, passwd)：客户端严格校验 CA、证书与密钥；
• ServerTLSVerifyClient(caFile, certFile, keyFile, passwd)：服务端启用 TLS 并校验客户端证书（双向 TLS）。

运维人员可通过为各服务配置证书与密钥文件，将内部通信切换为 HTTPS 加密链路，具体启用方式以各服务的配置文件模板为准（可参考 docs/support-file/config/templates 下的服务配置模板）。

8. 主机及其拓扑查询新增自定义层级查询条件

在"查询主机及其对应拓扑"（ListBizHostsTopo）场景中，本版本新增了自定义层级查询条件：除了主机自身属性过滤外，还可以同时对拓扑层级上的集群（Set）属性与模块（Module）属性进行过滤。这就是第 2 条模糊搜索背后的通用能力——SetPropertyFilter/ModulePropertyFilter不只支持模糊匹配，还支持任意属性条件的组合过滤，并在过滤完成后通过rearrangeBizHostTopo重组主机与拓扑的映射关系后返回。

三、缺陷修复（Bugfix）详解

1. 修复模型实例审计详情报错

此前在查看模型实例的审计详情时会出现错误提示，本版本已修复该问题。审计能力由 src/common/auditlog 系列模块承载，涉及实例操作（创建/更新/删除）的审计记录生成与回放，修复点在于实例审计详情回放时的数据组装逻辑。

2. 修复业务集视图下主机自动应用状态显示与拓扑地址参数校验

在业务集（而非单一业务）视图下使用主机自动应用时，存在两类问题：一是自动应用状态的展示与实际不符；二是拓扑地址（topo 地址）参数的合法性校验缺失或误判。本版本同时修复了状态显示与参数校验逻辑，保证业务集视图下自动应用的"所见即所得"。这与第 2 节中GenerateApplyPlan的"主机-模块关系"（HostModules）处理逻辑直接相关——跨业务聚合场景下，必须按业务集维度正确校验主机归属与拓扑地址。

3. 修复业务集编辑业务范围不生效

业务集的核心语义是"业务范围（Scope）"——即通过一组条件（如业务字段bk_biz_id之外的枚举/组织类型字段）圈定哪些业务被聚合。此前存在编辑业务范围后不生效的缺陷。

从当前源码看，UpdateBizSet（inst_business_set.go）已包含完整的范围更新链路：先通过validateScopeFields校验范围字段必须为枚举/组织类型（bk_biz_id字段除外），再调用doAboutBuiltInBusinessSet处理内置业务集约束，最后在事务（AutoRunTxn）内通过UpdateInst更新bk_biz_set_scope字段。同时源码明确约束：批量更新多个业务集时不允许同时修改名称（bk_biz_set_name）与范围（bk_biz_set_scope），以避免批量操作引发范围漂移。

4. 修复新建模型字段分组无法正常折叠

模型字段分组（Field Group）在新建后存在无法正常折叠显示的问题，本版本已修复。字段分组的数据模型定义在 attribute.go 等相关元数据文件中，修复主要涉及分组默认折叠状态（collapsed）的初始化与前端渲染同步。

5. 修复服务模板同步实例变更对比样式与拓扑节点创建下拉框触发

本版本修复了三个前端交互细节：

• 服务模板同步实例的变更对比（diff）内容溢出时文本样式错乱；
• 拓扑节点创建下拉框的触发事件失效，导致点击无法展开选择；
• 相关样式与事件处理均在拓扑管理/服务模板同步的前端页面中调整，涉及 src/ui/src 下拓扑与模板管理相关组件。

6. 修复 search_instance_associations 不支持双向查询关联关系

实例关联查询接口search_instance_associations此前只能按单一方向查询关联关系，本版本支持双向查询。

从源码调用链看，完整的链路为：topo_server 服务层 SearchInstanceAssociations（路由见 service_business_initfunc.go）→ 逻辑层association.SearchInstanceAssociations→ coreservice 的SearchInstanceAssociation（instance.go）。coreservice 侧通过searchInstanceAssociation（instance.go）按对象类型（objID）定位对应的实例关联表GetObjectInstAsstTableName并执行条件查询与分页排序。双向查询支持意味着：以关联任意一端实例 ID 发起查询，都能返回对应的关联记录，配合该接口的DisableCounter选项（默认返回总数count），可用于关联关系的双向盘点与校验。客户端接口定义见 apis.go。

四、升级优化（Upgrade）详解

1. 服务模板进程信息解锁按钮提示优化

服务模板的进程信息编辑区中，"解锁"按钮的提示文案被优化，使管理员明确解锁后的影响（进程字段将被修改并可能同步到实例），降低误操作概率。

2. 移除主机列表悬停跳转提示

此前在主机列表中将鼠标悬停在主机上时，会弹出"跳转业务拓扑"的浮层提示，在极端情况下该浮层会遮挡跳转图标，导致无法点击。本版本直接移除了该悬停提示，避免交互遮挡。

3. 主机自动应用可用字段限制

为保障自动应用的安全性，本版本明确了不可用于主机自动应用的字段范围：

• 非可编辑字段（editable为 false 的属性，如系统内置只读字段）；
• IPv6 字段（如bk_host_innerip_v6等）；
• CPU 架构字段。

这些字段被排除在自动应用规则的可选项之外，防止自动执行计划意外覆盖只读字段或网络地址类字段。结合第 2 节源码中GenerateApplyPlan的"按需取字段"实现（plan.go仅查询规则涉及的属性字段），可以推断可用字段的限制在规则创建/校验阶段即已完成过滤。

4. 接口分页限制适配

本版本对部分接口实施了分页限制适配，要求调用方显式携带分页参数。典型的如业务集批量删除接口：DeleteBizSet在 inst_business_set.go 中限制bk_biz_set_ids单次最多 100 个，超出即返回CCErrCommXXExceedLimit错误。升级后，凡是批量类接口的调用方都应检查是否携带合法的分页/批量上限参数。

5. 主机详情页服务实例标签与拓扑展示优化

主机详情页中，服务实例的标签（label）与拓扑（topology）信息此前受限于默认展示数量，本版本改为直接全量展示，避免因截断导致的信息缺失，便于快速确认主机在服务实例体系中的完整归属。

6. 服务（集群）选择器交互体验优化

服务选择器、集群选择器在选择时的交互流程得到优化，涉及选择器组件的数据加载与选中态反馈。相关组件实现可参考 src/ui/src/components 下的选择器类组件（如 filters 系列、search 系列组件）。

7. 进程端口字段默认锁定

服务模板配置中，进程端口（port）字段默认处于锁定状态，管理员需要先点击"解锁"才能修改端口。这是对"模板即配置基线"语义的强化——端口作为生产环境的关键配置项，默认锁定可防止模板被意外修改后批量同步到实例，同时与第 1 条"解锁按钮提示优化"形成配套体验。

8. procserver 无分页接口的性能优化（issue #5651）

本版本优化了 procserver 中无长度限制或分页的接口可能引发的性能问题。官方发布说明明确提示：若您正在使用 issue #5651 中涉及的接口，请按新的分页要求调用，否则接口调用将失败。这是一个不兼容变更，升级前必须排查 procserver 相关接口的调用方：

• 确认是否调用了未携带分页参数的进程/模板接口；
• 为所有调用补充合法的分页参数（start/limit）；
• 在测试环境先行验证调用方兼容性，再滚动升级生产环境。

procserver 相关服务与接口代码位于 src/scene_server/proc_server，调用方客户端可参考 src/apimachinery/procserver。

五、升级与适配建议

综合本版本的变更内容，升级到 v3.10.16 时建议按以下优先级处理：

1. 优先排查接口兼容性（必须）：issue #5651 涉及的 procserver 无分页接口已改为强制分页，属于破坏性变更，先完成调用方适配；
2. 验证业务集功能：业务集新增关联能力与范围编辑修复，若已在生产使用业务集，回归验证"创建 → 编辑范围 → 查询业务列表 → 删除"全链路；
3. 启用新能力：按需启用模型导入导出（zip/yaml/xlsx 四类格式）、主机+拓扑自定义层级过滤、HTTPS 通信与组件请求超时机制；
4. 回归主机自动应用：确认不可用字段（非可编辑字段、IPv6 字段、CPU 架构字段）的限制符合预期，并验证业务集视图下的状态显示；
5. 前端交互回归：覆盖服务模板进程端口默认锁定、主机列表悬停提示移除、模型字段分组折叠等 UI 变更点。

六、结语

bk-cmdb v3.10.16 是一个"功能与健壮性并重"的版本：模型导入导出、业务集关联、自定义层级查询条件显著扩展了配置模型的管理能力；组件请求超时、HTTPS 支持夯实了平台底座；procserver 分页强制化则提醒调用方在接口规范上保持一致。建议以本文的源码路径为线索，结合 docs/apidoc 下的接口文档与自身业务场景，逐项验证变更点后再执行生产升级。

• 后端
• 企业应用
• 运维