上云 API 2 鉴权接入指南

一、上云 API 2 鉴权介绍

上云 API 2 支持通过 Webhook 回调接入您自定义的鉴权逻辑。上云 API 2 不实现任何业务侧的鉴权逻辑。上云 API 2 鉴权流程如下：

① 客户端（Java SDK / 前端组件）发起请求，携带自定义鉴权 Header
        ↓
② 上云 API 2 网关拦截，提取鉴权 Header + 资源标识
        ↓
③ 上云 API 2 网关 POST 请求到您的 Webhook 服务（超时时长 3 秒）
        ↓
④ 您的服务返回 { "allowed": true } 或 { "allowed": false, "reason": "..." }
        ↓
⑤ 放行 → 网关剥离所有鉴权头，转发给后端业务服务
   拒绝 → 网关返回 401 给客户端

鉴权链路角色角色释义：

角色	由谁提供	职责
上云 API 2 网关	上云 API 2	拦截请求、转发鉴权、放行/拒绝
Webhook 鉴权服务	用户自建	校验凭据有效性，返回判定结果
客户端	Java SDK / 前端组件	把凭据注入到 HTTP 请求头或 WebSocket

Header 名称由您自定义。文档中的 X-User-Token 只是示例，可以是任意名称、也可以有多个。网关不认识任何固定字段名，它靠客户端发来的 auth_keys 头来决定读哪些 Header（格式见附录）。

鉴权通过后，上云 API 2 后端服务拿不到您的原始凭据。网关会剥离所有鉴权 Header 及 auth_keys头再转发。

凭据刷新由您定义。上云 API 2 SDK 和前端组件都不做 Token 自动刷新，是否刷新由您定义。

二、配置鉴权

2.1 前置：先把 Webhook 服务准备好

开启鉴权前，你的 Webhook 服务必须已经可用，否则一旦开启，所有请求都会被拒。

接口契约

项	值
请求方法	`POST`
请求地址	由 `ISV_WEBHOOK_URL` 指定
超时	3 秒（网关侧硬限制），超时即视为拒绝，返回 `401`
响应状态码	必须 `200`，非 200 会按拒绝处理

上云 API 2 网关传入的请求头

Header	说明
auth_keys	上云 API 2 网关根据该 Header 决定读取哪些 Header 作为凭据，示例：`auth_keys: tenant-id;x-auth-token`
你的自定义鉴权头	自定义鉴权头（由客户端 SDK 的 auth_keys 指定）客户端携带的 Token 等凭据，字段名由您与调用方约定
`X-Request-Id`	请求追踪 ID，建议落日志

响应格式

放行：

{ "allowed": true }

拒绝：

{ "allowed": false, "reason": "token expired" }

字段	类型	必填	说明
`allowed`	bool	✓	`true` 放行，`false` 拒绝
`reason`	string	—	拒绝原因，会原样透传给客户端

客户端收到的拒绝响应为 HTTP 401，Body：

{ "message": "token expired" }

message 取自你返回的 reason。

最简实现示例（Go）

实现时的四个注意点

必须在 3 秒内响应。若校验涉及查库或调用远程 IAM，务必加超时控制和本地缓存，不要把外部依赖的延迟直接暴露给网关。

Webhook 是单点。服务不可用 = 全部请求 401 = 业务全面中断。请按核心链路的标准做高可用部署与监控告警。

优先使用 https://。凭据会明文经由该地址传输，若走 http://，请确保网关与 Webhook 服务处于同一受控内网。

对 Webhook 接口本身做访问控制。该接口能决定全站放行与否，应限制来源，避免被任意调用方探测或滥用。

2.2 配置鉴权地址

鉴权回调地址由安装目录下 env 文件中的 ISV_WEBHOOK_URL 控制，位于「设备上云配置」区块：

根据您是否完成上云 API 2 底座来选择选择操作：

部署状态	操作
尚未完成底座安装	安装前编辑 `env`，改好 `ISV_WEBHOOK_URL` 后正常执行安装流程
已完成底座安装	编辑 `env`，然后执行 `./setuptools update` 使配置生效

注意事项：

