# RDP远程桌面

***Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.***

---

**RDP**（Remote Desktop Protocol，远程桌面协议）是一种图形化远程桌面连接方式。Windows 主机可使用系统自带的"远程桌面连接"工具访问 Quectel Pi M2 Debian 桌面，并在远端查看或控制图形界面。

Quectel Pi M2 主要使用 **GNOME** 桌面环境，可通过 **GNOME Remote Desktop** 提供 RDP 远程桌面功能，无需额外安装 VNC、Xvfb 或 x11vnc 等软件。

> 💡 注：M2 使用 GNOME 用户桌面共享方式连接 RDP 时，需保持图形桌面会话处于登录状态。

# 准备工作

1. **确认设备环境：**  
    - Quectel Pi M2 已启动 Debian 系统；  
    - Windows 主机和开发板处于同一网段或同一局域网内的可达网络；  
    - Windows 主机已安装或启用"远程桌面连接"工具。

2. **建议通过串口进入开发板。** 串口连接的详细说明可参考 debug_uart.md。M2 默认登录用户请按照引导使用自己所创建的账号密码。若本地调试环境已可用，也可以通过 ADB 进入系统。

3. **获取设备 IP 地址。** 在开发板端执行：

```bash
hostname -I
```

记录当前网络下的 IP 地址，后续 Windows 远程桌面连接时需要使用该地址。

> 💡 注：Windows 主机与开发板需要处于同一网段或同一局域网内，且两端网络可互通，否则即使板端已启动 RDP 服务，也无法正常连接。

# GNOME 远程桌面

## 软件安装

Quectel Pi M2 Debian 系统已集成 `gnome-remote-desktop`，可直接使用 GNOME Remote Desktop 提供 RDP 远程桌面功能。可在终端中执行以下命令确认软件包是否已安装：

```bash
dpkg -l | grep gnome-remote-desktop
```

若系统中未安装该软件包，可执行以下命令安装：

```bash
sudo apt update
sudo apt install -y gnome-remote-desktop
```

也可执行以下命令确认远程桌面管理工具是否存在：

```bash
which grdctl
```

若命令返回 `/usr/bin/grdctl`，说明系统已包含 GNOME 远程桌面管理工具。

## 软件配置

1. **图形界面配置** 通过 Quectel Pi M2 图形界面依次进入：设置 > 系统 > 远程桌面。在远程桌面设置界面中，可根据实际使用需求打开以下开关：  
    - **桌面共享**：允许其他设备通过 RDP 协议查看当前桌面。  
    - **远程控制**：允许远程连接端控制鼠标和键盘。  
  ```{image} images/image_HYYlbXeffok2WmxsVeNczraqn8c.webp
  :width: 1280px
  :height: 800px
  ```

2. **命令行配置** 如需通过命令行配置 RDP，可在已登录图形桌面的用户环境中执行以下命令。以下示例将 RDP 用户名和密码设置为 `q`，实际使用时请根据需要修改：  
  ```bash
  mkdir -p ~/.local/share/gnome-remote-desktop
  openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout ~/.local/share/gnome-remote-desktop/rdp-tls.key \
  -out ~/.local/share/gnome-remote-desktop/rdp-tls.crt \
  -days 3650 -subj /CN=Quectel-Pi-M2
  chmod 600 ~/.local/share/gnome-remote-desktop/rdp-tls.key

  grdctl rdp set-tls-cert ~/.local/share/gnome-remote-desktop/rdp-tls.crt
  grdctl rdp set-tls-key ~/.local/share/gnome-remote-desktop/rdp-tls.key
  grdctl rdp set-credentials q q
  grdctl rdp disable-view-only
  grdctl rdp enable
  systemctl --user restart gnome-remote-desktop.service
  ```

## 软件启动

在图形界面中打开 **桌面共享** 后，GNOME 远程桌面服务会自动启用。

也可以在终端中使用以下命令查看当前状态：

```bash
grdctl status --show-credentials
```

正常情况下，可看到 RDP 相关状态、端口、用户名以及远程控制模式等信息。

也可以查看用户服务和端口监听状态：

