API v2 · 默认

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=binary
execution_layer=native

使用受控 Native 模板与 nexus_* 命令,客户端通过 HTTPS/TLS 1.2+ 通信。

Kotlin / Java APK

client_type=kotlin
execution_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/uploadmultipart 文件上传
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. 权限边界

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 独立对接文档 →

下载完整文本版 · 返回官网