docs: add original repo and clone time notes

README.md

@@ -1,6 +1,11 @@
 
 # 关于此分支
 
+> **原始仓库**：https://github.com/lejianwen/rustdesk-server.git
+> **克隆时间**：2026-09-16
+> **镜像仓库**：https://gitea7.yangjieshao.work/rustdesk/rustdesk-server.git
+> **子模块 hbb_common**：https://gitea7.yangjieshao.work/rustdesk/hbb_common.git
+
 
 
 [![build](https://github.com/lejianwen/rustdesk-server/actions/workflows/build.yaml/badge.svg)](https://github.com/lejianwen/rustdesk-server/actions/workflows/build.yaml)
@@ -412,3 +417,303 @@ Secret Key:  egAVd44u33ZEUIDTtksGcHeVeAwywarEdHmf99KM5ajwEsuG3NQFT9coAfiZ6nen4hf
 | 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 向后兼容）