3.2 KiB
一、认证方案概述
GoEdge 的 API 调用采用 令牌机制（AccessToken） 来进行用户／系统权限认证。
整体流程可简化为：
创建 AccessKey（用户或管理员）
使用 AccessKey 调用获取 AccessToken 接口
在后续所有 API 请求中，在 HTTP Header 中携带该 AccessToken 以认证身份
二、关键步骤详解
- 创建 AccessKey
AccessKey 分为两种：
用户 AccessKey（针对平台用户，用于访问其用户相关数据）
管理员 AccessKey（针对系统／管理员用户，可操作所有管理员有权限的数据）
创建方式（概况）
用户版：在「平台用户 → 用户详情 → API AccessKey」页面创建。
管理员版：在「系统用户 → 用户详情 → API AccessKey」页面创建。
- 获取 AccessToken
接口地址：/APIAccessTokenService/getAPIAccessToken（HTTP POST）
请求参数示例：
{ "type": "admin", "accessKeyId": "<你的AccessKeyId>", "accessKey": "<你的AccessKey>" }
其中 "type" 字段：
值为 "user" 表示调用用户 AccessKey 获得 token
值为 "admin" 表示调用管理员 AccessKey 获得 token
响应结构示例：
{ "code": 200, "data": { "token": "<AccessToken字符串>", "expiresAt": 1609686945 }, "message": "ok" }
token 字段即为后续调用 API 时使用的 AccessToken。
expiresAt 表示该 token 的过期时间戳。
多次调用该接口会导致之前的 token 失效。
- 使用 AccessToken 调用 API
在每次 API 请求（其它服务接口）中，需要在 HTTP Header 中加入字段：
X-Edge-Access-Token: <从上述获取接口得到的AccessToken>
来进行身份认证。
请求方法一般为 POST，URL 为 /服务/方法 形式。
三、重要注意事项 &机制要点
Token 有有效期 (expiresAt)，一旦过期要重新获取。
多次获取新的 token 会使之前的 token 失效，因此应注意 token 管理。
区别 “用户” 与 “管理员” 权限：对应的 AccessKey 类型不同、权限范围不同。
每次 API 调用都必须携带 header 的 token，否则将无法认证。
创建 AccessKey 前，需要在后台／平台对应页面进行授权／配置（用户／管理员视其角色而定）
四、认证方案优缺点（基于文档公开信息分析）
优点
简单易用：通过 AccessKey → 获取 token → 携带 token 调用接口，该流程直观。
分角色控制：用户 vs 管理员两种 AccessKey 类型，可以区分权限。
Token 有失效机制，有助于安全控制。
可能的局限/需注意点
未明确提及「刷新 token（refresh token）」机制：若 token 过期，需重新用 AccessKey 再次获取。
若 AccessKey／token泄露，则可能被滥用；要做好保密。
文档未说明 token 是加密 JWT 还是简单字符串，也未说明 Scope（权限粒度）如何定义。
对于高频调用或长期服务而言，每次新的 token 使旧 token 失效，可能影响服务连续性。
五、总结一句话
在 GoEdge 的 API 中，认证方案为：“先用对应角色的 AccessKey 获取一个 AccessToken，然后在所有 API 请求头中携带该 token 以识别调用者身份与权限”。