RustDesk 第三方 API 完整安装指南

涉及项目：

RustDesk Server（修改版）：lejianwen/rustdesk-server
RustDesk API：lejianwen/rustdesk-api

一、整体架构与 Key 的原理

组件关系

RustDesk 客户端
     │
     ├─── hbbs（ID/会合服务器，端口 21116）
     ├─── hbbr（中继服务器，端口 21117）
     └─── rustdesk-api（API/管理后台，端口 21114）

Key 的本质

hbbs 启动时会生成一对 ED25519 密钥：

文件	内容	用途
`id_ed25519`	私钥	hbbs 内部加密用，绝不对外
`id_ed25519.pub`	公钥（base64 字符串）	客户端验证服务器身份用

以下三处的 Key 必须完全一致，否则连接时报 invalid public key：

hbbs 实际使用的密钥对（id_ed25519.pub 的内容）
config.yaml 中 rustdesk.key 的值
RustDesk 客户端网络设置中的 Key 字段

二、关于自定义 Key

结论

可以自定义 Key，但必须是合法的 ED25519 密钥对，不能是任意字符串。 hbbs 在握手时会用私钥签名，客户端用公钥验签。如果 Key 不是真正的 ED25519 公钥，握手必然失败。12356789 这类字符串只是 hbbs 的启动参数（-k），用于限制谁能连接，不等于 id_ed25519.pub 的内容。

自定义 Key 的方式

使用 rustdesk-utils 工具生成合法的密钥对： bash

# 方式一：用 Docker 生成（无需安装任何工具）
docker run --rm --entrypoint /usr/bin/rustdesk-utils \
  lejianwen/rustdesk-server-s6:latest genkeypair

输出示例：

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

然后在 hbbs 启动时通过环境变量指定密钥对（见下方安装步骤），这样就实现了"自定义 Key"。

三、安装 RustDesk Server（hbbs + hbbr）

强烈推荐使用 lejianwen/rustdesk-server，该 fork 修复了与 API 配合使用时的连接超时问题，并支持强制登录和 WebSocket。

方式一：二进制直接运行（Linux）

从 Releases 下载 hbbs 和 hbbr，放到同一目录： bash

# 创建数据目录
mkdir -p /opt/rustdesk/server
cd /opt/rustdesk/server

# 启动 hbbr（中继服务器），先启动
./hbbr &

# 启动 hbbs（ID 服务器）
# -r 指定中继服务器地址
# 不加 -k 参数则自动生成密钥对
./hbbs -r <你的服务器IP或域名>:21117 &

hbbs 首次启动后，在当前目录自动生成：

id_ed25519        ← 私钥
id_ed25519.pub    ← 公钥（后续需要用到）

若要使用自定义密钥对（先用 genkeypair 生成后）： bash

# 把生成的公钥写入文件
echo "8BLLhtzUBU/XKAH4mep3p+IX4DSApe7qbAwNH9nv4yA=" > id_ed25519.pub
# 把生成的私钥写入文件
echo "egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hfgNICl7upsDA0f2e/jIA==" > id_ed25519

# 启动时用 KEY 环境变量指定（hbbs 会优先使用已存在的密钥文件）
./hbbs -r <你的服务器IP或域名>:21117

方式二：Windows 安装

从 Releases 下载 Windows 压缩包（windows-amd64.zip），解压后包含：

hbbs.exe
hbbr.exe
RustDeskServer.Setup.exe   ← 图形化安装程序（内置 NSSM）
rustdesk-utils.exe

子方式 A：使用 RustDeskServer.Setup.exe 安装（简单）

该安装程序内部使用 NSSM 将 hbbs/hbbr 注册为 Windows 服务，适合快速部署。注意：部分杀毒软件可能误报，这是因为安装包内置了 NSSM，属于误判，可加入白名单。

以管理员身份运行 RustDeskServer.Setup.exe
按提示完成安装，程序会自动将 hbbs 和 hbbr 注册为 Windows 服务并启动
默认安装目录为 C:\Program Files\RustDesk Server\，密钥文件生成在该目录下

