[docs] refresh README screenshots and platform guides

2026-10-19 18:33:00 +08:00 · 2026-09-07 22:53:30 +08:00
parent abc8f907f3
commit b518ea82e2
19 changed files with 1223 additions and 812 deletions
@@ -0,0 +1,240 @@
+# 从源码构建
+
+[返回 README](../README.md) · [English](BUILD_EN.md)
+
+克隆仓库后，构建和打包命令均在仓库根目录执行。构建依赖与参数以 [Xmake 配置](../apps/desktop/xmake/options.lua) 和 [CI 工作流](../.github/workflows/build.yml) 为准。`1.4.3` 仅为本地构建示例版本号；调整时请同步修改配置命令与打包参数，避免程序内版本号与安装包不一致。
+
+## 构建依赖
+
+- Git、[Xmake](https://xmake.io/guide/quick-start.html) 及下文对应平台的编译工具链。
+- 构建脚本通过 Xmake 管理 **CMake 3.x（≥ 3.21、< 4.0）**、**Rust 1.92.0** 等依赖；首次构建需要下载工具与源码。具体约束见 [Slint 包配置](../deps/thirdparty/slint/xmake.lua)。
+
+## Windows
+
+安装 Visual Studio 2022 的“使用 C++ 的桌面开发”工作负载及 Windows SDK，并安装 Xmake。在开发者 PowerShell 中执行：
+
+```powershell
+git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
+cd crossdesk
+xmake f -c -p windows -a x64 -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false -y
+xmake b -vy crossdesk
+xmake r crossdesk
+```
+
+安装包还使用 NSIS，需将仓库中的 [nsProcess.dll](../apps/desktop/scripts/windows/nsProcess.dll) 放入 NSIS 的 `Plugins/x86-unicode` 目录，并确保 `makensis` 在 `PATH` 中。完成 Release 编译后运行：
+
+```powershell
+.\apps\desktop\scripts\windows\pkg_x64.ps1 1.4.3
+```
+
+完整流程见 [Windows 脚本](../apps/desktop/scripts/windows/pkg_x64.ps1) 和 [CI 工作流](../.github/workflows/build.yml)。手动部署时需保留运行库及两个服务辅助程序，见 [Windows 服务说明](../README.md#windows-service)。
+
+## macOS
+
+安装 Xcode 及其命令行工具、Xmake，然后执行：
+
+```bash
+git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
+cd crossdesk
+xmake f -c -m release --target_minver=14.0 --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false -y
+xmake b -vy crossdesk
+xmake r crossdesk
+```
+
+当前 CI 对 Intel 与 Apple Silicon 均设置 macOS 14.0 为最低目标版本，使用的 Xcode/SDK 版本见 [CI 工作流](../.github/workflows/build.yml)。打包时按本机架构执行一个脚本：
+
+```bash
+# Apple Silicon
+./apps/desktop/scripts/macos/pkg_arm64.sh 1.4.3
+# Intel
+./apps/desktop/scripts/macos/pkg_x64.sh 1.4.3
+```
+
+打包脚本会生成包含 Slint 运行库的 `.app` 和 `.pkg`。屏幕录制、辅助功能授权与应用路径及签名有关；测试被控能力时请使用固定路径下的应用包。
+
+## Linux
+
+Linux 构建支持 Ubuntu 20.04 及以上版本的 amd64 和 arm64。发布安装包以
+Ubuntu 20.04/glibc 2.31 为兼容基线。以下依赖命令以 Ubuntu 20.04 为例；其他发行版或较新版本需按其软件源调整包名和工具链，复现 CI 可使用下文的构建镜像。先安装基础编译依赖：
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  git curl unzip build-essential gcc-10 g++-10 python3-pip \
+  pkg-config binutils dpkg-dev \
+  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
+  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
+  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
+  libxcb-shape0-dev libxcb-xkb-dev libxcb-xfixes0-dev libxcb-shm0-dev \
+  libasound2-dev libsndio-dev libpulse-dev \
+  libgl1-mesa-dev
+```
+
+Ubuntu 20.04 自带的 CMake 3.16 不满足要求，Xmake 会下载符合上述范围的
+CMake 3.x，无需手动替换系统 CMake。
+
+Ubuntu 20.04 默认的 GCC 9 缺少 Slint C++ API 所需的部分 C++20 标准库，
+因此上述命令同时安装并在后续配置中指定 GCC 10。
+
+下载子模块并编译 Release 版本：
+
+```bash
+git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
+cd crossdesk
+
+# 已经克隆过仓库时执行这一行
+git submodule update --init --recursive
+
+xmake f -c -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false --toolchain=gcc-10 -y
+xmake b -vy crossdesk
+```
+
+这里应使用 `--toolchain=gcc-10`，以确保 CrossDesk 及 xmake 在配置阶段构建的
+libyuv 等第三方包都使用 GCC 10。只指定 `--cc`/`--cxx` 时，依赖安装可能仍回退到
+系统默认的 `/bin/cc` 和 `/bin/c++`。`-c` 会清除旧配置，切换编译器时必须保留。
+
+amd64 构建结果位于 `build/linux/x86_64/release/crossdesk`，arm64 构建结果位于 `build/linux/arm64/release/crossdesk`。
+
+启用 Wayland 和 DRM 时，再安装 D-Bus、DRM 及 PipeWire 开发依赖。Ubuntu 20.04 使用仓库提供的 PipeWire 头文件 SDK；Ubuntu 22.04 及以上可改用系统的 `libpipewire-0.3-dev` 和 `libspa-0.2-dev` 包：
+
+```bash
+sudo apt-get install -y libdbus-1-dev libdrm-dev
+# 已安装系统 PipeWire 0.3 开发包时跳过这一行
+sudo ./docker/linux-build/install-pipewire-sdk.sh
+
+xmake f -c -m release --USE_WAYLAND=true --USE_DRM=true --USE_CUDA=false \
+  --CROSSDESK_VERSION=1.4.3 --toolchain=gcc-10 -y
+xmake b -vy crossdesk
+```
+
+生成 Debian 安装包（必须在对应架构上先完成 Release 编译）：
+
+```bash
+# amd64
+./apps/desktop/scripts/linux/pkg_amd64.sh 1.4.3
+
+# arm64
+./apps/desktop/scripts/linux/pkg_arm64.sh 1.4.3
+```
+
+打包脚本会将 Slint 共享运行库安装到软件包私有目录 `/usr/lib/crossdesk`，无需用户另外安装 `libslint_cpp.so`。
+PipeWire 不属于强制运行时依赖：程序在运行时检测宿主系统的 PipeWire 0.3，
+没有该运行库时仍可使用 X11（以及构建时启用的 DRM）捕获。
+
+## 通用编译选项
+
+```text
+--USE_CUDA=true/false: 启用 CUDA 硬件编解码，默认不启用
+--USE_WAYLAND=true/false: 在 Linux 上启用 Wayland/PipeWire 捕获，默认不启用
+--USE_DRM=true/false: 在 Linux 上启用 DRM 捕获，默认不启用
+--CROSSDESK_PORTABLE=true/false: 构建便携版本，默认不启用
+--CROSSDESK_VERSION=xxx: 指定 CrossDesk 的版本
+
+# 示例
+xmake f --CROSSDESK_VERSION=1.4.3 --USE_CUDA=true
+```
+
+运行：
+
+```bash
+xmake r crossdesk
+```
+
+## 无 CUDA 环境下的开发支持
+
+对于**未安装 CUDA 环境的 Linux 开发者，如果希望编译后的成果物拥有硬件编解码能力**，这里提供了预配置的 [Ubuntu 20.04 兼容构建镜像](https://hub.docker.com/r/crossdesk/ubuntu20.04)。该镜像内置必要的构建依赖，可生成兼容 glibc 2.31 的单一 Linux 安装包。
+
+镜像版本和 amd64 / arm64 差异见 [构建镜像说明](../docker/linux-build/README.md)。以下 CUDA 示例适用于 amd64 镜像；进入容器、下载工程后执行：
+
+```bash
+export CUDA_PATH=/usr/local/cuda
+export XMAKE_GLOBALDIR=/data
+
+xmake f --root -c -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=true --toolchain=gcc-10 -y
+xmake b --root -vy crossdesk
+```
+
+对于**未安装 CUDA 环境的 Windows 开发者**，执行下面的命令安装 CUDA 编译环境：
+
+```powershell
+xmake require -vy "cuda 12.6.3"
+```
+
+安装完成后执行:
+
+```powershell
+xmake require --info "cuda 12.6.3"
+```
+
+在输出中查找 `installdir` 字段。
+
+使用 `installdir` 指向的 CUDA 安装目录。将 CUDA_PATH 加入系统环境变量，或在终端中输入：
+
+```powershell
+$env:CUDA_PATH = "C:\path\to\cuda_installdir"
+```
+
+重新执行：
+
+```powershell
+xmake f --USE_CUDA=true
+xmake b -vy crossdesk
+```
+
+### 运行时连接问题
+
+“未连接服务器”可能由网络、服务器配置或证书信任引起，不应只通过安装另一份客户端来排查。请按 [常见问题](FAQ.md) 和 [自托管证书说明](SELF_HOSTING.md) 检查。
+
+## 关于 Xmake
+
+### 安装 Xmake
+
+使用 curl：
+
+```bash
+curl -fsSL https://xmake.io/shget.text | bash
+```
+
+使用 wget：
+
+```bash
+wget https://xmake.io/shget.text -O - | bash
+```
+
+使用 powershell：
+
+```powershell
+irm https://xmake.io/psget.text | iex
+```
+
+### 编译选项
+
+```text
+# 切换到 Debug；Release 构建将 debug 替换为 release
+xmake f -m debug
+
+# 可选编译参数
+-r ：重新构建目标
+-v ：显示详细的构建日志
+-y ：自动确认提示
+
+# 示例
+xmake b -vy crossdesk
+```
+
+### 运行选项
+
+```bash
+# 使用调试器启动当前构建；不会自动切换为 Debug 编译模式
+xmake r -d crossdesk
+```
+
+更多使用方法可参考 [Xmake 官方文档](https://xmake.io/guide/quick-start.html)。
+
+## iOS / iPadOS
+
+原生客户端使用独立 Xcode 工程，要求 iOS 16+ 的 arm64 真机。构建与音视频、文件传输验证步骤见 [iOS 开发说明](../apps/ios/README.md)。当前 CI 导出未签名应用，真机安装需要自行签名。
+
+## 更新界面截图
+
+README 的桌面图片直接由当前 Slint UI 渲染，复现方式见 [截图说明](images/README.md)。
@@ -0,0 +1,253 @@
+# Build from source
+
+[Back to README](../README_EN.md) · [中文](BUILD.md)
+
+After cloning, run build and packaging commands from the repository root. The [Xmake options](../apps/desktop/xmake/options.lua) and [CI workflow](../.github/workflows/build.yml) define the build configuration. `1.4.3` is an example version for local builds; change both the configuration value and packaging argument together so the app and package versions match.
+
+## Build requirements
+
+- Git, [Xmake](https://xmake.io/guide/quick-start.html), and the platform toolchain listed below.
+- The build scripts use Xmake to manage **CMake 3.x (≥ 3.21, < 4.0)**, **Rust 1.92.0**, and other dependencies. The first build downloads tools and source archives. See the [Slint package configuration](../deps/thirdparty/slint/xmake.lua) for the constraints.
+
+## Windows
+
+Install Visual Studio 2022 with the **Desktop development with C++** workload and Windows SDK, plus Xmake. In a developer PowerShell, run:
+
+```powershell
+git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
+cd crossdesk
+xmake f -c -p windows -a x64 -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false -y
+xmake b -vy crossdesk
+xmake r crossdesk
+```
+
+Installer packaging also uses NSIS. Copy the repository's [nsProcess.dll](../apps/desktop/scripts/windows/nsProcess.dll) into NSIS's `Plugins/x86-unicode` directory and ensure `makensis` is on `PATH`. After building Release, run:
+
+```powershell
+.\apps\desktop\scripts\windows\pkg_x64.ps1 1.4.3
+```
+
+See the [Windows packaging script](../apps/desktop/scripts/windows/pkg_x64.ps1) and [CI workflow](../.github/workflows/build.yml) for the full process. Manual deployment must retain the runtime libraries and both service helpers; see [Windows Service](../README_EN.md#windows-service).
+
+## macOS
+
+Install Xcode and its command-line tools, plus Xmake, then run:
+
+```bash
+git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
+cd crossdesk
+xmake f -c -m release --target_minver=14.0 --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false -y
+xmake b -vy crossdesk
+xmake r crossdesk
+```
+
+The current CI sets macOS 14.0 as the minimum target for both Intel and Apple Silicon. Check the [workflow](../.github/workflows/build.yml) for its Xcode/SDK versions. Package with the script matching your architecture:
+
+```bash
+# Apple Silicon
+./apps/desktop/scripts/macos/pkg_arm64.sh 1.4.3
+# Intel
+./apps/desktop/scripts/macos/pkg_x64.sh 1.4.3
+```
+
+The scripts create an `.app` and `.pkg` containing the Slint runtime. Screen Recording and Accessibility grants depend on the app path and signature; use a consistent application bundle when testing host functionality.
+
+## Linux
+
+Linux builds support Ubuntu 20.04 or later on amd64 and arm64. Release packages
+use Ubuntu 20.04/glibc 2.31 as their compatibility baseline. The dependency
+commands below target Ubuntu 20.04; adapt package names and toolchains for
+other distributions or newer versions, or use the build image below to
+reproduce CI. Install the base build dependencies first:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+  git curl unzip build-essential gcc-10 g++-10 python3-pip \
+  pkg-config binutils dpkg-dev \
+  libx11-dev libxext-dev libxrender-dev libxft-dev libxrandr-dev \
+  libxinerama-dev libxcursor-dev libxi-dev libxfixes-dev libxv-dev \
+  libxtst-dev libxcb-randr0-dev libxcb-xtest0-dev libxcb-xinerama0-dev \
+  libxcb-shape0-dev libxcb-xkb-dev libxcb-xfixes0-dev libxcb-shm0-dev \
+  libasound2-dev libsndio-dev libpulse-dev \
+  libgl1-mesa-dev
+```
+
+Ubuntu 20.04's bundled CMake 3.16 is too old. Xmake downloads a CMake 3.x
+version within the range above; replacing the system CMake manually is not required.
+
+Ubuntu 20.04's default GCC 9 lacks parts of the C++20 standard library needed
+by Slint's C++ API, so the commands above install GCC 10 and the configuration
+below selects it explicitly.
+
+Clone the submodules and build a release binary:
+
+```bash
+git clone --recurse-submodules https://github.com/kunkundi/crossdesk.git
+cd crossdesk
+
+# Run this when the repository has already been cloned
+git submodule update --init --recursive
+
+xmake f -c -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=false --toolchain=gcc-10 -y
+xmake b -vy crossdesk
+```
+
+Use `--toolchain=gcc-10` so that both CrossDesk and third-party packages such
+as libyuv, which xmake builds during configuration, use GCC 10. Specifying only
+`--cc`/`--cxx` may still let dependency builds fall back to the system
+`/bin/cc` and `/bin/c++`. Keep `-c` when switching compilers to clear the old
+configuration.
+
+The amd64 binary is written to `build/linux/x86_64/release/crossdesk`; the arm64 binary is written to `build/linux/arm64/release/crossdesk`.
+
+For Wayland and DRM, install the D-Bus, DRM, and PipeWire development dependencies.
+Ubuntu 20.04 uses the repository's PipeWire header SDK; Ubuntu 22.04 and later
+can use the distribution's `libpipewire-0.3-dev` and `libspa-0.2-dev` packages instead:
+
+```bash
+sudo apt-get install -y libdbus-1-dev libdrm-dev
+# Skip this line if the system PipeWire 0.3 development packages are installed
+sudo ./docker/linux-build/install-pipewire-sdk.sh
+
+xmake f -c -m release --USE_WAYLAND=true --USE_DRM=true --USE_CUDA=false \
+  --CROSSDESK_VERSION=1.4.3 --toolchain=gcc-10 -y
+xmake b -vy crossdesk
+```
+
+Build a Debian package after compiling a release binary on the matching architecture:
+
+```bash
+# amd64
+./apps/desktop/scripts/linux/pkg_amd64.sh 1.4.3
+
+# arm64
+./apps/desktop/scripts/linux/pkg_arm64.sh 1.4.3
+```
+
+The package scripts install the shared Slint runtime in the private `/usr/lib/crossdesk` directory, so users do not need to install `libslint_cpp.so` separately.
+PipeWire is not a mandatory runtime dependency. CrossDesk detects the host's
+PipeWire 0.3 runtime dynamically and can still use X11 capture (and DRM when
+enabled at build time) when it is unavailable.
+
+## Common build options
+
+```text
+--USE_CUDA=true/false: Enable CUDA hardware codec acceleration, disabled by default
+--USE_WAYLAND=true/false: Enable Wayland/PipeWire capture on Linux, disabled by default
+--USE_DRM=true/false: Enable DRM capture on Linux, disabled by default
+--CROSSDESK_PORTABLE=true/false: Build the portable variant, disabled by default
+--CROSSDESK_VERSION=xxx: Set the CrossDesk version
+
+# Example
+xmake f --CROSSDESK_VERSION=1.4.3 --USE_CUDA=true
+```
+
+Run:
+
+```bash
+xmake r crossdesk
+```
+
+## Development Without CUDA Environment
+
+For **Linux developers who do not have a CUDA environment installed and want to enable hardware codec feature**, a preconfigured [Ubuntu 20.04 compatibility build image](https://hub.docker.com/r/crossdesk/ubuntu20.04) is provided.
+This image contains the required build dependencies and produces a single Linux package compatible with the glibc 2.31 baseline.
+
+See the [build image notes](../docker/linux-build/README.md) for image tags and architecture differences. The CUDA example below targets the amd64 image. Inside the container, download the project and run:
+
+```bash
+export CUDA_PATH=/usr/local/cuda
+export XMAKE_GLOBALDIR=/data
+
+xmake f --root -c -m release --CROSSDESK_VERSION=1.4.3 --USE_CUDA=true --toolchain=gcc-10 -y
+xmake b --root -vy crossdesk
+```
+
+For **Windows developers without a CUDA environment** installed, run the following command to install the CUDA build environment:
+
+```powershell
+xmake require -vy "cuda 12.6.3"
+```
+
+After the installation is complete, execute:
+
+```powershell
+xmake require --info "cuda 12.6.3"
+```
+
+Find the `installdir` field in the output.
+
+From the output above, locate the CUDA installation directory — this is the path pointed to by installdir.
+Add this path to your system environment variable CUDA_PATH, or set it in the terminal using:
+
+```powershell
+$env:CUDA_PATH = "C:\path\to\cuda_installdir"
+```
+
+Then re-run:
+
+```powershell
+xmake f --USE_CUDA=true
+xmake b -vy crossdesk
+```
+
+### Connection issues at runtime
+
+A disconnected status can result from network, server configuration, or certificate trust problems. See the [FAQ](FAQ.md#english) and [self-hosted TLS guide](SELF_HOSTING_EN.md) before changing the installation.
+
+## About Xmake
+
+### Installing Xmake
+
+You can install Xmake using one of the following methods:
+
+Using curl:
+
+```bash
+curl -fsSL https://xmake.io/shget.text | bash
+```
+
+Using wget:
+
+```bash
+wget https://xmake.io/shget.text -O - | bash
+```
+
+Using powershell:
+
+```powershell
+irm https://xmake.io/psget.text | iex
+```
+
+### Build Options
+
+```text
+# Select Debug; replace debug with release for a Release build
+xmake f -m debug
+
+# Optional build parameters
+-r : Rebuild the target
+-v : Show detailed build logs
+-y : Automatically confirm prompts
+
+# Example
+xmake b -vy crossdesk
+```
+
+### Run Options
+
+```bash
+# Launch the current build in a debugger; this does not select Debug build mode
+xmake r -d crossdesk
+```
+
+For more information, please refer to the [official Xmake documentation](https://xmake.io/guide/quick-start.html).
+
+## iOS / iPadOS
+
+The native client has a separate Xcode project and requires an arm64 physical device running iOS 16+. See the [iOS development guide](../apps/ios/README.md) for build and media/file-transfer checks. CI exports an unsigned app; device installation requires your own signing.
+
+## Refreshing screenshots
+
+Desktop README images are rendered directly from the current Slint UI. See the [screenshot notes](images/README.md) for reproduction commands.
@@ -1,33 +1,73 @@
-# 常见问题（FAQ）
+# 常见问题 / FAQ

-欢迎来到 **CrossDesk 常见问题** 页面！  
-这里整理了用户和开发者最常见的一些疑问。如果你没有找到答案，欢迎在 [Issues](https://github.com/kunkundi/crossdesk/issues) 中反馈。
+[返回 README](../README.md) · [English](#english)
+
+## 未连接服务器，或提示 TLS 证书错误
+
+先确认网络可用、两端使用预期的服务器配置。自托管环境检查信令端口、证书有效期、主机名匹配和系统信任；详见 [自托管指南](SELF_HOSTING.md)。这一步解决后，再排查远程设备和 P2P 连接。
+
+## 已连接服务器，但远程设备离线
+
+确认被控端 CrossDesk 仍在运行，双方连接同一个信令服务，并重新复制被控端当前的本机 ID。切换服务器后，原来的 ID 和连接记录可能不再适用。
+
+## 对等连接失败
+
+在 **☰ → 设置** 中勾选 **启用中继服务**，点击“确认”后重新连接。自托管用户还需检查 Coturn 是否正常运行，以及中继端口 TCP/UDP、媒体端口范围 UDP 是否放通。
+
+公共服务的兼容性变更也会影响旧客户端；请核对 [Release 说明](https://github.com/kunkundi/crossdesk/releases)，尽量让两端使用兼容的近期版本。
+
+## macOS 有连接但黑屏，或无法操作键鼠
+
+在“系统设置 → 隐私与安全性”中检查 CrossDesk 的屏幕录制与辅助功能权限。更换应用位置或签名、更新开发构建后，可能需要重新授权并重启应用。
+
+## Linux Wayland 无法捕获画面
+
+Wayland 画面捕获依赖启用了 Wayland 支持的构建、宿主系统 PipeWire 0.3 和桌面门户授权；无法捕获时也可在 X11 会话中对比验证。构建选项见 [Linux 构建说明](BUILD.md#linux)。
+
+## Windows 锁屏后无法操作
+
+在被控电脑检查 CrossDesk Service 是否安装、是否运行，并保持 CrossDesk 客户端运行。便携版可在“设置 → 锁屏控制服务”安装。服务状态检查命令见 [Windows 服务说明](../README.md#windows-service)。
+
+## 修改密码后连接失败
+
+修改密码时使用 6 位数字或英文字母，并保持连接服务器。等待修改成功、客户端重新连接后，重新复制当前密码。控制端保存的旧密码会失效，按弹窗输入新密码再连接。
+
+## 收到的文件在哪里
+
+桌面端见 **☰ → 设置 → 文件保存路径**。iOS 原生端收到的文件保存在应用的 `Documents/Received`，可以从分享入口导出；更多说明见 [iOS 开发文档](../apps/ios/README.md)。
+
+## 关闭主窗口后为什么还能连接
+
+关闭主窗口会隐藏窗口，客户端仍在后台运行。需要结束程序时，从系统托盘或 macOS 菜单栏中选择退出。
+
+## Windows 没有安装 CUDA，如何编译
+
+可以先使用 `--USE_CUDA=false` 构建。需要 CUDA 编解码支持时，按 [构建指南](BUILD.md) 安装对应依赖；PowerShell 中设置环境变量应使用 `$env:CUDA_PATH = "实际安装目录"`。
+
+## iOS 构建产物为什么不能直接安装
+
+当前 CI 导出的是未签名应用。需要使用自己的开发签名 / 分发方式安装；也可用 Xcode 打开工程并选择真机运行。见 [iOS 构建要求](../apps/ios/README.md)。

 ---

-### Q1. 对等连接失败
-**A:**  
-打开设置，勾选 **启用中继服务** 选项，尝试重新发起连接。
+<a id="english"></a>

-<img width="396" height="306" alt="Image" src="https://github.com/user-attachments/assets/fd8db148-c782-4f4d-b874-8f1b2a7ec7d6" />
+## English

-由于公共中继服务器带宽较小，连接的清晰度流畅度可能会下降，建议自建服务器。 [Issue #8](https://github.com/kunkundi/crossdesk/issues/8)
+[Back to README](../README_EN.md)

-### Q2. Windows 无 CUDA 环境下编译
-**A:**  
-运行下面的命令安装 CUDA 编译环境。
-```
-xmake require -vy "cuda 12.6.3"
-```
-安装完成后执行
-```
-xmake require --info "cuda 12.6.3"
-```
-输出如下
+| Symptom | What to check |
+| --- | --- |
+| Server disconnected / TLS error | Network access, signaling endpoint, certificate dates, hostname, and system trust. See [self-hosting](SELF_HOSTING_EN.md). |
+| Remote device offline | Keep the host running, connect both sides to the same signaling server, and copy its current ID again. |
+| P2P connection failed | Enable TURN relay in Settings and reconnect. For self-hosting, check Coturn and relay/media firewall ports. Review [release compatibility notes](https://github.com/kunkundi/crossdesk/releases). |
+| Black screen / no input on macOS | Grant Screen Recording and Accessibility, then reopen the app. A changed app path or signature may require fresh permission grants. |
+| No capture on Linux Wayland | Check the Wayland build option, host PipeWire 0.3, and desktop portal permission. Compare with an X11 session. See [Linux build instructions](BUILD_EN.md#linux). |
+| Cannot control a Windows lock screen | Install/start CrossDesk Service and keep the host client running. See [service commands](../README_EN.md#windows-service). |
+| Saved password no longer works | Use 6 ASCII letters or digits when changing the password, with the host connected to the server. Wait for the change and reconnection to complete, then copy the current password and enter it on the controller. |
+| Cannot find received files | Check Settings → File Save Path on desktop. Native iOS stores them in `Documents/Received` and provides a share action. |
+| Main window closed but app still running | Closing hides the window. Use the tray/menu-bar exit command to quit. |
+| Windows build without CUDA | Build with `--USE_CUDA=false`, or follow the [CUDA build instructions](BUILD_EN.md). Use `$env:CUDA_PATH` in PowerShell. |
+| iOS artifact cannot be installed directly | CI exports an unsigned app. Sign it yourself or build and run from Xcode on a physical device. See [iOS requirements](../apps/ios/README.md). |

-<img width="860" height="226" alt="Image" src="https://github.com/user-attachments/assets/999ac365-581a-4b9a-806e-05eb3e4cf44d" />
-
-根据上述输出获取到 CUDA 的安装目录，即 installdir 指向的位置。将 CUDA_PATH 加入系统环境变量，或在终端中输入 set CUDA_PATH=path_to_cuda_installdir，重新执行 xmake b -vy crossdesk 即可。
-[Issue #6](https://github.com/kunkundi/crossdesk/issues/6)
-
---
+If the issue persists, [open an issue](https://github.com/kunkundi/crossdesk/issues) with both OS versions, client versions, connection mode, and reproduction steps. Remove passwords and private device information from logs or screenshots before sharing them.
@@ -0,0 +1,99 @@
+# 自托管服务器
+
+[返回 README](../README.md) · [English](SELF_HOSTING_EN.md)
+
+CrossDesk 的信令服务与 TURN 中继由独立的 [CrossDesk Server](https://github.com/kunkundi/crossdesk-server) 项目维护。本页说明部署入口与当前客户端的配置方法；服务端文件请使用同一 Release 中的配套版本。
+
+## 1. 部署服务端
+
+以下步骤面向已安装 Docker Engine 和 Compose 插件的 Linux 服务器；先确认 `docker compose version` 可用。当前 Compose 使用主机网络，分别运行信令服务和 Coturn。
+
+按 [服务端部署文档](https://github.com/kunkundi/crossdesk-server#运行服务)，从其 [Releases](https://github.com/kunkundi/crossdesk-server/releases) 下载 `compose.yaml` 和 `env.example`，放到同一目录。在该目录执行：
+
+```bash
+cp env.example .env
+```
+
+用文本编辑器修改 `.env`，至少核对以下内容，填写完成后再启动。完整参数以配套的环境文件为准，也可参考服务端仓库的 [环境变量示例](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/.env.example)。
+
+| 配置 | 填写内容 |
+| --- | --- |
+| `CROSSDESK_IMAGE` | 与下载的配置匹配的固定发布 tag |
+| `EXTERNAL_IP` / `INTERNAL_IP` | 服务器真实公网 / 内网 IP；不要直接使用示例地址 |
+| `CROSSDESK_SERVER_PORT` | 信令端口，例如 `9099` |
+| `COTURN_PORT` | 中继端口，例如 `3478` |
+| `MIN_PORT` / `MAX_PORT` | TURN 媒体端口范围 |
+| `COTURN_AUTH_SECRET` | 信令服务与 Coturn 的共享密钥；不填入客户端 |
+| `COTURN_STATELESS_NONCE_SECRET` | 独立生成、持久保存的 nonce 密钥 |
+| `CROSSDESK_DATA_DIR` / `CROSSDESK_LOG_DIR` | 数据、证书和日志的持久化位置 |
+
+两个密钥分别用 `openssl rand -hex 32` 生成。防火墙及云安全组需允许信令端口 TCP、中继端口 TCP/UDP，以及所选媒体端口范围 UDP。容器挂载和网络配置见 [官方 Compose 文件](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/compose.yaml)。
+
+保存配置后，校验并启动：
+
+```bash
+sudo docker compose config -q
+sudo docker compose pull
+sudo docker compose up -d
+sudo docker compose ps
+```
+
+## 2. 配置桌面客户端
+
+使用自签证书时，先按 [证书信任步骤](#3-配置信任证书) 在两端导入根证书，再检查连接状态。
+
+1. 断开现有会话，点击主窗口右上角 **☰ → 设置**。
+2. 在设置列表中向下滚动，点击 **自托管配置**。
+3. 填写 **服务器地址**、**信令服务端口**、**中继服务端口**，点击“确认”。地址只填主机名或 IP，不加 `https://`、路径或端口。
+4. 回到设置窗口，勾选 **自托管配置** 右侧复选框，再点击“确认”保存。
+5. 在控制端和被控端执行相同配置。等待两端都显示“已连接服务器”，再使用被控端当前显示的 ID 发起连接。
+
+<p align="center">
+  <img src="images/desktop-self-hosted-zh.png" width="720" alt="当前 Slint 客户端自托管设置：服务器地址、信令端口、中继端口" />
+</p>
+
+切换服务器后请重新核对本机 ID；设备身份与服务端相关，旧服务上的 ID 不应直接套用。
+
+## 3. 配置信任证书
+
+客户端通过 TLS 连接信令服务。证书必须覆盖填写的域名 / IP，且被客户端系统信任。使用受信任 CA 签发的证书时按服务端说明配置证书链；使用自签证书时，需要信任自己部署的根证书。
+
+默认的 [证书生成脚本](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/docker/generate_certs.sh) 只将 `EXTERNAL_IP` 写入证书的地址范围；使用这份证书时，客户端应填写该 IP。改用域名需要配置包含该域名的证书。已有证书存在时，[启动脚本](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/docker/start.sh) 会复用它们，修改 `.env` 中的 IP 不会自动更新证书。
+
+默认证书文件位于服务端数据目录下的 `certs/`。将自己服务器的 `api.crossdesk.cn_root.crt` 下载到客户端机器，再执行对应平台命令；不要导入来源不明的根证书。
+
+**Windows（管理员 PowerShell）：**
+
+```powershell
+certutil -addstore "Root" "C:\path\to\api.crossdesk.cn_root.crt"
+```
+
+**Ubuntu / Debian：**
+
+```bash
+sudo cp /path/to/api.crossdesk.cn_root.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates
+```
+
+**macOS：**
+
+```bash
+sudo security add-trusted-cert -d -r trustRoot \
+  -k /Library/Keychains/System.keychain /path/to/api.crossdesk.cn_root.crt
+```
+
+完成后重新打开客户端。自签证书并不等于没有加密，但根证书信任和主机名校验必须正确配置。
+
+## 4. Web 与 iOS
+
+- **Web：** 按 [Web 客户端项目](https://github.com/kunkundi/crossdesk-web-client) 配置自己的信令连接。浏览器必须信任该服务的证书；不要通过关闭 TLS 校验解决证书错误。
+- **iOS：** 在“设置 → 服务器”填写信令服务器、信令端口与 STUN/TURN 端口，然后点击“应用”。自签证书需要在设备上安装对应根证书并启用信任。
+
+## 排查顺序
+
+- **未连接服务器 / TLS 错误：** 先检查地址、信令端口、证书有效期、证书主机名及根证书信任。
+- **已连服务器但设备离线：** 确认两端连接同一服务、被控端仍在运行，并重新复制当前 ID。
+- **P2P 连接失败：** 检查“启用中继服务”、Coturn 状态、TURN 端口和媒体端口范围，并核对客户端与服务端版本兼容性。
+- **配置修改未生效：** 在配置目录重新执行 `sudo docker compose up -d`；单纯重启容器不会应用修改过的环境变量。
+
+日志、备份和迁移操作请参考 [服务端维护说明](https://github.com/kunkundi/crossdesk-server)。
@@ -0,0 +1,99 @@
+# Self-hosting
+
+[Back to README](../README_EN.md) · [中文](SELF_HOSTING.md)
+
+Signaling and TURN deployment are maintained in [CrossDesk Server](https://github.com/kunkundi/crossdesk-server). Use matching server configuration files from the same release. This guide focuses on deployment entry points and the current client UI.
+
+## 1. Deploy the server
+
+These steps target a Linux server with Docker Engine and the Compose plugin installed. Confirm that `docker compose version` works. The current Compose deployment uses host networking and runs signaling and Coturn separately.
+
+Follow the [server deployment guide](https://github.com/kunkundi/crossdesk-server#运行服务). Download `compose.yaml` and `env.example` from its [Releases](https://github.com/kunkundi/crossdesk-server/releases) into one directory and run there:
+
+```bash
+cp env.example .env
+```
+
+Edit `.env` in a text editor and complete these values before starting the services. The repository also provides an [environment example](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/.env.example).
+
+| Variable | Value |
+| --- | --- |
+| `CROSSDESK_IMAGE` | A fixed release tag matching the configuration |
+| `EXTERNAL_IP` / `INTERNAL_IP` | Your actual public / private server IPs |
+| `CROSSDESK_SERVER_PORT` | Signaling port, e.g. `9099` |
+| `COTURN_PORT` | Relay port, e.g. `3478` |
+| `MIN_PORT` / `MAX_PORT` | TURN media port range |
+| `COTURN_AUTH_SECRET` | Secret shared by signaling and Coturn; never enter it in clients |
+| `COTURN_STATELESS_NONCE_SECRET` | A separately generated, persistent nonce secret |
+| `CROSSDESK_DATA_DIR` / `CROSSDESK_LOG_DIR` | Persistent data, certificate, and log locations |
+
+Generate each secret separately with `openssl rand -hex 32`. Allow signaling TCP, relay TCP/UDP, and the selected media UDP range through the firewall and cloud security group. Mounts and networking are defined in the [official Compose file](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/compose.yaml).
+
+After saving the configuration, validate it and start the services:
+
+```bash
+sudo docker compose config -q
+sudo docker compose pull
+sudo docker compose up -d
+sudo docker compose ps
+```
+
+## 2. Configure desktop clients
+
+For a self-signed deployment, complete the [certificate trust steps](#3-trust-the-tls-certificate) on both clients before checking their connection status.
+
+1. Disconnect existing sessions and open **☰ → Settings**.
+2. Scroll down and click **Self-Hosted Config**.
+3. Enter **Server Address**, **Signal Service Port**, and **Relay Service Port**, then confirm. Enter only the hostname or IP in the address field, without a URL scheme, path, or port.
+4. Enable the checkbox beside **Self-Hosted Config**, then click **OK** in the parent settings window.
+5. Configure both the controller and host this way. Once both report a server connection, connect using the host's currently displayed ID.
+
+<p align="center">
+  <img src="images/desktop-self-hosted-en.png" width="720" alt="Current Slint self-hosting dialog for server address, signaling port, and relay port" />
+</p>
+
+Recheck the device ID after changing servers. Device identities belong to their server; do not assume an old ID carries over.
+
+## 3. Trust the TLS certificate
+
+The signaling certificate must cover the configured hostname/IP and be trusted by the client OS. For a public CA certificate, configure the server's certificate chain as instructed by the server project. For a self-signed deployment, trust the root certificate belonging to your own server.
+
+The default [certificate generator](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/docker/generate_certs.sh) includes only `EXTERNAL_IP` in the certificate's subject alternative name. Use that IP in the client, or supply a certificate covering your custom domain. The [startup script](https://github.com/kunkundi/crossdesk-server/blob/admin-dashboard/docker/start.sh) reuses existing certificates; editing the IP in `.env` does not update them automatically.
+
+Default certificates are stored in the data directory's `certs/` folder. Copy your server's `api.crossdesk.cn_root.crt` to the client and run the relevant command. Do not trust a root certificate from an unknown source.
+
+**Windows — administrator PowerShell:**
+
+```powershell
+certutil -addstore "Root" "C:\path\to\api.crossdesk.cn_root.crt"
+```
+
+**Ubuntu / Debian:**
+
+```bash
+sudo cp /path/to/api.crossdesk.cn_root.crt /usr/local/share/ca-certificates/
+sudo update-ca-certificates
+```
+
+**macOS:**
+
+```bash
+sudo security add-trusted-cert -d -r trustRoot \
+  -k /Library/Keychains/System.keychain /path/to/api.crossdesk.cn_root.crt
+```
+
+Reopen the client afterwards. Self-signed certificates still support encryption; correct root trust and hostname verification are required.
+
+## 4. Web and iOS
+
+- **Web:** configure your signaling endpoint following the [Web Client project](https://github.com/kunkundi/crossdesk-web-client). The browser must trust its certificate; do not disable TLS verification to work around certificate errors.
+- **iOS:** enter the signaling host, signaling port, and STUN/TURN port under **Settings → Server**, then apply. A self-signed deployment requires installing and trusting its root certificate on the device.
+
+## Troubleshooting order
+
+- **Server disconnected / TLS error:** check the host, signaling port, certificate dates, certificate hostname, and root trust.
+- **Server connected, device offline:** confirm both clients use the same server, keep the host running, and copy its current ID again.
+- **P2P failed:** check the relay setting, Coturn status, relay/media ports, and compatibility between client and server versions.
+- **Environment changes ignored:** run `sudo docker compose up -d` from the configuration directory. Restarting existing containers alone does not apply changed environment variables.
+
+See the [server maintenance documentation](https://github.com/kunkundi/crossdesk-server) for logs, backups, and migration.
@@ -0,0 +1,56 @@
+# README 截图 / Screenshot notes
+
+[中文 README](../../README.md) · [English README](../../README_EN.md)
+
+## 来源 / Sources
+
+- 生成日期：2026-09-07。
+- 桌面 UI 源代码：`abc8f907`（`ios-support` 分支），Slint 1.17.1，macOS arm64；截图工具增加了可选的文档演示数据。
+- 桌面图片来自 [`slint_ui_smoke_test`](../../apps/desktop/tests/slint_ui_smoke_test.cpp) 的 UI 捕获模式，直接渲染仓库中的 Slint 组件；不是旧版本截图或重新绘制的界面。
+- 主窗口展示“已连接服务器”和三台在线设备的完整示例状态。ID `123 456 789`、密码 `123456`、连接状态及设备记录均为演示数据，不是真实设备凭据或真实远程会话。示例设置不代表应用运行时默认值。
+- 设备缩略图使用可公开的页面截图：`fixtures/source.png` 来自 [CrossDesk 的 Xmake 源码页](https://github.com/kunkundi/crossdesk/blob/ios-support/xmake.lua)，`fixtures/website.png` 来自 [CrossDesk 官网](https://www.crossdesk.cn/)，第三张复用 `web-client.png`。它们用于展示缩略图效果，不代表这些页面正在对应的远程电脑上运行。
+- `web-client.png`：2026-09-07 在 [web.crossdesk.cn](https://web.crossdesk.cn/) 截取的连接首页，视口为 1280 × 720，没有发起远程连接。
+
+Desktop images render the actual Slint components with an illustrative connected state and three populated recent-device cards. The thumbnails are public browser-page captures, not private remote desktops or evidence of live sessions. IDs, device names, statuses, and settings are demonstration data. The Web image captures the public connection page. Native iOS screenshots are not included because this update did not capture a signed app running on a physical device.
+
+## 文件 / Files
+
+| 文件 | 页面 | 语言 |
+| --- | --- | --- |
+| `desktop-main-zh.png` / `desktop-main-en.png` | Main window / 主窗口 | 中文 / English |
+| `desktop-settings-zh.png` / `desktop-settings-en.png` | Settings / 设置 | 中文 / English |
+| `desktop-self-hosted-zh.png` / `desktop-self-hosted-en.png` | Self-hosting / 自托管设置 | 中文 / English |
+| `web-client.png` | Web connection page / Web 连接首页 | 中文 |
+
+桌面图片为 1280 × 900 PNG，使用 2× 缩放保持文字清晰。Markdown 只设置展示宽度，保持原始比例。设置列表可滚动，截图仅展示首屏。演示配置显示硬件编解码器可用；实际可用性由平台、设备与构建决定。
+
+## 重新生成 / Regenerate
+
+以下命令在仓库根目录、已完成依赖配置的 macOS 开发环境运行。`sips` 仅将 Slint 导出的 PPM 无损转换为 PNG，不修改 UI。其他平台可以使用支持 PPM 的图片格式转换工具。
+
+```bash
+set -e
+xmake b -y slint_ui_smoke_test
+mkdir -p build/readme-capture docs/images
+
+for locale in zh en; do
+  language=0
+  if [ "$locale" = en ]; then language=1; fi
+  for page in main settings self-hosted; do
+    snapshot="$PWD/build/readme-capture/desktop-$page-$locale.ppm"
+    SLINT_BACKEND=winit-software SLINT_SCALE_FACTOR=2 \
+      CROSSDESK_UI_CAPTURE=1 \
+      CROSSDESK_UI_CAPTURE_DEMO_ASSETS="$PWD/docs/images" \
+      CROSSDESK_UI_CAPTURE_PAGE="$page" \
+      CROSSDESK_UI_CAPTURE_LANGUAGE="$language" \
+      CROSSDESK_UI_CAPTURE_SNAPSHOT="$snapshot" \
+      xmake r slint_ui_smoke_test
+    sips -s format png "$snapshot" \
+      --out "docs/images/desktop-$page-$locale.png"
+  done
+done
+```
+
+`CROSSDESK_UI_CAPTURE_DEMO_ASSETS` 必须指向包含上述图片的目录。缺失图片会让捕获命令失败，避免再次导出空白缩略图；不设置该变量时，仍保留原有测试状态。
+
+捕获模式兼容 `/tmp/crossdesk-ui-capture-page` 和 `/tmp/crossdesk-ui-capture-language` 两个旧覆盖文件；如存在，它们会优先于环境变量，运行前请检查。更新后逐张检查文字、布局、敏感信息和文档引用，并同步修改本页日期与源码版本。