自建RustDesk服务后，怎么补上账号、地址簿和 API 后台？

6次阅读

没有评论

很多人自建 RustDesk，第一步会装 rustdesk-server。
装完以后，服务器上主要跑两个东西：

`hbbs`：ID / Rendezvous 服务，负责设备发现、注册、打洞；
`hbbr`：Relay 中继服务，直连不通时转发流量。

客户端填上 ID 服务器、中继服务器和 Key，远程连接能用了。

问题也从这里开始。

你会发现，免费版 rustdesk-server 解决的是“能不能连”。它不等于一套完整的账号系统。

如果你想要这些功能：

账号登录；
地址簿同步；
设备列表；
用户和分组；
后台管理；
登录日志、连接日志；
客户端里填写 API 服务器；

只装官方 RustDesk Server OSS 不够。

RustDesk 官方文档也把这个边界写得很清楚：OSS 更适合个人和团队免费自建，提供的是 hbbs 和 hbbr；Server Pro 才提供 Web console、API、设备管理、访问控制、多中继管理等集中管理能力。

这篇讲的就是中间那条路：

text

不买 Pro，也不只停留在 hbbs/hbbr。
用第三方 rustdesk-api，给免费自建 RustDesk 补上 API、账号、地址簿和后台。

本文只用脱敏示例。域名、IP、真实路径、真实账号、证书路径都用示例值代替。

先说清楚：这不是官方 API 服务器

这里用的是 lejianwen/rustdesk-api。

它不是 RustDesk 官方 Server Pro，也不是官方承诺的免费 API 后台。它是第三方开源项目，用 Go 实现 RustDesk 客户端需要的一部分 API，并提供 Web Admin、地址簿、用户、分组、设备管理等功能。

这个定位很重要。

你不能把它当成“官方 Pro 的免费平替”直接扔到公网裸跑。你应该把它当成一个给自建 RustDesk 补能力的组件：

text

官方 rustdesk-server OSS：负责 ID / 中继
rustdesk-api：负责账号 / 地址簿 / 后台 / API
Nginx 或 Caddy：负责 HTTPS 入口

这三层边界分清，后面才不会乱。

这篇适合谁

适合：

已经能自建 `hbbs/hbbr`，但想要地址簿和账号；
有几台家用电脑、公司电脑、NAS、服务器需要统一记录；
想给家人或小团队分账号；
想免费试用 API 后台能力；
能接受第三方开源项目带来的维护和兼容风险。

不适合：

需要官方商业支持；
需要稳定合规审计、企业 SSO、细粒度权限；
不想维护服务器和反代；
无法判断端口、防火墙、证书和服务日志。

如果是企业生产环境，RustDesk Server Pro 仍然是更稳的路线。本文的重点是个人、小团队、实验环境怎样把免费方案搭起来，并知道哪些地方不能乱开。

推荐架构：API 只监听本机，公网只走 HTTPS

我更建议用这个结构：

text

RustDesk 客户端
 ├─ 21116 TCP/UDP -> hbbs
 ├─ 21117 TCP     -> hbbr
 └─ HTTPS 443     -> Nginx/Caddy -> 127.0.0.1:21114 -> rustdesk-api

数据目录：
/var/lib/rustdesk-server/ hbbs/hbbr 数据和密钥
/opt/rustdesk-api/<version>/ API 程序
/var/lib/rustdesk-api/ API 数据库
/etc/rustdesk-api/config.yaml API 配置

核心原则只有几条：

`hbbs/hbbr` 继续负责远控链路；
`rustdesk-api` 单独存自己的数据库；
`21114` 不直接暴露公网；
API 通过 HTTPS 反代出去；
API 读取公钥即可，不要碰私钥；
原有 RustDesk Server 数据先备份，再改配置。

RustDesk 官方文档里常见端口是 TCP 21114-21119 和 UDP 21116。但你要注意：21114 在官方 Pro 里用于 API / Web console；在这里，我们让第三方 rustdesk-api 监听 21114，再由反代提供 HTTPS。

21118/21119 是 Web Client 相关端口。你不用浏览器远控，就先别开。

部署前只读检查

不要上来复制命令。

先确认现在服务器是什么状态：

bash