安装完成后查看密钥文件：可以在rustdeskserver控制台直接查看:

或者 powershell

type "C:\Program Files\RustDesk Server\id_ed25519.pub"

若需修改 hbbs 的启动参数（如指定中继服务器地址），在服务管理器中找到 hbbs 服务，或使用 NSSM 编辑： powershell

# 管理员 PowerShell
nssm edit hbbs

在弹出的 GUI 中修改 Arguments 字段，添加 -r <你的服务器IP或域名>:21117，保存后重启服务。

子方式 B：手动使用 NSSM 安装为服务（灵活）

适合需要自定义安装目录、启动参数或已有解压好的二进制文件的场景。 第一步：准备文件 创建工作目录，例如 C:\rustdesk-server\，将解压出的 hbbs.exe 和 hbbr.exe 放入其中：

C:\rustdesk-server\
├── hbbs.exe
├── hbbr.exe
└── data\          ← 密钥文件将生成在此（首次运行后）

第二步：下载 NSSM 从 https://nssm.cc/download 下载最新版，解压后取出对应架构的 nssm.exe：

nssm-2.24\
├── win32\nssm.exe
└── win64\nssm.exe   ← 64位系统使用这个

将 nssm.exe 复制到 C:\rustdesk-server\，或放入已在 PATH 中的目录（如 C:\Windows\System32\）。 第三步：注册 hbbr 服务 以管理员身份打开 PowerShell 或 CMD，执行： powershell

# 注册 hbbr 服务
nssm install rustdesk-hbbr "C:\rustdesk-server\hbbr.exe"

# 设置工作目录（密钥文件会生成在这里）
nssm set rustdesk-hbbr AppDirectory "C:\rustdesk-server"

# 配置日志输出
nssm set rustdesk-hbbr AppStdout "C:\rustdesk-server\hbbr.log"
nssm set rustdesk-hbbr AppStderr "C:\rustdesk-server\hbbr.log"

# 设置开机自启
nssm set rustdesk-hbbr Start SERVICE_AUTO_START

# 启动服务
nssm start rustdesk-hbbr

第四步：注册 hbbs 服务 powershell

# 注册 hbbs 服务，-r 指定中继服务器地址
nssm install rustdesk-hbbs "C:\rustdesk-server\hbbs.exe"

# 设置启动参数（替换为你的服务器 IP 或域名）
nssm set rustdesk-hbbs AppParameters "-r <你的服务器IP或域名>:21117"

# 设置工作目录（与 hbbr 相同，共享密钥文件）
nssm set rustdesk-hbbs AppDirectory "C:\rustdesk-server"

# 配置日志输出
nssm set rustdesk-hbbs AppStdout "C:\rustdesk-server\hbbs.log"
nssm set rustdesk-hbbs AppStderr "C:\rustdesk-server\hbbs.log"

# 设置开机自启
nssm set rustdesk-hbbs Start SERVICE_AUTO_START

# 启动服务（先启动 hbbr 再启动 hbbs）
nssm start rustdesk-hbbs

第五步：查看生成的密钥文件 hbbs 首次启动后，在 AppDirectory（即 C:\rustdesk-server\）下自动生成：

C:\rustdesk-server\
├── id_ed25519        ← 私钥
├── id_ed25519.pub    ← 公钥（记下其内容，后续配置需要用到）
└── db_v2.sqlite3

查看公钥内容： powershell

type C:\rustdesk-server\id_ed25519.pub

常用 NSSM 管理命令： powershell

nssm status rustdesk-hbbs       # 查看服务状态
nssm restart rustdesk-hbbs      # 重启服务
nssm stop rustdesk-hbbs         # 停止服务
nssm edit rustdesk-hbbs         # 打开 GUI 编辑服务配置
nssm remove rustdesk-hbbs confirm  # 删除服务

也可以在 Windows 服务管理器（services.msc）中找到 rustdesk-hbbs 和 rustdesk-hbbr 进行管理。

