RustDesk 从源码构建完全指南：vcpkg 依赖、Linux/Docker 编译与源码结构解析

本文以 RustDesk 仓库的官方 README（土耳其语版 docs/README-TR.md）为主体，系统讲解如何从零开始编译这个用 Rust 编写的开源远程桌面应用：涵盖 GUI 依赖（Sciter/Flutter）与 vcpkg 编解码库（libvpx、libyuv、opus、aom）的准备、Ubuntu/openSUSE/Fedora/Arch 四大发行版的完整构建命令、Fedora 下的 libvpx 修复补丁、Docker 容器化构建流程，以及仓库核心目录（hbb_common、scrap、enigo、clipboard、server、rendezvous_mediator 等）的职责解析。读完本文，你能够在任意主流 Linux 发行版或 Docker 环境中成功产出 target/debug/rustdesk 或 target/release/rustdesk 可执行文件，并理解每个依赖项在编译链中的作用。

一、项目定位与使用边界声明

RustDesk 是一个用 Rust 编写的远程桌面解决方案。它开箱即用、无需任何配置即可连接，数据完全由用户自持。你可以直接使用官方的 rendezvous/relay 服务器，也可以自建服务器，甚至自行编写 rendezvous/relay 服务端（参见仓库中 docs/README-TR.md 开头的介绍段落）。

官方 README 在醒目位置保留了误用声明（misuse disclaimer）：开发者不认可也不支持任何不道德或非法用途，未经授权的访问、控制或侵犯隐私等行为严格违反使用规范，作者不对应用的任何滥用承担责任（见 docs/README-TR.md 第 14~16 行的 > [!Dikkat] 区块）。

当前仓库的版本信息可以从 Cargo.toml 中确认：包版本为 1.4.9，Rust 版本要求 rust-version = "1.75"，默认运行目标为 rustdesk 二进制，同时还有一个 service 子二进制（src/service.rs）用于系统服务模式。

二、GUI 框架依赖：Sciter 与 Flutter

桌面版 GUI 有两个选择（见 docs/README-TR.md 的 "Gereksinimler" 一节，与英文 README.md 的 "Dependencies" 一节一致）：

• Sciter（已被标记为 deprecated/待移除）：上手更容易，因此 README 中的本地构建教程只针对 Sciter 编写；
• Flutter：当前主力 GUI，其构建方式参考仓库 CI 配置（英文 README 指向 flutter-build workflow）。

Sciter 动态库需要自行下载并放入构建产物目录：

平台	库文件
Windows	sciter.dll（sciter-sdk 的 bin.win/x64）
Linux	libsciter-gtk.so（sciter-sdk 的 bin.lnx/x64）
macOS	libsciter.dylib（sciter-sdk 的 bin.osx）

从 Cargo.toml 的依赖声明可以印证这套 GUI 架构：sciter-rs（rust-sciter 的 dyn 分支）仅对 cfg(not(any(target_os = "android", target_os = "ios"))) 的目标启用，即只在桌面平台加载 Sciter；而 Flutter 侧则由可选 feature flutter = ["flutter_rust_bridge"]（flutter_rust_bridge = "=1.80"）驱动，与 flutter/lib 目录下的 Dart 代码通过 FFI（src/flutter_ffi.rs）衔接。这正是 README 中"Sciter 教程 + Flutter 看 CI"两套并存的源码依据。

三、核心构建步骤（Raw Steps to Build）

docs/README-TR.md 的 "Temel Derleme Adımları" 一节给出了三步式最小构建流程，这里保持原文的完整操作性并补充参数说明：

1. 准备 Rust 开发环境与 C++ 构建环境。C++ 环境是必须的，因为编解码库（见下文 vcpkg 部分）需要原生编译工具链；Rust 侧最低要求为 1.75 版本（Cargo.toml rust-version）。
2. 安装 vcpkg 并正确设置 VCPKG_ROOT 环境变量，然后安装四个编解码库：
   • Windows：vcpkg install libvpx:x64-windows-static libyuv:x64-windows-static opus:x64-windows-static aom:x64-windows-static（Windows 下必须使用 -static triplet 变体）；
   • Linux/macOS：vcpkg install libvpx libyuv opus aom。
3. 运行 cargo run 完成编译并启动。

这四个库各自承担不同的数据流：libvpx 提供 VP8/VP9 视频编解码，libyuv 负责像素格式/色彩空间转换，aom 提供 AV1，opus 提供音频编码——对应远程桌面的视频帧与音频两条通道。仓库根目录的 vcpkg.json 进一步说明：vcpkg 采用 manifest 模式（内置 registry baseline 9e593bb18ea69cc5095e012465dcd675a822ed0d），并启用了 ./res/vcpkg 作为 overlay-ports、./res/vcpkg-triplets 作为 overlay-triplets；其中 res/vcpkg 下带有大量补丁（aom、libvpx、opus 等 port 的 diff 文件），res/vcpkg-triplets 则提供 x64-android.cmake 等 Android 交叉编译 triplet。