systemctl status rustdesk-hbbs rustdesk-hbbr --no-pager
ss -lntup | grep -E '2111[4-9]'
ls -l /var/lib/rustdesk-server/

你要看这些：

现在的 `hbbs/hbbr` 是 Docker、DEB，还是二进制；
服务名是不是 `rustdesk-hbbs`、`rustdesk-hbbr`；
数据目录在哪里；
`id_ed25519.pub` 公钥是否存在；
`id_ed25519` 私钥权限是否过宽；
`21114` 是否已被别的服务占用；
云安全组和系统防火墙放行了哪些端口。

建议先备份：

bash

sudo tar -czf ~/rustdesk-server-backup-$(date +%F).tgz /var/lib/rustdesk-server

如果你的路径不是 /var/lib/rustdesk-server，换成自己的实际目录。

方案一：二进制 + systemd

这个方案适合已有裸机 hbbs/hbbr 的服务器。

优点是边界清楚，回滚简单，不需要把现有服务迁进 Docker。

1. 下载并解压

以 rustdesk-api v2.7 为例。版本以后会变，部署前去 Release 页面核对最新版本和资产名称。

bash

sudo useradd -r -s /usr/sbin/nologin rustdesk-api
sudo mkdir -p /opt/rustdesk-api/v2.7 /etc/rustdesk-api /var/lib/rustdesk-api /var/log/rustdesk-api
sudo tar -xzf linux-amd64.tar.gz -C /opt/rustdesk-api/v2.7
sudo chown -R rustdesk-api:rustdesk-api /var/lib/rustdesk-api /var/log/rustdesk-api

文件名以你实际下载的包为准。

2. 写配置

示例只保留关键项：

yaml

app:
  web-client: 0
  register: false
  show-swagger: 0
  token-expire: 168h

gin:
api-addr: “127.0.0.1:21114”
mode: “release”
resources-path: “/opt/rustdesk-api/v2.7/resources”
trust-proxy: “127.0.0.1”

gorm:
type: “sqlite”

rustdesk:
id-server: “remote.example.com:21116”
relay-server: “remote.example.com:21117”
api-server: “https://remote.example.com”
key-file: “/var/lib/rustdesk-server/id_ed25519.pub”
personal: 1

jwt:
key: “”

这些配置先按保守方式来：

`web-client: 0`：先关浏览器远控；
`register: false`：先关公开注册；
`show-swagger: 0`：生产环境别公开接口文档；
`api-addr: 127.0.0.1:21114`：只给反代访问；
`gorm.type: sqlite`：个人和小团队够用；
`jwt.key: “”`：先不强制客户端必须登录。

先跑通，再加限制。

3. 建 systemd 服务

ini

[Unit]
Description=RustDesk API Server
Wants=network-online.target
After=network-online.target rustdesk-hbbs.service rustdesk-hbbr.service

[Service]
Type=simple
User=rustdesk-api
Group=rustdesk-api
WorkingDirectory=/var/lib/rustdesk-api
Environment=TZ=Asia/Shanghai
ExecStart=/opt/rustdesk-api/v2.7/apimain -c /etc/rustdesk-api/config.yaml
Restart=on-failure
RestartSec=5s
LimitNOFILE=65535
UMask=0077
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/rustdesk-api /var/log/rustdesk-api

[Install]
WantedBy=multi-user.target

启用：

bash

sudo systemctl daemon-reload
sudo systemctl enable --now rustdesk-api
sudo systemctl status rustdesk-api --no-pager

如果服务启动失败，先看日志：

bash

journalctl -u rustdesk-api -n 100 --no-pager

4. 反代 HTTPS

Nginx 示例：

nginx

server {
    listen 443 ssl http2;
    server_name remote.example.com;

ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;

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 $scheme;
proxy_read_timeout 120s;
proxy_send_timeout 120s;
}
}

后台通常访问：

text

https://remote.example.com/_admin/

方案二：Docker / Docker Compose

新服务器、测试环境，或者你想少碰 systemd，可以用 Docker Compose。

如果只补 rustdesk-api，现有 hbbs/hbbr 仍在宿主机上，可以这样：

yaml

