RustDesk WebSocket (WSS) 配置教程

本教程将指导你使用 Nginx 为 RustDesk 服务端开启 WSS（WebSocket over HTTPS） 支持，让网页端（Web Client）可以通过 https:// 域名走加密的 WebSocket 连接。

一、为什么需要 WSS

场景	说明
Web Client（网页远程）	浏览器只能发起 HTTP/WebSocket 连接，必须通过 WSS 反代才能使用网页端远程
受限网络 / 防火墙	部分企业网络、校园网只放行 80/443 端口，WSS 可以复用 443 端口绕过去
HTTPS 加密传输	WebSocket 走 TLS 加密，避免中间人监听
统一域名入口	只需要一个域名 + 443 端口，无需暴露 21115-21119 等端口

端口对应关系

服务	本地端口	WSS 路径
API 服务	`21114`	`/`（HTTP 反代）
ID 服务（hbbs WebSocket）	`21118`	`/ws/id`
中继服务（hbbr WebSocket）	`21119`	`/ws/relay`

二、前置条件

在开始之前，请确保：

RustDesk 服务端已正常运行，21114、21118、21119 端口已在本地监听。
已安装 Nginx（本教程基于 Nginx 1.18+，需支持 proxy_socket_keepalive 指令）。
已准备好域名，并将域名 A 记录解析到服务器公网 IP。
已开放防火墙 / 安全组：80 与 443 端口。

检查本地端口监听

ss -tlnp | grep -E '21114|21118|21119'

如果只看到 127.0.0.1 监听，说明服务正常，只允许本机访问（这正是反向代理的正确姿势）。

三、获取 SSL 证书

Nginx 配置中的 ssl_certificate 和 ssl_certificate_key 需要指向有效的证书文件。推荐使用 Let's Encrypt 免费证书：

# 安装 certbot（以 Ubuntu/Debian 为例）
apt update && apt install -y nginx certbot python3-certbot-nginx

# 生成证书（自动申请并配置 Nginx）
certbot certonly --nginx -d your-domain.com

证书生成后位于：

/etc/letsencrypt/live/your-domain.com/fullchain.pem    # 证书文件
/etc/letsencrypt/live/your-domain.com/privkey.pem      # 私钥文件

多域名证书

如果有多个域名（例如 id.example.com、relay.example.com），可以一次性申请：

certbot certonly --nginx -d id.example.com -d relay.example.com

四、Nginx 配置（完整示例）

将以下配置保存为 /etc/nginx/conf.d/rustdesk-wss.conf（或放入 sites-available/ 并建立软链接），替换 your-domain.com 为你的域名、填写证书路径：

map $http_upgrade $rustdesk_connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:RustDeskTLS:10m;
    ssl_session_timeout 1d;

    location ^~ /ws/id {
        proxy_pass http://127.0.0.1:21118;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $rustdesk_connection_upgrade;
        proxy_socket_keepalive on;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_connect_timeout 10s;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
    location ^~ /ws/relay {
        proxy_pass http://127.0.0.1:21119;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $rustdesk_connection_upgrade;
        proxy_socket_keepalive on;
        proxy_buffering off;
        proxy_request_buffering off;
        proxy_connect_timeout 10s;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
    location / {
        proxy_pass http://127.0.0.1:21114;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_connect_timeout 10s;
        proxy_read_timeout 300s;
    }
}

五、配置逐段说明

1. map 指令（WebSocket 升级判断）

map $http_upgrade $rustdesk_connection_upgrade {
    default upgrade;
    ''      close;
}

当客户端请求头携带 Upgrade: websocket 时，$http_upgrade 非空，Connection 头被设置为 upgrade（保持 WebSocket 长连接）。
当普通 HTTP 请求（无 Upgrade 头）时，Connection 头被设置为 close（正常关闭），避免普通请求被误判为 WebSocket。

为什么不用 proxy_set_header Connection $http_upgrade;

很多网上教程直接写 Connection $http_upgrade，会导致普通 HTTP 请求的 Connection 头为空字符串，Nginx 可能报 upstream sent invalid header。使用 map 指令是更严谨的写法。

2. HTTP → HTTPS 跳转

server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

强制所有 HTTP 请求跳转到 HTTPS，保证 WebSocket 始终通过 WSS 加密传输。

3. SSL 配置

ssl_certificate     /etc/letsencrypt/live/your-domain.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;

证书与私钥路径替换为你自己的实际路径。
仅启用 TLS 1.2 / 1.3，禁用不安全的旧协议。

4. WebSocket 反代核心

以 /ws/id 为例：

location ^~ /ws/id {
    proxy_pass http://127.0.0.1:21118;
    proxy_http_version 1.1;                          # WebSocket 需要 HTTP/1.1
    proxy_set_header Upgrade $http_upgrade;          # 传递升级协议
    proxy_set_header Connection $rustdesk_connection_upgrade;  # map 判断后的 Connection
    proxy_socket_keepalive on;                       # 上游连接保活
    proxy_buffering off;                             # 禁用缓冲，实时转发
    proxy_request_buffering off;
    proxy_connect_timeout 10s;
    proxy_read_timeout 86400s;                       # 24h 长连接，远程会话保持
    proxy_send_timeout 86400s;
}

关键点

proxy_http_version 1.1：WebSocket 握手要求 HTTP/1.1，Nginx 默认 1.0 会导致握手失败。
proxy_read_timeout 86400s：远程控制会话可能持续数小时，超时时间必须足够长。
proxy_buffering off：实时转发数据，避免画面延迟。
^~ 前缀：优先匹配 /ws/id、/ws/relay 路径，避免被下方 location / 捕获。

5. API 反代

location / {
    proxy_pass http://127.0.0.1:21114;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto https;
}

API 服务使用普通 HTTP 反代，无需 WebSocket 升级。
传递真实客户端 IP（X-Real-IP、X-Forwarded-For）与协议（X-Forwarded-Proto: https），供服务端记录真实来源。

六、启用配置并验证

# 1. 检查配置语法
nginx -t

# 2. 重新加载配置
systemctl reload nginx   # 或 nginx -s reload

# 3. 验证 HTTPS 端口
curl -I https://your-domain.com

# 4. 验证 WebSocket 路径（应返回 101 Switching Protocols）
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" \
     -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
     https://your-domain.com/ws/id

预期输出：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

如果返回 400 或 502，说明 WebSocket 握手未成功。

七、客户端配置

WSS 配置完成后，客户端与服务端的配置如下：

服务端（RustDesk Console / hbbs 配置）

在 RustDesk 服务端配置中，将对外地址指向你的 HTTPS 域名：

ID 服务器：可以不填
中继服务器：可以不填
API 服务器：https://your-domain.com

客户端（Web Client 网页端）

打开浏览器访问 https://your-domain.com，使用账号登录。
网页端会自动通过 /ws/id、/ws/relay 建立 WSS 连接，即可远程控制已上线的设备。

桌面客户端

参考客户端配置教程填写 ID / 中继 / API 服务器与 Key。配置完成后状态显示 "就绪" 即表示连接成功。

一、为什么需要 WSS​

二、前置条件​

三、获取 SSL 证书​

四、Nginx 配置（完整示例）​

五、配置逐段说明​

1. map 指令（WebSocket 升级判断）​

2. HTTP → HTTPS 跳转​

3. SSL 配置​

4. WebSocket 反代核心​

5. API 反代​

六、启用配置并验证​

七、客户端配置​

服务端（RustDesk Console / hbbs 配置）​

客户端（Web Client 网页端）​

桌面客户端​