Windows 下使用自定义密钥对： 先用 Docker 或其他方式生成密钥对（见第二节），然后在首次启动 hbbs 之前将密钥文件放入工作目录： powershell

# 将公钥内容写入文件（替换为你生成的实际值）
echo 8BLLhtzUBU/XKAH4mep3p+IX4DSApe7qbAwNH9nv4yA= > C:\rustdesk-server\id_ed25519.pub
echo egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hfgNICl7upsDA0f2e/jIA== > C:\rustdesk-server\id_ed25519

注意：Windows 的 echo 命令会在文件末尾加换行，hbbs 读取时能正确处理。若担心格式问题，可用记事本手动创建这两个文件，确保内容只有一行 base64 字符串，不含多余空格。

方式三：Docker Compose（推荐）

使用官方镜像 + 独立 API 容器： yaml

# docker-compose.yml
networks:
  rustdesk-net:
    external: false

services:
  hbbs:
    container_name: hbbs
    image: lejianwen/rustdesk-server:latest
    command: hbbs -r <你的服务器IP或域名>:21117
    ports:
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21118:21118
    volumes:
      - /data/rustdesk/server:/root   # 密钥文件生成在这里
    networks:
      - rustdesk-net
    depends_on:
      - hbbr
    restart: unless-stopped

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

  rustdesk-api:
    container_name: rustdesk-api
    image: lejianwen/rustdesk-api
    ports:
      - 21114:21114
    environment:
      - TZ=Asia/Shanghai
      - RUSTDESK_API_RUSTDESK_ID_SERVER=<你的服务器IP或域名>:21116
      - RUSTDESK_API_RUSTDESK_RELAY_SERVER=<你的服务器IP或域名>:21117
      - RUSTDESK_API_RUSTDESK_API_SERVER=http://<你的服务器IP或域名>:21114
      # 方式A：直接填公钥内容（与下方 key-file 挂载二选一）
      #- RUSTDESK_API_RUSTDESK_KEY=<id_ed25519.pub 的内容>
    volumes:
      - /data/rustdesk/api:/app/data          # API 数据库
      - /data/rustdesk/server:/app/conf/data  # 挂载 server 目录，让 API 自动读取 id_ed25519.pub
    networks:
      - rustdesk-net
    depends_on:
      - hbbs
      - hbbr
    restart: unless-stopped

注意：通过挂载 /data/rustdesk/server 到 /app/conf/data，API 容器可以直接读取 id_ed25519.pub，不需要额外配置 KEY 环境变量。

方式四：一体化 S6 镜像（最简单，仅 Linux）

hbbs + hbbr + API 合并在一个容器中： yaml

# docker-compose.yml
networks:
  rustdesk-net:
    external: false

services:
  rustdesk:
    image: lejianwen/rustdesk-server-s6:latest
    ports:
      - 21114:21114
      - 21115:21115
      - 21116:21116
      - 21116:21116/udp
      - 21117:21117
      - 21118:21118
      - 21119:21119
    environment:
      - RELAY=<你的服务器IP或域名>:21117
      - ENCRYPTED_ONLY=1
      - MUST_LOGIN=N           # Y=必须登录API才能发起连接，N=不限制
      - TZ=Asia/Shanghai
      - RUSTDESK_API_RUSTDESK_ID_SERVER=<你的服务器IP或域名>:21116
      - RUSTDESK_API_RUSTDESK_RELAY_SERVER=<你的服务器IP或域名>:21117
      - RUSTDESK_API_RUSTDESK_API_SERVER=http://<你的服务器IP或域名>:21114
      - RUSTDESK_API_KEY_FILE=/data/id_ed25519.pub  # 自动读取生成的公钥
      - RUSTDESK_API_JWT_KEY=your_random_jwt_secret
    volumes:
      - /data/rustdesk/server:/data       # hbbs 密钥和数据
      - /data/rustdesk/api:/app/data      # API 数据库
    networks:
      - rustdesk-net
    restart: unless-stopped

