RustDesk Server 自托管部署完全指南:从源码编译到 Docker 密钥管理

原创2026-09-23 10:53:262,124 阅读
文章标签:后端网络通信认证鉴权

RustDesk Server 自托管部署完全指南:从源码编译到 Docker 密钥管理

本文以 RustDesk Server(rustdesk-server)官方 README(荷兰语版 README-NL.md)为骨架,完整覆盖自托管部署的核心链路:源码编译出 hbbs/hbbr/rustdesk-utils 三个可执行文件、两类 Docker 镜像(经典镜像与 S6-overlay 镜像)的拉取与运行、密钥对的生成与安全托管,以及 hbbs/hbbr 的全部 ENV 配置变量。读完本文,你将能够独立完成一套生产可用的 RustDesk 服务器部署,并理解每个配置项背后的源码实现逻辑。

一、三个核心可执行文件与源码编译

RustDesk Server 是免费开源的服务器程序(源码位于 src/ 目录),整个仓库由 Cargo workspace 组织,核心包定义在 Cargo.toml。手把手编译非常简单,只需一条命令:

cargo build --release

编译完成后,target/release 目录下会生成三个可执行文件,它们构成 RustDesk 自托管服务端的全部组件:

可执行文件 角色 说明
hbbs RustDesk ID/Rendezvous 服务器 负责客户端 ID 注册、信令与 NAT 穿透协调
hbbr RustDesk 中继(relay)服务器 负责无法直连时的流量中继转发
rustdesk-utils RustDesk CLI 工具 提供密钥对生成、密钥校验、服务器连通性诊断等命令

从 Cargo.toml 可以看到这三个二进制分别对应 src/main.rs(默认运行目标 hbbs)、src/hbbr.rs 与 src/utils.rs。编译时默认启用 release 优化(lto = true、codegen-units = 1、strip = true,见 Cargo.toml),因此产物体积更小、运行时性能更好。

hbbs 的命令行参数在 src/main.rs 中定义,可通过 -p/--port 指定监听端口(默认 21116)、-r/--relay-servers 指定默认中继服务器、-k/--key 指定密钥以限制客户端接入等;hbbr 则支持 -p/--port(默认 21117)与 -k/--key(见 src/hbbr.rs)。这些参数同样可以通过环境变量注入,详见本文第七节。

如果你打算基于 RustDesk 做二次开发,官方还提供了更简单的起步仓库 rustdesk-server-demo(README 原文推荐),比本仓库更适合作为开发起点;本文聚焦的是直接部署与运行。

二、经典 Docker 镜像:rustdesk/rustdesk-server

2.1 镜像构成与可用标签

经典镜像(classic image)在每次 GitHub release 时自动构建并发布,基于 ubuntu-20.04 构建,镜像内只包含最核心的两个二进制 hbbr 与 hbbs。其 Dockerfile 见 docker-classic/Dockerfile,从 scratch 起步,仅复制两个二进制到 /usr/bin 并将工作目录设为 /root。镜像发布在 Docker Hub,可用标签如下:

架构 image:tag
amd64 rustdesk/rustdesk-server:latest
arm64v8 rustdesk/rustdesk-server:latest-arm64v8

注意该镜像只内置 hbbr 和 hbbs,不包含 rustdesk-utils,也没有进程守护机制,因此需要分别启动两个容器来运行 hbbs 与 hbbr。

2.2 使用 host 网络直接运行

最直接的启动方式是使用 --net=host(容器与宿主机共享网络栈):

docker run --name hbbs --net=host -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbs -r <relay-server-ip[:port]>
docker run --name hbbr --net=host -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbr

其中 -v "$PWD/data:/root" 将宿主机当前目录下的 data 挂载到容器的 /root,用于持久化 hbbs 生成的密钥与数据库文件;hbbs -r 参数用于告知 hbbs 中继服务器的地址。

如果不用 --net=host,则必须显式做端口映射,但直接 P2P 连接将无法工作(NAT 穿透所需端口无法正确暴露)。

2.3 使用端口映射运行(非 host 网络)

对于无法使用 host 网络的场景(如 Docker Desktop、部分云主机),请使用端口映射方式:

