From 58c24b798ef7d08f5609fda48e7615f4ec02f293 Mon Sep 17 00:00:00 2001 From: dijunkun Date: Tue, 9 Dec 2025 00:19:25 +0800 Subject: [PATCH] [chore] update README: refresh self-hosted server setup guide --- README.md | 149 ++++++++---------------------------------------- README_EN.md | 156 ++++++++++----------------------------------------- 2 files changed, 52 insertions(+), 253 deletions(-) diff --git a/README.md b/README.md index 9e0b294..d50bf50 100644 --- a/README.md +++ b/README.md @@ -179,145 +179,42 @@ sudo docker run -d \ -e COTURN_PORT=xxxx \ -e MIN_PORT=xxxxx \ -e MAX_PORT=xxxxx \ - -v /path/to/your/certs:/crossdesk-server/certs \ - -v /path/to/your/db:/crossdesk-server/db \ - -v /path/to/your/logs:/crossdesk-server/logs \ - crossdesk/crossdesk-server:v1.1.1 + -v /var/lib/crossdesk:/var/lib/crossdesk \ + -v /var/log/crossdesk:/var/log/crossdesk \ + crossdesk/crossdesk-server:v1.1.2 ``` 上述命令中，用户需注意的参数如下： +**参数** - EXTERNAL_IP：服务器公网 IP , 对应 CrossDesk 客户端**自托管服务器配置**中填写的**服务器地址** - - INTERNAL_IP：服务器内网 IP - - CROSSDESK_SERVER_PORT：自托管服务使用的端口，对应 CrossDesk 客户端**自托管服务器配置**中填写的**服务器端口** - - COTURN_PORT: COTURN 服务使用的端口, 对应 CrossDesk 客户端**自托管服务器配置**中填写的**中继服务端口** - - MIN_PORT/MAX_PORT：COTURN 服务使用的端口范围，例如：MIN_PORT=50000, MAX_PORT=60000，范围可根据客户端数量调整。 - -- /path/to/your/certs：证书文件目录 - -- /path/to/your/db：CrossDesk Server 设备管理数据库 - -- /path/to/your/logs：日志目录 - +- `-v /var/lib/crossdesk:/var/lib/crossdesk`：持久化数据库和证书文件到宿主机 +- `-v /var/log/crossdesk:/var/log/crossdesk`：持久化日志文件到宿主机 +- **注意**： -- **/path/to/your/ 是示例路径，请替换为你自己的实际路径。挂载的目录必须事先创建好，否则容器会报错。** - **服务器需开放端口：3478/udp，3478/tcp，MIN_PORT-MAX_PORT/udp，CROSSDESK_SERVER_PORT/tcp。** +- 如果不挂载 volume，容器删除后数据会丢失 +- 证书文件会在首次启动时自动生成并持久化到宿主机的 `/var/lib/crossdesk/certs` 路径下 +- 数据库文件会自动创建并持久化到宿主机的 `/var/lib/crossdesk/db/crossdesk-server.db` 路径下 +- 日志文件会自动创建并持久化到宿主机的 `/var/log/crossdesk/` 路径下 + +**权限注意**：如果 Docker 自动创建的目录权限不足（属于 root），容器内用户无法写入，会导致： + - 证书生成失败，容器启动脚本会报错退出 + - 数据库目录创建失败，程序会抛出异常并崩溃 + - 日志目录创建失败，日志文件无法写入（但程序可能继续运行） + +**解决方案**：在启动容器前手动设置权限： +```bash +sudo mkdir -p /var/lib/crossdesk /var/log/crossdesk +sudo chown -R $(id -u):$(id -g) /var/lib/crossdesk /var/log/crossdesk +``` ## 证书文件 -客户端需加载根证书文件，服务端需加载服务器私钥和服务器证书文件。 - -如果已有SSL证书的用户，可以忽略下面的证书生成步骤。 - -对于无证书的用户，可使用下面的脚本自行生成证书文件： -``` -# 创建证书生成脚本 -vim generate_certs.sh -``` -拷贝到脚本中 -``` -#!/bin/bash -set -e - -# 检查参数 -if [ "$#" -ne 1 ]; then - echo "Usage: $0 " - exit 1 -fi - -SERVER_IP="$1" - -# 文件名 -ROOT_KEY="crossdesk.cn_root.key" -ROOT_CERT="crossdesk.cn_root.crt" -SERVER_KEY="crossdesk.cn.key" -SERVER_CSR="crossdesk.cn.csr" -SERVER_CERT="crossdesk.cn_bundle.crt" -FULLCHAIN_CERT="crossdesk.cn_fullchain.crt" - -# 证书主题 -SUBJ="/C=CN/ST=Zhejiang/L=Hangzhou/O=CrossDesk/OU=CrossDesk/CN=$SERVER_IP" - -# 1. 生成根证书 -echo "Generating root private key..." -openssl genrsa -out "$ROOT_KEY" 4096 - -echo "Generating self-signed root certificate..." -openssl req -x509 -new -nodes -key "$ROOT_KEY" -sha256 -days 3650 -out "$ROOT_CERT" -subj "$SUBJ" - -# 2. 生成服务器私钥 -echo "Generating server private key..." -openssl genrsa -out "$SERVER_KEY" 2048 - -# 3. 生成服务器 CSR -echo "Generating server CSR..." -openssl req -new -key "$SERVER_KEY" -out "$SERVER_CSR" -subj "$SUBJ" - -# 4. 生成临时 OpenSSL 配置文件，加入 SAN -SAN_CONF="san.cnf" -cat > $SAN_CONF < "$FULLCHAIN_CERT" - -# 7. 清理中间文件 -rm -f "$ROOT_CERT.srl" "$SAN_CONF" "$ROOT_KEY" "$SERVER_CSR" "FULLCHAIN_CERT" - -echo "Generation complete. Deployment files:" -echo " Client root certificate: $ROOT_CERT" -echo " Server private key: $SERVER_KEY" -echo " Server certificate: $SERVER_CERT" -``` -执行 -``` -chmod +x generate_certs.sh -./generate_certs.sh 服务器公网IP - -# 例如 ./generate_certs.sh 111.111.111.111 -``` -输出如下： -``` -Generating root private key... -Generating self-signed root certificate... -Generating server private key... -Generating server CSR... -Signing server certificate with root certificate... -Certificate request self-signature ok -subject=C = CN, ST = Zhejiang, L = Hangzhou, O = CrossDesk, OU = CrossDesk, CN = xxx.xxx.xxx.xxx -cleaning up intermediate files... -Generation complete. Deployment files:: - Client root certificate:: crossdesk.cn_root.crt - Server private key: crossdesk.cn.key - Server certificate: crossdesk.cn_bundle.crt -``` - -### 服务端 -将 **crossdesk.cn.key** 和 **crossdesk.cn_bundle.crt** 放置到 **/path/to/your/certs** 目录下。 +在宿主机的 `/var/lib/crossdesk/certs` 路径下可找到证书文件 `crossdesk.cn_root.crt`，下载到你的客户端主机，并在客户端的**自托管服务器设置**中选择相应的**证书文件路径**。 ### 客户端 1. 点击右上角设置进入设置页面。
diff --git a/README_EN.md b/README_EN.md index 321092c..9efad12 100644 --- a/README_EN.md +++ b/README_EN.md @@ -187,142 +187,44 @@ sudo docker run -d \ -e COTURN_PORT=xxxx \ -e MIN_PORT=xxxxx \ -e MAX_PORT=xxxxx \ - -v /path/to/your/certs:/crossdesk-server/certs \ - -v /path/to/your/db:/crossdesk-server/db \ - -v /path/to/your/logs:/crossdesk-server/logs \ - crossdesk/crossdesk-server:v1.1.1 + -v /var/lib/crossdesk:/var/lib/crossdesk \ + -v /var/log/crossdesk:/var/log/crossdesk \ + crossdesk/crossdesk-server:v1.1.2 ``` The parameters you need to pay attention to are as follows: -- **EXTERNAL_IP**: The server's public IP, corresponding to the **Server Address** in the CrossDesk client **Self-Hosted Server Configuration**. +**Parameters** +- **EXTERNAL_IP**: The server’s public IP. This corresponds to **Server Address** in the CrossDesk client’s **Self-Hosted Server Configuration**. +- **INTERNAL_IP**: The server’s internal IP. +- **CROSSDESK_SERVER_PORT**: The port used by the self-hosted service. This corresponds to **Server Port** in the CrossDesk client’s **Self-Hosted Server Configuration**. +- **COTURN_PORT**: The port used by the COTURN service. This corresponds to **Relay Service Port** in the CrossDesk client’s **Self-Hosted Server Configuration**. +- **MIN_PORT / MAX_PORT**: The port range used by the COTURN service. Example: `MIN_PORT=50000`, `MAX_PORT=60000`. Adjust the range depending on the number of clients. +- `-v /var/lib/crossdesk:/var/lib/crossdesk`: Persists database and certificate files on the host machine. +- `-v /var/log/crossdesk:/var/log/crossdesk`: Persists log files on the host machine. -- **INTERNAL_IP**: The server's internal IP. +**Notes** +- **The server must open the following ports: 3478/udp, 3478/tcp, MIN_PORT–MAX_PORT/udp, and CROSSDESK_SERVER_PORT/tcp.** +- If you don’t mount volumes, all data will be lost when the container is removed. +- Certificate files will be automatically generated on first startup and persisted to the host at `/var/lib/crossdesk/certs`. +- The database file will be automatically created and stored at `/var/lib/crossdesk/db/crossdesk-server.db`. +- Log files will be created and stored at `/var/log/crossdesk/`. -- **CROSSDESK_SERVER_PORT**: The port used by the self-hosted server, corresponding to the **Server Port** in the CrossDesk client **Self-Hosted Server Configuration**. +**Permission Notice** +If the directories automatically created by Docker belong to root and have insufficient write permissions, the container user may not be able to write to them. This can cause: + - Certificate generation failure, leading to startup script errors and container exit. + - Database directory creation failure, causing the program to throw exceptions and crash. + - Log directory creation failure, preventing logs from being written (though the program may continue running). -- **COTURN_PORT**: The port used by Coturn, corresponding to the **Relay Server Port** in the CrossDesk client **Self-Hosted Server Configuration**. - -- **MIN_PORT** and **MAX_PORT**: The range of ports used by the self-hosted server, corresponding to the **Minimum Port** and **Maximum Port** in the CrossDesk client **Self-Hosted Server Configuration**. Example: 50000-60000. It depends on the number of devices connected to the server. - -- **/path/to/your/certs**: Directory for certificate files. - -- **/path/to/your/db**: CrossDesk Server device management database. - -- **/path/to/your/logs**: Log directory. - -**Note**: -- **/path/to/your/ is an example path; please replace it with your actual path. The mounted directories must be created in advance, otherwise the container will fail.** -- **The server must open the following ports: 3478/udp, 3478/tcp, 30000-60000/udp, CROSSDESK_SERVER_PORT/tcp.** - -## Certificate Files -The client needs to load the root certificate, and the server needs to load the server private key and server certificate. - -If you already have an SSL certificate, you can skip the following certificate generation steps. - -For users without a certificate, you can use the script below to generate the certificate files: +**Solution:** Manually set permissions before starting the container: +```bash +sudo mkdir -p /var/lib/crossdesk /var/log/crossdesk +sudo chown -R $(id -u):$(id -g) /var/lib/crossdesk /var/log/crossdesk ``` -# Create certificate generation script -vim generate_certs.sh -``` -Copy the following into the script: -``` -#!/bin/bash -set -e -# Check arguments -if [ "$#" -ne 1 ]; then - echo "Usage: $0 " - exit 1 -fi - -SERVER_IP="$1" - -# Filenames -ROOT_KEY="crossdesk.cn_root.key" -ROOT_CERT="crossdesk.cn_root.crt" -SERVER_KEY="crossdesk.cn.key" -SERVER_CSR="crossdesk.cn.csr" -SERVER_CERT="crossdesk.cn_bundle.crt" -FULLCHAIN_CERT="crossdesk.cn_fullchain.crt" - -# Certificate subject -SUBJ="/C=CN/ST=Zhejiang/L=Hangzhou/O=CrossDesk/OU=CrossDesk/CN=$SERVER_IP" - -# 1. Generate root certificate -echo "Generating root private key..." -openssl genrsa -out "$ROOT_KEY" 4096 - -echo "Generating self-signed root certificate..." -openssl req -x509 -new -nodes -key "$ROOT_KEY" -sha256 -days 3650 -out "$ROOT_CERT" -subj "$SUBJ" - -# 2. Generate server private key -echo "Generating server private key..." -openssl genrsa -out "$SERVER_KEY" 2048 - -# 3. Generate server CSR -echo "Generating server CSR..." -openssl req -new -key "$SERVER_KEY" -out "$SERVER_CSR" -subj "$SUBJ" - -# 4. Create temporary OpenSSL config file with SAN -SAN_CONF="san.cnf" -cat > $SAN_CONF < "$FULLCHAIN_CERT" - -# 7. Clean up intermediate files -rm -f "$ROOT_CERT.srl" "$SAN_CONF" "$ROOT_KEY" "$SERVER_CSR" "FULLCHAIN_CERT" - -echo "Generation complete. Deployment files:" -echo " Client root certificate: $ROOT_CERT" -echo " Server private key: $SERVER_KEY" -echo " Server certificate: $SERVER_CERT" -``` -Execute: -``` -chmod +x generate_certs.sh -./generate_certs.sh EXTERNAL_IP - -# example ./generate_certs.sh 111.111.111.111 -``` -Expected output: -``` -Generating root private key... -Generating self-signed root certificate... -Generating server private key... -Generating server CSR... -Signing server certificate with root certificate... -Certificate request self-signature ok -subject=C = CN, ST = Zhejiang, L = Hangzhou, O = CrossDesk, OU = CrossDesk, CN = xxx.xxx.xxx.xxx -cleaning up intermediate files... -Generation complete. Deployment files:: - Client root certificate:: crossdesk.cn_root.crt - Server private key: crossdesk.cn.key - Server certificate: crossdesk.cn_bundle.crt -``` +### Certificate Files +You can find the certificate file `crossdesk.cn_root.crt` at `/var/lib/crossdesk/certs` on the host machine. +Download it to your client device and select it in the **Certificate File Path** field under the CrossDesk client’s **Self-Hosted Server Settings**. ### Server Side Place **crossdesk.cn.key** and **crossdesk.cn_bundle.crt** into the **/path/to/your/certs** directory.