这篇文章按我真实踩坑的顺序整理:从一台干净的 Debian 服务器开始,把 RustDesk 服务端跑起来,让 PC 客户端和网页端都能正常远程,再把过程中遇到的报错、原因和修法讲清楚,最后给一套能落地的安全加固清单。全文尽量用白话,命令都带中文注释。
适合谁看:有自己的云服务器和域名,想自建 RustDesk;或者已经搭好但网页端连不上、PC 客户端报 Failed to secure tcp;以及想给远程桌面做安全加固的人。
一、先认识三个角色:hbbs、hbbr、API
RustDesk 自建服务不是一个程序,而是三个角色配合。名字看着吓人,其实分工很简单:
- hbbs(ID / 信令服务器):负责设备 ID 注册、在线心跳、帮两端交换地址打洞。默认端口
21116 TCP/UDP,另有21115(NAT 测试)和21118(WebSocket)。 - hbbr(中继服务器):两端打洞失败时,数据改由它转发。端口
21117,WebSocket 中继是21119。 - rustdesk-api:管理台、网页客户端、设备列表、账号体系。端口
21114。

记住一句话:PC 客户端走原生 TCP/UDP,浏览器只能走 WebSocket 中继。后面很多“为什么网页端行、PC 不行”的问题,根源都在这里。
二、准备清单
- 一台 Debian/Ubuntu 云服务器,2 核 2G 起步;带宽比 CPU 更重要,因为中继会吃流量。
- 一个域名,规划三个子域:
2114(API + 网页端)、2116(ID)、2117(中继)。 - 安全组/防火墙放行:
21114-21119 TCP、21116 UDP、80/443 TCP。 - 安装 Docker 与 Compose;可选装宝塔面板方便管站点和证书。
# 检查 Docker 是否可用
docker version --format '{{.Server.Version}}'
docker compose version
# 放行端口(以 ufw 为例)
ufw allow 80/tcp
ufw allow 443/tcp
ufw allow 21114:21119/tcp
ufw allow 21116/udp
三、部署服务端(Docker Compose)
新建目录并写 docker-compose.yml。下面这份配置把关键项都注释了,照抄改成自己的域名即可:
mkdir -p /root/rustdesk && cd /root/rustdesk
cat > docker-compose.yml <<'YAML'
services:
rustdesk:
image: lejianwen/rustdesk-server-s6:1.1.16-local
container_name: rustdesk
ports:
- "127.0.0.1:21114:21114" # API/管理台:只绑本机,由 nginx 转发,避免明文暴露
- "21115:21115" # NAT 类型测试
- "21116:21116" # ID 注册/心跳(TCP)
- "21116:21116/udp" # ID 注册/心跳(UDP,必须)
- "21117:21117" # 中继
- "21118:21118" # hbbs WebSocket
- "21119:21119" # hbbr WebSocket
environment:
- RELAY=2117.example.com:21117 # 中继地址,别写占位符
- ENCRYPTED_ONLY=1 # 只允许加密连接
- MUST_LOGIN=N # N=客户端不用登录;Y=必须先登录
- RUSTDESK_API_RUSTDESK_ID_SERVER=2116.example.com
- RUSTDESK_API_RUSTDESK_RELAY_SERVER=2117.example.com
- RUSTDESK_API_RUSTDESK_API_SERVER=https://2114.example.com
- RUSTDESK_API_RUSTDESK_WS_HOST=2114.example.com # 网页端 WebSocket 域名
- RUSTDESK_API_JWT_KEY=请换成32位以上随机串 # 管理端 token 签名密钥
- RUSTDESK_API_JWT_EXPIRE_DURATION=24h
- TZ=Asia/Shanghai
volumes:
- ./data/rustdesk/server:/data # 服务端密钥与数据库
- ./data/rustdesk/api:/app/data # 管理端数据库
restart: unless-stopped
YAML
docker compose up -d
启动后先看容器状态,确认是 healthy:
docker ps --format '{{.Names}} {{.Status}} {{.Ports}}'
docker logs --tail 30 rustdesk