docker run --name hbbs -p 21115:21115 -p 21116:21116 -p 21116:21116/udp -p 21118:21118 -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbs -r <relay-server-ip[:port]>
docker run --name hbbr -p 21117:21117 -p 21119:21119 -v "$PWD/data:/root" -d rustdesk/rustdesk-server:latest hbbr

各端口用途如下(与 src/utils.rs 中 doctor 命令的诊断口径一致):

端口 协议 服务 用途
21115 TCP hbbs NAT 类型测试
21116 TCP/UDP hbbs ID 注册与信令(主端口,UDP 用于穿透)
21117 TCP hbbr 中继服务主端口
21118 TCP hbbs WebSocket 端口
21119 TCP hbbr WebSocket 端口

relay-server-ip 指的是运行这些容器的服务器 IP(或 DNS 名称);可选的 port 参数仅在你为 hbbr 使用了非默认的 21117 端口时才需要显式指定,即写成 hbbs -r <ip>:<port> 的形式。

2.4 SELinux 系统注意事项

对启用 SELinux 的系统,把卷挂载路径 /root 改为 /root:z 即可让容器正常工作;或者通过添加 --security-opt label=disable 选项完全关闭 SELinux 容器隔离。

2.5 docker-compose 部署模板

仓库根目录的 docker-compose.yml 与 README 提供的模板完全一致,可直接复制使用:

version: '3'

networks:
  rustdesk-net:
    external: false

services:
  hbbs:
    container_name: hbbs
    ports:
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21118:21118
    image: rustdesk/rustdesk-server:latest
    command: hbbs -r rustdesk.example.com:21117
    volumes:
      - ./data:/root
    networks:
      - rustdesk-net
    depends_on:
      - hbbr
    restart: unless-stopped

  hbbr:
    container_name: hbbr
    ports:
      - 21117:21117
      - 21119:21119
    image: rustdesk/rustdesk-server:latest
    command: hbbr
    volumes:
      - ./data:/root
    networks:
      - rustdesk-net
    restart: unless-stopped

使用要点:

  • 修改 hbbs 服务中 command 一行的 rustdesk.example.com:21117,指向你自己的中继服务器(即监听 21117 端口的机器);
  • hbbr 的 command(hbbr)与 hbbs 的 command(hbbs -r ...)可按需调整;
  • depends_on: hbbr 保证 hbbs 先于 hbbr 完成容器编排依赖。

三、S6-overlay 镜像:rustdesk/rustdesk-server-s6

3.1 镜像构成与可用标签

S6-overlay 镜像基于 busybox:stable 构建,在经典镜像基础上额外加入了 S6-overlay:基础镜像为 busybox:stable,默认 S6-overlay 版本 3.2.0.0,通过 COPY rootfs / 将 s6 服务编排脚本一并打入镜像,并默认声明 RELAY=relay.example.com、ENCRYPTED_ONLY=0 两个环境变量。

镜像发布在 Docker Hub,可用标签覆盖多架构与多个版本线:

架构 版本 image:tag
multiarch latest rustdesk/rustdesk-server-s6:latest
amd64 latest rustdesk/rustdesk-server-s6:latest-amd64
i386 latest rustdesk/rustdesk-server-s6:latest-i386
arm64v8 latest rustdesk/rustdesk-server-s6:latest-arm64v8
armv7 latest rustdesk/rustdesk-server-s6:latest-armv7
multiarch 2 rustdesk/rustdesk-server-s6:2
amd64 2 rustdesk/rustdesk-server-s6:2-amd64
i386 2 rustdesk/rustdesk-server-s6:2-i386
arm64v8 2 rustdesk/rustdesk-server-s6:2-arm64v8
armv7 2 rustdesk/rustdesk-server-s6:2-armv7
multiarch 2.0.0 rustdesk/rustdesk-server-s6:2.0.0
amd64 2.0.0 rustdesk/rustdesk-server-s6:2.0.0-amd64
i386 2.0.0 rustdesk/rustdesk-server-s6:2.0.0-i386
arm64v8 2.0.0 rustdesk/rustdesk-server-s6:2.0.0-arm64v8
armv7 2.0.0 rustdesk/rustdesk-server-s6:2.0.0-armv7

