crossdesk/README.md

CrossDesk

[ English / 中文 ]

PC 客户端

Web 客户端

简介

CrossDesk 是一个轻量级的跨平台远程桌面软件，支持 Web 端控制远程设备。

CrossDesk 是 MiniRTC 实时音视频传输库的实验性应用。MiniRTC 是一个轻量级的跨平台实时音视频传输库。它具有网络透传（RFC5245），视频软硬编解码（H264/AV1），音频编解码（Opus），信令交互，网络拥塞控制，传输加密（SRTP）等基础能力。

系统要求

平台	最低版本
Windows	Windows 10 及以上 (64 位)
macOS	macOS Intel 15.0 及以上 ( 大于 14.0 小于 15.0 的版本可自行编译实现兼容 ) macOS Apple Silicon 14.0 及以上
Linux	Ubuntu 22.04 及以上 ( 低版本可自行编译实现兼容 )

使用

在菜单栏“对端ID”处输入远端桌面的ID，点击“→”即可发起远程连接。

如果远端桌面设置了连接密码，则本端需填写正确的连接密码才能成功发起远程连接。

发起连接前，可在设置中自定义配置项，如语言、视频编码格式等。

Web 客户端

浏览器访问 CrossDesk Web Client。 输入 远程设备 ID 与 密码，点击连接即可接入远程设备。如图，iOS Safari 远程控制 Win11：

如何编译

依赖：

• xmake
• cmake

Linux环境下需安装以下包：

sudo apt-get install -y software-properties-common git curl unzip build-essential libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev libxcb-shape0-dev libxcb-xkb-dev libxcb-xfixes0-dev libxfixes-dev libxv-dev libxtst-dev libasound2-dev libsndio-dev libxcb-shm0-dev libasound2-dev libpulse-dev

编译

git clone https://github.com/kunkundi/crossdesk.git

cd crossdesk

git submodule init 

git submodule update

xmake b -vy crossdesk

编译选项

--USE_CUDA=true/false: 启用 CUDA 硬件编解码，默认不启用
--CROSSDESK_VERSION=xxx: 指定 CrossDesk 的版本

# 示例
xmake f --CROSSDESK_VERSION=1.0.0 --USE_CUDA=true

运行

xmake r crossdesk

无 CUDA 环境下的开发支持

对于未安装 CUDA 环境的 Linux 开发者，如果希望编译后的成果物拥有硬件编解码能力，这里提供了预配置的 Ubuntu 22.04 Docker 镜像。该镜像内置必要的构建依赖，可在容器中开箱即用，无需额外配置即可直接编译项目。

进入容器，下载工程后执行：

export CUDA_PATH=/usr/local/cuda
export XMAKE_GLOBALDIR=/data

xmake f --USE_CUDA=true
xmake b --root -vy crossdesk

对于未安装 CUDA 环境的 Windows 开发者，执行下面的命令安装 CUDA 编译环境：

xmake require -vy "cuda 12.6.3"

安装完成后执行:

xmake require --info "cuda 12.6.3"

输出如下:

根据上述输出获取到 CUDA 的安装目录，即 installdir 指向的位置。将 CUDA_PATH 加入系统环境变量，或在终端中输入：

set CUDA_PATH=path_to_cuda_installdir

重新执行：

xmake f --USE_CUDA=true
xmake b -vy crossdesk

注意

运行时如果客户端状态栏显示 未连接服务器，请先在 CrossDesk 官方网站 安装客户端，以便在环境中安装所需的证书文件。

关于 Xmake

安装 Xmake

使用 curl：

curl -fsSL https://xmake.io/shget.text | bash

使用 wget：

wget https://xmake.io/shget.text -O - | bash

使用 powershell：

irm https://xmake.io/psget.text | iex

编译选项

# 切换编译模式
xmake f -m debug/release

# 可选编译参数
-r ：重新构建目标
-v ：显示详细的构建日志
-y ：自动确认提示

# 示例
xmake b -vy crossdesk

运行选项

# 使用调试模式运行
xmake r -d crossdesk

更多使用方法可参考 Xmake官方文档 。

