apigw-manager

蓝鲸 API 网关管理 SDK 是一个用于管理 API 网关的工具，它提供了一套完整的工具和功能，可以帮助您更轻松地管理 API 网关，提高系统的安全性和可靠性。

Django Command：SDK 提供了 Django Command，支持网关注册、同步、发布等功能。您可以根据需要编排指令，以满足您的特定需求，并集成到您的项目自动执行 API 网关同步过程，以便更轻松地管理 API 网关。
Docker 镜像：对于非 Django 项目，提供了 Docker 基础镜像，封装了 SDK 同步网关的相关功能，以便非 Django 项目轻松管理 API 网关。
Django 中间件：SDK 还提供了 Django 中间件，用于解析 API 网关请求后端接口时添加的请求头 X-Bkapi-JWT，以方便后端服务校验请求是否来自 API 网关。这个中间件可以确保只有来自蓝鲸 API 网关的请求才能访问您的后端服务，从而提高系统的安全性。

安装

基础安装：

pip install apigw-manager

如果需要使用 apigw-manager 提供的 Django 中间件解析来自 API 网关的 X-Bkapi-JWT，可以安装：

pip install "apigw-manager[cryptography]"

功能使用

根据 YAML 同步网关配置：通过预定义的 YAML 文件，您可以轻松地执行网关创建、更新、发布和资源同步操作，从而简化 API 网关管理过程。主要有以下两种方案：
- 直接使用 Django Command 同步: 此方案适用于 Django 项目
- 通过镜像方式同步: 此方案适用于非 Django 项目
同步 MCP Server：支持将 MCP Server 配置同步到网关环境，可在 definition.yaml 的 stages 中声明 mcp_servers 配置，使用 sync_apigw_stage_mcp_servers 命令进行同步。
解析JWT: 使用 Django 中间件，您可以解析蓝鲸 API 网关的 X-Bkapi-JWT 请求头，确保只有来自 API 网关的请求才能访问您的后端服务，提升系统安全性。

网关版本兼容性

OAuth2 客户端配置依赖目标 API 网关版本：

使用场景	配置项	最低网关版本
MCP Server	`oauth2_public_client_enabled`	1.22.1
MCP Server	`oauth2_personal_client_enabled`	1.23.2
API 资源	`oauth2PersonalClientEnabled`	1.23.2

FAQ

1.同步过程中报错：`call_definition_command_or_exit: command not found`

这种大概率是自定义脚本有问题，参照文档，按照对应目录下的 examples 的同步脚本即可。

2.执行同步命令时报错：`Error responded by API Gateway, status_code:_code: 404, request_id:, error_code: 1640401, API not found`

网关URL BK_API_URL_TMPL 漏配或者配错了(自定义脚本中存在错误)。举例说明: BK_API_URL_TMPL: http://bkapi.example.com/api/{api_name}"l, 注意 {api_name}是占位符需要保留

3.同步过程中报错: `校验失败: api_type: api_type 为 1 时，网关名 name 需以 bk- 开头。

这个是因为 definition.yaml 定义的 apigateway.api_type为 1，标记网关为官方网关，网关名需以 bk- 开头，可选；非官方网关，可去除此配置当设置为 1 时,则 sync-apigateway.sh里面的 gateway_name 参数需要以 bk- 开头

4.definition.yaml 指定了一个环境，为啥发布时却将其他环境也进行了发布？

definition.yaml 指定的环境配置适用于 sync_apigw_stage 命令，而资源发布 create_version_and_release_apigw 需要通过指定 --stage prod test 等方式来指定，未指定则会发布所有该网关存在的环境

5. 调用 bk-apigateway 网关的 API，出现 ”应用无操作网关权限“错误

错误示例：

{
  "result": false,
  "code": "40403",
  "message": "应用无操作网关权限",
  "data": null
}

错误原因：

应用调用网关 bk-apigateway 的接口，去操作网关数据时，该应用需要有操作该网关数据的权限（而非调用 bk-apigateway 网关 API 的权限）。比如，应用 app1 操作网关 bk-demo 时，app1 应该有操作网关 bk-demo 数据的权限，以防止误修改其他网关的数据。则通过管理端页面 http://apigw.__bk_domain__ 创建网关，此时，没有任何应用可以通过 bk-apigateway 的接口修改该网关数据通过 bk-apigateway 的接口创建的网关，此时，除创建网关时使用的应用外，其它应用无权限修改此网关数据

修复方案：

访问 http://apigw.__bk_domain__/backend/admin42/core/apirelatedapp/，添加应用操作网关数据的权限

6. 注册网关资源时如果只想注册生成版本，不进行版本发布，该如何操作？

create_version_and_release_apigw 是进行网关资源生成版本和发布的命令，可以通过指定 --no-pub 只进行版本生成，不进行资源发布。

7. 同步网关资源的同时想直接根据 `resources.yaml` 即 swagger 或者 openapi3.0 生成文档，该如何操作？

sync_apigw_resources 是进行网关资源同步命令，可以通过指定 --doc_language: en/zh 生成接口文档

Metadata

Release files for apigw-manager 5.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for apigw-manager 5.0.2
File	Interpreter	ABI	Platform	Reset
apigw_manager-5.0.2-py3-none-any.whl 81.6 kB Oct 8, 2026	Python 3	none	any	Details

Release files / apigw_manager-5.0.2-py3-none-any.whl

Download URL	apigw_manager-5.0.2-py3-none-any.whl
Size	81.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1bfaf7c4feb0755ce6d9df6f385e82add5408c6abdbe0c8ed446e346b0f0c1ea`
BLAKE2b-256 checksum How to use checksums	`78cf47f709020f2c469322bacc4090202c7c4094bf6ab9eb4db8dd0a7c88aaa8`
Upload date	Oct 8, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.11.8`