从零构建 RustDesk：跨平台远程桌面应用的依赖、编译与 Docker 构建全解析

本篇指南基于 RustDesk 仓库的波兰语版项目文档 docs/README-PL.md 展开，系统讲解如何为 RustDesk 搭建完整的本地开发环境：包括 sciter GUI 引擎与 vcpkg 视频编码依赖的安装、四大 Linux 发行版（Ubuntu/openSUSE/Fedora/Arch）的编译流程，以及基于容器化构建镜像的 Docker 编译方案。读完本文，你将能够独立完成 RustDesk 的源码构建，并通过 Docker 在隔离环境中稳定复现 release 构建。

一、项目定位与构建前须知

RustDesk 是一个多平台远程桌面软件，使用 Rust 编写，设计上以"部署简单、安全、数据完全由用户自控"为目标：启动即用，无需复杂配置，既可以使用公共中继/注册服务器，也可以自建服务器或自行实现服务端。

从当前仓库的工程文件可以直接确认几个构建事实：

• 主包名为 rustdesk，当前版本 1.4.9，要求 Rust 工具链版本不低于 1.75，默认可执行目标为 rustdesk（见 Cargo.toml 的 [package] 段）；
• 除可执行程序外，工程还编译出一个名为 librustdesk 的库（cdylib/staticlib/rlib）以及两个辅助二进制 naming（src/naming.rs）与 service（src/service.rs），其中 service 对应文档结构中提到的后台服务形态；
• Linux 桌面端依赖 libxdo、libpulse、dbus、gtk 等系统库（见 Cargo.toml 中 [target.'cfg(target_os = "linux")'.dependencies] 段），这正是后文各发行版安装包列表存在的根本原因。

1.1 sciter：桌面端 GUI 引擎

桌面版 RustDesk 使用 sciter 库作为 GUI 渲染引擎（src/ui 目录下的 .tis 脚本与 .html 页面即运行在该引擎之上）。sciter 需要单独下载并放置在可执行文件旁边：

平台	所需文件
Windows	sciter.dll
Linux	libsciter-gtk.so
macOS	libsciter.dylib

在源码层面，Cargo.toml 对非移动端目标引入了 sciter-rs 绑定库，编译后的二进制在运行时按可执行文件同目录查找 sciter 动态库——这就是 Docker 入口脚本要把 libsciter-gtk.so 拷贝到 target/debug 或 target/release 的原因。

二、基础编译步骤（所有平台通用）

按 docs/README-PL.md 中 "Podstawowe kroki do kompilacji"（基础编译步骤）一节的顺序，通用流程为三步：

1. 准备 Rust 开发环境（rustup）与 C++ 编译工具链；
2. 安装 vcpkg 并正确设置环境变量 VCPKG_ROOT，然后安装四个核心多媒体依赖：
   • Windows：vcpkg install libvpx:x64-windows-static libyuv:x64-windows-static opus:x64-windows-static aom:x64-windows-static
   • Linux / macOS：vcpkg install libvpx libyuv opus aom
3. 运行 cargo run 启动应用。

2.1 这四个依赖是干什么的

这四个包对应 RustDesk 的音视频编码链路，可以从仓库的 vcpkg 清单 vcpkg.json 中得到印证——除 libvpx（VP8/VP9）、libyuv（YUV 色彩空间转换）、opus（音频编码）、aom（AV1）外，清单还声明了 libjpeg-turbo（JPEG 图片编码）、mfx-dispatch 与 ffmpeg（硬件编码加速，仅在 hwcodec 特性开启时参与构建，对应 Cargo.toml 中的 hwcodec、vram、mediacodec、drm 等特性开关）。清单中的 overlay-ports 指向 res/vcpkg 目录，其中存放了项目对 aom、ffmpeg、libvpx、opus 等包的定制补丁与端口定义，说明构建方对上游包做了针对性修改以保证静态链接可用。

2.2 程序入口与"server + UI"双角色

cargo run 启动后，入口逻辑在 src/main.rs：桌面端路径下先执行 core_main()（解析命令行、初始化全局状态），随后进入 ui::start(args) 启动 sciter GUI；而移动端/Flutter 路径下 main() 只做连通性自检（test_rendezvous_server、test_nat_type）。这也解释了为什么同一份源码既能跑前台 GUI，也能以后台服务方式运行被控端。

三、Linux 编译详解

3.1 各发行版系统依赖

不同发行版的包名不同，但覆盖的能力域一致：C/C++ 工具链、git/curl/wget 网络工具、nasm/yasm 汇编器（libvpx/aom 需要）、GTK3、clang、X11 扩展开发库（xcb-randr/xfixes/shape/xdo）、音频库（ALSA/PulseAudio）、cmake。以下四段命令完整继承自 docs/README-PL.md：

Ubuntu 18 / Debian 10