```bash
systemctl --user status gnome-remote-desktop.service --no-pager -l
ss -tulnp | grep -E ':3389|:3390'
```

> 💡 注：若系统级 GNOME Remote Desktop 已占用 `3389` 端口，当前登录用户的桌面共享服务可能会协商到其它端口，例如 `3390`。请以 `grdctl status --show-credentials` 和 `ss -tulnp` 的实际输出为准。

若需要通过命令行开启 RDP 后端，可执行：

```bash
grdctl rdp enable
```

若需要允许远程端控制鼠标和键盘，可执行：

```bash
grdctl rdp disable-view-only
```

若只允许远程端查看桌面，不允许控制鼠标和键盘，可执行：

```bash
grdctl rdp enable-view-only
```

> 💡 注：实际使用中建议优先通过图形界面完成配置，避免命令行配置与界面显示状态不一致。

# 远程桌面连接

1. 在 Windows 主机中打开"远程桌面连接"。

2. 在"计算机"输入框中填写开发板的 IP 地址，例如 `<开发板IP>`。如需手动指定端口，可填写 `<开发板IP>:3389`。若 `grdctl status --show-credentials` 或 `ss -tulnp` 显示 RDP 实际监听端口为其它端口，例如 `3390`，则填写 `<开发板IP>:3390`。  
  ```{image} images/image_IxXJbX3IBoW03Bxz6DLcpyzYnNf.webp
  :width: 475px
  :height: 286px
  ```

3. 点击"连接"，并根据提示输入远程桌面设置界面中显示的用户名和密码。若 Windows 安全中心提示输入凭据，可点击 **更多选项**，选择 **使用其他帐户**，然后输入远程桌面设置界面中配置的用户名和密码。  
  ```{image} images/image_ADpubOcglovxjaxCY9eciUjLnIf.webp
  :width: 456px
  :height: 580px
  ```

4. 连接成功后，即可在 Windows 主机中查看并操作 Debian 桌面。  
  ```{image} images/image_Lw8SbtDR4o0W9fxU7LgcKKSgnbf.webp
  :width: 1280px
  :height: 823px
  ```

# 疑难解答

| **问题现象** | **可能原因** | **处理方法** |
| --- | --- | --- |
| Windows 远程桌面无法连接 | Windows 主机和设备不在同一局域网 | 确认两端网络连接，重新获取设备的 IP 地址 |
| Windows 远程桌面无法连接 | IP 地址或端口填写错误 | 在设备上执行 `hostname -I` 确认 IP，并执行 `grdctl status --show-credentials`、`ss -tulnp \| grep -E ':3389\|:3390'` 确认实际监听端口 |
| Windows 远程桌面无法连接 | **桌面共享** 未开启 | 进入 `设置 > 系统 > 远程桌面`，打开 **桌面共享** |
| Windows 远程桌面无法连接 | 未安装或未启动 GNOME Remote Desktop | 执行 `which grdctl`、`grdctl status --show-credentials`、`systemctl --user status gnome-remote-desktop.service --no-pager -l` 确认安装和服务状态 |
| 只能查看桌面，无法控制鼠标和键盘 | **远程控制** 未开启，或当前为只读模式 | 打开 **远程控制**，或执行 `grdctl rdp disable-view-only` |
| 登录提示用户名或密码错误 | 输入的凭据与远程桌面设置中显示的不一致 | 使用远程桌面设置界面中显示的用户名和密码，必要时重新生成或手动修改密码 |
| 连接后很快断开，并回到开发板登录界面 | 当前图形桌面用户会话已退出，GNOME Remote Desktop 用户服务随会话停止 | 在开发板本地重新登录图形桌面后，再确认 `grdctl status --show-credentials` 中 `Unit status` 为 `active`，并重新连接 |
| 连接后画面异常或无法刷新 | 图形桌面会话状态异常 | 确认设备已登录图形桌面，断开后重新连接 |
| 网络切换后无法连接 | 设备 IP 地址发生变化 | 重新执行 `hostname -I` 获取当前 IP 地址，并在 Windows 远程桌面中更新连接地址 |