自托管服务器

推荐使用Docker部署CrossDesk Server。

sudo docker run -d \
  --name crossdesk_server \
  --network host \
  -e EXTERNAL_IP=xxx.xxx.xxx.xxx \
  -e INTERNAL_IP=xxx.xxx.xxx.xxx \
  -e CROSSDESK_SERVER_PORT=xxxx \
  -e COTURN_PORT=xxxx \
  -e MIN_PORT=xxxxx \
  -e MAX_PORT=xxxxx \
  -v /var/lib/crossdesk:/var/lib/crossdesk \
  -v /var/log/crossdesk:/var/log/crossdesk \
  crossdesk/crossdesk-server:v1.1.2

上述命令中，用户需注意的参数如下：

参数

• EXTERNAL_IP：服务器公网 IP , 对应 CrossDesk 客户端自托管服务器配置中填写的服务器地址
• INTERNAL_IP：服务器内网 IP
• CROSSDESK_SERVER_PORT：自托管服务使用的端口，对应 CrossDesk 客户端自托管服务器配置中填写的服务器端口
• COTURN_PORT: COTURN 服务使用的端口, 对应 CrossDesk 客户端自托管服务器配置中填写的中继服务端口
• MIN_PORT/MAX_PORT：COTURN 服务使用的端口范围，例如：MIN_PORT=50000, MAX_PORT=60000，范围可根据客户端数量调整。
• -v /var/lib/crossdesk:/var/lib/crossdesk：持久化数据库和证书文件到宿主机
• -v /var/log/crossdesk:/var/log/crossdesk：持久化日志文件到宿主机

示例：

sudo docker run -d \
  --name crossdesk_server \
  --network host \
  -e EXTERNAL_IP=114.114.114.114 \
  -e INTERNAL_IP=10.0.0.1 \
  -e CROSSDESK_SERVER_PORT=9099 \
  -e COTURN_PORT=3478 \
  -e MIN_PORT=50000 \
  -e MAX_PORT=60000 \
  -v /var/lib/crossdesk:/var/lib/crossdesk \
  -v /var/log/crossdesk:/var/log/crossdesk \
  crossdesk/crossdesk-server:v1.1.3

注意：

• 服务器需开放端口：COTURN_PORT/udp，COTURN_PORT/tcp，MIN_PORT-MAX_PORT/udp，CROSSDESK_SERVER_PORT/tcp。
• 如果不挂载 volume，容器删除后数据会丢失
• 证书文件会在首次启动时自动生成并持久化到宿主机的 /var/lib/crossdesk/certs 路径下
• 数据库文件会自动创建并持久化到宿主机的 /var/lib/crossdesk/db/crossdesk-server.db 路径下
• 日志文件会自动创建并持久化到宿主机的 /var/log/crossdesk/ 路径下

权限注意：如果 Docker 自动创建的目录权限不足（属于 root），容器内用户无法写入，会导致：

• 证书生成失败，容器启动脚本会报错退出
• 数据库目录创建失败，程序会抛出异常并崩溃
• 日志目录创建失败，日志文件无法写入（但程序可能继续运行）

解决方案：在启动容器前手动设置权限：

sudo mkdir -p /var/lib/crossdesk /var/log/crossdesk
sudo chown -R $(id -u):$(id -g) /var/lib/crossdesk /var/log/crossdesk

证书文件

在宿主机的 /var/lib/crossdesk/certs 路径下可找到证书文件 crossdesk.cn_root.crt，下载到你的客户端主机，并在客户端的自托管服务器设置中选择相应的证书文件路径。

客户端

1. 点击右上角设置进入设置页面。
   
   
   

2. 点击点击自托管服务器配置。
   
   
   
   

3. 在证书文件路径选择框中找到 crossdesk.cn_root.crt 的存放路径，选中 crossdesk.cn_root.crt，点击确认。
   
   
   
   

4. 勾选使用自托管服务器配置，点击确认配置生效。
   
   
   
   

Web 客户端

详情见项目 CrossDesk Web Client。

常见问题

见 常见问题 。