From 03bd34cadd4708e01db3b92f2987a2c0148e1206 Mon Sep 17 00:00:00 2001 From: ljw <84855512@qq.com> Date: Thu, 19 Sep 2024 12:03:18 +0800 Subject: [PATCH] up README_EN.md --- README_EN.md | 283 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 184 insertions(+), 99 deletions(-) diff --git a/README_EN.md b/README_EN.md index 821ebe3..222f56d 100644 --- a/README_EN.md +++ b/README_EN.md @@ -1,6 +1,7 @@ # 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.
@@ -9,64 +10,104 @@ This project implements RustDesk's API using Go and includes a Web UI and Web cl
-## Preparation +## Prerequisites ### [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. -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 -hbbs -r -k 123456789 -hbbr -k 123456789 -``` + ```bash + hbbs -r -k + hbbr -k + ``` + + Example: + + ```bash + hbbs -r -k abc1234567 + hbbr -k abc1234567 + ``` ## 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) + +#### 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) -### **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://: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://[: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) -2. Regular user interface - ![web_user](docs/web_user.png) -3. Password can be changed from the top-right corner +2. Regular user interface: + ![web_user](docs/web_admin_user.png) +3. You can change your password from the top right corner: ![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) +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:///api/oauth/callback`, + e.g., `http://127.0.0.1:21114/api/oauth/callback`. ### **Web Client**: -1. If you are already logged in to the admin panel, the web client will automatically log in. -2. If not logged in, click the login button in the top-right corner; the API server will be auto-configured. -3. Once logged into the admin panel, the address book will be saved automatically in the web client for convenience. +1. If you're already logged into the admin panel, the web client will log in automatically. +2. If you're not logged in, simply click the login button at the top right corner, and the API server will be + pre-configured. ![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: `/admin/swagger/index.html` -2. PC client documentation: `/swagger/index.html` +**: API documentation is generated using Swag, making it easier for developers to understand and use the API. + +1. Admin panel docs: `/admin/swagger/index.html` +2. PC client docs: `/swagger/index.html` ![api_swag](docs/api_swag.png) -## Installation and Running +## Installation and Setup ### 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 gin: api-addr: "0.0.0.0:21114" mode: "release" resources-path: 'resources' + trust-proxy: "" gorm: type: "sqlite" max-idle-conns: 10 @@ -83,88 +124,128 @@ rustdesk: key: "123456789" ``` +* Environment variables, with the prefix `RUSTDESK_API`, will override the settings in the configuration file if + present. + +| Variable Name | Description | Example | +|------------------------------------|-----------------------------------------------------------|--------------------------------| +| ----- GIN Configuration ----- | --------------------------------------- | ------------------------------ | +| RUSTDESK_API_GIN_TRUST_PROXY | Trusted proxy IPs, separated by commas. | 192.168.1.2,192.168.1.3 | +| ----- GORM Configuration ----- | --------------------------------------- | ------------------------------ | +| RUSTDESK_API_GORM_TYPE | Database type (`sqlite` or `mysql`). Default is `sqlite`. | 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_PASSWORD | MySQL password | 111111 | +| RUSTDESK_API_MYSQL_ADDR | MySQL address | 192.168.1.66:3306 | +| RUSTDESK_API_MYSQL_DBNAME | MySQL database name | rustdesk | +| ----- RUSTDESK Configuration ----- | --------------------------------------- | ------------------------------ | +| 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_API_SERVER | Rustdesk API server address | http://192.168.1.66:21114 | +| RUSTDESK_API_RUSTDESK_KEY | Rustdesk key | 123456789 | + ### Installation Steps -#### Running with Docker +#### Running via Docker -1. Run directly using 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 lejianwen/rustdesk-api +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 ``` -- Environment variables with the prefix `RUSTDESK_API` can be set. +2. Using `docker-compose` -| Variable Name | Description | Example | -|----------------------------------------|--------------------------------------------------|------------------------------| -| -----------GORM Configuration----------| -------------------------------------------------| -----------------------------| -| RUSTDESK_API_GORM_TYPE | Database type, either `sqlite` or `mysql`. Default is `sqlite` | sqlite | -| RUSTDESK_API_GORM_MAX_IDLE_CONNS | Maximum number of idle connections | 10 | -| RUSTDESK_API_GORM_MAX_OPEN_CONNS | Maximum number of open connections | 100 | -| -----------MySQL Configuration---------| ---Not required if using `sqlite`--- | | -| RUSTDESK_API_MYSQL_USERNAME | MySQL username | root | -| RUSTDESK_API_MYSQL_PASSWORD | MySQL password | 111111 | -| RUSTDESK_API_MYSQL_ADDR | MySQL address | 192.168.1.66:3306 | -| RUSTDESK_API_MYSQL_DBNAME | MySQL database name | rustdesk | -| -----------Rustdesk Configuration------| -------------------------------------------------| -----------------------------| -| 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_API_SERVER | Rustdesk API server address | http://192.168.1.66:21114 | -| RUSTDESK_API_RUSTDESK_KEY | Rustdesk key | 123456789 | + - Simple example: -2. Use `docker-compose`, adding your RustDesk API configuration to the provided RustDesk 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 + ``` -```docker-compose -networks: - rustdesk-net: - external: false -services: - hbbs: - container_name: hbbs - ports: - - 21115:21115 - - 21116:21116 # Custom hbbs port mapping - - 21116:21116/udp # Custom hbbs port mapping - - 21118:21118 # Required for web client - image: rustdesk/rustdesk-server - command: hbbs -r -k 123456789 # Use your domain or IP + hbbr exposed port - volumes: - - /data/rustdesk/hbbs:/root # Custom mount directory - networks: - - rustdesk-net - depends_on: - - hbbr - restart: unless-stopped - deploy: - resources: - limits: - memory: 64M - hbbr: - container_name: hbbr - ports: - - 21117:21117 # Custom hbbr port mapping - image: rustdesk/rustdesk-server - command: hbbr -k 123456789 - volumes: - - /data/rustdesk/hbbr:/root # Custom mount directory - networks: - - rustdesk-net - restart: unless-stopped - deploy: - resources: - limits: - memory: 64M - rustdesk-api: - container_name: rustdesk-api - ports: - - 21114:21114 - image: lejianwen/rustdesk-api - volumes: - - /data/rustdesk/api:/app/data # Mount database for easy backups - networks: - - rustdesk-net - restart: unless-stopped -``` + - Example with RustDesk's official Docker Compose file, adding your `rustdesk-api` service: + + ```docker-compose + networks: + rustdesk-net: + external: false + services: + hbbs: + container_name: hbbs + ports: + - 21115:21115 + - 21116:21116 # 自定义 hbbs 映射端口 + - 21116:21116/udp # 自定义 hbbs 映射端口 + - 21118:21118 # web client 需要 + image: rustdesk/rustdesk-server + command: hbbs -r -k 123456789 # 填入个人域名或 IP + hbbr 暴露端口 + volumes: + - /data/rustdesk/hbbs:/root # 自定义挂载目录 + networks: + - rustdesk-net + depends_on: + - hbbr + restart: unless-stopped + deploy: + resources: + limits: + memory: 64M + hbbr: + container_name: hbbr + ports: + - 21117:21117 # 自定义 hbbr 映射端口 + image: rustdesk/rustdesk-server + command: hbbr -k 123456789 + #command: hbbr + volumes: + - /data/rustdesk/hbbr:/root # 自定义挂载目录 + networks: + - rustdesk-net + restart: unless-stopped + deploy: + resources: + limits: + memory: 64M + 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 #将数据库挂载出来方便备份 + networks: + - rustdesk-net + restart: unless-stopped + + ``` #### 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 ``` -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 cd resources mkdir -p admin @@ -205,9 +287,12 @@ Download the release from [release](https://github.com/lejianwen/rustdesk-api/re 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://:21114/_admin/`, with default credentials `admin admin`. Please change the password promptly. +6. Open your browser and visit `http://:21114/_admin/`, with default credentials `admin admin`. Please + change the password promptly. ## Miscellaneous