远程解锁模块 API 文档

版本: 1.0

本文档是远程解锁模块 (Remote Unlock Module) 的官方API参考。提供了所有可用端点的详细信息，包括如何进行身份验证、请求参数、以及预期的响应格式。

免 责 声 明

本 [网站/文件/服务/产品]（以下简称“本服务”）提供的信息仅供一般参考之用。所有信息均基于诚信原则提供，但我们不对本服务上任何信息的准确性、充分性、有效性、可靠性、可用性或完整性作出任何明示或暗示的陈述或保证。

在任何情况下，对于因使用本服务或依赖本服务提供的任何信息而导致的任何形式的损失或损害，我们概不负责。您使用本服务以及对本服务上任何信息的依赖，风险完全由您自行承担。

本服务可能包含（或通过本服务将您引导至）来自第三方网站的链接或内容。我们不会对此类外部链接的准确性、相关性、及时性或完整性进行调查、监控或检查。

本服务提供的内容不构成任何形式的专业建议（包括但不限于法律、财务、医疗或其他专业建议）。所有内容仅为信息分享，在根据此类信息采取任何行动之前，我们强烈建议您咨询相关领域的专业人士。我们不提供任何形式的专业建议。

快速入门

基础URL

所有API请求的基础URL如下：

1
http://localhost:2091/api/v1

或者

1
https://localhost:2091/api/v1

SSL 证书为程序初始化的时候自动生成

身份验证

本API的大部分端点需要通过API密钥进行身份验证。请在HTTP请求头 (Header) 中包含 Authorization 字段。

  • 类型: apiKey
  • 请求头字段名: Authorization
  • 格式: Authorization: Bearer <YOUR_API_KEY>

中文提示: 这里的 <YOUR_API_KEY> 需要替换为您在登录或系统配置中获取的实际认证令牌 (Token)。所有需要认证的接口都必须携带此请求头，否则将返回 401 Unauthorized 错误。

通用响应格式

所有API的响应都遵循统一的数据结构，方便客户端进行统一处理。

1
2
3
4
5
6
{
    "code": 0,
    "msg": "success",
    "data": {},
    "request_id": "unique-request-id-string"
}
  • code: 状态码。0 通常表示成功，其他非零值表示不同类型的错误。
  • msg: 对本次响应的简短描述，可能是 “success” 或具体的错误信息。
  • data: 实际返回的数据内容，可以是对象、数组或null。
  • request_id: 本次请求的唯一标识符，可用于问题排查。

API 端点详解

计算机控制 (PC Control)

POST /control-pc/{action}/

控制计算机执行指定操作，如关机、待机或锁定。

  • 认证: ✅需要
  • 描述: 根据传入的 action 参数来控制计算机。shutdown (关机) 和 standby (待机) 操作还可以附加一个延迟时间。

路径参数 (Path Parameters)

参数名类型必需枚举值中文说明
actionstring是shutdown, standby, lock要执行的操作类型。分别是关机、待机、锁定。

查询参数 (Query Parameters)

参数名类型必需中文说明
delaystring是延迟执行的时间（秒）。仅在 action 为 shutdown 或 standby 时有效。
shutdown_typestring否关机类型。当且仅当action=shutdown生效。例如，可以指定为“强制”或“混合”等（具体可用值参考下面）。
shutdown_type中文说明
0不执行操作
通用 (General)
1注销当前用户
2强制关闭所有应用程序并关机
3强制关闭所有应用程序并重启
仅Windows 版可用
4关机但不关闭电源
5重启计算机
6强制关闭所有应用程序
7关机并关闭电源
8重启应用程序
9混合关机
10强制关闭所有应用程序并关机同时关闭电源
11重启计算机并重启应用程序
12强制关闭应用程序后重启并重启应用程序
13关机但不关闭电源，关机后重启应用程序
14混合关机并强制关闭应用程序
15混合关机并重启应用程序
16混合关机、强制关闭应用程序并重启应用程序

响应 (Responses)

  • 200 OK: 操作指令已成功发送。
  • 400 Bad Request: 无效的操作类型 (action 不在枚举值内)。
  • 500 Internal Server Error: 执行操作失败，可能是权限不足或其他系统错误。

系统信息 (System)

GET /info

获取软件的版本等基本信息。

  • 认证: ✅需要

响应 (Responses)

  • 200 OK: 成功获取信息。
  • 500 Internal Server Error: 服务器内部错误。

GET /info/check_update

检查系统是否有可用的更新。

  • 认证: ✅需要
  • 描述: 返回最新的可用更新详情，包括版本号、更新URL和发布说明。

查询参数 (Query Parameters)

参数名类型必需默认值中文说明
langstring否en指定更新信息的语言。

响应 (Responses)

  • 200 OK: 成功获取更新信息。
  • 500 Internal Server Error: 服务器内部错误。

GET /info/language

获取当前系统设置的语言。

  • 认证: ❌不需要

响应 (Responses)

  • 200 OK: 成功获取语言设置。
  • 500 Internal Server Error: 服务器内部错误。

PATCH /info/language

设置系统语言。

  • 认证: ❌不需要

查询参数 (Query Parameters)

参数名类型必需默认值中文说明
langstring否en要设置的目标语言。