官方强烈建议使用 multiarch 标签配合 major version(如 2)或 latest 标签,以获得架构自适应与滚动更新体验。

3.2 S6-overlay 的监督机制

S6-overlay 充当 supervisor,同时维持 hbbs 与 hbbr 两个进程的运行,因此使用这个镜像时无需像经典镜像那样启动两个独立容器。容器编排脚本位于 docker/rootfs/etc/s6-overlay/s6-rc.d/:

  • hbbs/run:进入 /data 工作目录,若 ENCRYPTED_ONLY=1 则附加 -k _ 参数,随后执行 /usr/bin/hbbs -r $RELAY $PARAMS;
  • hbbr/run:同样进入 /data,按 ENCRYPTED_ONLY 附加参数后执行 /usr/bin/hbbr $PARAMS。

镜像自带的 healthcheck.sh 通过 s6 的 s6-svstat 检查 hbbs、hbbr 两个服务目录的存活状态,配合 docker/Dockerfile 中的 HEALTHCHECK 指令每 10 秒检测一次。

3.3 启动方式

host 网络方式:

docker run --name rustdesk-server \
  --net=host \
  -e "RELAY=rustdeskrelay.example.com" \
  -e "ENCRYPTED_ONLY=1" \
  -v "$PWD/data:/data" -d rustdesk/rustdesk-server-s6:latest

端口映射方式(不用 host 网络时 P2P 直连不可用):

docker run --name rustdesk-server \
  -p 21115:21115 -p 21116:21116 -p 21116:21116/udp \
  -p 21117:21117 -p 21118:21118 -p 21119:21119 \
  -e "RELAY=rustdeskrelay.example.com" \
  -e "ENCRYPTED_ONLY=1" \
  -v "$PWD/data:/data" -d rustdesk/rustdesk-server-s6:latest

注意 s6 镜像的数据卷挂载点是 /data(而非经典镜像的 /root),这与 docker/Dockerfile 中声明的 WORKDIR /data、VOLUME /data 一致。

docker-compose 方式:

version: '3'

services:
  rustdesk-server:
    container_name: rustdesk-server
    ports:
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21117:21117
      - 21118:21118
      - 21119:21119
    image: rustdesk/rustdesk-server-s6:latest
    environment:
      - "RELAY=rustdesk.example.com:21117"
      - "ENCRYPTED_ONLY=1"
    volumes:
      - ./data:/data
    restart: unless-stopped

3.4 S6 镜像专属环境变量

在通用 ENV 变量(见第七节)之外,s6 镜像额外支持以下变量:

变量 是否可选 说明
RELAY 否 运行本容器的主机 IP/DNS 名称(即中继地址)
ENCRYPTED_ONLY 是 若设为 "1",则拒绝接受未加密的连接(等价于给 hbbs/hbbr 附加 -k _)
KEY_PUB 是 密钥对的公钥部分
KEY_PRIV 是 密钥对的私钥部分

RELAY 直接作为 /usr/bin/hbbs -r $RELAY 的参数传给 hbbs;ENCRYPTED_ONLY=1 时,hbbs/run 与 hbbr/run 都会追加 -k _,即“随机密钥 + 仅接受加密连接”模式。

四、密钥对:为什么需要、如何生成

4.1 密钥的作用

密钥对用于端到端加密:RustDesk 客户端与服务端之间通过共享密钥协商加密连接。你可以像上文那样把密钥交给服务端(通过环境变量或 secrets),但首先要有一条生成密钥对的途径。

4.2 生成密钥对

如果你安装了 rustdesk-utils 软件包,直接运行:

/usr/bin/rustdesk-utils genkeypair

如果系统上没有安装(或不打算安装)rustdesk-utils,可以用 s6 镜像以一次性容器方式执行同样的命令:

docker run --rm --entrypoint /usr/bin/rustdesk-utils  rustdesk/rustdesk-server-s6:latest genkeypair

输出形如:

Public Key:  8BLLhtzUBU/XKAH4mep3p+IX4DSApe7qbAwNH9nv4yA=
Secret Key:  egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hfgNICl7upsDA0f2e/jIA==

