bk-apigateway FAQ

[wklken]

Description

[toc]

网关错误响应说明

499

无response body

• 原因: client 调用网关等待时间超过设置的timeout时间, 主动关闭连接, 此时网关会主动关闭后端接口的调用, 返回 499
• 处理: 被调用方提升接口性能, 或者调大client的超时时间(不建议过大)

504

{
  "code_name": "REQUEST_BACKEND_TIMEOUT",
  "data": null,
  "code": 1650401,
  "message": "Request backend service timeout [upstream_error=\"cannot read header from upstream\"]",
  "result": false
}

• 原因: 网关资源会配置后端接口的timeout时间, 如果后端接口调用超时, 此时网关返回504
• 处理: 被调用方提升接口性能, 或者调大网关的超时时间(不建议过大)

后台错误响应说明

调用方式

认证

概念

• 应用认证: 蓝鲸PaaS平台会给每个应用分配一个唯一的bk_app_code, 以及对应的bk_app_secret用于应用身份认证; 如果 API 启用了应用认证, 那么调用方需要在请求头中提供合法的bk_app_code/bk_app_secret, 网关会校验应用是否合法
• 用户认证: 蓝鲸统一登录, 会给每个登录的用户分配唯一的登录态bk_token(在cookie中), 用于用户身份认证; 如果 API 启用了 用户认证, 那么调用方需要在请求头中提供合法的bk_token, 网关会校验用户是否合法
• 校验访问权限: 某些API开启了校验访问权限, 则需要应用开发者到蓝鲸开发者中心申请 应用调用该API的权限, 审批通过后, 这个蓝鲸应用才能调用这个 API, 否则会返回无权限; 注意: 校验访问权限要求该 API 开启 应用认证, 网关需要拿应用认证通过后的bk_app_code进行权限校验
• access_token: 蓝鲸的 bkauth(旧版本的ssm) 等服务, 提供了access_token签发, 支持签发 应用身份access_token(代表一个已认证应用) 以及 应用+用户身份 access_token (代表一个已认证应用+已认证用户); 在无用户登录态/定时任务/脚本等调用网关 API 的场景, 可以使用access_token替代 bk_app_code/bk_app_secret/bk_token

认证 Header 头

X-Bkapi-Authorization: {}

示例:

# 调用目标 API 开启: 应用认证+用户认证
X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y", "bk_token": "z"}

# 调用目标 API 开启: 应用认证
X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y"}

# 调用目标 API 开启: 用户认证
X-Bkapi-Authorization: {"bk_token": "z"}

# 使用access_token
X-Bkapi-Authorization: {"access_token": "z"}

curl 请求示例:

curl 'http://bkapi.example.com/prod/users/'
    -H 'X-Bkapi-Authorization: {"bk_app_code": "x", "bk_app_secret": "y", "bk_token": "z"}'

认证报错信息

message: app code cannot be empty

status: 400

{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"app code cannot be empty\"]",
  "result": false
}

• 原因: 没有提供 X-Bkapi-Authorization 头或者 X-Bkapi-Authorization头中没有 bk_app_code
• 处理: 提供 X-Bkapi-Authorization 头并且里面包含 bk_app_code

message: please provide bk_app_secret or bk_signature to verify app

status: 400


{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"please provide bk_app_secret or bk_signature to verify app\"]",
  "result": false
}

• 原因: X-Bkapi-Authorization头中没有 bk_app_secret
• 处理: X-Bkapi-Authorization 头里面包含 bk_app_secret

message: bk_app_code or bk_app_secret is incorrect

status: 400

{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"bk_app_code or bk_app_secret is incorrect\"]",
  "result": false
}

• 原因: bk_app_code + bk_app_secret 校验失败, 不合法
• 处理: 确认发起请求头中 bk_app_code / bk_app_secret 合法, 与蓝鲸 PaaS 平台或运维签发给到的一致

message: user authentication failed, please provide a valid user identity, such as bk_username, bk_token, access_token

status: 400

{
  "code": 1640001,
  "data": null,
  "code_name": "INVALID_ARGS",
  "message": "Parameters error [reason=\"user authentication failed, please provide a valid user identity, such as bk_username, bk_token, access_token\"]",
  "result": false
}

