RustDesk 1.1.16 配置参数详解
详解 RustDesk 1.1.16 服务端 hbbs/hbbr 全部命令行参数与环境变量:四级配置优先级实测、KEY 密钥四形态、中继带宽 QoS 五项、loopback 控制台命令集、数据库与日志参数,含生产配置模板。
RustDesk 1.1.16 配置参数详解
目标:把 RustDesk 1.1.16 开源服务端两个进程(hbbs ID/Rendezvous 服务器、hbbr Relay 中继服务器)的全部配置面讲透——命令行 flag、环境变量、
.env/INI 配置文件三条注入途径的优先级关系,KEY 密钥四形态、中继带宽 QoS 五项、loopback 运行时控制台命令集、数据库与日志参数,并给出可直接套用的生产配置模板。本文全部命令与回显已在 Ubuntu 22.04 + RustDesk 1.1.16 服务端环境实测通过(实测日期 2026-10-25),参数语义以官方仓库docs/environment-variables.md(查询日期 2026-10-25)为权威依据。
一、环境信息
- 操作系统:Ubuntu 22.04.5 LTS(x86_64)
- RustDesk 服务端版本:1.1.16(2026-07-20 发布,官方最新稳定版,发布信息查询日期 2026-10-25)
- 服务端组件:
hbbs(ID/Rendezvous 服务器)、hbbr(Relay 中继服务器),双仓库 AGPL-3.0 - 服务端部署形态:双进程分离部署(部署全链路见同专栏《RustDesk 1.1.16 服务端 Docker Compose 部署指南》)
- 默认工作目录:进程启动时的当前工作目录(密钥对与 SQLite 数据库落盘处)
- 标准端口矩阵:hbbs 21115/TCP(NAT 测试)+ 21116/TCP+UDP(注册心跳打洞)+ 21118/TCP(WebSocket);hbbr 21117/TCP(中继)+ 21119/TCP(WebSocket)
二、前置条件
- 服务端已按部署篇完成安装,
hbbs与hbbr二进制可用(裸机/systemd 形态位于/usr/bin/,官方镜像形态位于镜像内/usr/bin/),验证:
hbbs -V
实测输出:
hbbs 1.1.16
- 已知晓两个进程各自的工作目录(密钥对
id_ed25519/id_ed25519.pub与数据库db_v2.sqlite3均落在工作目录),本文示例以/opt/rustdesk/hbbs与/opt/rustdesk/hbbr为工作目录。 - 阅读顺序建议:先看第三章优先级规则,再按第五章分类查参数;只想要一份能直接抄的配置可看第六章模板。
三、参数查看方式与配置优先级
3.1 查看全部命令行参数
hbbs --help 实测输出(逐行照抄):
hbbs 1.1.16
Purslane Ltd. <info@rustdesk.com>
RustDesk ID/Rendezvous Server
USAGE:
hbbs [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-c, --config <FILE> Sets a custom config file
-k, --key <KEY> Only allow the client with the same key
--mask <MASK> Determine if the connection comes from LAN, e.g. 192.168.0.0/16
-p, --port <NUMBER(default=21116)> Sets the listening port
-r, --relay-servers <HOST> Sets the default relay servers, separated by comma
-R, --rendezvous-servers <HOSTS> Sets rendezvous servers, separated by comma
-M, --rmem <NUMBER(default=0)> Sets UDP recv buffer size, set system rmem_max first, e.g., sudo sysctl -w
net.core.rmem_max=52428800. vi /etc/sysctl.conf, net.core.rmem_max=52428800,
sudo sysctl –p
-s, --serial <NUMBER(default=0)> Sets configure update serial number
-u, --software-url <URL> Sets download url of RustDesk software of newest version
hbbr --help 实测输出(逐行照抄,可见 hbbr 的 flag 只有两个):
hbbr 1.1.16
Purslane Ltd. <info@rustdesk.com>
RustDesk Relay Server
USAGE:
hbbr [OPTIONS]
FLAGS:
-h, --help Prints help information
-V, --version Prints version information
OPTIONS:
-k, --key <KEY> Only allow the client with the same key
-p, --port <NUMBER(default=21117)> Sets the listening port
💡 说明:hbbr 的带宽/QoS 等调优项没有对应 flag,只能走环境变量(见 5.4)。
3.2 配置来源与优先级(官方规则)
两个进程都支持「flag / 配置文件 / 环境变量」三种注入途径。官方权威优先级(从高到低):
- hbbs:命令行 flag >
-c/--config指定的 INI 文件 > 工作目录下.env文件 > 继承的进程环境变量 - hbbr:命令行 flag > 工作目录下
.env文件 > 继承的进程环境变量(hbbr 不支持--config)
底层实现上,三种来源最终都会被转成同名进程环境变量再被代码读取,所以 flag、配置文件、环境变量只是同一组参数的三种写法。唯一例外是 RUST_LOG:日志初始化发生在 .env/--config 加载之前,RUST_LOG 必须放在继承的进程环境里才生效(实测见 5.7)。
3.3 优先级实测:flag 覆盖环境变量
同时设置 PORT 环境变量与 -p flag,观察 hbbs 实际监听端口:
cd /opt/rustdesk/hbbs
PORT=23116 hbbs -p 24116
实测日志(逐行照抄,监听端口为 flag 值 24116,而非环境变量 23116,且派生端口同步平移为 24115/24118):
[2026-10-25 04:25:22.766223 +00:00] INFO [src/rendezvous_server.rs:1243] Key: rvALMcyORW9+4o2gMQXkq9SR5JiKouVHBzPpJQZn9ys=
[2026-10-25 04:25:22.787974 +00:00] INFO [src/rendezvous_server.rs:109] Listening on tcp/udp :24116
[2026-10-25 04:25:22.787977 +00:00] INFO [src/rendezvous_server.rs:110] Listening on tcp :24115, extra port for NAT test
[2026-10-25 04:25:22.787979 +00:00] INFO [src/rendezvous_server.rs:111] Listening on websocket :24118
结论与官方规则一致:同名参数 flag 优先于环境变量。hbbs 改 -p 后 PORT-1(NAT 测试)与 PORT+2(WebSocket)两个派生端口自动跟随平移。
四、参数总览
4.1 hbbs 参数总览
| 环境变量 | CLI flag | 默认值 | 说明 |
|---|---|---|---|
KEY | -k, --key | - | 客户端校验密钥。支持公钥字符串 / base64 私钥 / -、_(加载或生成密钥对)/ 显式空值(关闭校验),四形态详解见 5.3 |
PORT | -p, --port | 21116 | 主监听端口(TCP+UDP 同号);同时派生绑定 PORT-1(NAT 类型测试,TCP)与 PORT+2(WebSocket,TCP) |
RELAY-SERVERS | -r, --relay-servers | 空 | 下发给客户端的中继服务器覆盖地址,逗号分隔 host 或 host:port。hbbr 与 hbbs 同地址同标准端口时留空即可,客户端自动推导;中继地址或端口非标准时才需要设置 |
| 无 | -R, --rendezvous-servers | 空 | 指定 rendezvous 服务器列表(逗号分隔),用于多 hbbs 互联场景 |
| 无 | -c, --config | 无 | 额外 INI 配置文件路径(优先级仅次于 flag) |
| 无 | --mask | 无 | 判定连接是否来自局域网的网段掩码,如 192.168.0.0/16 |
RMEM | -M, --rmem | 0(系统默认) | UDP 接收缓冲区字节数。调大前须先调 OS 上限:sudo sysctl -w net.core.rmem_max=52428800 |
| 无 | -s, --serial | 0 | 配置更新序列号 |
| 无 | -u, --software-url | 无 | 客户端「下载最新版」跳转的自定义下载地址 |
BIND | -b, --bind | 全部网卡 | 1.1.17 起新增,1.1.16 不可用。指定所有监听绑定的本地 IPv4/IPv6 地址,不改变下发给客户端的地址 |
TEST_HBBS 🅴 | 无 | 自动 | 启动时 UDP 自检目标。设为 no 跳过自检(部分 NAT/代理后有用),或设为显式 host:port |
ALWAYS_USE_RELAY 🅴 | 无 | N | Y 强制所有会话走中继(禁用直连/打洞);运行期可用控制台 always-use-relay 命令热切换(见 5.5) |
DB_URL 🅴 | 无 | ./db_v2.sqlite3 | SQLite 数据库文件路径/URL(见 5.6) |
MAX_DATABASE_CONNECTIONS 🅴 | 无 | 1 | SQLite 连接池大小 |
MAX_PUNCH_REQUESTS 🅴 | 无 | 100000 | 内存中保留的打洞请求记录条数(供控制台 punch-requests 查询),超出丢弃最旧记录;0 关闭记录 |
🅴 = 仅能通过继承的进程环境变量设置。
4.2 hbbr 参数总览
| 环境变量 | CLI flag | 默认值 | 说明 |
|---|---|---|---|
KEY | -k, --key | 空 | 默认空值是官方有意为之:关闭中继密钥校验,避免密钥对配置与失配故障。需开启中继校验时,设置与 hbbs 相同的非空 KEY |
PORT | -p, --port | 21117 | 中继监听端口;同时派生绑定 PORT+2(WebSocket 中继)。⚠️ 通过 PORT 环境变量(而非 -p)设置时,hbbr 实际监听 PORT+1(实测见 5.2),因此 hbbs 与 hbbr 共享 PORT=21116 时二者分别落在 21116/21117 |
BIND | -b, --bind | 全部网卡 | 1.1.17 起新增,1.1.16 不可用 |
SINGLE_BANDWIDTH 🅴 | 无 | 128 Mb/s | 单条中继连接常规带宽上限(见 5.4) |
TOTAL_BANDWIDTH 🅴 | 无 | 1024 Mb/s | 全部中继连接共享的总带宽上限 |
LIMIT_SPEED 🅴 | 无 | 32 Mb/s | 连接被降级后、以及 blacklist.txt 中 IP 的限速值 |
DOWNGRADE_THRESHOLD 🅴 | 无 | 0.66 | 降级阈值比例(0–1) |
DOWNGRADE_START_CHECK 🅴 | 无 | 1800 秒 | 连接建立多久后开始具备降级检查资格 |
4.3 端口总览
| 端口 | 协议 | 进程 | 用途 |
|---|---|---|---|
| 21115 | TCP | hbbs | NAT 类型测试(PORT-1) |
| 21116 | TCP+UDP | hbbs | ID 注册 / rendezvous / 打洞协调(PORT) |
| 21117 | TCP | hbbr | 中继(hbbr PORT) |
| 21118 | TCP | hbbs | WebSocket rendezvous(PORT+2) |
| 21119 | TCP | hbbr | WebSocket 中继(hbbr PORT+2) |
💡 说明:21118/21119 仅 Web 客户端需要,不用 Web 客户端可不映射/不放通。
五、核心参数分类详解
5.1 hbbs 参数
-p, --port(默认 21116):主端口,TCP 与 UDP 同号监听。改端口时两个派生端口自动平移(PORT-1 NAT 测试、PORT+2 WebSocket),实测见 3.3:-p 24116 后派生端口为 24115/24118。改非标准端口时务必同步:①防火墙放通 PORT-1/PORT/PORT+2 的 TCP 与 PORT 的 UDP;②hbbr 端口同步调整;③客户端「ID 服务器」填写新端口(格式 host:port)。
-k, --key(默认 -):客户端密钥校验,四形态语义与实测见 5.3。
-r, --relay-servers(默认空):hbbs 下发给客户端的中继地址。hbbr 与 hbbs 同机同标准端口(21117)时留空,客户端按「ID 服务器地址 + 21117」自动推导。仅当中继在不同地址或非标准端口时设置,如 -r rustdesk.example.com:22117。多中继用逗号分隔。
-R, --rendezvous-servers(默认空):指定 rendezvous 服务器列表,多 hbbs 互联/集群形态使用,单机留空。实测单机启动日志:rendezvous-servers=[]。
-c, --config <FILE>:指定额外 INI 配置文件,优先级仅次于 flag、高于 .env。INI 内写法与 .env 相同(如 PORT=22116、relay-servers=host:22117)。
--mask <MASK>:判定连接来源是否为局域网的网段,如 --mask 192.168.0.0/16。影响 LAN 判定与相关策略,公网服务器通常不需要。实测默认启动日志:mask: None、local-ip: ""。
-M, --rmem(默认 0):UDP 接收缓冲区(字节)。大并发打洞场景可调大,但必须先调 OS 上限,否则会话被内核截断:
sudo sysctl -w net.core.rmem_max=52428800
echo 'net.core.rmem_max=52428800' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
再启动 hbbs -M 52428800。
-s, --serial(默认 0):配置更新序列号,客户端拉取配置时按序列号判断是否增量更新,常规运维无需手工干预。实测默认启动日志:serial=0。
-u, --software-url <URL>:自定义「下载最新版 RustDesk」的跳转地址,企业内网分发定制客户端时使用。
5.2 hbbr 参数
hbbr 只有两个 flag:-k 与 -p(默认 21117)。需要重点实测确认的是 PORT 环境变量的 +1 行为:官方文档说明,hbbr 通过 PORT 环境变量(而非 -p flag)设置端口时,实际监听 PORT+1。
实测:只设环境变量 PORT=25116 启动 hbbr:
cd /opt/rustdesk/hbbr
PORT=25116 hbbr
实测日志(逐行照抄,监听落在 25117 = 25116+1,WebSocket 落在 25119 = 25117+2):
[2026-10-25 04:25:22.954345 +00:00] INFO [src/relay_server.rs:82] Listening on tcp :25117
[2026-10-25 04:25:22.954346 +00:00] INFO [src/relay_server.rs:84] Listening on websocket :25119
这个设计是为了让 hbbs 与 hbbr 共享同一个 PORT 环境变量时自动错开(PORT=21116 → hbbs 21116、hbbr 21117)。踩坑提示:如果只想给 hbbr 单独用环境变量改端口,得到的会比预期大 1;要精确控制 hbbr 端口请用 -p flag。
5.3 KEY 密钥机制(四形态)
KEY / -k 是客户端接入校验的核心参数,官方定义四种取值形态:
| 取值形态 | 行为 |
|---|---|
| 公钥字符串 | 客户端必须出示匹配密钥;服务端只做校验 |
| base64 编码的 64 字节私钥 | 服务端从私钥推导出公钥后校验 |
- 或 _ | 从工作目录加载 id_ed25519/id_ed25519.pub,首次启动不存在则生成密钥对并写盘 |
| 显式空值 | 关闭密钥校验。hbbs 仍加载/生成密钥文件用于签名,但活动校验密钥置空;hbbr 不加载也不生成密钥 |
两个进程的默认值不同且都是官方有意设计:
- hbbs 默认
-:不带任何-k即自动加载/生成密钥对,因此显式-k _对 hbbs 是多余的(当前实现中_与-行为完全相同,并非更严格模式) - hbbr 默认空:有意关闭中继密钥校验,避免密钥对配置与失配故障。要开启中继校验,给 hbbr 设置与 hbbs 相同的非空 KEY;两进程可共享同一工作目录复用同一份密钥材料
实测一:公钥与私钥形态等价。先取工作目录中公钥 id_ed25519.pub 内容,分别以「公钥字符串」和「base64 私钥(取自 id_ed25519)」启动 hbbs:
hbbs -k 'tIOS6+HyV3YtZbGh57aTlN5cKrAF2Kg0w2gjWgm2dYY='
实测日志:
[2026-10-25 04:25:44.995667 +00:00] INFO [src/rendezvous_server.rs:1243] Key: tIOS6+HyV3YtZbGh57aTlN5cKrAF2Kg0w2gjWgm2dYY=
hbbs -k '<id_ed25519 私钥的 base64 内容>'
实测日志(与公钥形态推导出的 Key 完全一致):
[2026-10-25 04:25:45.271318 +00:00] INFO [src/rendezvous_server.rs:1243] Key: tIOS6+HyV3YtZbGh57aTlN5cKrAF2Kg0w2gjWgm2dYY=
实测二:显式空值关闭校验。空目录下启动 hbbs -k "":
[2026-10-25 04:25:23.126183 +00:00] INFO [src/common.rs:147] Private/public key written to id_ed25519/id_ed25519.pub
[2026-10-25 04:25:23.128824 +00:00] INFO [libs/hbb_common/src/config.rs:895] Generated new keypair for id:
可见空值模式下 hbbs 仍会生成密钥对文件(用于签名),但日志中不再出现 Key: 行——活动校验密钥为空,客户端无需 Key 即可接入。
⚠️ 注意:要自带密钥对,在首次启动前把
id_ed25519与id_ed25519.pub放入进程当前工作目录即可(该目录是进程启动时的 cwd,未必是可执行文件所在目录)。密钥对就是这套服务端身份,更换后全部客户端须更新 Key,务必备份(备份恢复实测见同专栏《RustDesk 1.1.16 日常运维手册》)。
5.4 中继带宽与 QoS(hbbr,仅环境变量)
这五项没有 flag,只能走环境变量(或 .env),且运行期可通过 hbbr 控制台热改(见 5.5):
| 变量 | 默认值 | 单位 | 说明 |
|---|---|---|---|
SINGLE_BANDWIDTH | 128 | Mb/s | 单条中继连接常规带宽上限 |
TOTAL_BANDWIDTH | 1024 | Mb/s | 全部中继连接共享的总带宽上限 |
LIMIT_SPEED | 32 | Mb/s | 连接被降级后的限速,同时作用于 blacklist.txt 中的 IP |
DOWNGRADE_THRESHOLD | 0.66 | 比例 0–1 | 连接历史平均吞吐超过 SINGLE_BANDWIDTH × 该比例 即触发降级 |
DOWNGRADE_START_CHECK | 1800 | 秒 | 连接建立满该时长后才具备降级检查资格 |
hbbr 启动时会把当前生效值打进日志。实测默认启动日志(逐行照抄):
[2026-10-25 03:55:24.692085 +00:00] INFO [src/relay_server.rs:583] Key: id_ed25519
[2026-10-25 03:55:24.692099 +00:00] INFO [src/relay_server.rs:61] #blacklist(blacklist.txt): 0
[2026-10-25 03:55:24.692106 +00:00] INFO [src/relay_server.rs:76] #blocklist(blocklist.txt): 0
[2026-10-25 03:55:24.692107 +00:00] INFO [src/relay_server.rs:82] Listening on tcp :21117
[2026-10-25 03:55:24.692109 +00:00] INFO [src/relay_server.rs:84] Listening on websocket :21119
[2026-10-25 03:55:24.692114 +00:00] INFO [src/relay_server.rs:87] Start
[2026-10-25 03:55:24.692185 +00:00] INFO [src/relay_server.rs:105] DOWNGRADE_THRESHOLD: 0.66
[2026-10-25 03:55:24.692192 +00:00] INFO [src/relay_server.rs:115] DOWNGRADE_START_CHECK: 1800s
[2026-10-25 03:55:24.692196 +00:00] INFO [src/relay_server.rs:125] LIMIT_SPEED: 32Mb/s
[2026-10-25 03:55:24.692200 +00:00] INFO [src/relay_server.rs:136] TOTAL_BANDWIDTH: 1024Mb/s
[2026-10-25 03:55:24.692201 +00:00] INFO [src/relay_server.rs:146] SINGLE_BANDWIDTH: 128Mb/s
降级机制语义(官方权威描述):降级按每条连接独立判定,不检查中继整体拥塞。连接存活满 DOWNGRADE_START_CHECK 秒后,只要其自建立以来的平均吞吐超过 SINGLE_BANDWIDTH × DOWNGRADE_THRESHOLD,就被限速到 LIMIT_SPEED——因此即使中继整体空闲,单条大流量长连接也会被降级。TOTAL_BANDWIDTH 是独立的总量上限,与降级机制并行生效。
黑白名单(文件而非环境变量):hbbr 启动时从工作目录读两个可选文件:
blacklist.txt:每行一个 IP(行内首个空格后内容忽略),命中 IP 限速(限速值LIMIT_SPEED)blocklist.txt:每行一个 IP,命中 IP 直接拒绝
实测默认启动日志显示两者条数:#blacklist(blacklist.txt): 0、#blocklist(blocklist.txt): 0。两份名单均可通过控制台 ba/br、Ba/Br 命令在线增删(见 5.5)。
5.5 运行时控制台(loopback 单命令 TCP 接口)
hbbs 与 hbbr 内置运行时控制台:来自 127.0.0.1 的 TCP 连接被视为一条控制台命令,连接内容即命令文本,执行后返回结果。它不是交互式 stdin 控制台,也不是 rustdesk-utils 的子命令。控制台端口:hbbs 在 PORT-1(默认 21115),hbbr 在自己的 PORT(默认 21117);改过 PORT 就用对应端口。
hbbs 控制台命令集(printf 'h' | nc 127.0.0.1 21115 实测回显,逐行照抄):
relay-servers(rs) <separated by ,>
reload-geo(rg)
ip-blocker(ib) [<ip>|<number>] [-]
ip-changes(ic) [<id>|<number>] [-]
punch-requests(pr) [<number>] [-]
always-use-relay(aur)
test-geo(tg) <ip1> <ip2>
| 命令 | 作用 |
|---|---|
relay-servers (rs) | 在线查看/修改下发的中继服务器列表 |
reload-geo (rg) | 重载 GeoIP 数据 |
ip-blocker (ib) | 查看/操作 IP 阻断记录 |
ip-changes (ic) | 查看 ID 变更记录 |
punch-requests (pr) | 查看内存中的打洞请求记录(条数上限 MAX_PUNCH_REQUESTS) |
always-use-relay (aur) | 查看/热切换强制中继开关,如 always-use-relay Y |
test-geo (tg) | 测试两个 IP 的 Geo 判定 |
实测查询强制中继开关状态:
printf 'aur' | nc 127.0.0.1 21115
实测输出:
ALWAYS_USE_RELAY: false
实测查询打洞请求记录(空记录时无输出):
printf 'pr' | nc 127.0.0.1 21115
hbbr 控制台命令集(printf 'h' | nc 127.0.0.1 21117 实测回显,逐行照抄):
blacklist-add(ba) <ip>
blacklist-remove(br) <ip>
blacklist(b) <ip>
blocklist-add(Ba) <ip>
blocklist-remove(Br) <ip>
blocklist(B) <ip>
downgrade-threshold(dt) [value]
downgrade-start-check(t) [value(second)]
limit-speed(ls) [value(Mb/s)]
total-bandwidth(tb) [value(Mb/s)]
single-bandwidth(sb) [value(Mb/s)]
usage(u)
| 命令 | 作用 |
|---|---|
blacklist-add/remove (ba/br)、blacklist (b) | 在线增/删/查限速名单 |
blocklist-add/remove (Ba/Br)、blocklist (B) | 在线增/删/查拒绝名单 |
downgrade-threshold (dt) | 查看/设置降级阈值 |
downgrade-start-check (t) | 查看/设置降级起始检查秒数 |
limit-speed (ls) | 查看/设置降级限速(Mb/s) |
total-bandwidth (tb) | 查看/设置总带宽(Mb/s) |
single-bandwidth (sb) | 查看/设置单连接带宽(Mb/s) |
usage (u) | 查看中继用量 |
实测查询总带宽:
printf 'tb' | nc 127.0.0.1 21117
实测输出:
1024Mb/s
💡 说明:hbbr 控制台对 QoS 五项与黑白名单的修改是热生效的,适合临时压测/封禁;要固化仍需写
.env/环境变量与名单文件,否则重启还原。
5.6 数据库参数
hbbs 运行期数据库位置只认 DB_URL(默认 ./db_v2.sqlite3,即工作目录下的 SQLite 文件);MAX_DATABASE_CONNECTIONS 控制连接池大小(默认 1)。
实测 RUST_LOG=debug 启动日志中的数据库初始化片段(逐行照抄,可见默认值与建库 PRAGMA):
[2026-10-25 04:26:08.568269 +00:00] INFO [src/peer.rs:84] DB_URL=./db_v2.sqlite3
[2026-10-25 04:26:08.568296 +00:00] DEBUG [src/database.rs:58] MAX_DATABASE_CONNECTIONS=1
建库时还会以 DEBUG 级别打印执行的 SQL 明细(含 PRAGMA 与耗时)。实测建库执行的 PRAGMA(WAL 模式,备份时须连同 -wal/-shm 一起处理,见运维手册篇):
PRAGMA page_size = 4096;
PRAGMA locking_mode = NORMAL;
PRAGMA journal_mode = WAL;
⚠️ 陷阱:
DB_URL≠DATABASE_URL。仓库.env里的DATABASE_URL只在编译期被 sqlx 用于检查 SQL 语句,运行中的服务端不读它。在运行环境设置DATABASE_URL没有任何效果,改数据库位置请用DB_URL。
5.7 日志参数 RUST_LOG
两个进程都用 flexi_logger,遵循标准 RUST_LOG 环境变量(默认 info)。因日志初始化早于 .env/--config 加载,RUST_LOG 必须放在继承的进程环境(systemd 单元 Environment=、或启动命令前缀),写进 .env/--config 文件不生效。
实测:
RUST_LOG=debug hbbs
实测出现真实 DEBUG 行(逐行照抄,含公钥、DNS 解析、SQL 执行明细):
[2026-10-25 04:26:08.568224 +00:00] INFO [src/common.rs:147] Private/public key written to id_ed25519/id_ed25519.pub
[2026-10-25 04:26:08.568250 +00:00] DEBUG [src/common.rs:148] Public key: n9gmqG5WTdPwWqde3uY0HF11SR59ZSo6hhpgZvnKsjw=
[2026-10-25 04:26:08.568261 +00:00] INFO [src/rendezvous_server.rs:1243] Key: n9gmqG5WTdPwWqde3uY0HF11SR59ZSo6hhpgZvnKsjw=
[2026-10-25 04:26:08.568269 +00:00] INFO [src/peer.rs:84] DB_URL=./db_v2.sqlite3
[2026-10-25 04:26:08.568296 +00:00] DEBUG [src/database.rs:58] MAX_DATABASE_CONNECTIONS=1
[2026-10-25 04:26:08.569235 +00:00] INFO [libs/hbb_common/src/config.rs:895] Generated new keypair for id:
[2026-10-25 04:26:08.572153 +00:00] DEBUG [/cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hyper-0.14.32/src/client/connect/dns.rs:122] resolving host="api.rustdesk.com"
排障建议用 RUST_LOG=debug 临时拉起观察,日常保持 info。
5.8 s6 监督镜像专属变量
官方 s6 监督形态(rustdesk/rustdesk-server-s6)的服务脚本额外提供 4 个便利变量——它们由镜像内脚本处理,不是 hbbs/hbbr 原生参数:
| 变量 | 默认值 | 说明 |
|---|---|---|
RELAY | relay.example.com | 转成 hbbs -r $RELAY(填你的公网地址) |
ENCRYPTED_ONLY | 0 | 1 时给两个进程都加 -k _。对 hbbs 是冗余(默认即 -),对 hbbr 是把它从默认空值切换到开启校验 |
KEY_PUB | 未设置 | 首次启动写入 /data/id_ed25519.pub |
KEY_PRIV | 未设置 | 首次启动写入 /data/id_ed25519。KEY_PUB 与 KEY_PRIV 必须同时提供或同时不提供 |
本文 4.1/4.2 表中的所有变量也可直接透传给该形态(如 ALWAYS_USE_RELAY=Y、RUST_LOG=debug、SINGLE_BANDWIDTH=256)。注意经典 scratch 形态(rustdesk/rustdesk-server)只含二进制,不实现 RELAY/ENCRYPTED_ONLY/KEY_PUB/KEY_PRIV,传了会被忽略。
六、生产配置模板
6.1 推荐组合(双进程分离形态)
原则:端口/密钥用 flag 显式锁定(最高优先级、日志可见),QoS 与开关类用环境变量,RUST_LOG 必须走进程环境。
hbbs 启动命令:
cd /opt/rustdesk/hbbs
RUST_LOG=info hbbs -p 21116 -r rustdesk.example.com
hbbr 启动命令:
cd /opt/rustdesk/hbbr
RUST_LOG=info \
SINGLE_BANDWIDTH=256 \
TOTAL_BANDWIDTH=2048 \
hbbr -p 21117
6.2 .env 文件写法(两进程共享工作目录时)
# 非标准端口示例:两进程共享 PORT 时 hbbr 自动监听 PORT+1
PORT=22116
relay-servers=rustdesk.example.com:22117
SINGLE_BANDWIDTH=256
TOTAL_BANDWIDTH=2048
⚠️ 注意:
.env里写RUST_LOG不生效(日志初始化早于文件加载);hbbr 读.env但不支持--config。
6.3 systemd 单元写法
# /etc/systemd/system/rustdesk-hbbs.service
[Unit]
Description=RustDesk ID/Rendezvous Server (hbbs)
After=network.target
[Service]
WorkingDirectory=/opt/rustdesk/hbbs
Environment=RUST_LOG=info
Environment=ALWAYS_USE_RELAY=N
ExecStart=/usr/bin/hbbs -p 21116 -r rustdesk.example.com
Restart=always
[Install]
WantedBy=multi-user.target
# /etc/systemd/system/rustdesk-hbbr.service
[Unit]
Description=RustDesk Relay Server (hbbr)
After=network.target
[Service]
WorkingDirectory=/opt/rustdesk/hbbr
Environment=RUST_LOG=info
Environment=SINGLE_BANDWIDTH=256
Environment=TOTAL_BANDWIDTH=2048
ExecStart=/usr/bin/hbbr -p 21117
Restart=always
[Install]
WantedBy=multi-user.target
七、常见问题
Q1:把 RUST_LOG=debug 写进 .env 为什么不生效?
A:日志初始化发生在 .env/--config 文件加载之前,RUST_LOG 只能通过继承的进程环境注入(启动命令前缀 RUST_LOG=debug hbbs,或 systemd 单元 Environment=RUST_LOG=debug),实测见 5.7。
Q2:设置了 DATABASE_URL 后数据库位置没变?
A:DATABASE_URL 只在编译期被 sqlx 使用,运行期不读。改运行期数据库位置用 DB_URL(默认 ./db_v2.sqlite3),见 5.6。
Q3:用 PORT 环境变量给 hbbr 改端口,实际监听值比预期大 1?
A:这是官方设计——hbbr 经 PORT 环境变量设端口时监听 PORT+1(实测 PORT=25116 → 25117/25119),以便与 hbbs 共享同一 PORT 变量。要精确控制用 -p flag,见 5.2。
Q4:-k _ 和 -k - 有区别吗?hbbs 需要显式加吗?
A:当前实现二者行为完全相同(加载或生成密钥对)。hbbs 默认就是 -,显式加 -k _ 是多余的;hbbr 默认是空值(关闭校验),要开校验需显式给非空 KEY,见 5.3。
Q5:21118/21119 必须放通吗? A:只有 Web 客户端(浏览器直连)需要这两个 WebSocket 端口;纯桌面/移动客户端部署可不映射、不放通,攻击面更小。
Q6:改了 -k/KEY 之后客户端全部连不上?
A:KEY 就是服务端身份,变更后所有客户端的「Key」配置必须同步更新。生产环境不要随手换 KEY;密钥对文件(id_ed25519/id_ed25519.pub)纳入备份,换机迁移用原密钥对即可保持客户端零改动(迁移实测见同专栏《RustDesk 1.1.16 日常运维手册》)。
Q7:PORT_FOR_API / KEY_FOR_API 设置了没效果?
A:这两个变量只有 RustDesk Server Pro 及其 API 使用,开源版服务端不读,无需设置。
Q8:临时给某条大流量连接限速/封禁某个 IP,不想重启服务?
A:用 hbbr loopback 控制台热改:printf 'limit-speed 16' | nc 127.0.0.1 21117 调限速值,printf 'blocklist-add 1.2.3.4' | nc 127.0.0.1 21117 在线封禁;固化再写 .env 与 blocklist.txt,见 5.5。
八、参考链接
- 官方配置与环境变量权威文档(docs/environment-variables.md,查询日期 2026-10-25):https://github.com/rustdesk/rustdesk-server/blob/master/docs/environment-variables.md
- 官方服务端仓库(rustdesk-server,README 含参数速查表,查询日期 2026-10-25):https://github.com/rustdesk/rustdesk-server
- 官方自建文档(查询日期 2026-10-25):https://rustdesk.com/docs/en/self-host/
- 官方服务端 Releases(1.1.16 发布信息,查询日期 2026-10-25):https://github.com/rustdesk/rustdesk-server/releases
- 站内同系列:《RustDesk 1.5.0 介绍与选型指南》、《RustDesk 1.1.16 服务端 Docker Compose 部署指南》、《RustDesk 1.1.16 日常运维手册》(同专栏 RustDesk)