services:
  rustdesk-api:
    image: lejianwen/rustdesk-api:latest
    container_name: rustdesk-api
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai
      - RUSTDESK_API_LANG=zh-CN
      - RUSTDESK_API_APP_WEB_CLIENT=0
      - RUSTDESK_API_APP_REGISTER=false
      - RUSTDESK_API_APP_SHOW_SWAGGER=0
      - RUSTDESK_API_GIN_API_ADDR=0.0.0.0:21114
      - RUSTDESK_API_GORM_TYPE=sqlite
      - RUSTDESK_API_RUSTDESK_ID_SERVER=remote.example.com:21116
      - RUSTDESK_API_RUSTDESK_RELAY_SERVER=remote.example.com:21117
      - RUSTDESK_API_RUSTDESK_API_SERVER=https://remote.example.com
      - RUSTDESK_API_RUSTDESK_KEY_FILE=/data/id_ed25519.pub
      - RUSTDESK_API_JWT_KEY=
    volumes:
      - ./api-data:/app/data
      - ./server-data/id_ed25519.pub:/data/id_ed25519.pub:ro
    ports:
      - "127.0.0.1:21114:21114"

注意两点：

`GIN_API_ADDR` 在容器里可以是 `0.0.0.0:21114`，但宿主机端口映射仍然绑定到 `127.0.0.1`。
`id_ed25519.pub` 只读挂载，别把私钥挂进去。

如果你想把 hbbs/hbbr 和 API 一起容器化，可以用作者提供的 rustdesk-server-s6 一体方案。

一体方案适合新部署。迁移已有裸机服务时，要先确认旧数据、密钥、端口和客户端配置，不要直接覆盖。

部署后先看账号密码

打开后台：

text

https://remote.example.com/_admin/

rustdesk-api README 里写到，后台地址是 /_admin/。初次安装管理员用户名是 admin，密码会在控制台打印，也可以通过命令重置。有些位置还能看到“默认用户名密码为 admin”的旧描述，不要死记这个。

二进制部署看日志：

bash

journalctl -u rustdesk-api -n 100 --no-pager

Docker 部署看日志：

bash

docker compose logs --tail=100 rustdesk-api

如果没找到初始密码，直接重置：

bash

/opt/rustdesk-api/v2.7/apimain -c /etc/rustdesk-api/config.yaml reset-admin-pwd '新密码'

Docker 里进入容器执行对应命令，路径以镜像内实际文件为准。

第一次登录后做四件事：

改管理员密码；
关闭公开注册；
确认 ID Server、Relay Server、API Server；
确认返回给客户端的 Key 和 `id_ed25519.pub` 一致。

客户端要怎么填

RustDesk 客户端常见配置：

text

ID服务器：remote.example.com
中继服务器：remote.example.com
API服务器：https://remote.example.com
Key：id_ed25519.pub 里的公钥

如果你用了非默认端口，要写端口：

text

ID服务器：remote.example.com:21116
中继服务器：remote.example.com:21117
API服务器：https://remote.example.com

测试时别只看“能不能远程”。

要分开测：

不登录账号，只填 ID/Relay/Key，能不能连；
登录 API 账号后，地址簿能不能同步；
直连能不能成功；
中继能不能成功；
服务重启后，客户端能不能恢复；
手机热点、异地宽带、公司网络下能不能连。

哪些内容可以改

这些可以按自己的环境改：

配置	能改什么	改错会怎样
`id-server`	ID 服务器地址和端口	客户端找不到设备
`relay-server`	中继服务器地址和端口	直连失败时无法中继
`api-server`	API HTTPS 地址	客户端登录和地址簿失败
`key-file`	公钥文件路径	客户端 Key 对不上
`web-client`	是否启用浏览器远控	开了就要额外处理 WebSocket 端口
`register`	是否允许公开注册	开错会让陌生人注册账号
`show-swagger`	是否显示接口文档	生产环境暴露接口信息
`gorm.type`	SQLite / MySQL 等数据库	迁移和备份方式不同
`jwt.key`	是否配合强制登录	配错会导致登录或连接异常

个人或小团队建议先这样：

text

web-client: 0
register: false
show-swagger: 0
jwt.key: ""
api-addr: 127.0.0.1:21114

先把账号、地址簿和后台跑通。

哪些内容不要乱改

这些先别动：

