XCDesktop/remote/docs/开发/API文档.md

API 文档

目录

• 认证接口
• 输入控制接口
• 流媒体接口
• 文件传输接口
• WebSocket 消息类型

---

认证接口

POST /login

Web 登录接口，用于用户身份认证。

请求体

{
  "password": "your_password"
}

参数说明

参数	类型	必填	说明
password	string	否	用户密码（如果服务器未配置密码则不需要）

响应示例

成功响应（200）：

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "Authentication disabled"
}

失败响应（400）：

{
  "success": false,
  "error": "Password is required"
}

失败响应（401）：

{
  "success": false,
  "error": "Invalid password"
}

---

POST /api/auth/login

API 登录接口，功能与 /login 相同。

请求体

{
  "password": "your_password"
}

响应示例

成功响应（200）：

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

POST /api/auth/verify

Token 验证接口，用于验证 JWT Token 是否有效。

请求头

Authorization: Bearer <token>

响应示例

成功响应（200）：

{
  "success": true,
  "valid": true,
  "userId": "default-user"
}

失败响应（401）：

{
  "success": false,
  "valid": false,
  "error": "No token provided"
}

---

输入控制接口

所有输入控制接口需要在请求头中携带有效的 Token：

Authorization: Bearer <token>

鼠标操作

POST /api/input/mouse/move

移动鼠标到指定坐标。

请求体

{
  "x": 100,
  "y": 200
}

参数说明

参数	类型	必填	说明
x	number	是	目标 X 坐标
y	number	是	目标 Y 坐标

响应示例

成功响应（200）：

{
  "success": true
}

失败响应（400）：

{
  "success": false,
  "error": "Invalid coordinates"
}

---

POST /api/input/mouse/down

按下鼠标按键。

请求体

{
  "button": "left"
}

参数说明

参数	类型	必填	默认值	说明
button	string	否	left	鼠标按键：left、right、middle

响应示例

{
  "success": true
}

---

POST /api/input/mouse/up

释放鼠标按键。

请求体

{
  "button": "left"
}

参数说明

参数	类型	必填	默认值	说明
button	string	否	left	鼠标按键：left、right、middle

响应示例

{
  "success": true
}

---

POST /api/input/mouse/click

点击鼠标按键。

请求体

{
  "button": "left"
}

参数说明

参数	类型	必填	默认值	说明
button	string	否	left	鼠标按键：left、right、middle

响应示例

{
  "success": true
}

---

POST /api/input/mouse/wheel

鼠标滚轮滚动。

请求体

{
  "delta": 100
}

参数说明

参数	类型	必填	说明
delta	number	是	滚动量（正数向上，负数向下）

响应示例

{
  "success": true
}

---

键盘操作

POST /api/input/keyboard/down

按下键盘按键。

请求体

{
  "key": "a"
}

参数说明

参数	类型	必填	说明
key	string	是	按键名称（如 a、enter、ctrl、shift 等）

响应示例

{
  "success": true
}

---

POST /api/input/keyboard/up

释放键盘按键。

请求体

{
  "key": "a"
}

参数说明

参数	类型	必填	说明
key	string	是	按键名称

响应示例

{
  "success": true
}

---

POST /api/input/keyboard/press

按下并释放键盘按键（单击）。

请求体

{
  "key": "enter"
}

参数说明

参数	类型	必填	说明
key	string	是	按键名称

响应示例

{
  "success": true
}

---

POST /api/input/keyboard/type

输入文本字符串。

请求体

{
  "text": "Hello World"
}

参数说明

参数	类型	必填	说明
text	string	是	要输入的文本内容

响应示例

{
  "success": true
}

---

流媒体接口

GET /api/stream/info

获取流媒体信息。

响应示例

{
  "success": true,
  "stream": {
    "status": "running",
    "resolution": {
      "width": 1920,
      "height": 1080
    },
    "fps": 30,
    "bitrate": 2000,
    "gop": 60,
    "encoder": "libx264"
  }
}

字段说明

字段	类型	说明
status	string	流状态：running 或 stopped
resolution	object	屏幕分辨率
fps	number	帧率
bitrate	number	比特率（kbps）
gop	number	GOP 大小
encoder	string	编码器名称

---

POST /api/stream/start

启动流媒体。

响应示例

{
  "success": true,
  "message": "Stream started"
}

已运行时响应：

{
  "success": true,
  "message": "Stream is already running"
}

---

POST /api/stream/stop

停止流媒体。

响应示例

{
  "success": true,
  "message": "Stream stopped"
}