ISV_WEBHOOK_URL 必须是合法的 http:// 或 https:// 地址。

只改这一行，勿动同区块内的 BIND_CODE 系列、SUB_NET_SELF_SERVICE、FH_ENV 等字段，以免影响设备上云绑定和网段划分。

仅编辑 env 不会生效，已安装环境必须执行 ./setuptools update。

2.3 验证配置已生效

通过标准：输出地址与 env 中设置的 ISV_WEBHOOK_URL 完全一致。

若仍是旧地址或默认测试地址，依次检查：

env 文件是否已保存；

是否执行了 ./setuptools update（已安装场景必须执行）；

改的是不是安装目录下的 env，而非备份文件。

配置生效后，还需完成客户端侧凭据注入，再端到端联调。

2.4 关闭鉴权

为了保证应用安全，鉴权不支持关闭

1.
ISV_WEBHOOK_URL 置空或删除时，上云 API 2 会拒绝全部请求（fail-closed）
2.
为了便于开发调试，提供默认webhook接口：http://pf-gateway-service:8080/gateway/test/webhook-auth，此接口会放行所有接口请求，请您谨慎使用，仅用于开发调试！
3.
如果您配置了默认的webhook接口，在使用SDK或者前端组件时，需要配置Header头：{"authKeys":["user_id"],"headers":{"user_id":"paas_test"}}

三、SDK 接入鉴权

3.1 SDK 做什么、不做什么

	说明
SDK 做	自动注入 HTTP 请求头；自动注入 WebSocket 握手凭据
SDK 不做	不实现业务鉴权策略；不做 Token 自动刷新，过期后由你重新设置
配置入口类	`com.dji.flighthubsdk.FlightHubSDK`，静态方法，无需实例化

KOC3 变更：FlightHubSdkConfig.setToken() 已废弃，不再通过 config 注入 token，统一改用下述 setHttpHeaders() / setWebSocketAuthHeaders()注入鉴权信息。
接口所属类也已从 FlightHubSdkManager 迁移至 FlightHubSDK。

3.2 鉴权相关四个接口

接口	作用
`setWebSocketAuthHeaders(List<HeaderKeyValue>)`	设置 WebSocket 握手鉴权头（消息通知连接）
`setHttpHeaders(List<HeaderKeyValue>)`	设置 HTTP 公共请求头（仅注入到含 `/gateway/` 的请求）
`getWebSocketAuthHeaders()`	获取当前 WebSocket 鉴权头
`getHttpHeaders()`	获取当前 HTTP 请求头

set 返回 FlightHubSdkErrorCode，SUCCESS（整型 0）表示成功。

HeaderKeyValue 位于 com.dji.flighthubsdk.bean.HeaderKeyValue，key 为约定的字段名（大小写敏感），value 为凭据。

set 是全量覆盖，再次调用会替换整组头，不是按 key 合并。

native 未加载时，set 返回 ERROR_NOT_INITIALIZED，get 返回空列表。

3.3 调用时序（顺序不可颠倒）

JniLibraryLoader.loadLibrary()      ← 必须最先，否则 set 失败
  → setWebSocketAuthHeaders(headers)
  → setHttpHeaders(headers)
  → initialize(config)              ← 必须最后

JNI 只在 initialize() 内部自动加载，因此 set 之前必须先手动 JniLibraryLoader.loadLibrary()。

鉴权头必须在 initialize 之前设置完毕，否则首个 WebSocket 连接和 HTTP 请求不带凭据，会被网关拒绝（401）。

空 header 仍允许 initialize 成功——SDK 不校验，但后续请求会被网关 401。生产环境务必确认凭据已注入。

3.4 接入示例

读取当前鉴权头：

key 以对接环境的网关约定为准。Demo 里常见默认值是 x-demo-uuid，不要照抄成固定头名。

3.5 Token 刷新

set 可在 initialize 之后再次调用：重新构造 authHeaders，再调 setHttpHeaders / setWebSocketAuthHeaders 全量覆盖即可。

通道	生效时机
HTTP	对后续 `/gateway/` 请求立即生效
WebSocket	仅在下次握手 / 重连时生效

