NexusCore API 对接文档 版本:6.0 / 更新:2026-11-21 一、统一入口 首选:https://NexusCore.sufox.sbs/api/v2/ 备用:https://NexusCore.sufox.sbs/api/v1/ 调试方式:在统一入口后加查询参数 r,不需要 PHP 文件名。 示例:https://NexusCore.sufox.sbs/api/v2/?r=/health 为保持兼容,旧的 /api/v1/api_gateway.php?r=/... 与 /api/v2/api_gateway_v2.php?r=/... 仍可使用。 二、版本策略 1. 新客户端默认使用 V2。 2. 仅当 V2 处于 maintenance、disabled 或传输不可用时,允许对同一请求做一次 V1 重试。 3. 401 认证失败、403 权限不足、422 参数错误不得通过切换版本规避。 4. V2 健康检查返回 status、preferred、fallback 和支持的协议。 5. 管理端可设置 V2 为 active / maintenance / disabled;V1 为 active / fallback / maintenance / disabled。 6. V1 是受控兼容通道,不接收新协议能力;新功能只加入 V2。 三、协议选择 默认:json-command-v2。设备元数据通过一次心跳携带,不为每次心跳额外协商。 心跳/ACK/结果:HTTPS + application/json。 文件上传:HTTPS + multipart/form-data(/upload)。 客户端声明 protocol_version=2.0、client_version、client_type、execution_layer 和 capabilities。 服务端按 execution_layer 和 capabilities 选择命令;Native 与 Java 不得混用不兼容命令。 保留兼容:json-command-v1,仅用于旧 Native 客户端的受控接入。 四、身份认证 POST /api/v2/?r=/auth/token Content-Type: application/json 请求:{"key":"NexusCoreUserKey_..."} 成功:{"access_token":"...","token_type":"Bearer","expires_in":86400} 后续请求携带:Authorization: Bearer Token 使用 HS256、过期时间、账号状态、角色与当前 user_key 共同校验。 用户密钥被管理员重置后,旧 Token 立即失效。 五、主要接口 GET /api/v2/?r=/health POST /api/v2/?r=/auth/token POST /api/v2/?r=/devices/heartbeat POST /api/v2/?r=/devices/tasks/{request_id}/ack POST /api/v2/?r=/devices/tasks/{request_id}/result GET /api/v2/?r=/devices&limit=20&offset=0 GET /api/v2/?r=/devices/{device_key} POST /api/v2/?r=/devices/commands GET /api/v2/?r=/user/info GET /api/v2/?r=/private/files POST /api/v2/?r=/upload GET /api/v2/?r=/public/announcement 六、设备心跳示例 POST /api/v2/?r=/devices/heartbeat Authorization: Bearer Content-Type: application/json { "device_id":"apk_xxx 或用户设备标识", "info":{ "model":"Pixel 8 Pro","brand":"Google","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","file.list"] } } 返回示例: {"status":"ok","task":{"request_id":"cmd_...","command":"java.device.info"}} 无任务时 task 为 null。 七、Native 与 Java 命令 Native:沿用服务端模板生成的 su -c '...' 与 nexus_* 命令,由二进制客户端执行。 Kotlin/Java:使用 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 Java 客户端不具备跨应用文件访问、静默安装、后台截屏或后台摄像头权限;需要对应 Android 授权、Device Owner、MediaProjection 或辅助 Native 模块。 八、ACK 与结果 收到命令后:POST /api/v2/?r=/devices/tasks/{request_id}/ack,请求体 {}。 完成后:POST /api/v2/?r=/devices/tasks/{request_id}/result {"stdout":"...","stderr":"","exit_code":0,"duration_ms":120,"client_type":"kotlin"} stdout 有长度限制;客户端应保留错误信息,不应把权限错误报告为成功。 九、权限模型 user:仅本人设备、资源与获授权的 API。 admin:可管理普通用户和相应设备,不可修改 developer 或同级 admin,不可管理全局运行开关。 developer:平台运营控制,可管理普通用户与管理员、设备资源和用户 API 授权;主账号受保护。 全局 API 开关、运行状态和维护降级:V2 仅 admin;后台主账号通过 developer 会话控制。 普通用户的 user_api_permissions 显式拒绝优先;没有记录时维持兼容默认允许。 每次设备、文件和用户管理请求都执行归属校验,不能只依赖前端隐藏按钮。 十、请求限制与重放保护 普通 JSON 请求体最大 2 MiB;大文件走 multipart。 认证接口按来源 IP 限速;普通接口按路由与来源 IP 限速。 可携带 X-NC-Timestamp(Unix 秒)与 X-NC-Nonce(16-80 位安全随机字符串)。 带这两个头时,时间窗口为 300 秒,同来源重复 Nonce 返回 409。 旧设备轮询接口保留 JWT 兼容模式;新管理写操作应携带时间戳与 Nonce。 来源 IP 只信任 Web 服务器 peer address,不直接信任客户端提供的 X-Forwarded-For。 十一、统一错误格式 { "ok":false, "error":{"code":"PERMISSION_DENIED","message":"当前账号未被授予此 API 权限","details":{}}, "request_id":"...", "api_version":"v2" } 常见状态:400 参数错误;401 Token 缺失或失效;403 权限不足;404 路由不存在;409 重复请求; 413 请求体过大;415 Content-Type 错误;422 命令格式错误;429 触发限流;503 维护或服务暂不可用。 十二、安全与运维注意 密钥、Token、数据库配置不出现在日志和错误详情中。 密钥重置、用户封禁、角色变化、API 运行状态变更必须写入审计日志。 截图、媒体与命令输出属于用户数据,应设置访问期限、最小权限和清理策略。 Root、Device Owner、无障碍、MediaProjection 能力应按实际用途单独申请与明示。 TLS 证书必须验证,禁止信任所有证书、关闭主机名验证或回退明文 HTTP。 上传目录禁止执行脚本;文件名、扩展名、MIME、归属和大小均须校验。