• 原因:
  • 没有提供X-Bkapi-Authorization 头
  • 头里面没有包含 bk_token or access_token
  • bk_token 不合法(会到蓝鲸统一登录校验, 校验失败, 可能是非法的bk_token或已过期)
  • access_token不合法(会到蓝鲸bkauth/ssm校验, 校验失败, 可能是非法的access_token或已过期)
• 处理: 确认 bk_token/access_token 存在并且合法

message: user authentication failed, the user indicated by bk_username is not verified

status: 400

{
    "code":1640001,
    "data":null,
    "code_name":"INVALID_ARGS",
    "message":"Parameters error [reason=\"user authentication failed, the user indicated by bk_username is not verified\"]",
    "result":false
}

• 原因：
  • 提供的用户认证信息里面，只有 bk_username，没有 bk_token, access_token 等能表示用户真实身份的信息，而 bk_username 不能真实表示用户真实身份（非 verified)
• 处理：网关"插件配置”中，查找插件“免用户认证应用白名单(不推荐)”，在该插件配置中，将应用添加到免用户认证应用白名单中。该插件不推荐使用，非官方网关，暂可能无法添加此插件。

message: App has no permission to the resource

status: 403

{
  "code": 1640301,
  "data": null,
  "code_name": "APP_NO_PERMISSION",
  "message": "App has no permission to the resource",
  "result": false
}

• 原因: 网关 API 开启了 校验访问权限, 调用方bk_app_code无权限调用(没有申请权限或者权限过期)
• 处理: 申请权限/权限续期

权限

[wklken]

pending

APIGW网关地址拼接

容器化及二进制部署中, 会渲染环境变量BK_API_URL_TMPL (SaaS app 由paas平台部署时渲染, 非 SaaS 由运维部署脚本负责渲染)

BK_API_URL_TMPL=http://bkapi.xxxxx.com/api/{api_name}

使用示例:

# 访问 bk-iam
bk_iam_url_prefix = BK_API_URL_TMPL.render(api_name="bk-iam")

# 访问 bk-iam prod
policy_query_url = bk_iam_url_prefix + "/prod" + "/api/v1/policy/query"

[alex-smile]

使用 apigw-manager<=1.1.7 同步网关资源到 API 网关时，报错：版本 xxx 已存在

错误消息样例如下：

File "/usr/local/lib/python3.6/site-packages/apigw_manager/apigw/management/commands/create_version_and_release_apigw.py", line 86, in create_resource_version
...
apigw_manager.core.exceptions.ApiRequestError: status_code: 400, code: 40002, 校验失败: 版本 1.0.2 已存在。

错误原因：
发布版本后，回退到一个低版本号版本，然后，再次发布版本，此时，因版本号检查逻辑存在问题，导致出现错误。例如发布版本 1.0.2 后，将版本回退到 1.0.1，网关会创建一个新版本 1.0.1+20230720205646，此时，再发布新版本 1.0.2 时，则可能出现上面的错误。

查看资源版本地址：http://apigw.__bk_domain__/{gateway_id}/version

解决方案：
方案一：手动生成一个资源版本，版本号设置为：新版本号 + 一个时间字符串，例如：1.0.2+20230820205646
方案二：升级 apigw-manager >= 2.0.0

方案一可用于临时修复问题，建议按方案二升级 SDK 版本。

[alex-smile]

[apigw-manager] 调用 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/，添加应用操作网关数据的权限

[wklken]

部署配置

apisix 同步 etcd, 如果 etcd 发生了 compact, 此时apisix watch 的revision 小于 etcd compact revision, apisix watch 到事件变更会直接触发全量同步, 具体机制参考文档

带来的问题:

• apisix本身的性能抖动(全量同步后, 会重建radixtree)
• etcd 读 IO 波峰 / 内存波峰(所有连接的 worker 都进行了全量拉取)

解决方案:
默认etcd的配置 --auto-compaction-mode=periodic --auto-compaction-retention=5m, 如果apisix实例很多, 无论怎么配置, apisix 全量同步的概率还是很大;

建议将配置改成 --auto-compaction-mode=revision --auto-compaction-retention=1000, 默认会保留 1000 个有效的revision

注意, 如果网关的路由过多, 发布短时间内可能产生超过 1000 次更新, 也可能会导致有问题, 此时需要调整阈值

[wklken]

see the docs here:
https://bk.tencent.com/docs/markdown/ZH/APIGateway/1.14/UserGuide/FAQ/error-response.md