rustdesk/rustdesk-api
1
0 Fork 0
Code Releases 1 Activity

docs: add original repo and clone time notes

Browse Source
This commit is contained in:
admin committed 2026-09-16 13:30:01 +08:00
1 parent c5687e1506
commit 37b9991d0e
1 file changed
+222
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+222
View File
@@ -1,5 +1,9 @@
# RustDesk API
> **原始仓库**：https://github.com/lejianwen/rustdesk-api.git
> **克隆时间**：2026-09-16
> **镜像仓库**：https://gitea7.yangjieshao.work/rustdesk/rustdesk-api.git
[English Doc](README_EN.md)
本项目使用 Go 实现了 RustDesk 的 API，并包含了 Web Admin 和 Web 客户端。
@@ -333,3 +337,221 @@
## 感谢你的支持！如果这个项目对你有帮助，请点个⭐️鼓励一下，谢谢！
[lejianwen/rustdesk-server]: https://github.com/lejianwen/rustdesk-server
---
# 自连拦截（A 远程连 A）API 侧改动
> 日期：2026-09-06
> 关联文档：[lejianwen/rustdesk-server README](https://github.com/lejianwen/rustdesk-server)
> 说明：以下为自连拦截方案中涉及本仓库（rustdesk-api，Go）的代码改动，服务端（hbbs）改动见 [lejianwen/rustdesk-server README](https://github.com/lejianwen/rustdesk-server)。
## 改动清单
| 文件 | 改动 |
|---|---|
| `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（`ID: uuid.NewString()`），每次登录 token 唯一 |
## 运行配置
- API 内部地址可用 `RUSTDESK_API_INTERNAL_URL` 覆盖，默认 `http://127.0.0.1:21114`
- hbbs 与 API 同容器时，`RUSTDESK_API_JWT_KEY` 双方共享（hbbs 的 jwt::SECRET 即 API 的 jwt.key）
- ⚠️ **部署必设 `RUSTDESK_API_JWT_KEY`**（任意字符串）。未设置时 hbbs 的 JWT 密钥为空，
token 校验和自连拦截**整体静默关闭**（fail-open 设计）。修改该值后客户端需退出重新登录。
---
# RustDesk 服务器合并 1.1.17 与 Docker 镜像构建记录
> 日期：2026-09-05
> 目标：将官方 `rustdesk/rustdesk-server` 1.1.17 的更新合并到 `lejianwen/rustdesk-server`（forapi 分支，带账号 API 支持），并打包出可直接使用的完整 Docker 镜像。
## 1. 背景与仓库关系
| 仓库 | 说明 | 版本状态 |
|---|---|---|
| `/root/rustdesk/rustdesk/rustdesk-server` | 官方原版（只读，全程未改动） | 1.1.17（2026-08） |
| `/root/rustdesk/lejianwen/rustdesk-server` | 第三方修改版，`forapi` 分支持账号登录/API/JWT | 原基于 1.1.14（2025-09），本次合并到 1.1.17 |
| `/root/rustdesk/lejianwen/rustdesk-api` | Go 编写的 API 服务，`Dockerfile_full_s6` 打完整镜像 | 原样使用 |
两个 rustdesk-server 仓库在官方 1.1.14（merge-base `c650217`）处分叉：
官方之后有 43 个提交（1.1.15 → 1.1.17），lejianwen 有 38 个自己的提交。
**官方 1.1.15~1.1.17 的主要改动**（合并的重点）：
- 安全：禁用 UDP 打洞反射/放大路径（`PunchHoleRequest`/`PunchHoleSent`/`LocalAddr` 只允许走 TCP/WS）；中继 X-Real-IP 头欺骗风险注释；升级 mio 0.8.11、protobuf 3.7.2
- 功能：`-b/--bind` 绑定指定 IP；控制台监听独立绑到 127.0.0.1；`punch-requests(pr)` 连接日志控制台命令
- 修复：在线状态 `i32` 溢出（运行 24.9~49.7 天后误报在线）；中继限速默认值 4Mb/s → 32Mb/s
- 依赖：`hbb_common` 子模块多次推进（最终 `69cea8d`）、新增 `flate2`
## 2. 合并过程与冲突处理
执行 `git merge upstream/master`（在 lejianwen 仓库本地添加 `upstream` 指向官方目录）。
| 冲突文件 | 处理方式 |
|---|---|
| `src/rendezvous_server.rs` | 保留 fork 的 JWT/必须登录/KeyExchange/加密 Sink/API 特性，叠加上游全部修复（bind、console listener、UDP 禁用、i64、PUNCH_REQS、`punch-requests` 命令等）。共 4 处冲突块手动合并 |
| `src/main.rs` | 双方参数合并：上游的 `--bind` + DEPRECATED 标注，保留 fork 的 `--must-login` |
| `libs/hbb_common`（子模块） | 从 fork 的旧提交直接指到官方 1.1.17 用的 `69cea8d`。先确认 fork 用到的 `tcp::Encrypt` 接口在新版仍存在 |
| `Cargo.toml` / `Cargo.lock` | git 自动合并成功（1.1.17 + flate2 + 保留 jsonwebtoken/headers）；lock 文件 cargo 构建后未再变动，说明自动合并结果一致 |
| `README*.md`、`.github/workflows/*`、`docker-compose.yml`、`docker/Dockerfile` | 取 fork 版本（文档是 API 版、CI 是 lejianwen 自己的发布流程） |
**合并中发现的注意点**：
- 上游把 `handle_udp` 里的三个打洞消息改成"故意不支持"，fork 的 `handle_udp_punch_hole_request` 变成死代码（仅编译警告），保留不影响行为；webclient 打洞走 TCP/WS 路径不受影响
- 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`
## 3. 构建环境问题与解决（按时间顺序）
本机只有 `docker` 和 `gcc`，没有 rust/go 工具链，全部编译在容器中进行。
### 3.1 容器内访问 GitHub 失败
**现象**：容器内 `cargo build` 拉取 git 依赖（`confy` 等 3 个来自 github.com）时 `SSL routines::unexpected eof` / 连接超时，重试 10 次仍失败；直连 `git ls-remote github.com` 间歇性可用。
**原因**：到 GitHub 的连接被间歇性重置（典型网络环境问题），宿主机偶尔能通但容器内不稳定。
**解决**：
- 测试可用的加速代理：`gh-proxy.com`、`ghproxy.net`（`ghfast.top` 返回 403）
- 容器内配置系统级改写（注意写 `/etc/gitconfig`，`--global` 在某些 exec 环境不可靠）：
```sh
git config --system url.'https://gh-proxy.com/https://github.com/'.insteadOf 'https://github.com/'
```
- s6-overlay 等构建期从 GitHub 下载的文件改为**宿主机预下载**（走代理）后 `COPY` 进镜像，见 3.6
### 3.2 Alpine apk 源问题
**现象**：`rust:alpine`（Alpine 3.24.1）内 `apk add` 卡住 10 分钟无进展；换清华源后 `HTTP 403: Forbidden`。
**原因**：官方 CDN 在当前网络环境慢；清华源对 v3.24 索引 403。
**解决**：使用阿里云源（与镜像版本匹配的 v3.24）：
```sh
printf 'https://mirrors.aliyun.com/alpine/v3.24/main\nhttps://mirrors.aliyun.com/alpine/v3.24/community\n' > /etc/apk/repositories
```
注意先确认镜像的 Alpine 版本（`cat /etc/alpine-release`），不要照搬别的版本号。
### 3.3 挂载 CARGO_HOME 盖住了 Rust 工具链
**现象**：容器内 `cargo: not found`。
**原因**：把宿主目录挂载到 `/usr/local/cargo`（想持久化缓存），而 `rust:alpine` 的 cargo/rustc 就装在这个路径里，挂载把它们全遮住了。
**解决**：不挂载该路径，cargo 配置直接写容器内 `/usr/local/cargo/config.toml`；既然用持久化容器（`docker run -d ... sleep infinity` + `docker exec`），缓存本来就不会丢。
### 3.4 cargo 的 git-fetch-with-cli 需要 git 二进制
**现象**：`could not execute process 'git fetch ...' (never executed) - No such file or directory`。
**原因**：`rust:alpine` 不带 git，而 config 里设了 `git-fetch-with-cli = true`。
**解决**：`apk add git`。（该模式值得保留：CLI git 才能吃 `insteadOf` 改写，cargo 内置 libgit2 不认。）
### 3.5 Go 构建：go.sum 缺条目
**现象**：`missing go.sum entry for module providing package github.com/spf13/cobra`。
**原因**：仓库快照的 `go.mod` 与 `go.sum` 不同步（上游代码在 go.mod 里加了 cobra 但没提交 go.sum 条目）。
**解决**：把仓库**复制到临时目录**（不动原仓库）执行 `go mod tidy` 后再 `go build`。CGO 静态编译命令：
```sh
CGO_ENABLED=1 GOOS=linux GOARCH=amd64 CC=gcc CGO_LDFLAGS='-static' \
go build -ldflags '-s -w' -o ./amd64/release/apimain ./cmd/apimain.go
cp -ar resources docs conf amd64/release/ && mkdir -p amd64/release/{data,runtime}
```
（alpine 容器里 gcc 本身就是 musl-gcc，等价于官方 CI 的 musl-tools 静态构建；产物 `file` 确认 `statically linked`。）
### 3.6 docker build 阶段无法访问 GitHub（s6-overlay）
**现象**：官方 `docker/Dockerfile` 用 `ADD https://github.com/just-containers/s6-overlay/releases/download/...` 构建期联网下载。
**解决**：宿主机预下载（`curl -L https://gh-proxy.com/https://github.com/...`），复制官方 Dockerfile 后把两条 `ADD` 改成本地 `COPY`（不改动官方仓库）。下载物：
- `s6-overlay-noarch.tar.xz`
- `s6-overlay-x86_64.tar.xz`
- 版本 v3.2.0.0（与 Dockerfile 内 `S6_OVERLAY_VERSION` 一致）
### 3.7 没有 buildx，无法用 --build-context 覆盖 FROM
**现象**：本机 docker 26.1.4 无 buildx 插件，`docker build --build-context` 不可用。
**解决**：复制 `Dockerfile_full_s6` 到构建目录，sed 把首行 `FROM rustdesk/rustdesk-server-s6:latest AS server` 改为本地基础镜像名，构建时 `-f` 指向副本、context 指向含 `amd64/release` 的目录。
### 3.8 admin 面板 404：resources/admin 不在仓库里
**现象**：镜像跑起来后 `/_admin` 返回 404，release 目录里没有 `admin` 静态文件。
**原因**：admin 前端来自独立仓库 `lejianwen/rustdesk-api-web`，官方 CI 先 checkout 该仓库、`npm run build` 后把 `dist/*` 拷进 `resources/admin/`，这一步在本地打包时缺失。
**解决**：
```sh
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/. <api-release>/resources/admin/
```
Go 二进制从磁盘读 `resources` 目录（不内嵌），所以**无需重编 Go**，重打镜像层即可。
### 3.9 杂项
- **pkill 自杀**：`pkill -f cargo` 会匹配到承载它的 `sh -c "... pkill -f cargo ..."` 自身，返回 143。用 `pkill -f '[c]argo'` 括号模式规避
- **管道吞退出码**：`cargo build | tail` 拿到的是 tail 的退出码；busybox ash 不支持 bash 的 `PIPESTATUS`。判断成功与否要看日志里的 `Finished`/`error` 行，或不用管道
- **镜像标签冲突**：为避免与作者发布的 `lejianwen/rustdesk-api:full-s6-amd64` 撞名，最终镜像按需求改为 `yangjieshao/rustdesk-api:full-s6-amd64`（仅本地，未推送）
## 4. 产物与验证结果
### 4.1 镜像
| 镜像 | 说明 |
|---|---|
| `yangjieshao/rustdesk-api:full-s6-amd64` | 最终完整镜像（hbbs + hbbr + rustdesk-utils + apimain + admin 前端，s6 托管） |
| `rustdesk-server-s6:1.1.17-forapi` | 本地自建的 s6 基础镜像（对应官方 `rustdesk/rustdesk-server-s6`，内含合并后的 1.1.17 二进制，musl 静态链接） |
服务器二进制：`hbbs`/`hbbr`/`rustdesk-utils`，`file` 确认 `ELF x86-64 static-pie linked`。
### 4.2 实测结论
- 21114(API)/21115(NAT)/21116(tcp+udp hbbs)/21117(hbbr)/21118(ws)/21119(ws relay) 全部监听
- `POST /api/login` 返回业务校验 JSON（接口正常）
- `/_admin/` 返回 200（admin 面板正常）
- s6 healthcheck：3 个服务（hbbs、hbbr、api）全部 up
- `/data` 下正确生成 `id_ed25519(.pub)` 与 `db_v2.sqlite3`
- 日志出现 `LIMIT_SPEED: 32Mb/s`、`Listening on websocket :21119`，确认 1.1.17 代码与 fork 的 relay WS 支持同时生效
### 4.3 已知无害现象
- 启动日志 `ERROR ... Failed to get machine uid: No such file or directory`：busybox/alpine 容器内没有 dbus machine-id 所致，官方镜像同样存在，hbbs 自动生成 ID 兜底，不影响功能
- 对 21118/21119 用普通 curl 探测返回 000/连接重置：这两个端口只接受 WebSocket 握手，非 ws 请求被断开是预期行为
## 5. 注意事项
1. **远端未动**：全程未 push、未登录任何账号。本地仅有两个 git 操作：
- forapi 分支上一条本地合并提交（含格式串修复，已 amend 进合并提交）
- 备份分支 `forapi-backup-pre-merge`（合并前状态，`git reset --hard forapi-backup-pre-merge` 可整体还原）
2. **官方仓库 `/root/rustdesk/rustdesk/rustdesk-server` 全程只读**；镜像构建上下文是复制到 `/root/rustdesk/build/s6img` 后再改的
3. **代理配置时效性**：`gh-proxy.com`/`rsproxy.cn`/阿里云 apk 源均为当下可用的国内加速，失效时按 3.1/3.2/3.8 的思路换源
4. **目录占用**：`rustdesk-server/target/` 是编译缓存（数 GB，不需要可删）；`/root/cargo-home` 是一次失败尝试的残留（可删）；构建相关都在 `/root/rustdesk/build/`（`s6img/`、`fullimg/`、`apibuild/`、`rustdesk-api-web/`、`testdata/`）
5. **测试容器**：`rustdesk-test` 还在运行（测试数据在 `build/testdata`，admin 初始密码 `S2qAgqSw`），`docker rm -f rustdesk-test` 清理
6. **下次升级的路径**：本次做法可复用——`git fetch upstream && git merge upstream/master`，重点冲突仍会集中在 `src/rendezvous_server.rs`（fork 的 API 特性与上游安全修复叠加）；hbb_common 子模块直接指到上游对应提交；编译用同样的容器方案
## 6. 常用命令备忘
```sh
# 服务器编译（持久容器方案）
docker run -d --name rustbuild --network host \
-v /root/rustdesk/lejianwen/rustdesk-server:/srv -w /srv rust:alpine sleep infinity
# 容器内：换阿里云 apk 源 → apk add build-base pkgconf openssl-dev openssl-libs-static git
# /usr/local/cargo/config.toml 配置 rsproxy-sparse + git-fetch-with-cli
# git config --system insteadOf 走 gh-proxy
docker exec rustbuild cargo build --release
# s6 基础镜像
docker build -f /root/rustdesk/build/s6img/Dockerfile.local -t rustdesk-server-s6:1.1.17-forapi /root/rustdesk/build/s6img
# 最终镜像（context 必须含 amd64/release）
docker build -f /root/rustdesk/build/fullimg/Dockerfile \
--build-arg BUILDARCH=amd64 -t yangjieshao/rustdesk-api:full-s6-amd64 /root/rustdesk/build/apibuild
# 验证
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'
```