需要特别说明的一个前置细节：libs/hbb_common 是 git 子模块（.gitmodules 指向 https://github.com/rustdesk/hbb_common），因此克隆仓库时应使用 git clone --recurse-submodules（英文 README.md 的 Docker 小节即如此要求）。否则构建会因找不到 hbb_common crate 而失败。

四、Linux 各发行版构建指南

docs/README-TR.md 的 "Linux Üzerinde Derleme Nasıl Yapılır" 一节按发行版给出了完整的系统依赖安装命令，以下逐一保留：

Ubuntu 18（对应 Debian 10）

sudo apt install -y zip 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 make \
        libclang-dev ninja-build libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

这些依赖可以对照 Cargo.toml 中的 Linux 目标依赖理解：libxdo-dev/libxfixes-dev/libxcb-*-dev 服务于屏幕抓取与输入模拟（libxdo-sys 及 libs/scrap 的 X11 后端），libasound2-dev/libpulse-dev 服务于音频采集（psimple、pulse crate），libgstreamer1.0-dev 用于 Linux 的流媒体解码路径，nasm/yasm 是 libvpx/aom 汇编代码的必备汇编器。

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

安装 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

注意这里固定 checkout 到 2023.04.15 提交——这不是随意选择：仓库的 Docker 构建（Dockerfile 第 42 行）同样以 --branch 2023.04.15 安装 vcpkg，保证本地构建与 CI 环境一致。VCPKG_ROOT 指向 vcpkg 根目录后，[build-dependencies] 中的 cc crate 才能按 vcpkg 的库布局找到静态库。

修复 libvpx（Fedora 专用）

在 Fedora 上构建 libvpx 时需要手工给 Makefile 追加 -fPIC 标志，否则静态库无法链接进共享构建：

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

这段流程的本质是：libvpx 自带的 configure 在 Fedora 的默认编译环境下不产生位置无关代码（PIC），而 RustDesk 以 cdylib 等动态库形态输出（Cargo.toml 的 [lib] crate-type 包含 cdylib），静态链接其中的汇编/静态对象时必须全部是 PIC 代码，因此用 sed 在 CFLAGS/CXXFLAGS 前注入 -fPIC 后重新 make，并把产物 libvpx.a 复制回 vcpkg 的 installed/x64-linux/lib 覆盖。

五、完整 Linux 构建流水线

文档最后给出的 "Derleme"（构建）小节，把以上步骤串成一条可复制的完整命令链：

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
VCPKG_ROOT=$HOME/vcpkg cargo run

几个关键点的解释：

• Sciter 库放入 target/debug/：cargo run 在 debug 模式下运行时，可执行文件与 libsciter-gtk.so 同目录，动态加载器即可找到它。Docker 版 entrypoint.sh 也做了完全相同的处理：test -f target/debug/libsciter-gtk.so || cp "$HOME"/libsciter-gtk.so target/debug/。
• VCPKG_ROOT=$HOME/vcpkg：作为单次命令的环境变量前缀注入，cc 构建依赖据此定位 vcpkg 安装的编解码库。
• 英文版 README.md 在同一节使用 git clone --recurse-submodules，而土耳其语版此处省略了该参数；由于 libs/hbb_common 是子模块，实际执行时建议保留 --recurse-submodules。

另外从 Cargo.toml 可以看到与构建相关的 feature 开关，按需可用于 cargo run/build --features ...：hwcodec（启用 scrap 的硬件编码）、vram（GPU 显存直捕）、drm/drm-wake（Linux DRM 捕获，drm-wake 在 drm 之上额外加入显示唤醒代码）、flutter、linux-pkg-config、screencapturekit 等。release 构建则受 [profile.release] 优化配置约束（lto = true、codegen-units = 1、panic = 'abort'、strip = true），因此 --release 产物更小但编译更慢。

六、Docker 方式构建

docs/README-TR.md 的 "Docker ile Derleme Nasıl Yapılır" 一节提供了一条不污染宿主环境的构建路径：

第一步：克隆仓库并构建构建镜像

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

第二步：每次需要构建时运行构建容器

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：把仓库根目录挂进容器，源码与产物双向可见；
• -v rustdesk-git-cache:...cargo/git、-v rustdesk-registry-cache:...cargo/registry：两个具名卷分别缓存 git 依赖（本仓库大量依赖来自 git 分支，如 kcp-sys、magnum-opus、flutter_rust_bridge 等）与 crates.io registry，是第二次构建显著提速的关键；
• -e PUID/-e PGID：把宿主机用户 UID/GID 传入容器，使产物文件权限归宿主用户所有（Dockerfile 中容器内置 user 账户并放通了 sudoers）。

首次构建因需下载并缓存全部依赖会比较久，后续构建明显更快。若需要给构建命令传参数，直接追加在命令末尾即可，例如构建优化版本就追加 --release。

