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

2025-06-26 23:08:03作者：蔡丛锟

项目概述

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

MQTT通信基础

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

认证机制详解

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

桌面端认证：
- 客户端ID必须以"desktop:"开头
- 用户名必须为桌面ID
- 密码必须为桌面密钥
- 采用预共享密钥(PSK)认证方式
用户端认证：
- 客户端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信令交互

Offer发送：
- 主题：desktops/{desktop-id}/session/{session-id}/webrtc-offer
- 内容：SDP Offer（UTF-8编码）
Answer响应：
- 主题：desktops/{desktop-id}/session/{session-id}/webrtc-answer
- 内容：SDP Answer（UTF-8编码）
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"  // 固定协议版本
});