NexusCore 接口文档
版本 6.0 · 2026-11-21。V2 承载新协议与新客户端,V1 作为受控兼容和维护降级通道。
1. 访问地址
首选 https://NexusCore.sufox.sbs/api/v2/ 备用 https://NexusCore.sufox.sbs/api/v1/ 示例 https://NexusCore.sufox.sbs/api/v2/?r=/health
统一入口不需要 PHP 文件名。旧 api_gateway.php?r=... 地址仅为兼容保留。仅当 V2 维护或传输不可用时降级;401、403、422 不通过切换版本重试。
2. 认证
POST /api/v2/?r=/auth/token
Content-Type: application/json
{"key":"NexusCoreUserKey_..."}成功返回 access_token。之后使用 Authorization: Bearer <token>。密钥重置或账号禁用后,旧 Token 会失效。
3. 协议与客户端
Native
client_type=binaryexecution_layer=native
使用受控 Native 模板与 nexus_* 命令,客户端通过 HTTPS/TLS 1.2+ 通信。
Kotlin / Java APK
client_type=kotlinexecution_layer=java
默认由 Java 层执行结构化命令。无 Root 时只提供已声明、已授权的 Android 能力。
设备心跳同时上报 protocol_version=2.0、client_version 和 capabilities,无需每次额外协商。文件上传采用 multipart,其余接口采用 JSON。
4. 核心接口
| 方法 | r 参数 | 用途 |
|---|---|---|
| POST | /auth/token | 获取访问 Token |
| POST | /devices/heartbeat | 设备心跳、能力声明、拉取任务 |
| POST | /devices/tasks/{id}/ack | 确认收到任务 |
| POST | /devices/tasks/{id}/result | 上传执行结果 |
| GET | /devices | 列出当前账号设备 |
| POST | /devices/commands | 设备命令入队 |
| GET | /user/info | 账号资料 |
| POST | /upload | multipart 文件上传 |
| GET | /health | 运行状态与降级入口 |
5. 心跳示例
POST /api/v2/?r=/devices/heartbeat
Authorization: Bearer <token>
Content-Type: application/json
{
"device_id":"apk_example",
"info":{
"model":"Pixel 8 Pro","sdk":"35","android":"15",
"client_type":"kotlin","execution_layer":"java",
"client_version":"6.0","protocol_version":"2.0",
"capabilities":["device.info","device.network","app.list"]
}
}
6. Java 命令
java.device.ping java.device.info java.device.network java.app.list java.file.list:<应用私有目录,可空> java.media.list:<数量> java.notification.post:<文本>
Java 层不执行任意 Shell,不接收 nexus_run_script / nexus_run_binary。无 Root 时不能提供跨应用文件访问、静默安装、后台截屏或后台摄像头等系统能力。
7. 权限边界
- user:本人设备、资源及获授权的 API。
- admin:管理普通用户,不可修改 developer、同级 admin 或全局运行开关。
- developer:平台运营管理、用户授权和维护降级;主账号受保护。
- 所有归属和角色校验由服务端执行,前端按钮隐藏不作为权限依据。
8. 请求限制与错误
普通 JSON 请求体最大 2 MiB。认证与业务接口按来源和路由限流。可携带 X-NC-Timestamp 与 X-NC-Nonce;携带后执行 300 秒时间窗和同来源 Nonce 重放校验。
{
"ok":false,
"error":{"code":"PERMISSION_DENIED","message":"当前账号未被授予此 API 权限","details":{}},
"request_id":"...",
"api_version":"v2"
}常见状态码:400、401、403、404、405、409、413、415、422、429、503。
9. 数据与安全
密钥、Token 和数据库配置不写入日志或错误详情。密钥轮换、账号状态变化、角色变更、运行状态变更写入审计。上传目录禁止脚本执行。客户端必须验证 TLS 证书和主机名,不得回退明文 HTTP。媒体、设备信息和命令输出按账号隔离,并应按业务需要设置保留期限。
使用旧客户端?切换至 API V1 独立对接文档 →