thomas/rustdesk-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

up README_EN.md

Browse Source
This commit is contained in:
ljw
2024-09-19 12:03:18 +08:00
parent 1c3f87fecb
commit 03bd34cadd
1 changed files with 184 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README_EN.md
+137 -52
View File
@@ -1,6 +1,7 @@
# RustDesk API # RustDesk API
This project implements RustDesk's API using Go and includes a Web UI and Web client. RustDesk is a remote desktop software that provides a self-hosting solution. This project implements the RustDesk API using Go, and includes both a web UI and web client. RustDesk is a remote
desktop software that provides self-hosted solutions.
<div align=center> <div align=center>
<img src="https://img.shields.io/badge/golang-1.22-blue"/> <img src="https://img.shields.io/badge/golang-1.22-blue"/>
@@ -9,64 +10,104 @@ This project implements RustDesk's API using Go and includes a Web UI and Web cl
<img src="https://img.shields.io/badge/swag-v1.16.3-yellow"/> <img src="https://img.shields.io/badge/swag-v1.16.3-yellow"/>
</div> </div>
## Preparation ## Prerequisites
### [Rustdesk](https://github.com/rustdesk/rustdesk) ### [Rustdesk](https://github.com/rustdesk/rustdesk)
1. The PC client version used is ***1.3.0***, and versions ***1.2.6+*** have been tested to work. 1. The PC client version used is ***1.3.0***, and versions ***1.2.6+*** have been tested to work.
2. The server must specify a key and not use the built-in generated key; otherwise, connection issues or timeouts may occur. 2. The server must specify a key, and not use the auto-generated key, otherwise there may be connection failures or
timeouts.
```bash ```bash
hbbs -r <relay-server-ip[:port]> -k 123456789 hbbs -r <relay-server-ip[:port]> -k <key>
hbbr -k 123456789 hbbr -k <key>
```
Example:
```bash
hbbs -r <relay-server-ip[:port]> -k abc1234567
hbbr -k abc1234567
``` ```
## Features ## Features
### **API Service**: Implements the basic interfaces for the PC client. ### API Service: Basic implementation of the PC client's primary interfaces.
#### Login
- Added `GitHub` login, which can be used after configuration in the admin panel. See the OAuth configuration section
for details.
- Added authorization login for the web admin panel.
![pc_login](docs/pc_login.png)
#### Address Book
![pc_ab](docs/pc_ab.png) ![pc_ab](docs/pc_ab.png)
#### Groups: Groups are divided into `shared groups` and `regular groups`. In shared groups, everyone can see the addresses of all group members, while in regular groups, only administrators can see all members' addresses.
![pc_gr](docs/pc_gr.png) ![pc_gr](docs/pc_gr.png)
### **Web UI**: Uses a front-end and back-end separation, providing a user-friendly management interface primarily for administration and display. ### **Web UI
***The front-end code is available at [rustdesk-api-web](https://github.com/lejianwen/rustdesk-api-web).*** **: The frontend and backend are separated to provide a user-friendly management interface, primarily for managing and
displaying data.
***The admin panel can be accessed at `http://<your server>:21114/_admin/` with default credentials of `admin admin`. Please change the password promptly.*** ***Frontend code is available at [rustdesk-api-web](https://github.com/lejianwen/rustdesk-api-web)***
1. Admin interface ***Admin panel URL: `http://<your server>[:port]/_admin/`. The default username and password for the initial
installation are `admin` `admin`, please change the password immediately.***
1. Admin interface:
![web_admin](docs/web_admin.png) ![web_admin](docs/web_admin.png)
2. Regular user interface 2. Regular user interface:
![web_user](docs/web_user.png) ![web_user](docs/web_admin_user.png)
3. Password can be changed from the top-right corner 3. You can change your password from the top right corner:
![web_resetpwd](docs/web_resetpwd.png) ![web_resetpwd](docs/web_resetpwd.png)
4. Groups can be customized for easier management. Two types of groups are currently supported: `Shared Group` and `Regular Group`. 4. Groups can be customized for easy management. Currently, two types are supported: `shared group` and `regular group`.
![web_admin_gr](docs/web_admin_gr.png) ![web_admin_gr](docs/web_admin_gr.png)
5. You can open the web client directly for convenience:
![web_webclient](docs/admin_webclient.png)
6. OAuth support: Currently, only `GitHub` is supported. You need to create an `OAuth App` and configure it in the admin
panel.
![web_admin_oauth](docs/web_admin_oauth.png)
- Create a `GitHub OAuth App`
at `Settings` -> `Developer settings` -> `OAuth Apps` -> `New OAuth App` [here](https://github.com/settings/developers).
- Set the `Authorization callback URL` to `http://<your server[:port]>/api/oauth/callback`,
e.g., `http://127.0.0.1:21114/api/oauth/callback`.
### **Web Client**: ### **Web Client**:
1. If you are already logged in to the admin panel, the web client will automatically log in. 1. If you're already logged into the admin panel, the web client will log in automatically.
2. If not logged in, click the login button in the top-right corner; the API server will be auto-configured. 2. If you're not logged in, simply click the login button at the top right corner, and the API server will be
3. Once logged into the admin panel, the address book will be saved automatically in the web client for convenience. pre-configured.
![webclient_conf](docs/webclient_conf.png) ![webclient_conf](docs/webclient_conf.png)
3. After logging in, the ID server and key will be automatically synced.
4. The address book will also be automatically saved to the web client for convenient use.
### **Automated Documentation**: API documentation is generated using Swag, making it easier for developers to understand and use the API. ### **Automated Documentation
1. Admin documentation: `<your server>/admin/swagger/index.html` **: API documentation is generated using Swag, making it easier for developers to understand and use the API.
2. PC client documentation: `<your server>/swagger/index.html`
1. Admin panel docs: `<your server>/admin/swagger/index.html`
2. PC client docs: `<your server>/swagger/index.html`
![api_swag](docs/api_swag.png) ![api_swag](docs/api_swag.png)
## Installation and Running ## Installation and Setup
### Configuration ### Configuration
* Refer to the `conf/config.yaml` file to modify relevant configurations. If `gorm.type` is `sqlite`, MySQL configurations are not required. * Modify the configuration in `conf/config.yaml`. If `gorm.type` is set to `sqlite`, MySQL-related configurations are
not required.
```yaml ```yaml
gin: gin:
api-addr: "0.0.0.0:21114" api-addr: "0.0.0.0:21114"
mode: "release" mode: "release"
resources-path: 'resources' resources-path: 'resources'
trust-proxy: ""
gorm: gorm:
type: "sqlite" type: "sqlite"
max-idle-conns: 10 max-idle-conns: 10
@@ -83,36 +124,69 @@ rustdesk:
key: "123456789" key: "123456789"
``` ```
### Installation Steps * Environment variables, with the prefix `RUSTDESK_API`, will override the settings in the configuration file if
present.
#### Running with Docker
1. Run directly using Docker:
```bash
docker run -d --name rustdesk-api -p 21114:21114 -v /data/rustdesk/api:/app/data lejianwen/rustdesk-api
```
- Environment variables with the prefix `RUSTDESK_API` can be set.
| Variable Name | Description | Example | | Variable Name | Description | Example |
|----------------------------------------|--------------------------------------------------|------------------------------| |------------------------------------|-----------------------------------------------------------|--------------------------------|
| -----------GORM Configuration----------| -------------------------------------------------| -----------------------------| | ----- GIN Configuration ----- | --------------------------------------- | ------------------------------ |
| RUSTDESK_API_GORM_TYPE | Database type, either `sqlite` or `mysql`. Default is `sqlite` | sqlite | | RUSTDESK_API_GIN_TRUST_PROXY | Trusted proxy IPs, separated by commas. | 192.168.1.2,192.168.1.3 |
| RUSTDESK_API_GORM_MAX_IDLE_CONNS | Maximum number of idle connections | 10 | | ----- GORM Configuration ----- | --------------------------------------- | ------------------------------ |
| RUSTDESK_API_GORM_MAX_OPEN_CONNS | Maximum number of open connections | 100 | | RUSTDESK_API_GORM_TYPE | Database type (`sqlite` or `mysql`). Default is `sqlite`. | sqlite |
| -----------MySQL Configuration---------| ---Not required if using `sqlite`--- | | | RUSTDESK_API_GORM_MAX_IDLE_CONNS | Maximum idle connections | 10 |
| RUSTDESK_API_GORM_MAX_OPEN_CONNS | Maximum open connections | 100 |
| ----- MYSQL Configuration ----- | --------------------------------------- | ------------------------------ |
| RUSTDESK_API_MYSQL_USERNAME | MySQL username | root | | RUSTDESK_API_MYSQL_USERNAME | MySQL username | root |
| RUSTDESK_API_MYSQL_PASSWORD | MySQL password | 111111 | | RUSTDESK_API_MYSQL_PASSWORD | MySQL password | 111111 |
| RUSTDESK_API_MYSQL_ADDR | MySQL address | 192.168.1.66:3306 | | RUSTDESK_API_MYSQL_ADDR | MySQL address | 192.168.1.66:3306 |
| RUSTDESK_API_MYSQL_DBNAME | MySQL database name | rustdesk | | RUSTDESK_API_MYSQL_DBNAME | MySQL database name | rustdesk |
| -----------Rustdesk Configuration------| -------------------------------------------------| -----------------------------| | ----- RUSTDESK Configuration ----- | --------------------------------------- | ------------------------------ |
| RUSTDESK_API_RUSTDESK_ID_SERVER | Rustdesk ID server address | 192.168.1.66:21116 | | RUSTDESK_API_RUSTDESK_ID_SERVER | Rustdesk ID server address | 192.168.1.66:21116 |
| RUSTDESK_API_RUSTDESK_RELAY_SERVER | Rustdesk relay server address | 192.168.1.66:21117 | | RUSTDESK_API_RUSTDESK_RELAY_SERVER | Rustdesk relay server address | 192.168.1.66:21117 |
| RUSTDESK_API_RUSTDESK_API_SERVER | Rustdesk API server address | http://192.168.1.66:21114 | | RUSTDESK_API_RUSTDESK_API_SERVER | Rustdesk API server address | http://192.168.1.66:21114 |
| RUSTDESK_API_RUSTDESK_KEY | Rustdesk key | 123456789 | | RUSTDESK_API_RUSTDESK_KEY | Rustdesk key | 123456789 |
2. Use `docker-compose`, adding your RustDesk API configuration to the provided RustDesk example: ### Installation Steps
#### Running via Docker
1. Run directly with Docker. Configuration can be modified by mounting the config file `/app/conf/config.yaml`, or by
using environment variables to override settings.
```bash
docker run -d --name rustdesk-api -p 21114:21114 \
-v /data/rustdesk/api:/app/data \
-e RUSTDESK_API_RUSTDESK_ID_SERVER=192.168.1.66:21116 \
-e RUSTDESK_API_RUSTDESK_RELAY_SERVER=192.168.1.66:21117 \
-e RUSTDESK_API_RUSTDESK_API_SERVER=http://192.168.1.66:21114 \
-e RUSTDESK_API_RUSTDESK_KEY=123456789 \
lejianwen/rustdesk-api
```
2. Using `docker-compose`
- Simple example:
```docker-compose
services:
rustdesk-api:
container_name: rustdesk-api
environment:
- RUSTDESK_API_RUSTDESK_ID_SERVER=192.168.1.66:21116
- RUSTDESK_API_RUSTDESK_RELAY_SERVER=192.168.1.66:21117
- RUSTDESK_API_RUSTDESK_API_SERVER=http://192.168.1.66:21114
- RUSTDESK_API_RUSTDESK_KEY=123456789
ports:
- 21114:21114
image: lejianwen/rustdesk-api
volumes:
- /data/rustdesk/api:/app/data # Mount the database for easy backup
networks:
- rustdesk-net
restart: unless-stopped
```
- Example with RustDesk's official Docker Compose file, adding your `rustdesk-api` service:
```docker-compose ```docker-compose
networks: networks:
@@ -123,13 +197,13 @@ services:
container_name: hbbs container_name: hbbs
ports: ports:
- 21115:21115 - 21115:21115
- 21116:21116 # Custom hbbs port mapping - 21116:21116 # 自定义 hbbs 映射端口
- 21116:21116/udp # Custom hbbs port mapping - 21116:21116/udp # 自定义 hbbs 映射端口
- 21118:21118 # Required for web client - 21118:21118 # web client 需要
image: rustdesk/rustdesk-server image: rustdesk/rustdesk-server
command: hbbs -r <relay-server-ip[:port]> -k 123456789 # Use your domain or IP + hbbr exposed port command: hbbs -r <relay-server-ip[:port]> -k 123456789 # 填入个人域名或 IP + hbbr 暴露端口
volumes: volumes:
- /data/rustdesk/hbbs:/root # Custom mount directory - /data/rustdesk/hbbs:/root # 自定义挂载目录
networks: networks:
- rustdesk-net - rustdesk-net
depends_on: depends_on:
@@ -142,11 +216,12 @@ services:
hbbr: hbbr:
container_name: hbbr container_name: hbbr
ports: ports:
- 21117:21117 # Custom hbbr port mapping - 21117:21117 # 自定义 hbbr 映射端口
image: rustdesk/rustdesk-server image: rustdesk/rustdesk-server
command: hbbr -k 123456789 command: hbbr -k 123456789
#command: hbbr
volumes: volumes:
- /data/rustdesk/hbbr:/root # Custom mount directory - /data/rustdesk/hbbr:/root # 自定义挂载目录
networks: networks:
- rustdesk-net - rustdesk-net
restart: unless-stopped restart: unless-stopped
@@ -156,14 +231,20 @@ services:
memory: 64M memory: 64M
rustdesk-api: rustdesk-api:
container_name: rustdesk-api container_name: rustdesk-api
environment:
- RUSTDESK_API_RUSTDESK_ID_SERVER=192.168.1.66:21116
- RUSTDESK_API_RUSTDESK_RELAY_SERVER=192.168.1.66:21117
- RUSTDESK_API_RUSTDESK_API_SERVER=http://192.168.1.66:21114
- RUSTDESK_API_RUSTDESK_KEY=123456789
ports: ports:
- 21114:21114 - 21114:21114
image: lejianwen/rustdesk-api image: lejianwen/rustdesk-api
volumes: volumes:
- /data/rustdesk/api:/app/data # Mount database for easy backups - /data/rustdesk/api:/app/data #将数据库挂载出来方便备份
networks: networks:
- rustdesk-net - rustdesk-net
restart: unless-stopped restart: unless-stopped
``` ```
#### Running from Release #### Running from Release
@@ -186,7 +267,8 @@ Download the release from [release](https://github.com/lejianwen/rustdesk-api/re
go install github.com/swaggo/swag/cmd/swag@latest go install github.com/swaggo/swag/cmd/swag@latest
``` ```
3. Build the admin front-end (the front-end code is in [rustdesk-api-web](https://github.com/lejianwen/rustdesk-api-web)): 3. Build the admin front-end (the front-end code is
in [rustdesk-api-web](https://github.com/lejianwen/rustdesk-api-web)):
```bash ```bash
cd resources cd resources
mkdir -p admin mkdir -p admin
@@ -205,9 +287,12 @@ Download the release from [release](https://github.com/lejianwen/rustdesk-api/re
go generate generate_api.go go generate generate_api.go
``` ```
5. To compile, change to the project root directory. For Windows, run `build.bat`, and for Linux, run `build.sh`. After compiling, the corresponding executables will be generated in the `release` directory. Run the compiled executables directly. 5. To compile, change to the project root directory. For Windows, run `build.bat`, and for Linux, run `build.sh`. After
compiling, the corresponding executables will be generated in the `release` directory. Run the compiled executables
directly.
6. Open your browser and visit `http://<your server>:21114/_admin/`, with default credentials `admin admin`. Please change the password promptly. 6. Open your browser and visit `http://<your server>:21114/_admin/`, with default credentials `admin admin`. Please
change the password promptly.
## Miscellaneous ## Miscellaneous