现有 `hbbs/hbbr` 的密钥；
原有 `id_ed25519` 私钥；
已在线客户端正在使用的 Key；
正在使用的服务端口；
云安全组里已经验证过的端口策略；
现有生产数据目录。

最容易翻车的是两件事：

第一，重新生成 RustDesk Server 密钥。
客户端里的 Key 会对不上，原来能连的设备可能突然连不上。

第二，强制登录和 JWT 一起乱开。
客户端版本、服务端分支、API 配置没对齐时，会出现“后台能登录，客户端连不上”。

MUST_LOGIN、Web Client、JWT 怎么理解

MUST_LOGIN=N

客户端不登录 API 账号，也能继续使用 ID/Relay。

这适合平滑迁移：原来只填服务器和 Key 的客户端不会立刻失效。

它不等于任何人都能控制你的电脑。目标设备仍需要临时确认、永久密码或系统权限。

关闭 Web Client

关闭的是浏览器远控。

它不影响：

桌面客户端；
移动客户端；
管理后台；
地址簿和用户 API。

官方 Docker 文档提醒，Web Client 相关 21118/21119 端口涉及反代和来源 IP 处理风险。不用 Web Client，就先关。

暂不启用 JWT

JWT 用来让 API 和支持该机制的服务端一起验证登录状态。

如果你要强制登录，通常要同时满足：

text

MUST_LOGIN=Y
rustdesk-server 支持并读取同一 JWT key
rustdesk-api 配置同一 JWT key
客户端版本兼容

只改一项，容易变成“后台能登录，客户端不能连”。

所以第一次部署建议用兼容模式跑通，再考虑强制登录。

用户、地址簿和设备别混在一起

API 后台能管用户、地址簿、设备和分组。但它们不是一回事。

用户：谁能登录 API；
设备：客户端上报或后台记录的机器；
地址簿：用户看到和保存的远程条目；
分组：管理用户和共享范围。

普通用户默认只看自己的设备和地址簿。管理员能看到更多后台数据。

如果你想让家人或同事只看到自己的设备，不要把所有人都放进共享组，也不要随手给管理员权限。

设备名里出现的 某某@主机名，可能只是被控电脑的系统用户名，不一定是 API 账号。

最后检查清单

部署前：

已确认 OSS / Pro / 第三方 API 的边界；
已备份 RustDesk Server 数据目录；
已找到 `id_ed25519.pub`；
已确认 `21114` 没被占用；
已确认防火墙和云安全组；
已准备回滚命令。

部署中：

API 只监听本机或内网；
SQLite 数据目录可写；
反代带上 `Host` 和 `X-Forwarded-Proto`；
公开注册关闭；
Web Client 先关闭；
Swagger 先关闭；
JWT 先不启用。

部署后：

后台能打开；
管理员能登录；
已修改管理员密码；
API 返回的 ID/Relay/API/Key 正确；
未登录客户端仍能连；
登录账号后地址簿同步；
`21116/udp` 没漏；
服务没有循环重启；
日志没有 panic、fatal、数据库写入失败。

怎么选

第一次搭建，先用 Docker Compose，快。

已有稳定裸机 hbbs/hbbr，我会用二进制 + systemd，只补 API，不碰原来的 Server。

需要官方支持、企业审计、LDAP/OIDC、访问控制和长期稳定性，就别绕，直接评估 Server Pro。

第三方 rustdesk-api 的价值很明确：它让个人和小团队免费用上账号、地址簿、API 后台这些能力。

它的边界也很明确：你要自己承担维护、升级、兼容和安全配置。

把这两点想清楚，再部署。

参考资料

RustDesk 官方 Self-host 文档：https://rustdesk.com/docs/en/self-host/
RustDesk Server OSS Docker 文档：https://rustdesk.com/docs/en/self-host/rustdesk-server-oss/docker/
RustDesk Server Pro 文档：https://rustdesk.com/docs/en/self-host/rustdesk-server-pro/
`lejianwen/rustdesk-api` README：https://github.com/lejianwen/rustdesk-api
`lejianwen/rustdesk-api` Releases：https://github.com/lejianwen/rustdesk-api/releases
`lejianwen/rustdesk-server` README：https://github.com/lejianwen/rustdesk-server