Pod-Arcade项目API接口详解：MQTT与WebRTC深度解析

项目概述

Pod-Arcade是一个基于WebRTC技术的远程桌面交互系统，通过MQTT协议进行信令交互，实现低延迟的远程桌面控制体验。本文将深入解析该项目的API接口设计，帮助开发者理解其核心通信机制。

MQTT通信基础

Pod-Arcade采用MQTT协议作为核心通信机制，所有API交互都通过MQTT主题(Topic)实现。MQTT服务器与Web服务器运行在同一实例上，并支持WebSocket连接，这使得浏览器客户端可以直接建立连接。

认证机制详解

系统提供三种认证方式，适用于不同安全需求的场景：

1. 桌面端认证：

   • 客户端ID必须以"desktop:"开头
   • 用户名必须为桌面ID
   • 密码必须为桌面密钥
   • 采用预共享密钥(PSK)认证方式

2. 用户端认证：

   • 客户端ID必须以"user:"开头
   • 支持三种认证方式：
     • OIDC认证：使用OpenID Connect协议，需要从配置获取oidc_server和oidc_client_id
     • PSK认证：需要用户输入预共享密钥
     • 无认证：可直接连接（仅限低安全需求场景）

核心API接口解析

服务器级API

ICE服务器获取接口

主题：server/ice-servers

该接口返回可用于建立WebRTC连接的ICE服务器列表，包含以下字段：

• urls：服务器URL列表
• username：认证用户名（可选）
• credential：认证凭证（字符串或对象）
• credentialType：凭证类型（password或oauth）

桌面级API

桌面状态监控

主题：desktops/{desktop-id}/status

状态值：

• "online"：桌面在线
• "offline"：桌面离线

开发技巧：通过订阅desktops/+/status可以监控所有桌面状态。

桌面专属ICE服务器

主题：desktops/{desktop-id}/ice-servers

该接口返回桌面专属的ICE服务器配置，可与全局ICE服务器配合使用。

会话级API

会话状态监控

主题：desktops/{desktop-id}/session/{session-id}/status

状态值：

• "connecting"：正在连接
• "online"：已连接
• "offline"：已断开

WebRTC信令交互

1. Offer发送：

   • 主题：desktops/{desktop-id}/session/{session-id}/webrtc-offer
   • 内容：SDP Offer（UTF-8编码）

2. Answer响应：

   • 主题：desktops/{desktop-id}/session/{session-id}/webrtc-answer
   • 内容：SDP Answer（UTF-8编码）

3. ICE候选交换：

   • 主题：desktops/{desktop-id}/session/{session-id}/offer-ice-candidate
   • 主题：desktops/{desktop-id}/session/{session-id}/answer-ice-candidate
   • 内容：JSON格式的ICE候选信息

WebRTC数据通道详解

成功建立WebRTC连接后，系统会创建专用的数据通道用于输入事件传输。

输入通道配置

var inputChannel = peerConnection.createDataChannel("input", {
  id: 0,                  // 固定通道ID
  negotiated: true,       // 预协商通道
  ordered: true,          // 保证消息顺序
  protocol: "pod-arcade-input-v1"  // 固定协议版本
});

输入事件类型

1. 键盘输入 (0x01)

数据结构：

• 字节0：类型标识(0x01)
• 字节1：按键状态（位掩码）
  • Bit 0：按键状态
  • Bit 1：Shift键
  • Bit 2：Ctrl键
  • Bit 3：Alt键
  • Bit 4：Meta键
  • Bit 5：Caps Lock
• 字节2-3：键码（参考MDN标准）

2. 鼠标输入 (0x02)

数据结构：

• 字节0：类型标识(0x02)
• 字节1：按钮状态（位掩码）
  • Bit 0：左键
  • Bit 1：右键
  • Bit 2：中键
• 字节2-5：X轴速度（float32小端序）
• 字节6-9：Y轴速度（float32小端序）
• 字节10-13：X轴滚轮（float32小端序）
• 字节14-17：Y轴滚轮（float32小端序）

3. 触摸屏输入 (0x03)

数据结构：

• 字节0：类型标识(0x03)
• 字节1：事件类型
  • 0x00：触摸开始
  • 0x01：触摸结束
• 字节2-3：X坐标（uint16小端序）
• 字节4-5：Y坐标（uint16小端序）

4. 游戏手柄输入 (0x04)

数据结构：

• 字节0：类型标识(0x04)
• 字节1：手柄索引
• 字节2-3：按钮状态（位掩码）
  • 包含所有常见手柄按钮状态
• 字节4-23：各轴和触发器数据（float32小端序）

5. 手柄震动反馈 (0x05)

数据结构：

• 字节0：类型标识(0x05)
• 字节1：手柄索引
• 字节2-5：震动强度（0-1，float32小端序）
• 字节6-9：持续时间（毫秒，uint32小端序）

开发建议

1. 连接管理：合理利用MQTT的Last Will特性实现状态监控
2. ICE处理：合并使用服务器和桌面提供的ICE服务器列表
3. 输入优化：根据实际场景调整输入事件的发送频率
4. 错误处理：妥善处理WebRTC连接中断和重连场景

通过深入理解这些API接口，开发者可以更好地集成Pod-Arcade系统，或基于其协议开发兼容的客户端应用。