响应 (Responses)

  • 200 OK: 成功设置语言。
  • 500 Internal Server Error: 服务器内部错误。

GET /logs/{module}

实时获取系统日志流。

  • 认证: ✅需要
  • 描述: 此端点会建立一个长连接，实时推送系统产生的日志。连接将保持打开状态，直到客户端关闭或发生错误。

路径参数 (Path Parameters)

参数名类型必需中文说明
modulestring是指定要获取哪个模块的日志。当前文档中，此值必须是 service。

响应 (Responses)

  • 200 OK: 开始推送日志流 (Content-Type: text/event-stream)。
  • 400 Bad Request: 指定了无效的模块。
  • 500 Internal Server Error: 服务器内部错误，例如日志缓冲区不可用。

节能模式 (Power Saving)

POST /power-saving

开启、关闭或自动设置节能模式。

  • 认证: ✅需要
  • 描述: 该功能会先将设置写入数据库，如果写入成功，再应用到系统。即使系统应用失败，数据库中的值也会被更新。

查询参数 (Query Parameters)

参数名类型必需默认值中文说明
modestring否auto节能模式。可选值为 enable (开启), disable (关闭), 或 auto (自动)。

响应 (Responses)

  • 200 OK: 成功设置节能模式。
  • 400 Bad Request: 无效的请求参数。
  • 500 Internal Server Error: 服务器内部错误。

GET /power-saving/status

获取当前节能模式的状态。

  • 认证: ✅需要

响应 (Responses)

  • 200 OK: 成功获取节能模式状态。
  • 500 Internal Server Error: 服务器内部错误。

网络接口 (Network Interfaces)

GET /interface

获取有效的网络接口列表。

  • 认证: ✅需要
  • 描述: 根据指定的IP版本（IPv4或IPv6），返回一个当前设备上所有有效网络接口的列表。

查询参数 (Query Parameters)

参数名类型必需默认值枚举值中文说明
typestring否44, 6IP协议版本类型，4 代表IPv4，6 代表IPv6。

响应 (Responses)

  • 200 OK: 成功返回网络接口列表。
  • 400 Bad Request: 请求参数不正确。
  • 500 Internal Server Error: 服务器内部错误。

GET /interface/{ip}

根据IP地址获取其对应的MAC地址。

  • 认证: ✅需要

路径参数 (Path Parameters)

参数名类型必需中文说明
ipstring是要查询的IP地址。

响应 (Responses)

  • 200 OK: 成功获取MAC地址。
  • 400 Bad Request: 请求格式不正确（例如IP地址无效）。
  • 500 Internal Server Error: 服务器内部错误。

GET /interface/{ip}/all

根据IP地址获取完整的接口信息。

  • 认证: ✅需要

路径参数 (Path Parameters)

参数名类型必需中文说明
ipstring是要查询的IP地址。

响应 (Responses)

  • 200 OK: 成功获取接口信息。
  • 400 Bad Request: 请求格式不正确。
  • 500 Internal Server Error: 服务器内部错误。

用户认证与操作 (User)

POST /login

用户登录。

  • 认证: ✅需要 (此处的认证可能是指客户端的基础认证，用于换取更长时效的Token)
  • 描述: 使用用户名和密码进行身份验证，成功后会返回一个JWT（JSON Web Token），用于后续需要认证的API请求。

请求体 (Request Body)

1
2
3
4
{
    "username": "your_username",
    "password": "your_password"
}
  • Schema: LoginRequest

响应 (Responses)

  • 200 OK: 认证成功，响应的 data 字段中会包含JWT Token。
  • 400 Bad Request: 请求参数无效（例如用户名或密码为空）。
  • 500 Internal Server Error: 服务器内部错误。

POST /unlock

解锁你的电脑。

  • 认证: ❌不需要
  • 描述: 发送电脑的用户名和密码来执行解锁操作。

请求体 (Request Body)

1
2
3
4
{
    "username": "your_pc_username",
    "password": "your_pc_password"
}
  • Schema: PcUserInfo

响应 (Responses)

  • 200 OK: 解锁成功。
  • 400 Bad Request: 请求格式不正确。
  • 500 Internal Server Error: 内部错误（例如用户名或密码错误，解锁失败）。

其他 (Miscellaneous)

GET /ping

服务探活（Ping）。

  • 认证: ❌不需要
  • 描述: 用于检查服务是否正常运行，或特定子服务（如WebSocket）的状态。

查询参数 (Query Parameters)

参数名类型必需枚举值中文说明
typestring否ws, pairing探测类型。ws 可能用于测试WebSocket服务，pairing 可能用于测试配对服务。

响应 (Responses)

  • 200 OK: 服务正常。
  • 500 Internal Server Error: 服务异常。

数据模型 (Definitions)

LoginRequest

用户登录时使用的凭据对象。

字段名类型必需中文说明
usernamestring是用户名
passwordstring是密码

PcUserInfo

解锁电脑时使用的用户信息对象。

字段名类型必需中文说明
usernamestring否电脑的用户名
passwordstring否电脑的登录密码

ResponseData

所有API响应的通用数据结构。

字段名类型中文说明
codeinteger业务状态码, 0 表示成功
dataobject实际返回的数据
msgstring提示信息
request_idstring本次请求的唯一ID