⚠️ 刷新 WS 凭据后，若连接仍存活，会继续使用旧凭据——SDK 不会因 set 而主动断开重连。需要立刻切换到新凭据时，请由业务侧主动触发重连，不要假定 set 会踢掉旧连接。

3.6 注意事项

先 loadLibrary，再 set，再 initialize，漏掉第一步 set 必然失败。

key 必须与网关约定完全一致（大小写敏感）。上云 API 2 网关靠 auth_keys 决定读哪些头。

Token 刷新由你负责，SDK 不自动刷新token；HTTP 请求token刷新会立即生效，WebSocket的token刷新需重新握手。

不要打印 Token 明文。HeaderKeyValue.toString() 会带出 value，排查日志时注意脱敏。

四、前端独立组件鉴权

4.1 IAuth 结构

四个组件共用同一份鉴权配置结构：

字段	类型	必需	说明
`authKeys`	`string[]`	✓	鉴权 Header 的名称列表，供网关识别 `auth_keys`
`headers`	`() => Record<string, string>`	✓	函数形式，每次请求 / 连接时调用，返回当前鉴权头

两条硬约束：

authKeys 列出的名称必须与 headers() 返回对象的 key 一一对应（大小写敏感），否则上云 API 2 网关无法识别。

headers 必须是函数，不能是静态对象。函数形式才能在 Token 刷新后自动取到新值。

SDK 不接收 token 字段。凭据存在哪里由你决定——内存变量、状态管理、cookie、sessionStorage / localStorage 均可，只要 headers 闭包能读到。

同一份 auth 同时用于 HTTP 与 WebSocket，无需分别构造。

4.2 各组件的传入方式

IAuth 结构四个组件通用，但传入位置不同：

组件	HTTP 鉴权	WebSocket 鉴权
航线编辑 `WaylineEditor`	`api.auth`	`ws.auth`
飞行记录回放 `FlyDataReplay`	`api.auth`	`ws.auth`
设备管理 `UranusDeviceManagerApp.init`	顶层 `auth`（HTTP / WS 共用一份）	同左
驾驶舱 `FH2.loadCockpit`	`FH2.loadMap(serverUrl, auth)`	`FH2.initNotifyCenter(wssUrl, auth)`

航线编辑 / 飞行记录回放

auth 分别传给 api 和 ws：

设备管理

顶层传一份 auth，内部同时用于 HTTP 与 WebSocket：

组件内部接口路由自带 gateway 前缀，域名后加与不加 gateway，最终都会请求到带 gateway 的接口。

驾驶舱

auth 通过 FH2 全局流程传入，FH2 内部缓存并自动透传给驾驶舱及其子应用：

4.3 鉴权相关错误码

错误码	名称	说明
`4001`	`WS_AUTH_ERROR`	WebSocket 鉴权失败（服务端 close code `4001`）
`4002`	`WS_DISCONNECTED`	WebSocket 连接断开（非鉴权原因）
`5001`	`API_AUTH_ERROR`	HTTP 鉴权失败（`401` / `403`），应引导用户重新登录

五、端到端联调

按顺序确认五个环节，任何一环失败都表现为 401，务必逐项验证而非跳跃排查。

#	环节	验证方式
1	Webhook 服务可用	直接 `curl` 你的 Webhook 地址，确认 3 秒内返回 `200` + `{"allowed":true}`
2	网关已加载新地址	`docker exec pf-gateway-service grep "webhook_url" /app/config/config.tmpl.yaml`
3	客户端已注入凭据	Java：`FlightHubSDK.getHttpHeaders()` 非空前端：浏览器 Network 面板确认请求头已带上
4	Webhook 收到预期请求头	在 Webhook 服务中打印全部 Header（脱敏），确认能取到约定字段和 `X-Resource-*`
5	判定结果正确	分别用有效凭据和无效凭据各发一次请求，确认放行与拒绝均符合预期

第 1 步自测示例：

六、鉴权排障

401 有多个不同成因，客户端表现一致，需按下表逐项排除。建议从上往下依次验证。