这套机制的容器侧实现就是仓库根目录的 Dockerfile 与 entrypoint.sh：

• Dockerfile 基于 debian:bullseye-slim，安装 gcc/g++、nasm/yasm、gtk3、xcb 全家桶、gstreamer、clang 等系统依赖（与第四节的 apt 清单同源），从源码编译安装 CMake 3.30.6，以 2023.04.15 分支克隆 vcpkg 并预装 libvpx libyuv opus aom，最后用 rustup 安装 Rust 工具链；
• entrypoint.sh 进入 $HOME/rustdesk，解析命令行：遇到 --release 就 mkdir -p target/release 并把 Sciter 库复制到 release 目录、置位 release=1，遇到 --target 会自动 rustup target add 以支持交叉编译目标；最终统一执行 VCPKG_ROOT=/vcpkg cargo build --locked $argv。--locked 保证依赖版本与 Cargo.lock 完全一致，可复现性强。

构建产物在宿主机的仓库根目录下直接可执行（务必在 RustDesk 仓库根目录运行，否则应用可能找不到所需资源）：

target/debug/rustdesk

或 release 版本：

target/release/rustdesk

文档还明确提醒：install、run 等其他 cargo 子命令目前不能通过该 Docker 方式使用——它们会在容器内部安装/运行程序，而不是宿主机上。

七、仓库源码结构（File Structure）

docs/README-TR.md 的 "Dosya Yapısı" 一节给出了模块级目录职责表，全部路径均已核对存在于本仓库：

路径	职责（对照源码确认）
libs/hbb_common	视频编解码封装、配置、tcp/udp 网络封装、protobuf 协议、文件传输用的 fs 函数及其他通用工具（git 子模块）
libs/scrap	屏幕抓取。源码按平台分目录：libs/scrap/src/wayland、libs/scrap/src/x11、libs/scrap/src/dxgi、libs/scrap/src/quartz、libs/scrap/src/android 等
libs/enigo	平台特定的键盘/鼠标控制。实现分 libs/enigo/src/linux、libs/enigo/src/macos、libs/enigo/src/win
libs/clipboard	Windows/Linux/macOS 的复制粘贴（含文件）实现，平台代码见 libs/clipboard/src/platform
src/ui	旧版 Sciter UI（已标记 deprecated），包含 index/remote/file_transfer 等 .tis 脚本与 HTML/CSS
src/server	服务端各服务：video_service.rs、audio_service.rs、input_service.rs、clipboard_service.rs、connection.rs 等
src/client.rs	发起对等（peer）连接的客户端入口
src/rendezvous_mediator.rs	与 rustdesk-server 通信，等待远端直连（TCP 打洞）或中继连接
src/platform	平台特定代码，含 Windows（src/platform/windows.rs）、macOS（src/platform/macos.rs）、Linux（src/platform/linux.rs）及权限脚本 src/platform/privileges_scripts
flutter	桌面与移动端共用的 Flutter 代码，Dart 入口在 flutter/lib/main.dart

从 Cargo.toml 的 [workspace] 定义可以看到完整的本地 crate 成员清单：libs/scrap、libs/hbb_common、libs/enigo、libs/clipboard、libs/virtual_display（及其 dylib）、libs/portable、libs/remote_printer；其中 libs/portable 提供无安装便携模式（libs/portable/src/main.rs），libs/remote_printer 则是 Windows 远程打印驱动组件。

八、构建检查清单与常见问题

把全文要点浓缩为一份可执行检查清单：

1. Rust 工具链 ≥ 1.75（rust-version 约束）+ C++ 工具链（gcc/g++、clang、cmake、nasm/yasm）；
2. vcpkg 固定在 2023.04.15，VCPKG_ROOT 指向其根目录；vcpkg install libvpx libyuv opus aom 四个库缺一不可；
3. 系统库按发行版安装（第二节四个发行版命令之一）；
4. Sciter 动态库放入 target/debug（debug 运行）或由 entrypoint 自动放入对应 profile 目录；
5. 仓库克隆带 --recurse-submodules，确保 libs/hbb_common 就绪；
6. Fedora 用户额外执行 libvpx 的 -fPIC 修复流程；
7. 运行 VCPKG_ROOT=$HOME/vcpkg cargo run（或走 Docker：docker build -t rustdesk-builder . + docker run ... rustdesk-builder）；
8. 产物位置：target/debug/rustdesk 或 target/release/rustdesk，须在仓库根目录执行。

常见失败点：忘记导出 VCPKG_ROOT 导致找不到编解码库；未初始化 hbb_common 子模块导致编译报错；Fedora 下链接 libvpx 报符号/重定位错误（需执行第五节的 Makefile 修补）；在非仓库根目录运行可执行文件导致资源加载失败。按照 docs/README-TR.md 与 Dockerfile、entrypoint.sh 的实际实现逐一比对，上述每一步都有明确的仓库内证据可查。