后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载导读本文以 BlueKing CMDBbk-cmdb蓝鲸智云配置平台开源仓库中的 docs/apidoc/apigw 目录为核心完整讲解 bk-cmdb 如何通过蓝鲸 API Gateway 对外提供标准化的 HTTP 接口。你将掌握网关定义文件definition.yaml的每个配置项含义、Swagger 资源映射文件的编写规范、一键同步发布脚本sync-apigateway.sh的完整执行链路以及如何将这套配置部署到 Kubernetes/容器环境。文中所有内容均可在当前仓库中找到对应文件与源码佐证可直接作为网关接入与维护的实操手册。一、整体定位API Gateway 在 bk-cmdb 开放体系中的角色bk-cmdb 本身提供了基于/api/v3前缀的众多内部 REST 接口见 src/web_server/service 与 src/apiserver/service 中的路由实现。当这些能力需要开放给业务系统、第三方平台如作业平台、监控平台、容器管理平台等时直接暴露内部接口存在鉴权、限流、文档化等多重问题。蓝鲸 API Gateway 正是解决这一问题的统一出口层。本仓库 docs/apidoc/apigw/README.md 明确说明该目录存放 cmdb 在 API Gateway 的接口文档与映射关系包含四大组成部分组成部分作用backend存放 cmdb 后台服务在 API Gateway 的接口文档与映射关系面向蓝鲸体系内部组件open存放 cmdb 对外开放的 API 资源文档与映射关系面向外部应用开发者saas存放 cmdb 官方 SaaS 在 API Gateway 的接口文档与映射关系definition.yamlAPI Gateway 的网关定义文件用于注册网关bin/sync-apigateway.shAPI Gateway 同步脚本用于注册网关并发布资源这套体系实现了内部接口 → 网关资源 → 外部调用的三层解耦内部接口保持原样网关负责认证、限流、权限申请与文档展示外部调用方只需按照网关资源文档即可完成对接。二、仓库目录结构逐层解析docs/apidoc/apigw目录的实际结构如下以当前仓库为准docs/apidoc/apigw/ ├── README.md # 本说明文档 ├── definition.yaml # 网关定义文件注册网关的核心配置 ├── bin/ │ └── sync-apigateway.sh # 网关同步脚本 ├── backend/ │ ├── en/ # 后台接口英文文档49 篇 │ ├── zh/ # 后台接口中文文档49 篇 │ └── bk_apigw_resources_bk-cmdb.yaml # 后台接口的 Swagger 资源映射 ├── open/ │ ├── en/ # 开放接口英文文档180 篇 │ ├── zh/ # 开放接口中文文档180 篇 │ └── bk_apigw_resources_bk-cmdb.yaml # 开放接口的 Swagger 资源映射 └── saas/ ├── en/ ├── zh/ # SaaS 接口文档示例 demo └── bk_apigw_resources_bk-cmdb.yaml # SaaS 接口的 Swagger 资源映射每一部分的目录结构遵循同一规范en英文文档目录与zh中文文档目录存放与 API 资源一一对应的 Markdown 接口文档bk_apigw_resources_bk-cmdb.yaml存放 cmdb 与 API Gateway 的接口映射关系Swagger 2.0 格式。也就是说一个 API 资源由两件东西组成映射文件定义请求如何路由、鉴权、限流和接口文档定义入参、出参、调用示例供调用方查阅。以open为例其覆盖的能力面非常广主机管理list_biz_hosts、transfer_host_module等、模型与实例create_object、search_inst等、业务与拓扑create_business、search_biz_inst_topo等、动态分组create_dynamic_group、execute_dynamic_group、服务模板create_service_template、容器资源list_kube_cluster、list_kube_pod、事件订阅resource_watch等。backend则面向蓝鲸平台内部的后台级接口如容器缓存拓扑list_kube_container_by_topo、实例 ID 规则sync_inst_id_rule、缓存全量同步条件create_full_sync_cond_for_cache等。三、网关定义文件 definition.yaml 详解docs/apidoc/apigw/definition.yaml是注册与发布网关的总配置约 250 行由七个配置块组成每个配置块分别对应apigw-manager提供的一条同步命令。下面逐块展开说明。3.1 版本信息release# spec_version 配置文件版本号必填固定值 1 spec_version: 1 # 定义发布内容用于命令 create_version_and_release_apigw release: version: 3.14.8-beta1 title: 3.14.8-beta1 comment: 3.14.8-beta1spec_version配置文件版本号必填固定为1。release.version发布版本号。配置中特别强调资源配置更新需更新此版本号才会发布资源版本此版本号和 sdk 版本号一致错误设置会影响调用方使用。这是实践中的高频踩坑点——只改资源不 bump 版本号发布不会真正生效。title/comment版本标题与描述随版本一同展示在网关版本记录中。3.2 网关基本信息apigatewayapigateway: description: 蓝鲸配置平台 description_en: BlueKing Configuration Management DataBase is_public: true api_type: 1 allow_auth_from_params: false allow_delete_sensitive_params: false maintainers: - {{ environ.BK_CMDB_MAINTAINER }}该块用于命令sync_apigw_config各字段含义字段说明description/description_en网关的中英文描述。蓝鲸官方网关需提供英文描述以支持国际化is_public是否公开网关。公开后用户可查看资源文档、申请资源权限不公开则网关对用户隐藏api_type标记网关为官方网关网关名需以bk-开头。非官方网关可去掉此配置allow_auth_from_params是否允许从请求参数querystring、body中获取蓝鲸认证信息默认 true。配置为false时只能从请求头X-Bkapi-Authorization获取认证信息。当前仓库设为false属于推荐收紧的取值注释说明新接入的网关可以设置为 false已接入的网关待推动所有调用者将认证信息放到请求头后可设置为 falseallow_delete_sensitive_params网关请求后端时是否删除请求参数中的认证敏感信息如bk_token。为true表示允许删除当所有调用者改用请求头传认证参数时可将其设为falsemaintainers网关维护人员仅维护人员有管理网关的权限。通过模板变量{{ environ.BK_CMDB_MAINTAINER }}从环境变量注入3.3 环境信息stagestage: name: {{ environ.BK_CMDB_STAGE_NAME }} description: 正式环境 description_en: Production Environment proxy_http: timeout: 30 upstreams: loadbalance: roundrobin hosts: - host: {{ environ.BK_CMDB_HOST }} weight: 100 transform_headers: set: X-Bkcmdb-Supplier-Account: 0该块用于命令sync_apigw_stage。stage环境决定了网关将请求转发到哪个后端name环境名如prod由环境变量BK_CMDB_STAGE_NAME注入。proxy_http.timeout网关调用后端的超时时间秒此处为 30 秒。upstreams.loadbalance负载均衡类型当前为roundrobin轮询。upstreams.hosts后端主机列表host为网关调用后端服务的默认域名或 IP不包含 Path例如http://api.example.comweight为权重。transform_headers.setHeader 转换规则此处设置X-Bkcmdb-Supplier-Account: 0即网关转发请求时统一为后端注入开发商账号0保证以默认开发商身份访问 cmdb。vars环境变量注释示例如未使用可去除。3.4 主动授权grant_permissionsgrant_permissions: - bk_app_code: {{ settings.BK_APP_CODE }} grant_dimension: gateway - bk_app_code: {{ environ.BK_JOB_APP_CODE }} grant_dimension: resource resource_names: - list_kube_container_by_topo - get_biz_kube_cache_topo # ... 其余资源名省略该块用于命令grant_apigw_permissions实现网关主动给应用添加访问网关资源的权限是蓝鲸体系中各平台应用开箱即用免去逐个申请的关键配置bk_app_code被授权的蓝鲸应用编码通过模板变量注入如settings.BK_APP_CODE、environ.BK_JOB_APP_CODE、environ.BK_NODEMAN_APP_CODE等。grant_dimension授权维度可选gateway按网关授权包括网关下所有资源以及未来新创建的资源或resource按资源名逐个授权。resource_namesgrant_dimension: resource时列出的资源名清单。当前仓库为以下应用配置了授权均以环境变量注入应用编码应用变量授权维度授权资源概要settings.BK_APP_CODEgateway网关全部资源environ.BK_JOB_APP_CODE作业平台resource容器、拓扑、主机、watch 等约 27 个资源environ.BK_NODEMAN_APP_CODE节点管理resourcebatch_update_host_all_propertiesenviron.BK_NODEMGR_APP_CODEresource主机、拓扑、动态分组、云区域等约 57 个资源environ.BK_BCS_APP_CODE容器管理平台resourcelist_hosts_without_biz、list_biz_hostsenviron.BK_BCS_SYNC_APP_CODEresource容器集群/节点/Pod/命名空间/工作负载的增删改查environ.BK_HCM_APP_CODEresource主机、云区域、watch 等environ.BK_MONITOR_APP_CODE监控平台resource拓扑、主机、服务模板、动态分组等environ.BK_OPS_APP_CODEresource业务集、容器、watch 等3.5 申请权限注释示例apply_permissions# apply_permissions: # - gateway_name: {{ settings.BK_APIGW_NAME }} # grant_dimension: gateway该块用于命令apply_apigw_permissions语义与grant_permissions相反由应用主动申请指定网关所有资源的权限待网关管理员审批后应用才可访问。当前仓库中该配置处于注释状态说明默认场景以网关主动授权grant为主申请模式按需开启。3.6 关联应用related_appsrelated_apps: - {{ settings.BK_APP_CODE }}用于命令add_related_apps。关联应用可以通过网关bk-apigateway的接口操作网关数据每个网关最多可有 10 个关联应用。当前仅关联了BK_APP_CODE指定的应用。3.7 资源文档目录resource_docsresource_docs: # archivefile: {{ settings.BK_APIGW_RESOURCE_DOCS_ARCHIVE_FILE }} basedir: /data/apidocs/用于命令sync_resource_docs_by_archive定义资源文档的存放位置basedir资源文档目录。目录格式要求en为英文文档、zh为中文文档例如./ - en - get_user.md - zh - get_user.mdarchivefile资源文档的归档文件可为tar.gz、zip格式basedir与archivefile二者至少一个有效若同时存在则archivefile优先。归档文件可通过tar czvf xxx.tgz en zh创建。四、同步发布脚本 sync-apigateway.sh 执行链路bin/sync-apigateway.sh 是网关接入的一键发布脚本整个流程与 definition.yaml 的各配置块一一对应#!/bin/bash # 加载 apigw-manager 原始镜像中的通用函数 source /apigw-manager/bin/functions.sh gateway_namebk-cmdb definition_file/data/definition.yaml resources_file/data/resources.yaml title begin to db migrate call_command_or_warning migrate apigw title syncing apigateway call_definition_command_or_exit sync_apigw_config ${definition_file} --gateway-name${gateway_name} call_definition_command_or_exit sync_apigw_stage ${definition_file} --gateway-name${gateway_name} call_definition_command_or_exit sync_apigw_resources ${resources_file} --gateway-name${gateway_name} --delete call_definition_command_or_exit sync_resource_docs_by_archive ${definition_file} --gateway-name${gateway_name} --safe-mode title fetch apigateway public key apigw-manager.sh fetch_apigw_public_key --gateway-name${gateway_name} --print /tmp/apigateway.pub title releasing call_definition_command_or_exit create_version_and_release_apigw ${definition_file} --gateway-name${gateway_name} title grant apigateway permissions call_definition_command_or_exit grant_apigw_permissions ${definition_file} --gateway-name${gateway_name} title done各步骤的实际作用与对应配置步骤命令作用对应配置1migrate apigw对网关相关数据表执行数据库迁移—2sync_apigw_config同步网关基本信息描述、公开性、认证参数、维护人apigateway块3sync_apigw_stage同步环境配置后端地址、超时、Header 转换stage块4sync_apigw_resources从 Swagger 映射文件同步 API 资源--delete表示删除映射文件中不存在的资源bk_apigw_resources_bk-cmdb.yaml5sync_resource_docs_by_archive同步资源文档--safe-mode表示安全模式resource_docs块6fetch_apigw_public_key获取网关公钥并写入/tmp/apigateway.pub供后续请求签名校验使用—7create_version_and_release_apigw创建版本并发布release块8grant_apigw_permissions给各蓝鲸应用授予访问权限grant_permissions块脚本执行顺序暗含了依赖关系先迁移数据库再同步配置/环境/资源/文档然后获取公钥、发布版本最后授权。其中--gateway-name参数优先级高于 Django settings 中的BK_APIGW_NAME脚本顶部注释说明若命令参数未指定--gateway-name则使用 settings 中的BK_APIGW_NAME。脚本中gateway_namebk-cmdb是待同步网关名的默认值实际部署时可按需修改。五、Swagger 资源映射文件bk_apigw_resources_bk-cmdb.yaml三个子目录backend / open / saas各持有一份bk_apigw_resources_bk-cmdb.yaml采用 Swagger 2.0 规范描述资源并通过x-bk-apigateway-resource扩展字段携带网关专属配置。以 open/bk_apigw_resources_bk-cmdb.yaml 中的一个资源为例swagger: 2.0 basePath: / info: version: 0.1 title: API Gateway Resources schemes: - http paths: /api/v3/hosts/app/{bk_biz_id}/list_hosts: post: operationId: list_biz_hosts description: 查询业务下的主机 responses: default: description: x-bk-apigateway-resource: isPublic: false allowApplyPermission: true matchSubpath: false backend: type: HTTP method: post path: /api/v3/hosts/app/{bk_biz_id}/list_hosts matchSubpath: false timeout: 0 upstreams: {} transformHeaders: {} pluginConfigs: - type: bk-rate-limit yaml: | rates: __default: - period: 1 tokens: 100 authConfig: userVerifiedRequired: false disabledStages: [] descriptionEn: Search the hosts of business关键字段说明paths下的每个路径 HTTP 方法对应一个网关资源operationId是资源的唯一标识如list_biz_hosts也是授权清单中resource_names引用的名字。x-bk-apigateway-resource扩展块isPublic资源是否公开false 表示需申请权限才能访问。allowApplyPermission是否允许调用方申请该资源权限。matchSubpath是否匹配子路径。backend.type/method/path网关转发到后端的协议、方法与路径此处后端路径与网关路径一致/api/v3/...即透传 cmdb 内部接口。timeout后端调用超时0 表示使用默认。pluginConfigs插件配置当前统一启用了bk-rate-limit限流插件规则为每 1 秒 100 个 tokentokens: 100, period: 1。authConfig.userVerifiedRequired是否要求用户登录验证。disabledStages禁用该资源的 stage 列表空表示所有环境可用。descriptionEn资源的英文描述。saas子目录的映射文件saas/bk_apigw_resources_bk-cmdb.yaml结构相同但authConfig.userVerifiedRequired为trueSaaS 场景要求用户身份验证且后端路径直接指向/demo这类 SaaS 自身接口。六、资源文档规范一篇接口文档的完整要素en/zh目录下的每篇 Markdown 即一个资源的接口文档。以 open/zh/list_biz_hosts.md 为例文档固定由五部分构成这也是网关资源文档的编写规范描述功能概述与权限说明如根据业务ID查询业务下的主机可附带其他的过滤信息权限业务访问权限。输入参数参数表格包含参数名称、类型、必选、描述四列。嵌套对象用####小节展开如host_property_filter、set_cond、module_cond、page。该文档展示了主机查询的完整过滤能力bk_set_ids与set_cond互斥、bk_module_ids与module_cond互斥、host_property_filter支持 AND/OR 组合嵌套最多 2 层、fields控制返回字段以加速请求并减少流量。调用示例完整 JSON 请求体。响应示例完整 JSON 响应体。响应参数说明逐层说明result/code/message/permission/data及各业务字段并注明此处返回值仅对系统内置属性字段做了说明其余返回值取决于用户自定义属性字段。backend下的文档如 backend/zh/list_kube_container_by_topo.md面向更复杂的场景例如按容器拓扑cluster / namespace / deployment / daemonSet / statefulSet / gameStatefulSet / gameDeployment / cronJob / job / pods / customResource查询容器信息支持pod_filter、container_filter双层过滤以及enable_count纯计数模式此时start为 0、limit为 0、sort为空字符串。open/zh/resource_watch.mdresource_watch.md则展示了事件订阅类文档的写法其核心特性包括3 小时内高可用数据变更 watch、基于游标cursor的事件回溯、支持按时间点/游标/当前时间三种回溯方式、支持 create/update/delete 事件类型过滤、短长链设计20 秒内无事件则保持连接、有事件直接推送、批量事件能力以及字段定制bk_fields。输入参数bk_resource的枚举值覆盖host、host_relation、biz、set、module、process、object_instance、mainline_instance、biz_set、biz_set_relation、plat、project等全部资源类型。七、容器化部署与 Helm 集成7.1 镜像构建docs/support-file/dockerfile/apigw/dockerfile 展示了网关同步镜像的构建方式FROM hub.bktencent.com/blueking/apigw-manager:3.0.3 COPY apidocs /data/ RUN chmod x /data/bin/sync-apigateway.sh即以蓝鲸官方的apigw-manager:3.0.3镜像为基础将整个apidocs目录内含definition.yaml、bin/sync-apigateway.sh与各语言资源文档复制到/data/与脚本中definition_file/data/definition.yaml、resources_file/data/resources.yaml的路径约定一一对应并授予同步脚本执行权限。7.2 Helm Job 与环境变量注入docs/support-file/helm/backend/templates/job/apigw-job.yaml 将同步脚本包装为 Kubernetes Job 执行由{{- if .Values.apigatewaySync.enabled }}控制开关默认关闭values.yaml中apigatewaySync.enabled: false。启动命令为bash bin/sync-apigateway.sh。通过环境变量把 definition.yaml 中的全部模板变量注入运行时BK_APIGW_NAME→{{ .Values.bkApigatewayName }}网关名BK_APP_CODE/BK_APP_SECRET/BK_API_URL_TMPL→ 蓝鲸应用凭证与网关地址BK_CMDB_HOST→apigatewaySync.host默认http://bk-cmdb-api对应stage.proxy_http.upstreams.hostsBK_CMDB_MAINTAINER→ 网关维护人默认adminBK_CMDB_STAGE_NAME→ 环境名默认prodBK_JOB_APP_CODE/BK_NODEMAN_APP_CODE/BK_NODEMGR_APP_CODE/BK_BCS_APP_CODE/BK_BCS_SYNC_APP_CODE/BK_HCM_APP_CODE/BK_MONITOR_APP_CODE/BK_OPS_APP_CODE→ 各被授权平台的bk_app_coderestartPolicy: OnFailure配合backoffLimit: 20保证同步失败时自动重试ttlSecondsAfterFinished: 600使任务完成后自动清理。可见网关接入全程不需要手工在网关管理端操作只需在 Helm values 中配置上述参数并开启apigatewaySync.enabled由 Job 在集群内完成注册、发布与授权。八、调用侧链路网关 SDK 客户端网关资源的消费侧同样在本仓库留有实现src/thirdparty/apigw/cmdb/api.go 提供了调用 cmdb 网关资源的 RESTful 客户端其Proxy方法展示了完整的调用链路读取请求体 → 通过rest.ClientInterface发起同路径请求 → 通过SetApiGWAuthHeader注入网关认证头实现见 apigwutil/auth.go→ 将网关响应格式bk_apicode/bk_apimessage转换为 cmdb 内部响应格式。Client()返回的客户端可直接复用configcenter/src/apimachinery/rest的连接管理能力。这印证了整体设计网关资源文档中的路径与参数与 cmdb 内部接口保持一致同步脚本只是把映射关系和文档注册到网关而网关 SDK 客户端则负责在消费侧完成认证与格式转换两侧配合实现接口透传、能力开放。九、接入与维护操作速查基于以上分析在真实环境中完成一次 bk-cmdb 网关接入或更新推荐的操作顺序为准备定义文件修改docs/apidoc/apigw/definition.yaml重点确认release.version版本号是否递增否则资源变更不会发布、stage.proxy_http.upstreams.hosts是否指向正确的 cmdb 后端地址、grant_permissions是否覆盖需要开箱即用权限的应用。准备映射与文档在open对外或backend内部目录维护对应的bk_apigw_resources_bk-cmdb.yaml映射与en/zh接口文档保持二者中operationId、路径、参数一致。构建镜像按 dockerfile/apigw/dockerfile 将apidocs打入apigw-manager基础镜像。执行同步直接运行docs/apidoc/apigw/bin/sync-apigateway.sh或在 Kubernetes 中开启 apigw-job.yaml 对应的 Job 并注入环境变量。验证发布通过fetch_apigw_public_key输出的公钥与网关平台上的资源文档核对资源是否上线再以被授权应用的bk_app_code发起一次真实调用验证鉴权与限流配置。日常维护新增资源时同步更新映射文件与中英文文档并 bump 版本号收敛认证方式时调整allow_auth_from_params/allow_delete_sensitive_params并推动调用方迁移到X-Bkapi-Authorization请求头。十、总结bk-cmdb 的 API Gateway 接入体系以 docs/apidoc/apigw 目录为单一事实来源通过网关定义文件definition.yaml Swagger 资源映射bk_apigw_resources_bk-cmdb.yaml 中英文资源文档en/zh 同步脚本sync-apigateway.sh四件套的有机结合实现了从接口注册、环境配置、文档发布到权限授予的全链路自动化。对调用方而言蓝鲸 API Gateway 提供了统一的认证、限流与文档化出口对 cmdb 平台本身而言内部接口的稳定演进与对外能力的灵活开放得到了有效解耦。赞分享后端企业应用运维【免费下载链接】bk-cmdb蓝鲸智云配置平台(BlueKing CMDB)项目地址https://gitcode.com/gh_mirrors/bk/bk-cmdb点击查看免费下载相关推荐蓝鲸配置平台 bk-cmdb 接口文档体系详解ESB 与 API Gateway 双通道接口映射与查阅指南蓝鲸配置平台 bk cmdb 接口文档体系详解ESB 与 API Gateway 双通道接口映射与查阅指南 蓝鲸配置平台bk cmdb的对外接口通过「ES后端企业应用运维蓝鲸CMDB与蓝鲸生态集成指南如何实现PaaS、CI、SOPS等平台的无缝对接蓝鲸CMDB与蓝鲸生态集成指南如何实现PaaS、CI、SOPS等平台的无缝对接 蓝鲸CMDB配置管理数据库作为蓝鲸智云生态的核心配置平台通过与蓝鲸Paa后端企业应用运维LX Music 桌面版免费多音源音乐播放器快速上手与使用完整指南LX Music 桌面版免费多音源音乐播放器快速上手与使用完整指南 想找首歌听得挨个打开几个音乐 App看谁家有这首歌再在两三个应用之间来回切换。免费音桌面应用音视频前端上一篇模型验证终极指南如何在TRL中正确设置评估集下一篇终极LLaMA模型保护指南从许可合规到安全部署的完整实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考