切换深色模式
平台管理 API
本册用于用户、权限、授权、系统维护等平台能力。终端登记、数据订阅、单播下行和组播统一在 LoRaWAN API 查阅；消息接入和网关传输分别见 MQTT 与 UDP。
连接方式
| 类型 | 入口 | 请求格式 |
|---|---|---|
| gRPC | 服务器主机:API端口，原生默认 8080 | Protobuf；Postman gRPC 可填写 protobuf JSON |
| gRPC-Web | /api.服务名/方法名 | gRPC-Web 帧，不是普通 JSON HTTP |
| 原生 HTTP | 本册“原生 HTTP”所列路由 | 按接口使用 JSON / 文件 |
| REST Gateway | 仅额外部署后才可使用 | proto 中 REST 注解不能直接当当前服务的路由 |
开发环境本次 API 端口为 18080，不是发行包默认值。浏览器 5173 是开发前端。正式部署以启动输出和 server.toml 为准。
登录与凭据
Postman 创建 gRPC 请求，选择 api.InternalService/Login，填写 email 和 password。这里字段名为 email，登录名仍可按系统账号填写，例如初始账号 admin。成功返回 jwt。其他请求的 Metadata 设置 authorization 为 Bearer <token>。
业务系统可由管理员在“接口密钥”创建长期凭据。API Key、用户登录 JWT 和 MQTT 账号密码不能互换；平台管理员与租户/只读凭据权限不同。没有权限时应申请所需范围，不能默认给所有业务管理员权限。
权限和登录态的例外
Login 用于获取登录 JWT，不先带 JWT。Profile、GetLicenseInfo、GetAiAssistantStatus 要求有效用户登录态；不要假设只持 API Key 就一定可用。ApplyLicense、TestAiAssistant 要求平台管理员。原生 HTTP 更新还要求管理员用户身份，不能仅用管理员 API Key 替代。
设备、网关、组播的读取与修改分别按对应资源权限校验；查询权限不包含写入和删除权限。ListApiKeys 中 is_admin 与 tenant_id 不能同时指定，非管理员密钥列表需指定 tenant_id；limit 为 0 的返回数量行为另见参数表。
通用字段规则
bytes在 protobuf JSON 中使用 Base64，不是 HEX。- EUI 为 16 位 HEX，设备短地址为 8 位 HEX，AES 密钥为 32 位 HEX；UUID 使用服务端返回值。
- protobuf JSON 的字段名工具可能接受 snake_case 和 lowerCamelCase；SDK 使用生成字段方法。
- 时间戳按 Timestamp 类型处理，跨时区比对时转换到相同基准。
- List 通常使用 limit / offset；部分方法 limit 为 0 仅返回数量，不能因此判断没有记录。
- proto3 未声明 required；本册“按业务校验”并非表示可以随意省略。嵌套对象、资源存在性、权限和字段组合都可能被检查。
- repeated 为列表，map 为键值映射；枚举可按工具支持形式使用枚举名称。64 位整数在 JSON 客户端中可能表现为字符串，避免精度丢失。
错误与重试
gRPC-Web HTTP 200 仍可能在 trailer 中返回业务错误，应检查 grpc-status / grpc-message。gRPC 客户端直接检查 status code。
| 常见状态 | 处理 |
|---|---|
| UNAUTHENTICATED | 检查 token 是否存在、过期或失效 |
| PERMISSION_DENIED | 检查账号/密钥的资源范围和操作权限 |
| INVALID_ARGUMENT | 检查格式、必填对象、枚举和组合约束 |
| NOT_FOUND | 核对资源 ID 和是否已删除 |
| ALREADY_EXISTS | 先查询确认，避免重复创建 |
| RESOURCE_EXHAUSTED | 检查资源/消息限制及相关提示 |
| UNAVAILABLE / DEADLINE_EXCEEDED | 检查服务和网络；写操作先查询结果再重试 |
| INTERNAL | 记录时间和脱敏错误，查对应服务日志 |
此表是统一排错方式，不承诺每个方法都会产生全部状态。创建、下行和远程执行超时后不可直接无限重试，以免重复操作。
平台功能与完整字段索引
| 分类 | 文档 |
|---|---|
| 登录、用户资料与 API Key | InternalService |
| 平台用户 | UserService |
| 租户与成员（后台保留） | TenantService |
| 授权、远程网关、审计、诊断与扩展 | AlinkwiseService |
| 原生 HTTP 更新与下载 | 原生 HTTP |
LoRaWAN 对应完整结构可进一步查看：应用、终端、模版、网关、组播、Relay、FUOTA。后台接口存在不等于标准网页提供对应操作入口。
版本与覆盖
本版参考覆盖当前项目 proto 声明的 180 个 RPC 方法。每个方法给出请求、返回与嵌套结构；这表示字段覆盖，不表示 180 个方法全部经过线上调用或硬件实测。平台维护中会产生外部请求、清理数据或写入配置的接口应由管理员按场景执行。