若要使用自定义密钥对，在启动前先将生成的密钥文件放入 /data/rustdesk/server/： bash

mkdir -p /data/rustdesk/server
echo "<你的 Public Key>" > /data/rustdesk/server/id_ed25519.pub
echo "<你的 Secret Key>" > /data/rustdesk/server/id_ed25519

四、安装 rustdesk-api（二进制方式）

1. 下载

从 rustdesk-api Releases 下载对应平台的压缩包，解压后目录结构：

release/
├── apimain（或 apimain.exe）
├── conf/
│   └── config.yaml
└── resources/

2. 配置 config.yaml

yaml

rustdesk:
  id-server: "<你的服务器IP或域名>:21116"
  relay-server: "<你的服务器IP或域名>:21117"
  api-server: "http://<你的服务器IP或域名>:21114"

  # 【二选一】
  # 方式A：直接填 id_ed25519.pub 的文件内容（推荐）
  key: "UzIFFYN6anQWt4042DNFWOlahpnc3Nwzidr2AE5A+6k="
  key-file: ""

  # 方式B：填 pub 文件路径，key 留空（注意：key 不为空时 key-file 会被忽略）
  # key: ""
  # key-file: "./data/id_ed25519.pub"

  personal: 1

重要：key 和 key-file 的优先级——源码中若 key 不为空则直接使用，key-file 被忽略。两者只填其一即可。

3. 运行

bash

# 必须在 release 目录下运行
cd release
./apimain

# 或指定配置文件（在其他目录运行时）
RUSTDESK_API_GIN_RESOURCES_PATH=/opt/rustdesk-api/resources \
  ./apimain -c /opt/rustdesk-api/conf/config.yaml

首次运行会在控制台打印初始管理员密码，请及时保存：

Admin password: xxxxxxxx

重置管理员密码： bash

./apimain reset-admin-pwd <新密码>

五、配置 RustDesk 客户端

打开 RustDesk → 网络设置，填写：

字段	填写内容
ID 服务器	`<你的服务器IP或域名>`
中继服务器	`<你的服务器IP或域名>`
API 服务器	`http://<你的服务器IP或域名>:21114`
Key	`<id_ed25519.pub 的文件内容>`

Key 必须与 config.yaml 中 rustdesk.key 的值完全一致。

六、验证安装

访问管理后台：http://<你的服务器IP或域名>:21114/_admin/
用 admin 账号和控制台打印的初始密码登录
在 RustDesk 客户端登录 API 账号，尝试连接另一台设备
连接正常则说明安装成功

七、开放端口说明

端口	协议	用途
21114	TCP	API / Web 管理后台
21115	TCP	NAT 类型检测
21116	TCP/UDP	ID 注册与心跳（hbbs）
21117	TCP	中继转发（hbbr）
21118	TCP	WebSocket（hbbs）
21119	TCP	WebSocket（hbbr）

八、常见问题

Q：报错 invalid public key from rendezvous server 客户端收到的 hbbs 公钥与客户端配置的 Key 不匹配。排查顺序：

查看 hbbs 实际使用的公钥：cat /data/rustdesk/server/id_ed25519.pub
确认 config.yaml 的 rustdesk.key 值与上述内容一致
确认 RustDesk 客户端 Key 字段也是同一个值
不要手动修改 id_ed25519.pub，内容必须与 id_ed25519 私钥匹配

Q：key-file 配置了但没生效 key 字段不为空时，key-file 会被忽略（源码逻辑）。两者选一填写：要么填 key，要么 key 留空再填 key-file。 Q：连接超时 使用 lejianwen/rustdesk-server 或 lejianwen/rustdesk-server-s6 镜像，该 fork 专门修复了 API 配合使用时的连接超时问题。官方 rustdesk/rustdesk-server 镜像与第三方 API 配合时存在此问题。 Q：能否强制用户必须登录 API 才能远程连接 使用 S6 镜像时，设置环境变量 MUST_LOGIN=Y 即可。

烂笔记 - letvar's blog