sudo apt install -y g++ gcc git curl wget nasm yasm libgtk-3-dev clang libxcb-randr0-dev libxdo-dev libxfixes-dev libxcb-shape0-dev libxcb-xfixes0-dev libasound2-dev libpulse-dev cmake

openSUSE Tumbleweed

sudo zypper install gcc-c++ git curl wget nasm yasm gcc gtk3-devel clang libxcb-devel libXfixes-devel cmake alsa-lib-devel gstreamer-devel gstreamer-plugins-base-devel xdotool-devel

Fedora 28 / CentOS 8

sudo yum -y install gcc-c++ git curl wget nasm yasm gcc gtk3-devel clang libxcb-devel libxdo-devel libXfixes-devel pulseaudio-libs-devel cmake alsa-lib-devel

Arch / Manjaro

sudo pacman -Syu --needed unzip git cmake gcc curl wget yasm nasm zip make pkg-config clang gtk3 xdotool libxcb libxfixes alsa-lib pipewire

这些包与 Dockerfile 中的 apt install 列表基本一一对应（Docker 方案基于 debian:bullseye-slim，额外加装了 libssl-dev、libgstreamer1.0-dev 与 ninja-build，并手动安装了 CMake 3.30.6），可以互为对照验证依赖清单的完整性。

3.2 安装并配置 vcpkg

git clone https://github.com/microsoft/vcpkg
cd vcpkg
git checkout 2023.04.15
cd ..
vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=$HOME/vcpkg
vcpkg/vcpkg install libvpx libyuv opus aom

注意两处要点：

• 文档锁定 vcpkg 到 2023.04.15 这个 tag，Dockerfile 同样以 git clone --branch 2023.04.15 --depth=1 的方式固定版本，避免上游包定义变化导致构建不可复现；
• VCPKG_ROOT 必须指向 vcpkg 根目录，cargo 构建脚本在链接期依赖该变量定位已安装的二进制库。

3.3 Fedora 的 libvpx 修补

Fedora 环境下 vcpkg 构建 libvpx 需要手动补加位置无关代码（PIC）标志，原文档给出的操作是：

cd vcpkg/buildtrees/libvpx/src
cd *
./configure
sed -i 's/CFLAGS+=-I/CFLAGS+=-fPIC -I/g' Makefile
sed -i 's/CXXFLAGS+=-I/CXXFLAGS+=-fPIC -I/g' Makefile
make
cp libvpx.a $HOME/vcpkg/installed/x64-linux/lib/
cd

原理是：RustDesk 最终生成的是动态链接的共享对象场景，而 libvpx 默认的 Makefile 未开启 -fPIC，链接 libvpx.a 时会报 R_X86_64 重定位错误。修改 CFLAGS/CXXFLAGS 后重新编译并覆盖 vcpkg 安装目录下的静态库即可。

3.4 完整编译流程

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env
git clone https://github.com/rustdesk/rustdesk
cd rustdesk
mkdir -p target/debug
wget https://raw.githubusercontent.com/c-smile/sciter-sdk/master/bin.lnx/x64/libsciter-gtk.so
mv libsciter-gtk.so target/debug
cargo run

关键细节：libsciter-gtk.so 必须放进 target/debug（对应 Cargo.toml 中 default-run = "rustdesk" 的调试构建输出目录），否则运行时找不到 GUI 引擎动态库。

四、使用 Docker 编译

对于希望隔离环境、避免污染宿主机的开发者，仓库提供了容器化构建方案，由 Dockerfile 与 entrypoint.sh 两部分协作完成。

4.1 构建构建器镜像

git clone https://github.com/rustdesk/rustdesk
cd rustdesk
docker build -t "rustdesk-builder" .

该 Dockerfile 预装了全部系统依赖、CMake 3.30.6、固定版本的 vcpkg 及其四个多媒体包、sciter 动态库，并以非 root 用户 user 安装 rustup 工具链。

4.2 运行编译

docker run --rm -it -v $PWD:/home/user/rustdesk -v rustdesk-git-cache:/home/user/.cargo/git -v rustdesk-registry-cache:/home/user/.cargo/registry -e PUID="$(id -u)" -e PGID="$(id -g)" rustdesk-builder

参数含义逐一对应：

• -v $PWD:/home/user/rustdesk：把宿主机仓库目录挂载进容器，编译产物直接落回本机；
• 两个 cargo 缓存卷（rustdesk-git-cache、rustdesk-registry-cache）持久化 git 依赖与 crates 注册表缓存——首次构建较慢，之后因缓存命中显著加快；
• PUID/PGID 传入宿主机 uid/gid，保证容器内生成的文件归属正确；
• 如需构建 release 版本，在上述命令末尾追加 --release 即可。

4.3 入口脚本做了什么