未运行时响应：

{
  "success": true,
  "message": "Stream is not running"
}

---

文件传输接口

GET /api/files

获取文件列表。

响应示例

{
  "files": [
    {
      "name": "example.txt",
      "size": 1024,
      "modifiedTime": "2024-01-01T12:00:00.000Z"
    }
  ]
}

---

GET /api/files/browse

浏览目录内容。

查询参数

参数	类型	必填	说明
path	string	否	目录路径（默认为根目录）

请求示例

GET /api/files/browse?path=documents

响应示例

{
  "path": "documents",
  "directories": ["folder1", "folder2"],
  "files": [
    {
      "name": "file1.txt",
      "size": 1024,
      "modifiedTime": "2024-01-01T12:00:00.000Z"
    }
  ]
}

---

POST /api/files/upload/start

开始上传会话（分块上传第一步）。

请求体

{
  "filename": "example.zip",
  "totalChunks": 10,
  "fileSize": 52428800
}

参数说明

参数	类型	必填	说明
filename	string	是	文件名
totalChunks	number	是	总分块数
fileSize	number	是	文件总大小（字节）

响应示例

{
  "fileId": "a1b2c3d4e5f6g7h8",
  "chunkSize": 5242880,
  "message": "Upload session started"
}

---

POST /api/files/upload/chunk

上传文件分块（分块上传第二步）。

请求体

Content-Type: multipart/form-data

字段	类型	说明
fileId	string	上传会话 ID
chunkIndex	number	分块索引（从 0 开始）
chunk	file	分块数据

响应示例

{
  "success": true,
  "chunkIndex": 0
}

---

POST /api/files/upload/merge

合并文件分块（分块上传第三步）。

请求体

{
  "fileId": "a1b2c3d4e5f6g7h8",
  "totalChunks": 10,
  "filename": "example.zip"
}

参数说明

参数	类型	必填	说明
fileId	string	是	上传会话 ID
totalChunks	number	是	总分块数
filename	string	是	最终文件名

响应示例

{
  "success": true,
  "filename": "example.zip"
}

---

GET /api/files/:filename

下载文件。

路径参数

参数	类型	说明
filename	string	文件名

请求头

支持 Range 请求，可用于断点续传：

Range: bytes=0-1023

响应示例

成功响应（200 或 206）：

• Content-Type: application/octet-stream
• Accept-Ranges: bytes
• Content-Length: 文件大小
• Content-Range: 范围（仅 206 响应）

失败响应（404）：

{
  "error": "File not found"
}

---

DELETE /api/files/:filename

删除文件。

路径参数

参数	类型	说明
filename	string	文件名

响应示例

成功响应（200）：

{
  "success": true
}

失败响应（404）：

{
  "error": "File not found"
}

---

WebSocket 消息类型

客户端发送的消息类型

消息类型	说明	数据格式
mouseMove	鼠标移动	{ x: number, y: number }
mouseDown	鼠标按下	{ button: 'left' | 'right' | 'middle' }
mouseUp	鼠标释放	{ button: 'left' | 'right' | 'middle' }
mouseWheel	鼠标滚轮	{ delta: number }
keyDown	键盘按下	{ key: string }
keyUp	键盘释放	{ key: string }
clipboardGet	获取剪贴板内容	无额外数据
clipboardSet	设置剪贴板内容	{ content: string }

服务端发送的消息类型

消息类型	说明	数据格式
screenInfo	屏幕信息	{ width: number, height: number }
clipboardData	剪贴板数据	{ content: string }
clipboardResult	剪贴板操作结果	{ success: boolean }
clipboardTooLarge	剪贴板数据过大	{ message: string }

消息格式示例

客户端发送鼠标移动：

{
  "type": "mouseMove",
  "data": {
    "x": 100,
    "y": 200
  }
}

客户端发送键盘按键：

{
  "type": "keyDown",
  "data": {
    "key": "ctrl"
  }
}

服务端发送屏幕信息：

{
  "type": "screenInfo",
  "data": {
    "width": 1920,
    "height": 1080
  }
}

客户端请求剪贴板：

{
  "type": "clipboardGet"
}

服务端返回剪贴板数据：

{
  "type": "clipboardData",
  "data": {
    "content": "复制的文本内容"
  }
}

---

错误响应格式

所有接口在发生错误时返回统一的错误格式：

{
  "success": false,
  "error": "错误描述信息"
}

常见 HTTP 状态码：

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（Token 无效或过期）
404	资源不存在
500	服务器内部错误