docs: restructure README - put our modifications first, add build steps
This commit is contained in:
admin committed
1 parent
18a966c28e
commit
4db4504f9b
1 file changed
+422
-302
@@ -8,6 +8,428 @@
|
|||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 本仓库修改
|
||||||
|
|
||||||
|
## 编译与打包步骤
|
||||||
|
|
||||||
|
### 1. 编译服务器二进制（hbbs / hbbr / rustdesk-utils）
|
||||||
|
|
||||||
|
使用持久化 Rust 容器编译：
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# 启动编译容器
|
||||||
|
docker run -d --name rustbuild --network host \
|
||||||
|
-v /root/rustdesk/lejianwen/rustdesk-server:/srv -w /srv rust:alpine sleep infinity
|
||||||
|
|
||||||
|
# 容器内：换阿里云 apk 源
|
||||||
|
printf 'https://mirrors.aliyun.com/alpine/v3.24/main\nhttps://mirrors.aliyun.com/alpine/v3.24/community\n' > /etc/apk/repositories
|
||||||
|
|
||||||
|
# 安装依赖
|
||||||
|
apk add build-base pkgconf openssl-dev openssl-libs-static git
|
||||||
|
|
||||||
|
# 配置 cargo（rsproxy 源 + CLI git fetch）
|
||||||
|
# /usr/local/cargo/config.toml:
|
||||||
|
# [source.crates-io] replace-with = "rsproxy-sparse"
|
||||||
|
# [source.rsproxy-sparse] registry = "sparse+https://rsproxy.cn/index/"
|
||||||
|
# [net] git-fetch-with-cli = true
|
||||||
|
|
||||||
|
# GitHub 加速（容器内系统级改写）
|
||||||
|
git config --system url.'https://gh-proxy.com/https://github.com/'.insteadOf 'https://github.com/'
|
||||||
|
|
||||||
|
# 编译
|
||||||
|
docker exec rustbuild cargo build --release
|
||||||
|
```
|
||||||
|
|
||||||
|
编译产物：`target/release/hbbs`、`target/release/hbbr`、`target/release/rustdesk-utils`
|
||||||
|
|
||||||
|
### 2. 构建 s6 基础镜像
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# 拷贝二进制到 rootfs
|
||||||
|
docker cp rustbuild:/srv/target/release/hbbs /root/rustdesk/build/s6img/rootfs/usr/bin/
|
||||||
|
docker cp rustbuild:/srv/target/release/hbbr /root/rustdesk/build/s6img/rootfs/usr/bin/
|
||||||
|
docker cp rustbuild:/srv/target/release/rustdesk-utils /root/rustdesk/build/s6img/rootfs/usr/bin/
|
||||||
|
|
||||||
|
# 构建镜像（必须 --no-cache，否则 COPY rootfs 走缓存）
|
||||||
|
docker build --no-cache \
|
||||||
|
-f /root/rustdesk/build/s6img/Dockerfile.local \
|
||||||
|
-t rustdesk-server-s6:1.1.17-forapi \
|
||||||
|
/root/rustdesk/build/s6img
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 编译 API 二进制（apimain）
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# 启动 Go 编译容器
|
||||||
|
docker run -d --name gobuild --network host \
|
||||||
|
-v /root/rustdesk/build/apibuild:/srv -w /srv golang:1.23-alpine sleep infinity
|
||||||
|
|
||||||
|
# 安装 git + gcc（CGO 静态编译需要）
|
||||||
|
docker exec gobuild apk add --no-cache git gcc musl-dev
|
||||||
|
|
||||||
|
# 设置 Go 代理（直连 GitHub 或国内镜像）
|
||||||
|
docker exec gobuild go env -w GOPROXY=https://goproxy.cn,direct
|
||||||
|
|
||||||
|
# 编译（CGO 静态编译）
|
||||||
|
docker exec gobuild env CGO_ENABLED=1 GOOS=linux GOARCH=amd64 CC=gcc \
|
||||||
|
go build -ldflags '-s -w' -o ./amd64/release/apimain ./cmd/apimain.go
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 构建 admin 前端
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# admin 前端来自 lejianwen/rustdesk-api-web
|
||||||
|
git clone --depth 1 -b master https://gh-proxy.com/https://github.com/lejianwen/rustdesk-api-web
|
||||||
|
docker run --rm -v $PWD:/srv -w /srv node:20-alpine sh -c \
|
||||||
|
"npm config set registry https://registry.npmmirror.com && npm install && npm run build"
|
||||||
|
cp -a rustdesk-api-web/dist/. /root/rustdesk/build/apibuild/resources/admin/
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. 打完整镜像
|
||||||
|
|
||||||
|
```sh
|
||||||
|
# 修改 Dockerfile_full_s6 首行，指向本地 s6 基础镜像
|
||||||
|
cp /root/rustdesk/build/apibuild/Dockerfile_full_s6 /tmp/Dockerfile_full_s6
|
||||||
|
sed -i 's|FROM rustdesk/rustdesk-server-s6:latest AS server|FROM rustdesk-server-s6:1.1.17-forapi AS server|' /tmp/Dockerfile_full_s6
|
||||||
|
|
||||||
|
# 构建（context 必须含 amd64/release）
|
||||||
|
docker build -f /tmp/Dockerfile_full_s6 \
|
||||||
|
--build-arg BUILDARCH=amd64 \
|
||||||
|
-t yangjieshao/rustdesk-api:full-s6-amd64 \
|
||||||
|
/root/rustdesk/build/apibuild
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. 验证运行
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker run -d --name rustdesk-test -p 21114-21119:21114-21119 \
|
||||||
|
-p 21116:21116/udp \
|
||||||
|
-e RELAY=<IP[:21117]> \
|
||||||
|
-v <data>:/data -v <appdata>:/app/data \
|
||||||
|
yangjieshao/rustdesk-api:full-s6-amd64
|
||||||
|
|
||||||
|
curl -s http://127.0.0.1:21114/_admin/ -o /dev/null -w '%{http_code}\n'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 构建产物
|
||||||
|
|
||||||
|
| 镜像 | 说明 |
|
||||||
|
|---|---|
|
||||||
|
| `rustdesk-server-s6:1.1.17-forapi` | s6 基础镜像（hbbs + hbbr + rustdesk-utils） |
|
||||||
|
| `yangjieshao/rustdesk-api:full-s6-amd64` | 完整镜像（+ apimain + admin 前端，s6 托管） |
|
||||||
|
|
||||||
|
| SINGLE_BANDWIDTH | hbbr | 单个连接的最大带宽（以Mb/s为单位） |
|
||||||
|
| TOTAL_BANDWIDTH | hbbr | 最大总带宽（以Mb/s为单位） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 1.1.17 合并记录
|
||||||
|
|
||||||
|
> 日期：2026-09-05
|
||||||
|
> 关联文档：[lejianwen/rustdesk-api README](https://github.com/lejianwen/rustdesk-api)
|
||||||
|
> 说明：将官方 `rustdesk/rustdesk-server` 1.1.17 合并到本仓库（forapi 分支），完整构建记录见 [lejianwen/rustdesk-api README](https://github.com/lejianwen/rustdesk-api)。
|
||||||
|
|
||||||
|
## 合并要点
|
||||||
|
|
||||||
|
- 官方 1.1.14（merge-base `c650217`）→ 1.1.17，共 43 个上游提交
|
||||||
|
- **安全**：禁用 UDP 打洞反射/放大路径（`PunchHoleRequest`/`PunchHoleSent`/`LocalAddr` 只允许走 TCP/WS）
|
||||||
|
- **功能**：`-b/--bind` 绑定指定 IP；控制台监听独立绑到 127.0.0.1；`punch-requests(pr)` 连接日志控制台命令
|
||||||
|
- **修复**：在线状态 `i32` 溢出（运行 24.9~49.7 天后误报在线）；中继限速默认值 4Mb/s → 32Mb/s
|
||||||
|
- **依赖**：`hbb_common` 子模块推进到 `69cea8d`、新增 `flate2`
|
||||||
|
|
||||||
|
## 冲突处理
|
||||||
|
|
||||||
|
| 冲突文件 | 处理方式 |
|
||||||
|
|---|---|
|
||||||
|
| `src/rendezvous_server.rs` | 保留 fork 的 JWT/必须登录/KeyExchange/加密 Sink/API 特性，叠加上游全部修复，共 4 处冲突块手动合并 |
|
||||||
|
| `src/main.rs` | 双方参数合并：上游的 `--bind` + DEPRECATED 标注，保留 fork 的 `--must-login` |
|
||||||
|
| `libs/hbb_common`（子模块） | 从 fork 的旧提交直接指到官方 1.1.17 用的 `69cea8d` |
|
||||||
|
| `Cargo.toml` / `Cargo.lock` | git 自动合并成功 |
|
||||||
|
|
||||||
|
**注意点**：
|
||||||
|
- fork 侧 `check_cmd` 帮助文本比上游多一行 `must-login`，合并 `punch-requests` 时要同步把 format! 占位符从 7 个加到 8 个，**否则编译报 `argument never used`**
|
||||||
|
- 上游的 `peers_online_state` 是内联代码，fork 抽成了 helper（`handle_online_request` 复用），合并时保留 helper 并把 `as i32` 改 `as i64`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# 自连拦截（A 远程连 A）服务器端方案
|
||||||
|
|
||||||
|
> 状态：**已实施并通过端到端验证**（2026-09-06）
|
||||||
|
> 日期：2026-09-05 设计 / 2026-09-06 实施
|
||||||
|
> 关联文档：[lejianwen/rustdesk-api README](https://github.com/lejianwen/rustdesk-api)
|
||||||
|
>
|
||||||
|
> v2 变更：经用户提示，发现 API 的 `UserToken` 表**已存在 token→设备ID 映射**，
|
||||||
|
> 方案从"JWT 加 claim"改为"映射查询"，JWT 结构完全不动。
|
||||||
|
> 实施时额外修复：API 签发的 JWT 增加 `jti`（见 4.4）。
|
||||||
|
|
||||||
|
## 1. 问题描述
|
||||||
|
|
||||||
|
用户偶尔会误操作"用 A 电脑远程连接 A 电脑自己"（比如通讯录里点了自己、输错 ID），连接一旦成功，画面里包含自己的画面，形成无限嵌套（镜中镜）。
|
||||||
|
|
||||||
|
- 该问题正统修法在**客户端**（发起前检查目标 == 自己），但 rustdesk 客户端仓库太大、用户不希望动客户端
|
||||||
|
- 因此考虑**服务器端**拦截：发现"自己连自己"时直接拒绝，并把原因返回给客户端弹窗
|
||||||
|
|
||||||
|
## 2. 服务器端能拦截的位置分析
|
||||||
|
|
||||||
|
连接建立的时序（hbbs = ID/信令服务器，hbbr = 中继）：
|
||||||
|
|
||||||
|
```
|
||||||
|
主控端 A ──PunchHoleRequest──▶ hbbs ──PunchHoleResponse──▶ 主控端 A
|
||||||
|
│
|
||||||
|
└──PunchHoleSent──▶ 被控端 B
|
||||||
|
（之后 A/B 直连打洞，或双方连 hbbr 中继）
|
||||||
|
```
|
||||||
|
|
||||||
|
**关键结论：拦截窗口只有 hbbs 处理 `PunchHoleRequest` / `RequestRelay` 这两步。**
|
||||||
|
一旦放行、两端直连建立（本机自连几乎必然直连成功），后续流量完全不经服务器，无法感知也无法切断。
|
||||||
|
|
||||||
|
API（Go 服务）不在打洞数据路径上（客户端直连 hbbs 的 21116/21118），所以 API 层没有拦截点；hbbr 也只在打洞失败后才登场。**唯一可行的服务端拦截点就是 hbbs。**
|
||||||
|
|
||||||
|
## 3. 代码调查结论（证据）
|
||||||
|
|
||||||
|
### 3.1 协议里没有"发起方设备 ID"
|
||||||
|
|
||||||
|
`libs/hbb_common/protos/rendezvous.proto`：
|
||||||
|
|
||||||
|
```proto
|
||||||
|
message PunchHoleRequest {
|
||||||
|
string id = 1; // 目标设备 ID（有）
|
||||||
|
NatType nat_type = 2;
|
||||||
|
string licence_key = 3;
|
||||||
|
ConnType conn_type = 4;
|
||||||
|
string token = 5; // ← 发起方的登录 token（fork 已在用）
|
||||||
|
...
|
||||||
|
} // 没有任何"发起方自己 ID"字段
|
||||||
|
|
||||||
|
message RequestRelay {
|
||||||
|
string id = 1; // 目标设备 ID
|
||||||
|
...
|
||||||
|
string token = 8; // ← 中继请求也带 token
|
||||||
|
...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
→ "目标 ID == 发起 ID 就拒"的规则本身正确，但服务器必须先知道**发起方是谁**。
|
||||||
|
|
||||||
|
### 3.2 token（JWT）里目前只有账号，但 API 数据库里已有 token→设备ID 映射
|
||||||
|
|
||||||
|
- hbbs 侧（`src/jwt.rs`）：`Claims { user_id, exp }` —— JWT 本身不含设备
|
||||||
|
- API 签发侧（`rustdesk-api/service/user.go:89`）：`Jwt.GenerateToken(u.Id)` 只放 user_id
|
||||||
|
- 仅凭 user_id 对比目标设备归属 → 会误伤"同账号下 A 连自己的另一台设备 B"（合法主场景）❌
|
||||||
|
- **但**：API 的 `model/userToken.go` `UserToken` 表已存 `Token + DeviceId + DeviceUuid + ExpiredAt`，
|
||||||
|
且 `Login()`（`service/user.go:97`）签发时就写入 `DeviceId: llog.DeviceId`，`Logout` 时删行。
|
||||||
|
即 **token → 设备ID 的映射已经持久化在 API 的 sqlite 中**（v2 方案的基础）。
|
||||||
|
|
||||||
|
### 3.3 映射数据的来源：登录时 API 已经拿到发起方设备 ID
|
||||||
|
|
||||||
|
`rustdesk-api/http/request/api/user.go:31`：
|
||||||
|
|
||||||
|
```go
|
||||||
|
type LoginForm struct {
|
||||||
|
AutoLogin bool `json:"autoLogin"`
|
||||||
|
DeviceInfo DeviceInfoInLogin `json:"deviceInfo"`
|
||||||
|
Id string `json:"id"` // ← 客户端自己的 rustdesk ID
|
||||||
|
Type string `json:"type"`
|
||||||
|
Uuid string `json:"uuid"`
|
||||||
|
Username string `json:"username"`
|
||||||
|
Password string `json:"password,omitempty"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
桌面客户端和 web 客户端登录 API 都走这个接口并携带 `Id`，登录流程将其写入 `LoginLog.DeviceId` 并落到 `UserToken.DeviceId` —— **无需客户端任何改动，设备身份已经入库**。
|
||||||
|
|
||||||
|
### 3.4 MUST_LOGIN 只影响发起方（已确认）
|
||||||
|
|
||||||
|
hbbs 中 MUST_LOGIN 的强制点**只有一处**：`src/rendezvous_server.rs:932`（`handle_punch_hole_request` 内），即只有发起打洞的会话要求 token。
|
||||||
|
|
||||||
|
| 消息 | 发送方 | MUST_LOGIN=Y 时 |
|
||||||
|
|---|---|---|
|
||||||
|
| `PunchHoleRequest` | 发起方 | 必须带有效 token |
|
||||||
|
| `RequestRelay` | 发起方（force_relay 场景） | **目前不检查（现状缺口）** |
|
||||||
|
| `RegisterPeer`（注册/心跳） | 被控端 | 不检查，不登录可被连 |
|
||||||
|
| `RegisterPk` | 被控端 | 不检查 |
|
||||||
|
| hbbr 中继连接 | 双方 | 无校验 |
|
||||||
|
|
||||||
|
→ 被连接设备**不需要**登录；MUST_LOGIN=Y 恰好只保证"发起方必带 token"，与自连拦截（只需要发起方身份）完全匹配。
|
||||||
|
|
||||||
|
### 3.5 错误原因回传客户端有现成通道
|
||||||
|
|
||||||
|
现有代码已经用 `PunchHoleResponse.other_failure` 给客户端弹窗：
|
||||||
|
|
||||||
|
```rust
|
||||||
|
msg_out.set_punch_hole_response(PunchHoleResponse {
|
||||||
|
other_failure: String::from("Connection failed, please login!"),
|
||||||
|
..Default::default()
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
→ 自连拒绝提示用同一字段，客户端零改动。
|
||||||
|
|
||||||
|
## 4. 推荐方案（v2：映射查询，不改 JWT）
|
||||||
|
|
||||||
|
数据流：
|
||||||
|
|
||||||
|
```
|
||||||
|
客户端登录 ──LoginForm{Id}──▶ API：签发JWT + UserToken{Token, DeviceId}（已有）
|
||||||
|
主控端发起连接 ──PunchHoleRequest{id, token}──▶ hbbs
|
||||||
|
hbbs：验JWT签名/有效期（逻辑不变）
|
||||||
|
→ 按 token 查 UserToken 得 device_id（内存缓存 → 未命中走 API 内部接口）
|
||||||
|
→ device_id == ph.id ？
|
||||||
|
是 → 回 PunchHoleResponse{other_failure:"不能远程自己"}，拒绝
|
||||||
|
否 → 正常打洞
|
||||||
|
```
|
||||||
|
|
||||||
|
### 改动 1：API（rustdesk-api，Go，改动极小）
|
||||||
|
|
||||||
|
- 确认登录时 `LoginLog.DeviceId` 取自 `LoginForm.Id`（rustdesk ID），对不上则补一行赋值
|
||||||
|
- 新增内部查询接口（如 `GET /api/internal/token-device`，入参 token，返回 device_id），
|
||||||
|
**仅允许 localhost/容器内访问**（IP 判断 + 共享密钥头），不记日志避免 token 泄露
|
||||||
|
|
||||||
|
### 改动 2：hbbs（lejianwen/rustdesk-server，Rust，约 40 行）
|
||||||
|
|
||||||
|
- `handle_punch_hole_request`：验签通过后查映射（`token 哈希 → device_id`，
|
||||||
|
hbbs 内置 HashMap 缓存 + TTL 几分钟；未命中调 API 内部接口），
|
||||||
|
`device_id == ph.id` → 拒绝并回 `other_failure`
|
||||||
|
- `RequestRelay` 分支（`handle_tcp`）：**补上 token 校验**（顺带堵掉 force_relay 绕过 MUST_LOGIN 的口子）+ 同样的自连比对
|
||||||
|
- **fail-open**：API 不可达/查询失败 → 视为"无设备信息"，跳过自连检查（不拖累正常连接）
|
||||||
|
|
||||||
|
### 兜底规则（已确认的设计决策）：无 token 一律跳过校验
|
||||||
|
|
||||||
|
自连校验的触发条件是"请求携带有效 token 且查得到 device_id"，**与 MUST_LOGIN 取值解耦**：
|
||||||
|
|
||||||
|
| 场景 | 行为 |
|
||||||
|
|---|---|
|
||||||
|
| MUST_LOGIN=Y，任意发起方 | 必有 token → 校验生效，100% 拦截 |
|
||||||
|
| MUST_LOGIN=N，发起方已登录 | 带 token → 顺路校验，同样拦截（免费保护） |
|
||||||
|
| MUST_LOGIN=N，发起方未登录 | 无 token → **跳过校验直接放行**，保持现状行为（套娃风险被明确接受） |
|
||||||
|
|
||||||
|
理由：没有 token 就没有设备身份，无从判断"是不是自己连自己"；强行用 IP/user_id 猜
|
||||||
|
只会引入误伤（见第 5 节）。跳过 = 该场景退化为现状，不比现在更差，已是改动范围内的最优解。
|
||||||
|
|
||||||
|
### 改动 3：开启 `MUST_LOGIN=Y`
|
||||||
|
|
||||||
|
- 保证所有发起连接的会话都带 token → 拦截覆盖率 100%
|
||||||
|
- 代价即其既有语义：所有"主动发起连接"的设备必须登录；纯被连设备不受影响
|
||||||
|
|
||||||
|
### 明确不推荐：hbbs 直读 API 的 sqlite
|
||||||
|
|
||||||
|
同容器共享 `/app/data` 技术上可行，但 Go gorm 与 Rust sqlx 双进程写同一 sqlite 有锁风险，
|
||||||
|
且 hbbs 从此耦合 API 表结构（API 升级改表即崩）——映射读取统一走 HTTP 内部接口。
|
||||||
|
|
||||||
|
### 4.4 实施补充：JWT 签发增加 jti
|
||||||
|
|
||||||
|
实施中发现：JWT claims 只有 `{user_id, exp}`，同一账号**同一秒内**多次登录会产出
|
||||||
|
字节级相同的 token，UserToken 表中无法区分设备（hbbs 查映射会命中错误设备）。
|
||||||
|
修复：`lib/jwt/jwt.go` GenerateToken 的 RegisteredClaims 增加 `ID: uuid.NewString()`（jti），
|
||||||
|
每次登录 token 唯一。旧客户端/旧 token 不受影响（Rust 侧 serde 忽略未知字段）。
|
||||||
|
|
||||||
|
## 4.5 实际改动清单（已全部落地）
|
||||||
|
|
||||||
|
**rustdesk-api（Go）**
|
||||||
|
|
||||||
|
| 文件 | 改动 |
|
||||||
|
|---|---|
|
||||||
|
| `service/user.go` | 新增 `GetDeviceIdByToken(token)`：查 UserToken（校验 ExpiredAt）返回 DeviceId |
|
||||||
|
| `http/controller/api/internal.go` | 新增内部接口 `GET /api/internal/token-device?token=`：仅回环 IP + `X-Secret` 头必须等于 JWT 密钥，否则 403；查不到 404 |
|
||||||
|
| `http/router/api.go` | 注册路由（置于 RustAuth 中间件之前） |
|
||||||
|
| `lib/jwt/jwt.go` | GenerateToken 增加 jti |
|
||||||
|
|
||||||
|
**lejianwen/rustdesk-server（Rust）**
|
||||||
|
|
||||||
|
| 文件 | 改动 |
|
||||||
|
|---|---|
|
||||||
|
| `src/token_device.rs`（新增） | 映射查询模块：`get_device_id(token)`，内存缓存（命中 TTL 300s / 未命中 60s，容量上限 4096），minreq 在 `spawn_blocking` 中调 API，超时 3s，任何失败返回 None（fail-open） |
|
||||||
|
| `src/lib.rs` | 注册 `mod token_device` |
|
||||||
|
| `src/rendezvous_server.rs` `handle_punch_hole_request` | MUST_LOGIN 验签后：token 有效且 `get_device_id == ph.id` → 返回 `PunchHoleResponse{other_failure:"不能远程自己…/You are connecting to yourself"}`，不打洞 |
|
||||||
|
| `src/rendezvous_server.rs` `handle_tcp` RequestRelay 分支 | **补上缺失的 MUST_LOGIN token 校验**（堵 force_relay 绕过口子）+ 同样的自连比对，命中则丢弃中继请求并记 warn 日志 |
|
||||||
|
| `src/main.rs` | `--must-login` 帮助文本标注 default Y |
|
||||||
|
| `src/rendezvous_server.rs` `start_with_bind` | **MUST_LOGIN 默认值改为 Y**：仅当显式 `--must-login=N` 或 `MUST_LOGIN=N` 时关闭 |
|
||||||
|
| `docker-compose.yml` | 示例 env `MUST_LOGIN=N` → `Y` |
|
||||||
|
|
||||||
|
**运行配置**：hbbs 与 API 同容器，`RUSTDESK_API_JWT_KEY` 双方共享（hbbs 的 jwt::SECRET 即 API 的 jwt.key）；
|
||||||
|
API 内部地址可用 `RUSTDESK_API_INTERNAL_URL` 覆盖，默认 `http://127.0.0.1:21114`。
|
||||||
|
|
||||||
|
> ⚠️ **部署必设 `RUSTDESK_API_JWT_KEY`**（任意字符串）。未设置时 hbbs 的 JWT 密钥为空，
|
||||||
|
> token 校验和自连拦截**整体静默关闭**（fail-open 设计，日志无报错，连接照常放行）。
|
||||||
|
> 新版本已在启动日志中显式告警：`RUSTDESK_API_JWT_KEY is not set: ... DISABLED`；
|
||||||
|
> 设置后日志显示 `Self-connection blocking: enabled`。修改该值后客户端需退出重新登录。
|
||||||
|
|
||||||
|
## 4.6 端到端验证结果（2026-09-06，全部通过）
|
||||||
|
|
||||||
|
验证方法：Python 脚本按 hbb_common `bytes_codec` 帧格式与 rendezvous.proto 手工构造
|
||||||
|
`PunchHoleRequest` 直连 hbbs 21116 端口（脚本：`/root/rustdesk/build/punch_test.py`）。
|
||||||
|
|
||||||
|
| 用例 | 结果 |
|
||||||
|
|---|---|
|
||||||
|
| 自连：token 属于设备 11010050，目标 11010050 | ✅ 拦截，客户端收到 `other_failure: "不能远程自己：发起方与目标是同一台设备 / You are connecting to yourself"`，hbbs 记 `Blocked self-connection attempt` warn 日志 |
|
||||||
|
| 误伤检查：token 属于设备 99999999，目标 11010050 | ✅ 放行（映射返回 99999999 ≠ 目标），无误拦 |
|
||||||
|
| 无 token（MUST_LOGIN=Y） | ✅ 拒绝：`Connection failed, please login!` |
|
||||||
|
| 内部接口：正确密钥 + 回环 | ✅ 返回 `{"device_id":"11010050"}` |
|
||||||
|
| 内部接口：错误密钥 / 非回环来源 | ✅ 均 403 |
|
||||||
|
| MUST_LOGIN 默认值 | ✅ 未配置任何 env 时日志显示 `MUST_LOGIN=Y` |
|
||||||
|
|
||||||
|
注：验证容器中以 `-k ""` 跳过密钥交换直连明文路径（打洞处理代码与加密路径完全相同），
|
||||||
|
正式镜像仍按官方流程自动生成密钥对并对 TCP 连接先发 KeyExchange 阶段 1，由客户端正常完成握手。
|
||||||
|
|
||||||
|
## 5. 为什么其他做法不行 / 不选
|
||||||
|
|
||||||
|
| 做法 | 结论 |
|
||||||
|
|---|---|
|
||||||
|
| 拿 user_id 对比目标设备归属 | 误伤同账号多设备互连（RustDesk 的主场景）❌ |
|
||||||
|
| 拿来源 IP 对比目标注册 IP | 误伤整个局域网 A→B（同一 NAT 出口）❌ |
|
||||||
|
| API/前端层拦截 | API 不在打洞路径上，没有拦截点 ❌ |
|
||||||
|
| 连接建立后检测/切断 | 直连流量不经服务器，无法感知 ❌ |
|
||||||
|
| hbbs 直读 API 的 sqlite | 双进程双 ORM 同库有锁风险，hbbs 耦合 API 表结构 ❌（见 4 节末） |
|
||||||
|
| rustdesk-api-web 前端加"目标==自己"提示 | 可选退路：只覆盖 webclient 点击路径，桌面客户端管不到；本质仍是客户端补丁 ⚠️ |
|
||||||
|
| 客户端修复（正统） | 用户排除（客户端仓库太大）⛔ |
|
||||||
|
| 协议增强：`PunchHoleRequest` 加 `my_id` 字段 | 长期正解，proto3 加字段向后兼容，但需要改客户端；**远期项**，服务端将来可"有字段就校验、无字段跳过" |
|
||||||
|
|
||||||
|
**JWT 加 claim（v1 方案）降为备选**：同样可行且无运行时查询，但改动面（改签发+改 Claims 结构）
|
||||||
|
比映射查询大，且登出不能即时失效设备身份；若将来想去掉对 API 的运行时依赖可切换。
|
||||||
|
|
||||||
|
| 对比项 | v2 映射查询（推荐） | v1 JWT 加 claim（备选） |
|
||||||
|
|---|---|---|
|
||||||
|
| JWT 结构 | 不动 | 加字段（向后兼容） |
|
||||||
|
| API 改动 | 加 1 个内部接口（映射已存在） | 改签发逻辑 |
|
||||||
|
| hbbs 改动 | 两处校验 + 查询缓存 | 两处校验 |
|
||||||
|
| 运行时依赖 | 查询时 API 参与一次（有缓存，fail-open） | 无 |
|
||||||
|
| 登出语义 | 设备身份即时失效（增强） | token 到期前一直有效 |
|
||||||
|
|
||||||
|
## 6. 覆盖范围与边缘情况
|
||||||
|
|
||||||
|
- **MUST_LOGIN=Y**：webclient 与桌面客户端发起 → 100% 拦截
|
||||||
|
（`LoginForm.Id` → `UserToken.DeviceId` 提供设备身份）
|
||||||
|
- **MUST_LOGIN=N**：已登录设备发起 → 拦截；未登录设备发起 → 放行（见第 4 节兜底规则，
|
||||||
|
套娃风险被明确接受，行为与现状一致）
|
||||||
|
- **MUST_LOGIN=Y 时未登录客户端**（无 token）→ 本来就被拒绝（"please login"），不存在漏网
|
||||||
|
- API 暂时不可达 → fail-open，自连拦截暂时降级，正常连接不受影响
|
||||||
|
- **边缘情况**：客户端 ID 变更（重装/清数据）到重新登录之间的短窗口内，映射里的旧 device_id
|
||||||
|
与目标不匹配 → 可能漏拦或误拦一次，重新登录即恢复，影响很小
|
||||||
|
- 实施时需抽查验证 `UserToken.DeviceId` 对各端（桌面/webclient/OAuth 登录）都已正确填充
|
||||||
|
- 错误文案建议中英对照，走 `other_failure`
|
||||||
|
|
||||||
|
## 7. 名词澄清：hbbs 的代码就在本机
|
||||||
|
|
||||||
|
"hbbs"不是另一个项目，是 `lejianwen/rustdesk-server` 仓库编译出的二进制名（`Cargo.toml` 里 `[[bin]] name = "hbbs"`），主体代码即 `src/rendezvous_server.rs`。本机已有该仓库（刚完成 1.1.17 合并）、依赖子模块 hbb_common、完整容器编译链路——改完重新打镜像约十几分钟，无需再拉取任何大仓库（不动的 rustdesk 客户端仓库才是大家伙）。
|
||||||
|
|
||||||
|
## 8. 实施决策记录
|
||||||
|
|
||||||
|
1. ✅ 按 v2 方案实施（API 内部查询接口 + hbbs 两处校验，JWT 结构不动，仅加 jti）
|
||||||
|
2. ✅ 错误文案：`不能远程自己：发起方与目标是同一台设备 / You are connecting to yourself`
|
||||||
|
3. ✅ 已顺带补上 `RequestRelay` 缺失的 token 校验（堵住 MUST_LOGIN 的绕过口子）
|
||||||
|
4. ✅ 查不到映射（API 不可达）时 fail-open：只影响自连拦截，不拖累正常连接
|
||||||
|
5. ✅ MUST_LOGIN 默认值改为 Y（显式配置 N 可关闭）
|
||||||
|
6. ⏳ 远期项（未实施）：`PunchHoleRequest` 增加 `my_id` 字段（需改客户端，proto3 向后兼容）
|
||||||
|
---
|
||||||
|
|
||||||
|
# 原始 README 内容
|
||||||
|
|
||||||
|
> 以下为 `lejianwen/rustdesk-server` 原始仓库的 README，本仓库在此基础上增加了
|
||||||
|
> 自连拦截（A 远程连 A）服务器端方案和 1.1.17 合并支持。
|
||||||
|
|
||||||
[](https://github.com/lejianwen/rustdesk-server/actions/workflows/build.yaml)
|
[](https://github.com/lejianwen/rustdesk-server/actions/workflows/build.yaml)
|
||||||
|
|
||||||
- 解决当客户端登录了`API`账号时链接超时的问题
|
- 解决当客户端登录了`API`账号时链接超时的问题
|
||||||
@@ -415,305 +837,3 @@ Secret Key: egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hf
|
|||||||
| PORT | hbbs/hbbr | 监听端口（hbbs为21116，hbbr为21117） |
|
| PORT | hbbs/hbbr | 监听端口（hbbs为21116，hbbr为21117） |
|
||||||
| RELAY_SERVERS | hbbs | 运行hbbr的机器的IP地址/DNS名称（用逗号分隔） |
|
| RELAY_SERVERS | hbbs | 运行hbbr的机器的IP地址/DNS名称（用逗号分隔） |
|
||||||
| RUST_LOG | all | 设置 debug level (error\|warn\|info\|debug\|trace) |
|
| RUST_LOG | all | 设置 debug level (error\|warn\|info\|debug\|trace) |
|
||||||
| SINGLE_BANDWIDTH | hbbr | 单个连接的最大带宽（以Mb/s为单位） |
|
|
||||||
| TOTAL_BANDWIDTH | hbbr | 最大总带宽（以Mb/s为单位） |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# 1.1.17 合并记录
|
|
||||||
|
|
||||||
> 日期：2026-09-05
|
|
||||||
> 关联文档：[lejianwen/rustdesk-api README](https://github.com/lejianwen/rustdesk-api)
|
|
||||||
> 说明：将官方 `rustdesk/rustdesk-server` 1.1.17 合并到本仓库（forapi 分支），完整构建记录见 [lejianwen/rustdesk-api README](https://github.com/lejianwen/rustdesk-api)。
|
|
||||||
|
|
||||||
## 合并要点
|
|
||||||
|
|
||||||
- 官方 1.1.14（merge-base `c650217`）→ 1.1.17，共 43 个上游提交
|
|
||||||
- **安全**：禁用 UDP 打洞反射/放大路径（`PunchHoleRequest`/`PunchHoleSent`/`LocalAddr` 只允许走 TCP/WS）
|
|
||||||
- **功能**：`-b/--bind` 绑定指定 IP；控制台监听独立绑到 127.0.0.1；`punch-requests(pr)` 连接日志控制台命令
|
|
||||||
- **修复**：在线状态 `i32` 溢出（运行 24.9~49.7 天后误报在线）；中继限速默认值 4Mb/s → 32Mb/s
|
|
||||||
- **依赖**：`hbb_common` 子模块推进到 `69cea8d`、新增 `flate2`
|
|
||||||
|
|
||||||
## 冲突处理
|
|
||||||
|
|
||||||
| 冲突文件 | 处理方式 |
|
|
||||||
|---|---|
|
|
||||||
| `src/rendezvous_server.rs` | 保留 fork 的 JWT/必须登录/KeyExchange/加密 Sink/API 特性，叠加上游全部修复，共 4 处冲突块手动合并 |
|
|
||||||
| `src/main.rs` | 双方参数合并：上游的 `--bind` + DEPRECATED 标注，保留 fork 的 `--must-login` |
|
|
||||||
| `libs/hbb_common`（子模块） | 从 fork 的旧提交直接指到官方 1.1.17 用的 `69cea8d` |
|
|
||||||
| `Cargo.toml` / `Cargo.lock` | git 自动合并成功 |
|
|
||||||
|
|
||||||
**注意点**：
|
|
||||||
- fork 侧 `check_cmd` 帮助文本比上游多一行 `must-login`，合并 `punch-requests` 时要同步把 format! 占位符从 7 个加到 8 个，**否则编译报 `argument never used`**
|
|
||||||
- 上游的 `peers_online_state` 是内联代码，fork 抽成了 helper（`handle_online_request` 复用），合并时保留 helper 并把 `as i32` 改 `as i64`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
# 自连拦截（A 远程连 A）服务器端方案
|
|
||||||
|
|
||||||
> 状态：**已实施并通过端到端验证**（2026-09-06）
|
|
||||||
> 日期：2026-09-05 设计 / 2026-09-06 实施
|
|
||||||
> 关联文档：[lejianwen/rustdesk-api README](https://github.com/lejianwen/rustdesk-api)
|
|
||||||
>
|
|
||||||
> v2 变更：经用户提示，发现 API 的 `UserToken` 表**已存在 token→设备ID 映射**，
|
|
||||||
> 方案从"JWT 加 claim"改为"映射查询"，JWT 结构完全不动。
|
|
||||||
> 实施时额外修复：API 签发的 JWT 增加 `jti`（见 4.4）。
|
|
||||||
|
|
||||||
## 1. 问题描述
|
|
||||||
|
|
||||||
用户偶尔会误操作"用 A 电脑远程连接 A 电脑自己"（比如通讯录里点了自己、输错 ID），连接一旦成功，画面里包含自己的画面，形成无限嵌套（镜中镜）。
|
|
||||||
|
|
||||||
- 该问题正统修法在**客户端**（发起前检查目标 == 自己），但 rustdesk 客户端仓库太大、用户不希望动客户端
|
|
||||||
- 因此考虑**服务器端**拦截：发现"自己连自己"时直接拒绝，并把原因返回给客户端弹窗
|
|
||||||
|
|
||||||
## 2. 服务器端能拦截的位置分析
|
|
||||||
|
|
||||||
连接建立的时序（hbbs = ID/信令服务器，hbbr = 中继）：
|
|
||||||
|
|
||||||
```
|
|
||||||
主控端 A ──PunchHoleRequest──▶ hbbs ──PunchHoleResponse──▶ 主控端 A
|
|
||||||
│
|
|
||||||
└──PunchHoleSent──▶ 被控端 B
|
|
||||||
（之后 A/B 直连打洞，或双方连 hbbr 中继）
|
|
||||||
```
|
|
||||||
|
|
||||||
**关键结论：拦截窗口只有 hbbs 处理 `PunchHoleRequest` / `RequestRelay` 这两步。**
|
|
||||||
一旦放行、两端直连建立（本机自连几乎必然直连成功），后续流量完全不经服务器，无法感知也无法切断。
|
|
||||||
|
|
||||||
API（Go 服务）不在打洞数据路径上（客户端直连 hbbs 的 21116/21118），所以 API 层没有拦截点；hbbr 也只在打洞失败后才登场。**唯一可行的服务端拦截点就是 hbbs。**
|
|
||||||
|
|
||||||
## 3. 代码调查结论（证据）
|
|
||||||
|
|
||||||
### 3.1 协议里没有"发起方设备 ID"
|
|
||||||
|
|
||||||
`libs/hbb_common/protos/rendezvous.proto`：
|
|
||||||
|
|
||||||
```proto
|
|
||||||
message PunchHoleRequest {
|
|
||||||
string id = 1; // 目标设备 ID（有）
|
|
||||||
NatType nat_type = 2;
|
|
||||||
string licence_key = 3;
|
|
||||||
ConnType conn_type = 4;
|
|
||||||
string token = 5; // ← 发起方的登录 token（fork 已在用）
|
|
||||||
...
|
|
||||||
} // 没有任何"发起方自己 ID"字段
|
|
||||||
|
|
||||||
message RequestRelay {
|
|
||||||
string id = 1; // 目标设备 ID
|
|
||||||
...
|
|
||||||
string token = 8; // ← 中继请求也带 token
|
|
||||||
...
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
→ "目标 ID == 发起 ID 就拒"的规则本身正确，但服务器必须先知道**发起方是谁**。
|
|
||||||
|
|
||||||
### 3.2 token（JWT）里目前只有账号，但 API 数据库里已有 token→设备ID 映射
|
|
||||||
|
|
||||||
- hbbs 侧（`src/jwt.rs`）：`Claims { user_id, exp }` —— JWT 本身不含设备
|
|
||||||
- API 签发侧（`rustdesk-api/service/user.go:89`）：`Jwt.GenerateToken(u.Id)` 只放 user_id
|
|
||||||
- 仅凭 user_id 对比目标设备归属 → 会误伤"同账号下 A 连自己的另一台设备 B"（合法主场景）❌
|
|
||||||
- **但**：API 的 `model/userToken.go` `UserToken` 表已存 `Token + DeviceId + DeviceUuid + ExpiredAt`，
|
|
||||||
且 `Login()`（`service/user.go:97`）签发时就写入 `DeviceId: llog.DeviceId`，`Logout` 时删行。
|
|
||||||
即 **token → 设备ID 的映射已经持久化在 API 的 sqlite 中**（v2 方案的基础）。
|
|
||||||
|
|
||||||
### 3.3 映射数据的来源：登录时 API 已经拿到发起方设备 ID
|
|
||||||
|
|
||||||
`rustdesk-api/http/request/api/user.go:31`：
|
|
||||||
|
|
||||||
```go
|
|
||||||
type LoginForm struct {
|
|
||||||
AutoLogin bool `json:"autoLogin"`
|
|
||||||
DeviceInfo DeviceInfoInLogin `json:"deviceInfo"`
|
|
||||||
Id string `json:"id"` // ← 客户端自己的 rustdesk ID
|
|
||||||
Type string `json:"type"`
|
|
||||||
Uuid string `json:"uuid"`
|
|
||||||
Username string `json:"username"`
|
|
||||||
Password string `json:"password,omitempty"`
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
桌面客户端和 web 客户端登录 API 都走这个接口并携带 `Id`，登录流程将其写入 `LoginLog.DeviceId` 并落到 `UserToken.DeviceId` —— **无需客户端任何改动，设备身份已经入库**。
|
|
||||||
|
|
||||||
### 3.4 MUST_LOGIN 只影响发起方（已确认）
|
|
||||||
|
|
||||||
hbbs 中 MUST_LOGIN 的强制点**只有一处**：`src/rendezvous_server.rs:932`（`handle_punch_hole_request` 内），即只有发起打洞的会话要求 token。
|
|
||||||
|
|
||||||
| 消息 | 发送方 | MUST_LOGIN=Y 时 |
|
|
||||||
|---|---|---|
|
|
||||||
| `PunchHoleRequest` | 发起方 | 必须带有效 token |
|
|
||||||
| `RequestRelay` | 发起方（force_relay 场景） | **目前不检查（现状缺口）** |
|
|
||||||
| `RegisterPeer`（注册/心跳） | 被控端 | 不检查，不登录可被连 |
|
|
||||||
| `RegisterPk` | 被控端 | 不检查 |
|
|
||||||
| hbbr 中继连接 | 双方 | 无校验 |
|
|
||||||
|
|
||||||
→ 被连接设备**不需要**登录；MUST_LOGIN=Y 恰好只保证"发起方必带 token"，与自连拦截（只需要发起方身份）完全匹配。
|
|
||||||
|
|
||||||
### 3.5 错误原因回传客户端有现成通道
|
|
||||||
|
|
||||||
现有代码已经用 `PunchHoleResponse.other_failure` 给客户端弹窗：
|
|
||||||
|
|
||||||
```rust
|
|
||||||
msg_out.set_punch_hole_response(PunchHoleResponse {
|
|
||||||
other_failure: String::from("Connection failed, please login!"),
|
|
||||||
..Default::default()
|
|
||||||
});
|
|
||||||
```
|
|
||||||
|
|
||||||
→ 自连拒绝提示用同一字段，客户端零改动。
|
|
||||||
|
|
||||||
## 4. 推荐方案（v2：映射查询，不改 JWT）
|
|
||||||
|
|
||||||
数据流：
|
|
||||||
|
|
||||||
```
|
|
||||||
客户端登录 ──LoginForm{Id}──▶ API：签发JWT + UserToken{Token, DeviceId}（已有）
|
|
||||||
主控端发起连接 ──PunchHoleRequest{id, token}──▶ hbbs
|
|
||||||
hbbs：验JWT签名/有效期（逻辑不变）
|
|
||||||
→ 按 token 查 UserToken 得 device_id（内存缓存 → 未命中走 API 内部接口）
|
|
||||||
→ device_id == ph.id ？
|
|
||||||
是 → 回 PunchHoleResponse{other_failure:"不能远程自己"}，拒绝
|
|
||||||
否 → 正常打洞
|
|
||||||
```
|
|
||||||
|
|
||||||
### 改动 1：API（rustdesk-api，Go，改动极小）
|
|
||||||
|
|
||||||
- 确认登录时 `LoginLog.DeviceId` 取自 `LoginForm.Id`（rustdesk ID），对不上则补一行赋值
|
|
||||||
- 新增内部查询接口（如 `GET /api/internal/token-device`，入参 token，返回 device_id），
|
|
||||||
**仅允许 localhost/容器内访问**（IP 判断 + 共享密钥头），不记日志避免 token 泄露
|
|
||||||
|
|
||||||
### 改动 2：hbbs（lejianwen/rustdesk-server，Rust，约 40 行）
|
|
||||||
|
|
||||||
- `handle_punch_hole_request`：验签通过后查映射（`token 哈希 → device_id`，
|
|
||||||
hbbs 内置 HashMap 缓存 + TTL 几分钟；未命中调 API 内部接口），
|
|
||||||
`device_id == ph.id` → 拒绝并回 `other_failure`
|
|
||||||
- `RequestRelay` 分支（`handle_tcp`）：**补上 token 校验**（顺带堵掉 force_relay 绕过 MUST_LOGIN 的口子）+ 同样的自连比对
|
|
||||||
- **fail-open**：API 不可达/查询失败 → 视为"无设备信息"，跳过自连检查（不拖累正常连接）
|
|
||||||
|
|
||||||
### 兜底规则（已确认的设计决策）：无 token 一律跳过校验
|
|
||||||
|
|
||||||
自连校验的触发条件是"请求携带有效 token 且查得到 device_id"，**与 MUST_LOGIN 取值解耦**：
|
|
||||||
|
|
||||||
| 场景 | 行为 |
|
|
||||||
|---|---|
|
|
||||||
| MUST_LOGIN=Y，任意发起方 | 必有 token → 校验生效，100% 拦截 |
|
|
||||||
| MUST_LOGIN=N，发起方已登录 | 带 token → 顺路校验，同样拦截（免费保护） |
|
|
||||||
| MUST_LOGIN=N，发起方未登录 | 无 token → **跳过校验直接放行**，保持现状行为（套娃风险被明确接受） |
|
|
||||||
|
|
||||||
理由：没有 token 就没有设备身份，无从判断"是不是自己连自己"；强行用 IP/user_id 猜
|
|
||||||
只会引入误伤（见第 5 节）。跳过 = 该场景退化为现状，不比现在更差，已是改动范围内的最优解。
|
|
||||||
|
|
||||||
### 改动 3：开启 `MUST_LOGIN=Y`
|
|
||||||
|
|
||||||
- 保证所有发起连接的会话都带 token → 拦截覆盖率 100%
|
|
||||||
- 代价即其既有语义：所有"主动发起连接"的设备必须登录；纯被连设备不受影响
|
|
||||||
|
|
||||||
### 明确不推荐：hbbs 直读 API 的 sqlite
|
|
||||||
|
|
||||||
同容器共享 `/app/data` 技术上可行，但 Go gorm 与 Rust sqlx 双进程写同一 sqlite 有锁风险，
|
|
||||||
且 hbbs 从此耦合 API 表结构（API 升级改表即崩）——映射读取统一走 HTTP 内部接口。
|
|
||||||
|
|
||||||
### 4.4 实施补充：JWT 签发增加 jti
|
|
||||||
|
|
||||||
实施中发现：JWT claims 只有 `{user_id, exp}`，同一账号**同一秒内**多次登录会产出
|
|
||||||
字节级相同的 token，UserToken 表中无法区分设备（hbbs 查映射会命中错误设备）。
|
|
||||||
修复：`lib/jwt/jwt.go` GenerateToken 的 RegisteredClaims 增加 `ID: uuid.NewString()`（jti），
|
|
||||||
每次登录 token 唯一。旧客户端/旧 token 不受影响（Rust 侧 serde 忽略未知字段）。
|
|
||||||
|
|
||||||
## 4.5 实际改动清单（已全部落地）
|
|
||||||
|
|
||||||
**rustdesk-api（Go）**
|
|
||||||
|
|
||||||
| 文件 | 改动 |
|
|
||||||
|---|---|
|
|
||||||
| `service/user.go` | 新增 `GetDeviceIdByToken(token)`：查 UserToken（校验 ExpiredAt）返回 DeviceId |
|
|
||||||
| `http/controller/api/internal.go` | 新增内部接口 `GET /api/internal/token-device?token=`：仅回环 IP + `X-Secret` 头必须等于 JWT 密钥，否则 403；查不到 404 |
|
|
||||||
| `http/router/api.go` | 注册路由（置于 RustAuth 中间件之前） |
|
|
||||||
| `lib/jwt/jwt.go` | GenerateToken 增加 jti |
|
|
||||||
|
|
||||||
**lejianwen/rustdesk-server（Rust）**
|
|
||||||
|
|
||||||
| 文件 | 改动 |
|
|
||||||
|---|---|
|
|
||||||
| `src/token_device.rs`（新增） | 映射查询模块：`get_device_id(token)`，内存缓存（命中 TTL 300s / 未命中 60s，容量上限 4096），minreq 在 `spawn_blocking` 中调 API，超时 3s，任何失败返回 None（fail-open） |
|
|
||||||
| `src/lib.rs` | 注册 `mod token_device` |
|
|
||||||
| `src/rendezvous_server.rs` `handle_punch_hole_request` | MUST_LOGIN 验签后：token 有效且 `get_device_id == ph.id` → 返回 `PunchHoleResponse{other_failure:"不能远程自己…/You are connecting to yourself"}`，不打洞 |
|
|
||||||
| `src/rendezvous_server.rs` `handle_tcp` RequestRelay 分支 | **补上缺失的 MUST_LOGIN token 校验**（堵 force_relay 绕过口子）+ 同样的自连比对，命中则丢弃中继请求并记 warn 日志 |
|
|
||||||
| `src/main.rs` | `--must-login` 帮助文本标注 default Y |
|
|
||||||
| `src/rendezvous_server.rs` `start_with_bind` | **MUST_LOGIN 默认值改为 Y**：仅当显式 `--must-login=N` 或 `MUST_LOGIN=N` 时关闭 |
|
|
||||||
| `docker-compose.yml` | 示例 env `MUST_LOGIN=N` → `Y` |
|
|
||||||
|
|
||||||
**运行配置**：hbbs 与 API 同容器，`RUSTDESK_API_JWT_KEY` 双方共享（hbbs 的 jwt::SECRET 即 API 的 jwt.key）；
|
|
||||||
API 内部地址可用 `RUSTDESK_API_INTERNAL_URL` 覆盖，默认 `http://127.0.0.1:21114`。
|
|
||||||
|
|
||||||
> ⚠️ **部署必设 `RUSTDESK_API_JWT_KEY`**（任意字符串）。未设置时 hbbs 的 JWT 密钥为空，
|
|
||||||
> token 校验和自连拦截**整体静默关闭**（fail-open 设计，日志无报错，连接照常放行）。
|
|
||||||
> 新版本已在启动日志中显式告警：`RUSTDESK_API_JWT_KEY is not set: ... DISABLED`；
|
|
||||||
> 设置后日志显示 `Self-connection blocking: enabled`。修改该值后客户端需退出重新登录。
|
|
||||||
|
|
||||||
## 4.6 端到端验证结果（2026-09-06，全部通过）
|
|
||||||
|
|
||||||
验证方法：Python 脚本按 hbb_common `bytes_codec` 帧格式与 rendezvous.proto 手工构造
|
|
||||||
`PunchHoleRequest` 直连 hbbs 21116 端口（脚本：`/root/rustdesk/build/punch_test.py`）。
|
|
||||||
|
|
||||||
| 用例 | 结果 |
|
|
||||||
|---|---|
|
|
||||||
| 自连：token 属于设备 11010050，目标 11010050 | ✅ 拦截，客户端收到 `other_failure: "不能远程自己：发起方与目标是同一台设备 / You are connecting to yourself"`，hbbs 记 `Blocked self-connection attempt` warn 日志 |
|
|
||||||
| 误伤检查：token 属于设备 99999999，目标 11010050 | ✅ 放行（映射返回 99999999 ≠ 目标），无误拦 |
|
|
||||||
| 无 token（MUST_LOGIN=Y） | ✅ 拒绝：`Connection failed, please login!` |
|
|
||||||
| 内部接口：正确密钥 + 回环 | ✅ 返回 `{"device_id":"11010050"}` |
|
|
||||||
| 内部接口：错误密钥 / 非回环来源 | ✅ 均 403 |
|
|
||||||
| MUST_LOGIN 默认值 | ✅ 未配置任何 env 时日志显示 `MUST_LOGIN=Y` |
|
|
||||||
|
|
||||||
注：验证容器中以 `-k ""` 跳过密钥交换直连明文路径（打洞处理代码与加密路径完全相同），
|
|
||||||
正式镜像仍按官方流程自动生成密钥对并对 TCP 连接先发 KeyExchange 阶段 1，由客户端正常完成握手。
|
|
||||||
|
|
||||||
## 5. 为什么其他做法不行 / 不选
|
|
||||||
|
|
||||||
| 做法 | 结论 |
|
|
||||||
|---|---|
|
|
||||||
| 拿 user_id 对比目标设备归属 | 误伤同账号多设备互连（RustDesk 的主场景）❌ |
|
|
||||||
| 拿来源 IP 对比目标注册 IP | 误伤整个局域网 A→B（同一 NAT 出口）❌ |
|
|
||||||
| API/前端层拦截 | API 不在打洞路径上，没有拦截点 ❌ |
|
|
||||||
| 连接建立后检测/切断 | 直连流量不经服务器，无法感知 ❌ |
|
|
||||||
| hbbs 直读 API 的 sqlite | 双进程双 ORM 同库有锁风险，hbbs 耦合 API 表结构 ❌（见 4 节末） |
|
|
||||||
| rustdesk-api-web 前端加"目标==自己"提示 | 可选退路：只覆盖 webclient 点击路径，桌面客户端管不到；本质仍是客户端补丁 ⚠️ |
|
|
||||||
| 客户端修复（正统） | 用户排除（客户端仓库太大）⛔ |
|
|
||||||
| 协议增强：`PunchHoleRequest` 加 `my_id` 字段 | 长期正解，proto3 加字段向后兼容，但需要改客户端；**远期项**，服务端将来可"有字段就校验、无字段跳过" |
|
|
||||||
|
|
||||||
**JWT 加 claim（v1 方案）降为备选**：同样可行且无运行时查询，但改动面（改签发+改 Claims 结构）
|
|
||||||
比映射查询大，且登出不能即时失效设备身份；若将来想去掉对 API 的运行时依赖可切换。
|
|
||||||
|
|
||||||
| 对比项 | v2 映射查询（推荐） | v1 JWT 加 claim（备选） |
|
|
||||||
|---|---|---|
|
|
||||||
| JWT 结构 | 不动 | 加字段（向后兼容） |
|
|
||||||
| API 改动 | 加 1 个内部接口（映射已存在） | 改签发逻辑 |
|
|
||||||
| hbbs 改动 | 两处校验 + 查询缓存 | 两处校验 |
|
|
||||||
| 运行时依赖 | 查询时 API 参与一次（有缓存，fail-open） | 无 |
|
|
||||||
| 登出语义 | 设备身份即时失效（增强） | token 到期前一直有效 |
|
|
||||||
|
|
||||||
## 6. 覆盖范围与边缘情况
|
|
||||||
|
|
||||||
- **MUST_LOGIN=Y**：webclient 与桌面客户端发起 → 100% 拦截
|
|
||||||
（`LoginForm.Id` → `UserToken.DeviceId` 提供设备身份）
|
|
||||||
- **MUST_LOGIN=N**：已登录设备发起 → 拦截；未登录设备发起 → 放行（见第 4 节兜底规则，
|
|
||||||
套娃风险被明确接受，行为与现状一致）
|
|
||||||
- **MUST_LOGIN=Y 时未登录客户端**（无 token）→ 本来就被拒绝（"please login"），不存在漏网
|
|
||||||
- API 暂时不可达 → fail-open，自连拦截暂时降级，正常连接不受影响
|
|
||||||
- **边缘情况**：客户端 ID 变更（重装/清数据）到重新登录之间的短窗口内，映射里的旧 device_id
|
|
||||||
与目标不匹配 → 可能漏拦或误拦一次，重新登录即恢复，影响很小
|
|
||||||
- 实施时需抽查验证 `UserToken.DeviceId` 对各端（桌面/webclient/OAuth 登录）都已正确填充
|
|
||||||
- 错误文案建议中英对照，走 `other_failure`
|
|
||||||
|
|
||||||
## 7. 名词澄清：hbbs 的代码就在本机
|
|
||||||
|
|
||||||
"hbbs"不是另一个项目，是 `lejianwen/rustdesk-server` 仓库编译出的二进制名（`Cargo.toml` 里 `[[bin]] name = "hbbs"`），主体代码即 `src/rendezvous_server.rs`。本机已有该仓库（刚完成 1.1.17 合并）、依赖子模块 hbb_common、完整容器编译链路——改完重新打镜像约十几分钟，无需再拉取任何大仓库（不动的 rustdesk 客户端仓库才是大家伙）。
|
|
||||||
|
|
||||||
## 8. 实施决策记录
|
|
||||||
|
|
||||||
1. ✅ 按 v2 方案实施（API 内部查询接口 + hbbs 两处校验，JWT 结构不动，仅加 jti）
|
|
||||||
2. ✅ 错误文案：`不能远程自己：发起方与目标是同一台设备 / You are connecting to yourself`
|
|
||||||
3. ✅ 已顺带补上 `RequestRelay` 缺失的 token 校验（堵住 MUST_LOGIN 的绕过口子）
|
|
||||||
4. ✅ 查不到映射（API 不可达）时 fail-open：只影响自连拦截，不拖累正常连接
|
|
||||||
5. ✅ MUST_LOGIN 默认值改为 Y（显式配置 N 可关闭）
|
|
||||||
6. ⏳ 远期项（未实施）：`PunchHoleRequest` 增加 `my_id` 字段（需改客户端，proto3 向后兼容）
|
|
||||||
Reference in new issue
Block a user