从源码看,genkeypair 基于 libsodium 的 Ed25519 签名体系实现(src/utils.rs),使用 sodiumoxide::crypto::sign::gen_keypair() 生成密钥对,公钥、私钥分别以 base64 编码输出。而 src/main.rs 中 hbbs 的 -k 参数正是用这把密钥来限制接入客户端——只有携带相同密钥的客户端才能连接,这是防止陌生人蹭用自建服务器的重要防线。

4.3 更多 CLI 子命令

rustdesk-utils 还提供两个实用的诊断命令(帮助文本见 src/utils.rs):

  • validatekeypair <a href="https://link.gitcode.com/i/e7e76a145f1a421bedf2cfb1ac0d0beb" target="_blank">public key] [secret key]:校验公钥/私钥是否匹配。其实现会尝试用私钥签名一段测试数据再用公钥验签,验签失败即判定密钥对无效([src/utils.rs);
  • doctor <a href="https://link.gitcode.com/i/7ad4ad4bc0f6c9917abaf37f8786e124" target="_blank">rustdesk-server]:对指定服务器执行连通性诊断,依次检查 21114(API)、21115、21116、21117、21118、21119 共六个 TCP 端口的连通性,并输出解析到的 IP 及反向 DNS 比对结果([src/utils.rs)。

五、S6 镜像中的密钥托管与 Docker secrets

虽然可以把密钥对保存在 docker volume 中,但最佳实践建议不要将密钥明文写入文件系统,因此 s6 镜像内置了两套托管方案。容器启动时,key-secret/up.real 脚本会执行完整的密钥初始化流程:

  1. 检查 /data/id_ed25519.pub 与 /data/id_ed25519 是否存在;
  2. 若任一密钥缺失,则依次尝试从 docker secrets(/run/secrets/key_pub、/run/secrets/key_priv)恢复,其次从 KEY_PUB/KEY_PRIV 环境变量恢复;
  3. 校验密钥对有效性:如果两个密钥文件都存在,会修正权限为 0600、属主为 root:root,并调用 /usr/bin/rustdesk-utils validatekeypair 验证公私钥匹配,不匹配则容器直接 halt 退出;
  4. 只提供了其中一个密钥(公私不成对)时同样直接 halt 并提示必须同时提供两个密钥;
  5. 如果完全没提供密钥,则由 hbbs 在启动时自动生成并写入默认位置。

5.1 通过环境变量托管密钥

docker run --name rustdesk-server \
  --net=host \
  -e "RELAY=rustdeskrelay.example.com" \
  -e "ENCRYPTED_ONLY=1" \
  -e "DB_URL=/db/db_v2.sqlite3" \
  -e "KEY_PRIV=FR2j78IxfwJNR+HjLluQ2Nh7eEryEeIZCwiQDPVe+PaITKyShphHAsPLn7So0OqRs92nGvSRdFJnE2MSyrKTIQ==" \
  -e "KEY_PUB=iEyskoaYRwLDy5+0qNDqkbPdpxr0kXRSZxNjEsqykyE=" \
  -v "$PWD/db:/db" -d rustdesk/rustdesk-server-s6:latest

docker-compose 写法:

version: '3'

services:
  rustdesk-server:
    container_name: rustdesk-server
    ports:
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21117:21117
      - 21118:21118
      - 21119:21119
    image: rustdesk/rustdesk-server-s6:latest
    environment:
      - "RELAY=rustdesk.example.com:21117"
      - "ENCRYPTED_ONLY=1"
      - "DB_URL=/db/db_v2.sqlite3"
      - "KEY_PRIV=FR2j78IxfwJNR+HjLluQ2Nh7eEryEeIZCwiQDPVe+PaITKyShphHAsPLn7So0OqRs92nGvSRdFJnE2MSyrKTIQ=="
      - "KEY_PUB=iEyskoaYRwLDy5+0qNDqkbPdpxr0kXRSZxNjEsqykyE="
    volumes:
      - ./db:/db
    restart: unless-stopped

5.2 通过 Docker secrets 托管密钥

docker secrets 适用于 docker-compose 或 docker swarm 场景,密钥以受控方式挂载到 /run/secrets/,不落盘到镜像层。

先用 docker secret create 从本地密钥文件创建 secret:

cat secrets/id_ed25519.pub | docker secret create key_pub -
cat secrets/id_ed25519 | docker secret create key_priv -
docker service create --name rustdesk-server \
  --secret key_priv --secret key_pub \
  --net=host \
  -e "RELAY=rustdeskrelay.example.com" \
  -e "ENCRYPTED_ONLY=1" \
  -e "DB_URL=/db/db_v2.sqlite3" \
  --mount "type=bind,source=$PWD/db,destination=/db" \
  rustdesk/rustdesk-server-s6:latest

docker-compose 中挂载 secrets 的写法(secret 定义从本地文件 secrets/id_ed25519.pub、secrets/id_ed25519 读取):

version: '3'

services:
  rustdesk-server:
    container_name: rustdesk-server
    ports:
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21117:21117
      - 21118:21118
      - 21119:21119
    image: rustdesk/rustdesk-server-s6:latest
    environment:
      - "RELAY=rustdesk.example.com:21117"
      - "ENCRYPTED_ONLY=1"
      - "DB_URL=/db/db_v2.sqlite3"
    volumes:
      - ./db:/db
    restart: unless-stopped
    secrets:
      - key_pub
      - key_priv

secrets:
  key_pub:
    file: secrets/id_ed25519.pub
  key_priv:
    file: secrets/id_ed25519

结合 key-secret/up.real 的实现可以确认:secrets 的优先级高于环境变量——脚本先检查 /run/secrets/,再检查 KEY_PUB/KEY_PRIV,且只有在对应密钥文件不存在时才会执行恢复动作,已存在的密钥不会被覆盖。

六、Debian 软件包安装

每次 release 都会为每个二进制发布独立的 .deb 包(rustdesk-server-hbbs、rustdesk-server-hbbr、rustdesk-server-utils),适用于以下发行版:

  • Ubuntu 22.04 LTS
  • Ubuntu 20.04 LTS
  • Ubuntu 18.04 LTS
  • Debian 11 bullseye
  • Debian 10 buster

仓库内 debian/ 目录包含完整的打包配方:三个软件包的元数据定义在 debian/control.tpl,rustdesk-server-hbbs 与 rustdesk-server-hbbr 依赖 systemd(对应 systemd/rustdesk-hbbs.service 与 systemd/rustdesk-hbbr.service 两个单元文件,由 postinst 脚本安装),rustdesk-server-utils 则是纯 CLI 工具包。安装 hbbs/hbbr 包后,服务会以 systemd 方式常驻并自动重启(Restart=always、RestartSec=10),日志分别追加写入 /var/log/rustdesk-server/hbbs.log 与 /var/log/rustdesk-server/hbbs.error,工作目录为 /var/lib/rustdesk-server/。

七、ENV 变量详解(附源码级解析)

hbbs 与 hbbr 都可以通过环境变量配置。除了常规的 export 方式,在启动目录放置一个 .env 文件同样会被读取——src/hbbr.rs 会使用 ini 解析器加载当前目录下的 .env 文件并把键值写入进程环境。完整变量清单如下:

变量 适用二进制 说明
ALWAYS_USE_RELAY hbbs 若设为 "Y",则不允许客户端直接 P2P 连接
DB_URL hbbs 数据库文件路径
DOWNGRADE_START_CHECK hbbr 降级(downgrade)检查的延迟时间(秒)
DOWNGRADE_THRESHOLD hbbr 降级检查的阈值(bit/ms)
KEY hbbs/hbbr 若设置则强制使用指定密钥;若设为 "_" 则强制使用随机密钥
LIMIT_SPEED hbbr 速度限制(Mb/s)
PORT hbbs/hbbr 监听端口(hbbs 默认 21116,hbbr 默认 21117)
RELAY_SERVERS hbbs 运行 hbbr 的主机 IP/DNS 名称(逗号分隔)
RUST_LOG 全部 设置调试级别(error|warn|info|debug|trace)
SINGLE_BANDWIDTH hbbr 单条连接的最大带宽(Mb/s)
TOTAL_BANDWIDTH hbbr 中继的总带宽上限(Mb/s)

以下是每个变量在源码中的具体实现位置与行为细节:

  • ALWAYS_USE_RELAY:在 src/rendezvous_server.rs 中读取,值转大写后与 "Y" 比较,命中则把全局原子标志 ALWAYS_USE_RELAY 置为 true。该标志在 src/rendezvous_server.rs 的穿透决策中生效:ALWAYS_USE_RELAY 为真(或双方不在同一局域网)时强制走中继,从而禁止 P2P 直连。
  • DB_URL:在 src/peer.rs 中读取,用于指定 hbbs 持久化数据的 SQLite 数据库文件路径;未设置时默认使用 db_v2.sqlite3(位于运行目录)。
  • DOWNGRADE_START_CHECK / DOWNGRADE_THRESHOLD:在 src/relay_server.rs 中读取。DOWNGRADE_START_CHECK 以秒为单位,内部换算为毫秒存储(* 1000);DOWNGRADE_THRESHOLD 以 bit/ms 为单位,内部放大 100 倍为整数存储(* 100.)。两者用于控制中继在延迟/带宽劣化时的降级判定。
  • LIMIT_SPEED / TOTAL_BANDWIDTH / SINGLE_BANDWIDTH:在 src/relay_server.rs 中读取,单位均为 Mb/s,内部换算为字节(* 1024 * 1024)。SINGLE_BANDWIDTH 限制单条连接的带宽,TOTAL_BANDWIDTH 限制整个中继的总带宽,LIMIT_SPEED 则是在两者之外的速度上限。三者都只在值大于 0 时生效。
  • KEY:hbbr 在 src/hbbr.rs 中读取作为 -k 参数的兜底值;hbbs 同理。设为 "_" 时使用随机密钥(s6 镜像的 ENCRYPTED_ONLY=1 正是通过追加 -k _ 实现只允许加密连接)。
  • PORT:hbbr 在 src/hbbr.rs 中读取,注意一个特殊行为:hbbr 内部监听的是 PORT + 1(因为 21116 的主端口被 hbbs 占用,hbbr 默认实际监听 21117),因此设置 PORT=21116 时 hbbr 实际监听 21117,与 hbbs 的端口体系保持一致。hbbs 侧端口同样受该变量影响(默认 21116)。
  • RELAY_SERVERS:README 中列为 hbbs 的配置项,从源码看与之对应的是 hbbs 的 -r/--relay-servers 参数(src/main.rs 与 src/rendezvous_server.rs),支持逗号分隔多个中继;src/rendezvous_server.rs 显示 hbbs 会轮询(round-robin)选取其中一个中继服务器分配给客户端。
  • RUST_LOG:由 src/main.rs 与 src/hbbr.rs 中的 flexi_logger::Logger::try_with_env_or_str("info") 读取,未设置时默认日志级别为 info,支持 error|warn|info|debug|trace 逐级调高输出量。

八、部署要点速查

综合以上内容,完成一套自托管 RustDesk 服务器部署的最小路径如下:

  1. 准备服务器:一台具有公网 IP 的主机,放行 TCP 21115/21116/21117/21118/21119 与 UDP 21116 端口;
  2. 选择部署方式:二进制编译(cargo build --release)、经典 Docker 镜像(双容器)或 S6-overlay 镜像(单容器,推荐)三者任选其一;
  3. 配置密钥:用 rustdesk-utils genkeypair 生成密钥对,通过 KEY_PUB/KEY_PRIV 环境变量或 docker secrets 注入,或直接省略让 hbbs 自动生成;
  4. 告知中继地址:通过 -r 参数或 RELAY 环境变量把 hbbr 所在主机地址交给 hbbs;
  5. 可选加固:设置 ENCRYPTED_ONLY=1 拒绝非加密连接;通过 SINGLE_BANDWIDTH/TOTAL_BANDWIDTH 限制带宽占用;对公网环境用 ALWAYS_USE_RELAY=Y 强制走中继。

部署完成后,在 RustDesk 客户端中填入服务器地址与密钥(若设置了 KEY),即可让客户端通过你的自建服务器完成注册、穿透与中继,实现完全自主可控的远程桌面服务。

登录后查看全文
rustdesk-server