症状 / 线索	可能原因	验证与处理
所有请求 401，且 Webhook 服务无任何访问日志	网关未加载新地址	执行 2.3 的验证命令；确认已跑 `./setuptools update`
所有请求 401，Webhook 有日志但取不到凭据字段	`authKeys` 与实际 Header 名不一致（大小写）	核对客户端 `authKeys` / `HeaderKeyValue` 的 key 与 Webhook 读取的字段名三者完全一致
所有请求 401，客户端未发送任何鉴权头	客户端未注入凭据，或注入时机太晚	Java：确认 set 在 `initialize` 之前，且已先 `loadLibrary()` 前端：Network 面板确认请求头
偶发 401，高峰期加剧	Webhook 响应超过 3 秒	检查 Webhook 的 P99 耗时；为外部依赖加超时与缓存
401 的 `message` 为空或非你返回的 `reason`	Webhook 返回非 `200`、超时或响应解析失败	确认响应状态码严格为 `200`，Body 为合法 JSON
401 的 `message` 是你返回的 `reason`	鉴权逻辑正常工作，是业务判定拒绝	按 `reason` 排查凭据本身（过期、无权限等）
HTTP 正常但 WebSocket 报 `4001`	WS 凭据未注入，或刷新后未重连	Java：确认调了 `setWebSocketAuthHeaders`；刷新后需主动重连前端：确认 `headers` 是函数形式
刷新 Token 后 HTTP 恢复、WS 仍失败	旧 WS 连接仍用旧凭据	预期行为，见 3.5；需业务侧主动断开重连
前端接口报 404 或 401	服务地址格式不对	对照 4.2 各组件示例核对：航线编辑 / 飞行记录的 `api.baseUrl` 需带 `/gateway`

附录：协议细节

自建客户端（不使用 Java SDK / 前端组件，直接发 HTTP 请求）时需按本节实现。使用 SDK 或组件时，以下拼装由其自动完成，无需关心。

`auth_keys` Header

上云 API 2 网关根据该 Header 决定读取哪些 Header 作为凭据。

值：所有鉴权 Header 的 key 列表，分号 ; 分隔，按 key 字母序排列。

示例：auth_keys: tenant-id;x-auth-token

鉴权头为空时不注入该头。

HTTP 注入规则（Java SDK 行为）

仅对 URL 中含 /gateway/ 的请求注入。

注入两类头：你设置的鉴权 Headers，以及上述 auth_keys。

若请求已带同名头或已有 auth_keys，SDK 不覆盖。

WebSocket 握手编码

凭据走 Sec-WebSocket-Protocol 头：

Sec-WebSocket-Protocol: v1.notify,auth.<Base64URL(key=value;...)>

key=value 按 key 字母序用 ; 拼接后，做 URL-safe Base64 编码：+ → -，/ → _，去掉末尾 =。

失败语义

网关鉴权失败统一返回 401，SDK 原样透传，不自动刷新。这与 SDK 自身接口的错误码（如 JNI 未加载时的 ERROR_NOT_INITIALIZED）是两回事，不要混淆。

鉴权接入指南

上云 API 2 鉴权接入指南#

一、上云 API 2 鉴权介绍#

二、配置鉴权#

2.1 前置：先把 Webhook 服务准备好#

接口契约#

上云 API 2 网关传入的请求头#

响应格式#

最简实现示例（Go）#

实现时的四个注意点#

2.2 配置鉴权地址#

2.3 验证配置已生效#

2.4 关闭鉴权#

三、SDK 接入鉴权#

3.1 SDK 做什么、不做什么#

3.2 鉴权相关四个接口#

3.3 调用时序（顺序不可颠倒）#

3.4 接入示例#

3.5 Token 刷新#

3.6 注意事项#

四、前端独立组件鉴权#

4.1 IAuth 结构#

4.2 各组件的传入方式#

航线编辑 / 飞行记录回放#

设备管理#

驾驶舱#

4.3 鉴权相关错误码#

五、端到端联调#

六、鉴权排障#

附录：协议细节#

auth_keys Header#

HTTP 注入规则（Java SDK 行为）#

WebSocket 握手编码#

失败语义#