关键点:21114 一定要绑 127.0.0.1。Docker 发布的端口会绕过 ufw,只靠防火墙挡不住,绑定回环才是真的收口。
四、域名与反向代理
三个子域的分工:
2116、2117:直接解析到服务器 IP,客户端直连端口,不需要 nginx(只有启用 WebSocket 时才需要给它们加/ws/id、/ws/relay的转发)。2114:必须走 nginx 443,反代 API 21114,并把/ws/id转到 21118、/ws/relay转到 21119。
# 2114 站点的反向代理核心片段
location ^~ /ws/id {
proxy_pass http://127.0.0.1:21118; # hbbs 的 WebSocket
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
}
location ^~ /ws/relay {
proxy_pass http://127.0.0.1:21119; # hbbr 的 WebSocket
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_read_timeout 3600s;
}
location ^~ / {
proxy_pass http://127.0.0.1:21114; # API / 管理台 / 网页端
proxy_set_header Host $host;
}
改完一定先测试再重载:
nginx -t # 语法检查
nginx -s reload # 平滑重载,不中断连接

配置文件到底在哪?手改和宝塔改有什么区别?
这是新手最容易踩的坑:宝塔面板点“保存”,和直接改文件,运行效果一样,但“谁说了算”不一样。nginx 启动时只认文件,面板只是一个图形化编辑器,保存时把内容写进文件,再帮你重载。
| 文件/目录(以 2114.example.com 为例) | 作用 | 谁在管 |
|---|---|---|
| /www/server/panel/vhost/nginx/2114.example.com.conf | 站点主配置(监听、SSL、include) | 宝塔 |
| /www/server/panel/vhost/nginx/proxy/2114.example.com/*.conf | 反向代理规则(proxy_pass、location) | 宝塔 |
| /www/server/panel/vhost/nginx/extension/2114.example.com/*.conf | 自定义扩展片段 | 没人管,推荐放这里 |
| /www/server/panel/vhost/rewrite/2114.example.com.conf | 伪静态/重写规则 | 宝塔 |
| /www/server/panel/vhost/cert/2114.example.com/ | 证书文件 | 宝塔 |
主配置里能看到两个 include,意思是这两个目录里的文件都会被自动加载:
include /www/server/panel/vhost/nginx/extension/2114.example.com/*.conf;
include /www/server/panel/vhost/nginx/proxy/2114.example.com/*.conf;
这两个 include 到底是什么意思?
include 是 nginx 的“把那个文件的内容原样抄到这里”,相当于 Word 里的“插入文件”。它不是两个网站,也不是两条独立配置,只是两个“插页入口”。
- 第一行:把
extension/<域名>/目录下所有.conf文件的内容,抄到这个位置; - 第二行:把
proxy/<域名>/目录下所有.conf文件的内容,抄到这个位置。
星号 * 是通配符,表示该目录下所有以 .conf 结尾的文件,按文件名顺序依次加载;目录为空也不会报错。
为什么这么设计:这两个目录里的内容本来就属于当前站点的 server { } 内部,主配置只搭框架,具体规则拆成小文件,方便面板和人来改,不用每次动主配置。
| 目录 | 谁写 | 放什么 |
|---|---|---|
| extension/ | 人(你/我) | 自定义片段:/ws/id 转发、限速、额外 header 等 |
| proxy/ | 宝塔面板 | 反向代理规则(proxy_pass、location ^~ /) |
顺序上 extension 先加载、proxy 后加载。所以自定义规则放 extension,面板不会覆盖;面板保存反代时只重写 proxy 里的文件。
三个容易踩的点:
- include 进来的文件里不能再写 server { },因为它已经被插到 server 内部了,再套一层就是语法错误;里面只能写 location、if、add_header 这类 server 级指令。
- 同一个 server 里不能有两个完全相同的 location,否则 nginx 会报 duplicate location,nginx -t 直接失败。
- 同一目录按文件名顺序加载;如果两条规则有覆盖关系,后加载的可能生效,建议用 10-、20- 这样的前缀命名。
确认它到底加载了什么:执行 nginx -T,会把 include 展开后的完整配置打印出来,并在每个文件前标注来源路径,能直接看到哪条规则来自哪个文件。
一句话总结:这两个 include 就是两个“插页口”,把 extension 和 proxy 目录里的配置片段装进这个站点里;改片段不用动主配置,但片段里只能写 server 内部能用的指令。
该改哪个:改反代目标、加 location,改 proxy/ 下那个哈希命名的文件,或者在面板“反向代理 → 编辑”;加自定义规则(比如 /ws/id、限速),优先放 extension/;改证书、PHP 版本、根目录,用面板改,别手改主配置。
会不会冲突:运行时不冲突,编辑时会“打架”。最常见的是——你手改了 proxy 文件,之后又在面板点了同一个反代的“保存”,面板会按数据库里的内容重新生成整个文件,你手加的内容就被覆盖了;面板改站点设置(SSL、PHP 版本)会重写主配置,但 extension 和 proxy 目录通常保留;面板新建反代和你手写的同名 location 同时存在时,nginx 只认一个,行为可能和预期不一致。
一句话记法:面板保存会重写它“管”的文件,extension 目录它不管。所以:自定义规则放 extension;改代理目标用面板或改完别再点保存;任何手改前先备份;改完必须 nginx -t 再 nginx -s reload;面板保存后用 nginx -T | grep -A5 location 核对实际生效内容。
举一反三:宝塔其它功能的“文件真相”
| 场景 | 面板操作 | 实际文件 | 手改会不会被覆盖 |
|---|---|---|---|
| 网站配置 | 网站 → 设置 | vhost/nginx/<域名>.conf | 会(改 SSL/PHP 时重写) |
| 反向代理 | 反向代理 → 编辑 | vhost/nginx/proxy/<域名>/*.conf | 会 |
| 伪静态 | 网站 → 伪静态 | vhost/rewrite/<域名>.conf | 会 |
| 自定义片段 | 无 | vhost/nginx/extension/<域名>/*.conf | 不会(推荐) |
| 防火墙 | 安全 → 防火墙 | /etc/ufw/user.rules | 面板保存会重写 |
| 计划任务 | 计划任务 | /www/server/cron/<hash> + crontab | 面板会重写脚本 |
| Docker | Docker 面板 | compose 文件 / docker 命令 | 面板操作可能覆盖 compose |
通用原则:想长期保留的自定义规则放 extension;改代理目标用面板改,或改完文件后别再点面板保存;手改前先 cp 备份;改完 nginx -t 再重载;面板保存后核对 nginx -T 的实际内容。
五、网页端连不上?先查 ws_host(小白版)
先说现象:PC 客户端能正常远程,但打开浏览器网页端,一直转圈,提示 Failed to connect to rendezvous server, 2114.example.com/ws/id。
一句话原因:网页把 WebSocket 地址拼成了“相对路径”,请求打到了错误的地方,服务器返回 404。不是服务器没开,也不是端口没放行。
5.1 改之前长什么样
浏览器实际发出去的请求是:
GET /webclient2/2114.example.com/ws/id → 404
而正常应该是:
wss://2114.example.com/ws/id → 101
打开页面加载的 /webclient-config/index.js,会看到这一行:
window.ws_host = '2114.example.com'; // 只有域名,没有 wss://
浏览器执行 new WebSocket(window.ws_host + "/ws/id") 时,没有协议头的字符串会被当成相对地址,自动拼到当前页面路径后面,于是变成了 /webclient2/2114.example.com/ws/id。

小知识:ws 和 wss 到底有什么区别?
很多教程直接写 wss://,但不解释为什么。其实它和 http / https 是一对:
| 写法 | 全称 | 加不加密 | 默认端口 | 白话类比 |
|---|---|---|---|---|
| ws:// | WebSocket | 不加密 | 80 | 明信片,路上谁都能看 |
| wss:// | WebSocket Secure | TLS 加密 | 443 | 密封信封,只有收发双方能看 |
普通网页是“你问一句、服务器答一句”,说完就断。WebSocket 是建立一条一直不断的双向通道,服务器可以主动推数据——聊天、实时监控、远程桌面画面都靠它。握手时先发一个 HTTP 请求说“我要升级”,服务器回 101 Switching Protocols,之后这条连接就变成双向数据通道。
为什么网页端必须用 wss:
- 浏览器有“混合内容”限制:页面是
https://打开的,就不允许再连ws://,会被直接拦掉; wss走 443,和普通 https 一样,防火墙和代理最友好;ws走 80,很多环境会被拦或劫持;- 远程桌面传的是屏幕和键鼠,不加密等于裸奔,
wss至少有传输层保护。
回到前面的坑:window.ws_host 如果只写域名、不带协议头,浏览器就不知道你要连 ws 还是 wss,干脆把它当相对路径。写成 wss://2114.example.com 之后,浏览器才知道“这是加密的 WebSocket,去连 443”,请求才会变成 wss://2114.example.com/ws/id 并拿到 101。
什么时候用哪个:公网、正式环境、https 页面,一律用 wss;本机调试、纯内网 http 页面,才可以用 ws。只要页面是 https,就只能是 wss,没有选择。
一句话记:ws 是裸奔的 WebSocket,wss 是套了 TLS 的 WebSocket;https 页面只能连 wss。
5.2 改哪里、怎么改
文件路径:/www/server/panel/vhost/nginx/proxy/2114.example.com/ 目录下那个哈希命名的 .conf 文件(反代规则)。更稳妥的做法是放到 extension/2114.example.com/ 下,面板不会覆盖。
在 server { } 里加一段只针对这个文件的替换规则:
location = /webclient-config/index.js {
proxy_pass http://127.0.0.1:21114;
proxy_set_header Accept-Encoding ""; # 让上游不要压缩,否则替换不生效
sub_filter "window.ws_host = '2114.example.com'"
"window.ws_host = 'wss://2114.example.com'";
sub_filter_types application/javascript; # 告诉 nginx 这个文件是 JS
sub_filter_once on; # 只替换第一次出现
}
逐行白话解释:
| 这一行 | 白话意思 |
|---|---|
| location = /webclient-config/index.js | 只精确匹配这一个文件,不影响其它请求 |
| proxy_pass http://127.0.0.1:21114 | 把请求转给本机的 API 服务 |
| proxy_set_header Accept-Encoding “” | 告诉后端“别压缩”,不然文本替换找不到目标 |
| sub_filter A B | 把文件里的 A 替换成 B |
| sub_filter_types application/javascript | 声明这个文件是 JS,默认只处理 HTML |
| sub_filter_once on | 只替换第一次出现的位置 |
5.3 操作步骤(照着做)
- SSH 登录服务器;
- 先备份原文件(出问题能马上回退);
- 编辑反代文件,把上面的 location 粘到
server { }里、其它 location 之前; - 执行
nginx -t,看到 syntax is ok 才继续; - 执行
nginx -s reload让配置生效; - 浏览器按
Ctrl+F5强刷(普通刷新会用缓存的旧文件); - 用 curl 验证
/ws/id返回 101。
# 1) 备份(文件名换成你自己的)
cp /www/server/panel/vhost/nginx/proxy/2114.example.com/xxxx.conf \
/root/xxxx.conf.bak-$(date +%F)
# 2) 检查语法
nginx -t
# 3) 平滑重载
nginx -s reload
# 4) 验证 WebSocket 握手
curl -sk --http1.1 -o /dev/null -w '%{http_code}\n' \
-H 'Connection: Upgrade' -H 'Upgrade: websocket' \
-H 'Sec-WebSocket-Version: 13' \
-H 'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==' \
https://2114.example.com/ws/id
# 期望输出:101
5.4 改前 / 改后对比
| 项目 | 改之前 | 改之后 |
|---|---|---|
| ws_host 的值 | 2114.example.com | wss://2114.example.com |
| 浏览器请求 | /webclient2/2114.example.com/ws/id → 404 | wss://2114.example.com/ws/id → 101 |
| 网页端表现 | 转圈、报 rendezvous 错误 | 正常登录、能看到设备、能连接 |
| PC 客户端 | 不受影响 | 不受影响 |
5.5 小白最容易踩的五个坑
- 没强刷:浏览器缓存了旧
index.js,改完看着没效果。用 Ctrl+F5 或无痕窗口再试。 - 忘了 Accept-Encoding “”:后端返回 gzip 压缩内容,sub_filter 替换不到,日志里看不到任何变化。
- 替换字符串不完全一致:单引号、空格、域名,差一个字符都替换不成功。先从浏览器直接打开
/webclient-config/index.js复制原文。 - 在宝塔面板重新保存反代:面板会重写 proxy 文件,手加的 location 丢了。自定义规则放
extension/目录。 - 只看页面不看日志:一定要用 curl 或访问日志确认 101/200,页面“看起来好了”不算数。
六、客户端怎么填
PC 客户端打开「设置 → 网络」:
- ID 服务器:
2116.example.com - 中继服务器:
2117.example.com - API 服务器(如果客户端版本支持):
https://2114.example.com - 「使用 WebSocket」不要勾:除非服务端和客户端版本都支持,否则会出现“连上又断开”。


七、故障排查:三个真实案例
案例 1:网页端报 Failed to connect to rendezvous server
现象:PC 客户端能连,网页端连不上。
排查:看浏览器请求路径、nginx 访问日志、以及 /ws/id 是否返回 101。多数是 /ws/id 没转发或 ws_host 缺协议头。
修复:补 nginx 的 /ws/id、/ws/relay,再按上一节修正 ws_host。
案例 2:PC 客户端报 Failed to secure tcp: deadline has elapsed

含义:TCP 连接建立成功了,但双方加密握手没有完成。常见原因有三类:
- 被控端没有真正注册到 hbbs(面板显示在线只是 API 心跳);
- 被控端在对称 NAT 后面,打洞失败又没有及时走中继;
- 两端版本或密钥不一致。
定位方法:
# 1) 看服务端日志里有没有该 ID 的注册记录
docker logs --since 30m rustdesk | grep update_pk
# 2) 看中继有没有配对记录
docker logs --since 30m rustdesk | grep -i relay
# 3) 看两端版本是否一致(管理台设备列表里有版本列)
如果是对称 NAT:在 compose 里加 ALWAYS_USE_RELAY=Y,让服务端直接告诉客户端“统一走中继”,重建容器即可。代价是所有流量都走服务器,带宽要够。
environment:
- ALWAYS_USE_RELAY=Y # 对称 NAT 环境强制走中继
案例 3:面板显示在线,但就是连不上
面板的“在线”来自客户端向 API 发的心跳,不等于它已经连上信令服务器。去被控端把 RustDesk 完全退出再启动,或重启 RustDesk Service,然后观察服务端日志里是否出现该 ID 的 update_pk。

八、安全加固清单
服务跑通只是开始,下面这些是我实际做完的加固项,按性价比排序。
1. 收口 21114
# compose 端口改为只绑本机
- "127.0.0.1:21114:21114"
# nginx 回源也改成本机
proxy_pass http://127.0.0.1:21114;
2. 登录限速 + fail2ban
# nginx:同一 IP 每分钟最多 10 次登录,超出返回 429
limit_req_zone $binary_remote_addr zone=rd_login:10m rate=10r/m;
location = /api/login {
limit_req zone=rd_login burst=5 nodelay;
limit_req_status 429;
proxy_pass http://127.0.0.1:21114;
}
# fail2ban:10 分钟错 5 次封 1 小时
[rustdesk-api]
enabled = true filter = rustdesk-api port = http,https logpath = /www/wwwlogs/2114.example.com.log maxretry = 5 findtime = 10m bantime = 1h

3. 只留 TLS 1.2/1.3
ssl_protocols TLSv1.2 TLSv1.3; # 去掉 TLSv1.1
4. 网页端限速与强制登录
网页端保持公开,但对接口和 WebSocket 限速;匿名访问 API 返回 401,必须登录才能用。
limit_req_zone $binary_remote_addr zone=rd_api:10m rate=50r/s;
limit_conn_zone $binary_remote_addr zone=rd_conn:10m;
location ^~ /api/ {
limit_req zone=rd_api burst=100 nodelay;
limit_conn rd_conn 40;
proxy_pass http://127.0.0.1:21114;
}
5. MUST_LOGIN 与 JWT
MUST_LOGIN=Y 会让所有客户端必须先登录才能用服务器,适合不对外的情况;JWT_KEY 一定要设成 32 位以上随机串,否则管理端 token 可被伪造。
6. Docker 侧
# 只给需要的端口放行;Docker 发布的端口不受 ufw 控制
iptables -I DOCKER-USER 1 -i eth0 -p tcp --dport 8080 -j DROP
# 日志轮转,避免单个容器日志撑满磁盘
# /etc/docker/daemon.json
{"log-driver":"json-file","log-opts":{"max-size":"50m","max-file":"3"}}
九、备份与回滚
每次改动前备份这几样,出问题能 5 分钟回退:
cp docker-compose.yml docker-compose.yml.bak-$(date +%F)
cp /www/server/panel/vhost/nginx/proxy/2114.example.com/*.conf /root/nginx-bak/
ufw status numbered > /root/ufw-$(date +%F).txt
# 证书与密钥目录
tar czf /root/rustdesk-data-$(date +%F).tgz /root/rustdesk/data
回滚顺序:先恢复文件,再 nginx -t && nginx -s reload;compose 改动则 docker compose up -d。
十、上线检查清单
| 检查项 | 怎么验证 |
|---|---|
| 容器状态 | docker ps 显示 healthy |
| 端口 | 21116 TCP/UDP、21117、21114 按需可达 |
| 21114 是否只绑本机 | ss -lntp | grep 21114 显示 127.0.0.1 |
| WebSocket | curl /ws/id 返回 101 |
| 网页端 | 浏览器打开 webclient2 能登录并连接 |
| 证书 | openssl x509 -enddate 未过期 |
| 登录限速 | 连续错误登录出现 429 |
| fail2ban | fail2ban-client status 有对应 jail |
| 备份 | compose 与 nginx 配置有 .bak 文件 |
十一、常见问题
Q:网页端能用,PC 客户端不能用?
浏览器只能走中继,PC 会先尝试直连。直连失败又没及时回退时,就会卡在握手;对称 NAT 环境建议开 ALWAYS_USE_RELAY。
Q:客户端勾了“使用 WebSocket”就连不上?
老版本服务端的 ws 实现和新版客户端不一致,勾了会“101 后立刻断开”。保持关闭即可,网页端不受影响。
Q:21114 关了,管理台还能用吗?
能。管理台走 443 的 nginx,回源到 127.0.0.1:21114,不需要公网直连 21114。
Q:需要开 2FA 吗?
被控端长期在线、暴露公网时值得开;代价是每次连接要输入手机上的动态码,手机丢失需要本地关闭。
本文基于真实环境整理,域名、ID、密码均已替换为示例值。按步骤操作前请先备份配置。
相关阅读:自建 RustDesk 远程桌面服务器
