后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载本文以蓝鲸智云配置平台BlueKing CMDB即 bk-cmdb的list_operation_audit接口为切入点系统讲解如何按条件查询操作审计日志从 ESB 网关的接口定义、请求参数与两种查询方式user/resource_name字段查询与condition条件查询、分页排序到后端 topo_server 的参数解析、coreservice 的 MongoDB 查询实现与鉴权模型帮助开发者快速掌握审计日志查询的完整调用链与实操要点。一、接口概述与适用场景操作审计日志是 CMDB 平台安全与合规能力的核心组件每一次对业务、主机、模型、模型实例、服务实例、云资源等对象的增删改操作都会被写入审计日志表形成可追溯的操作记录。list_operation_audit即承担按条件检索操作审计日志的职责调用方需要拥有操作审计查询权限。该接口在 ESB企业服务总线侧的定义位于 docs/apidoc/cc/cc.yaml- path: /v2/cc/list_operation_audit/ name: list_operation_audit label: 根据条件获取操作审计日志 label_en: find operation audit logs based on conditions suggest_method: POST api_type: query comp_codename: generic.v2.cc.cc_component dest_path: /api/v3/findmany/audit_list dest_http_method: POST is_hidden: true可以看到ESB 的/v2/cc/list_operation_audit/实际转发到 CMDB 的POST /api/v3/findmany/audit_list由 topo_server 的SearchAuditList处理器承接注册见 src/scene_server/topo_server/service/service_initfunc.go。前端审计列表页也正是通过该地址查询数据见 src/ui/src/store/modules/api/audit.js。二、请求参数详解接口整体请求体为两层结构最外层携带 ESB 通用鉴权参数bk_app_code、bk_app_secret、bk_username、bk_token内层为接口专属参数condition与page。2.1 接口参数内层字段类型必选描述pageobject是分页参数conditionobject否操作审计日志查询条件2.2 page 分页参数字段类型必选描述startint否记录开始位置偏移量默认从 0 开始limitint是每页限制条数最大 200sortstring否排序字段支持-前缀表示倒序如-operation_timelimit上限 200 是硬性校验对应源码中的常量BKAuditLogPageLimit 200见 src/common/definitions.go。在 src/common/metadata/audit.go 的AuditQueryInput.Validate()中limit 0或limit 200都会被拒绝并返回参数错误func (input *AuditQueryInput) Validate() errors.RawErrorInfo { if input.Page.Limit 0 { return errors.RawErrorInfo{ ErrCode: common.CCErrCommParamsInvalid, Args: []interface{}{limit}, } } if input.Page.Limit common.BKAuditLogPageLimit { return errors.RawErrorInfo{ ErrCode: common.CCErrCommPageLimitIsExceeded, } } // operation_time 的 start 与 end 必须至少提供一个 if len(input.Condition.OperationTime.Start) 0 len(input.Condition.OperationTime.End) 0 { return errors.RawErrorInfo{ ErrCode: common.CCErrCommParamsNeedSet, Args: []interface{}{common.BKOperationTimeField}, } } return errors.RawErrorInfo{} }注意operation_time是必选条件start与end至少提供一个否则请求会被拒绝。2.3 condition 查询条件字段类型必选描述bk_biz_idint否业务 idresource_typestring否操作的具体资源类型如host、business、set、model_instance等actionarray否操作类型数组如create、update、delete等operation_timeobject是操作时间范围含start、end两个字段格式为yyyy-MM-dd HH:mm:ssuserstring否操作人与下方condition二选一不能同时提供resource_namestring否资源名称如主机 IP与下方condition二选一不能同时提供categorystring否查询的类型取值business/resource/host/other用于前端按审计大类过滤fuzzy_querybool否是否对resource_name使用模糊查询模糊查询效率低、性能差该字段只影响resource_name使用condition方式查询时会被忽略conditionarray否指定查询条件与user、resource_name不能同时提供resource_type与action的合法取值均可在 src/common/metadata/audit.go 中找到完整定义。例如ResourceType枚举包含business、biz_set、project、set、module、host、process、model、model_instance、instance_association、cloud_area、cloud_account、cloud_sync_task、kube_cluster、kube_node、field_template等ActionType枚举包含create、update、delete、assign_host、unassign_host、transfer_host_module、archive、recover、stop、resume。2.4 condition.condition 子条件数组当需要使用新的查询方式时可在condition内再传condition数组对user与resource_name做多条件组合过滤。数组每个元素的字段定义如下字段类型必选描述fieldstring是对象字段仅可为user或resource_nameoperatorstring是操作符in表示属于not_in表示不属于contains表示包含field为resource_name时可使用contains进行模糊查询valuestring/array是字段对应的值in和not_in需要 array 类型contains需要 string 类型该约束在后端有严格校验在 src/scene_server/topo_server/service/auditlog.go 中SearchAuditList遍历condition.Condition若操作符不是in/not_in则必须满足字段为resource_name且操作符为contains否则直接返回CCErrCommParamsInvalid错误同时user、resource_name与condition三者互斥的规则由AuditQueryCondition.Validate()保证见 src/common/metadata/audit.gofunc (a *AuditQueryCondition) Validate() error { if (len(a.User) ! 0 || len(a.ResourceName) ! 0) len(a.Condition) ! 0 { return errors.New(common.CCErrCommParamsInvalid, condition, user and resource_name cannot exist at the same time) } return nil }三、请求参数示例完整可复制3.1 方式一使用 user / resource_name / fuzzy_query 直接过滤{ bk_app_code: esb_test, bk_app_secret: xxx, bk_username: xxx, bk_token: xxx, condition:{ bk_biz_id:2, resource_type:host, action:[ create, delete ], operation_time:{ start:2020-09-23 00:00:00, end:2020-11-01 23:59:59 }, user:admin, resource_name:1.1.1.1, category:host, fuzzy_query: false }, page:{ start:0, limit:10, sort:-operation_time } }该请求查询业务 2 下、资源类型为 host、操作为 create/delete、时间在 2020-09-23 至 2020-11-01 之间、操作人为 admin 且资源名精确等于1.1.1.1的审计记录按操作时间倒序返回前 10 条。若将fuzzy_query置为trueresource_name将按正则模糊匹配对应源码中转换为$regex $options: i的 MongoDB 条件见 src/scene_server/topo_server/service/auditlog.go此时建议配合更精确的condition数组方式缩小结果集避免模糊查询带来的性能开销。3.2 方式二使用 condition 数组做组合过滤{ condition:{ bk_biz_id:2, resource_type:host, action:[ create, delete ], operation_time:{ start:2020-09-23 00:00:00, end:2020-11-01 23:59:59 }, condition:[ { field:user, operator:in, value:[admin] }, { field:resource_name, operator:in, value:[1.1.1.1] } ], category:host }, page:{ start:0, limit:10, sort:-operation_time } }注意该请求示例未携带bk_app_code等 ESB 公共参数生产调用仍需按环境补齐。此处condition数组的每一项经item.ToMgo()转换为 MongoDB 查询条件后与其余过滤条件合并见 src/scene_server/topo_server/service/auditlog.go从而支持user in [...]、resource_name in [...]、resource_name contains xxx等更灵活的语义。四、返回结果示例{ result:true, code:0, message:success, permission: null, request_id: e43da4ef221746868dc4c837d36f3807, data:{ count:2, info:[ { id:7, audit_type:, bk_supplier_account:, user:admin, resource_type:host, action:delete, operate_from:, operation_detail:null, operation_time:2020-10-09 21:30:51, bk_biz_id:1, resource_id:4, resource_name:2.2.2.2 }, { id:2, audit_type:, bk_supplier_account:, user:admin, resource_type:host, action:delete, operate_from:, operation_detail:null, operation_time:2020-10-09 17:13:55, bk_biz_id:1, resource_id:1, resource_name:1.1.1.1 } ] } }五、返回结果参数说明5.1 response 顶层字段类型描述resultbool请求成功与否。true:请求成功false:请求失败codeint错误编码。0 表示 success0 表示失败错误messagestring请求失败返回的错误信息permissionobject权限信息request_idstring请求链 iddataobject请求返回的数据5.2 data字段类型描述countint记录条数满足条件的审计记录总数infoarray操作审计的记录信息列表5.3 info 列表项字段类型描述idint审计 ID记录唯一标识audit_typestring操作审计类型如business、business_resource、host、model、model_instance、cloud_resource、kube等bk_supplier_accountstring开发商账号userstring操作人resource_typestring资源类型actionstring操作类型operate_fromstring来源平台如user、cc_system、data_collection、synchronizer、cloud_syncoperation_detailobject操作细节本次列表查询默认不返回可通过find_audit_by_id获取详情operation_timestring操作时间bk_biz_idint业务 idresource_idint资源 idresource_namestring资源名称info中各字段与存储模型metadata.AuditLog一一对应见 src/common/metadata/audit.go。需要说明的是列表接口SearchAuditList为了前端表格展示效率查询时只投影了id、user、resource_type、action、operation_time、bk_biz_id、resource_id、resource_name、extend_resource_name等字段见 src/scene_server/topo_server/service/auditlog.go因此audit_type、operate_from、operation_detail等字段在列表场景下通常为空如需审计详情应调用find_audit_by_idESB 侧映射POST /api/v3/find/audit即SearchAuditDetail见 src/scene_server/topo_server/service/auditlog.go。六、后端实现原理从请求到 MongoDB 的完整调用链6.1 鉴权操作审计查询权限ESB 网关将请求转发到POST /api/v3/findmany/audit_list后请求先经过权限解析。在 src/ac/parser/topology.go 中该路径被注册为资源类型AuditLog见 src/ac/meta/resource.go、操作FindMany的权限点var ( searchAuditDict /api/v3/find/audit_dict searchAuditList /api/v3/findmany/audit_list searchAuditDetail /api/v3/find/audit searchInstAudit /api/v3/find/inst_audit ) // ... if ps.hitPattern(searchAuditList, http.MethodPost) { ps.Attribute.Resources []meta.ResourceAttribute{ { Basic: meta.Basic{ Type: meta.AuditLog, Action: meta.FindMany, }, }, } return ps }这也就是文档开头权限操作审计查询权限的源码落点——未授权用户请求该接口会被 IAM 鉴权拦截。6.2 topo_server条件解析与组合SearchAuditList处理器src/scene_server/topo_server/service/auditlog.go负责把AuditQueryInput翻译为 MongoDB 查询条件关键逻辑包括condition 数组转换逐项校验operator仅允许in、not_inresource_name额外允许contains再调用item.ToMgo()生成 MongoDB 条件fuzzy_query 处理为 true 时resource_name转为{$regex: ..., $options: i}模糊匹配否则做精确匹配见parseAuditCond第 145-154 行操作时间范围parseOperationTimeCondition将start、end分别映射为$gte、$lte条件见 src/scene_server/topo_server/service/auditlog.gocategory 分类映射parseAuditTypeCondition调用GetAuditTypesByCategory将business/resource/host/other分别展开为对应的AuditType集合如business映射为business_resource与dynamic_grouping并据此生成audit_type: {$in: [...]}条件见 src/scene_server/topo_server/service/auditlog.go 与 src/common/metadata/audit.goaction 数组转为action: {$in: [...]}第 164-168 行。最终组装为metadata.QueryCondition后通过CoreService().Audit().SearchAuditLog调用 coreservice 的/read/auditlog接口客户端实现见 src/apimachinery/coreservice/auditlog/api.go路由注册见 src/source_controller/coreservice/service/service_initfunc.go。6.3 coreservice审计日志存储与查询审计日志存储在 MongoDB 的cc_AuditLog表见 src/common/tablenames.go。coreservice 侧的实现位于 src/source_controller/coreservice/core/auditlog/audit.go写入CreateAuditLog第 46-85 行为每条日志分配自增 ID自动补充OperateFrom默认user、SupplierAccount、User、AppCode、RequestID并取当前时间作为OperationTimeResourceName超长超过NameFieldMaxLength即 1024时会被截断查询SearchAuditLog第 87-135 行先调用util.SetQueryOwner注入开发商账号过滤再对operation_time条件做字符串到time.Time的解析使用timeparser解析失败返回CCErrCommParamsInvalid随后执行Find().Sort().Start().Limit()查询并按同一条件Count统计总数查询超时会返回CCErrAuditSelectTimeout其余查询失败返回CCErrAuditSelectFailed。写入侧的入口同样暴露为/create/auditlog由各业务模块在操作资源后通过common/auditlog包如 src/common/auditlog/audit.go 的SaveAuditLog统一落库从而保证查询接口看到的审计数据与真实操作一一对应。6.4 存储索引与性能cc_AuditLog表在启动时会注册若干后台索引以支撑常见查询见 src/common/index/collections/auditlog.go索引名键index_ididindex_operationTimeoperation_timeindex_useruserindex_resourceNameresource_nameindex_operationTime_auditType_resourceType_actionaudit_type, resource_type, action, operation_time这也印证了文档中模糊查询效率低、性能差的提醒contains对应的$regex查询难以充分利用resource_name单字段索引在数据量较大时应优先使用condition数组中的精确in过滤或配合operation_time范围条件收敛数据。七、调用建议与常见错误时间范围必填operation_time.start/end至少提供一个否则返回CCErrCommParamsNeedSetlimit 上限 200超过 200 返回CCErrCommPageLimitIsExceeded可通过翻页start累加获取全量数据查询方式二选一user/resource_name与condition数组不能同时出现否则返回参数无效错误operator 白名单condition数组内仅支持in、not_inresource_name可加contains其它操作符会被拒绝慎用模糊查询fuzzy_query: true或resource_name contains走正则匹配建议配合operation_time、bk_biz_id、resource_type等精确条件使用避免全表扫描列表与详情分离列表接口默认只返回表格展示字段需要operation_detail操作细节时请改用find_audit_by_id接口权限前置调用者必须具备操作审计查询权限auditlog资源的find_many操作否则请求会被 IAM 拦截。至此从 ESB 网关参数、topo_server 条件解析、coreservice 存储查询到 MongoDB 索引设计list_operation_audit的完整调用链与开发注意事项已全部打通可直接参照上文请求示例接入蓝鲸 CMDB 的审计日志查询能力。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 操作审计日志查询接口 list_operation_audit 实战指南蓝鲸配置平台 bk cmdb 操作审计日志查询接口 list_operation_audit 实战指南 本文面向接入蓝鲸智云配置平台BlueKing CMDB后端企业应用运维蓝鲸配置平台bk-cmdb操作审计日志查询 API 实战指南list_operation_audit 调用与原理全解析蓝鲸配置平台bk cmdb操作审计日志查询 API 实战指南list_operation_audit 调用与原理全解析 操作审计日志是蓝鲸配置平台bk后端企业应用运维蓝鲸配置平台bk-cmdb按审计 ID 查询操作审计详情接口实战指南蓝鲸配置平台bk cmdb按审计 ID 查询操作审计详情接口实战指南 导读 本文围绕蓝鲸智云配置平台bk cmdb开放 API 网关后端接口 find_后端企业应用运维上一篇Substrate 项目中的 Google Cloud Go 消息类型迁移指南从 go-genproto 迁往 product 专属模块下一篇Skia 的 Bazel Project Exporter从 Bazel 构建系统导出 CMake 与 GNI 工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考