entrypoint.sh 的参数解析逻辑值得细看：它遍历 docker run 传入的参数，识别出 --release（设置 release 标志）与 --target（自动 rustup target add <值>），其余参数原样透传给最终的 VCPKG_ROOT=/vcpkg cargo build --locked 命令；同时无论 debug 还是 release，都会确保 libsciter-gtk.so 拷贝到对应 target/{debug,release} 目录。因此 cargo build --locked 意味着严格遵循 Cargo.lock 锁定版本，保证可复现构建。

4.4 运行编译产物

target/debug/rustdesk      # debug 构建
target/release/rustdesk   # release 构建

两条注意事项（原文档明确强调）：

1. 务必在仓库根目录运行可执行文件，否则应用可能找不到所需资源文件；
2. 该 Docker 方式目前不支持 install、run 等 cargo 子命令——因为那会在容器内部执行安装/运行，而非宿主机上。

五、源码目录结构：读懂文档中列出的核心模块

docs/README-PL.md 的 "Struktura plików"（文件结构）一节列出了八个核心模块，下面结合仓库实际内容逐一说明，可作为编译后阅读源码的路线图：

路径	职责（文档描述 + 源码印证）
libs/hbb_common	公共基础库：视频编解码封装、配置系统、TCP/UDP 连接处理、protobuf 定义、文件传输等通用工具。RustDesk 的 Config、RENDEZVOUS_PORT 等配置常量即出自该库的 config 模块（见 src/rendezvous_mediator.rs 顶部的 use hbb_common::config 引用）
libs/scrap	屏幕采集。libs/scrap/src/lib.rs 按编译目标条件编译多个后端：quartz（macOS）、x11、wayland（feature 开关）、dxgi（Windows）、android，common 子目录再细分 aom/vpx/wayland/x11/drm 等实现
libs/enigo	跨平台键鼠注入。目录划分为 linux（含 xdo.rs，对应上文安装的 xdotool 开发库）、macos、win 三套平台实现
src/ui	sciter GUI 页面：index.tis（主界面）、cm.tis（连接管理器）、remote.tis（远程会话工具栏）等，以及配套的 .css/.html 资源
src/server	被控端服务：display_service.rs（视频）、audio_service.rs（音频）、input_service.rs（输入）、clipboard_service.rs（剪贴板）、connection.rs（会话连接管理），与文档"audio/clipboard/input/video 及网络"的描述一致
src/client.rs	客户端：发起直连（TCP 探测成功后直接建立点对点连接）
src/rendezvous_mediator.rs	与 rustdesk-server 的中继/注册通信：维护心跳、等待直连或中转连接，是"先直连、失败再中转"策略的实现核心
src/platform	平台特定代码：linux.rs、macos.rs/macos.mm、windows.rs/windows.cc、macOS 权限脚本等
flutter	Flutter 端代码，覆盖移动端（Android/iOS）与桌面新版 UI，lib 下按 mobile/desktop/web 划分页面，android/ios/windows/linux 为各平台宿主工程

从源码结构看，这套模块划分与 Cargo.toml 中 [workspace] 声明的成员（libs/scrap、libs/hbb_common、libs/enigo、libs/clipboard、libs/virtual_display、libs/portable、libs/remote_printer）相吻合——其中 clipboard、virtual_display、remote_printer 是文档发布后新增的工作区成员，可作为补充参考。

六、构建排错速查

综合上文，构建失败时可按以下顺序自查：

1. 链接 libvpx.a 报重定位错误（Fedora 常见）→ 执行 3.3 节的 -fPIC 修补；
2. 运行时提示缺少 GUI 或界面不显示 → 确认 libsciter-gtk.so（或对应平台的 sciter 库）位于 target/debug 或 target/release 下；
3. 找不到 vcpkg 包 → 检查 VCPKG_ROOT 是否指向 vcpkg 根目录，且已执行过四个包的 install；
4. Docker 方式下 cargo 子命令行为异常 → 该方式仅等价于 cargo build，不支持 install/run，产物需在宿主机仓库根目录手动运行；
5. 依赖版本漂移导致构建失败 → 保持 vcpkg 固定在 2023.04.15、cargo 使用 --locked（Docker 入口已默认启用），不要随意升级工具链，最低要求 Rust 1.75。

小结

本文完整覆盖了 docs/README-PL.md 的全部技术要素——sciter 依赖说明、通用三步编译法、四个 Linux 发行版的系统依赖、vcpkg 安装与 Fedora 修补、Docker 容器化构建，以及八模块源码结构——并以当前仓库的 Cargo.toml、vcpkg.json、Dockerfile 与 entrypoint.sh 作为实现层证据加以扩充。掌握这套流程后，无论是本地开发调试还是 CI 化的可复现构建，都可以稳定地在任意主流 Linux 发行版或容器环境中完成 RustDesk 的编译与运行。