远程访问

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

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

Quectel Pi M1 主要使用 GNOME 桌面环境，已集成 GNOME 远程桌面功能，无需额外安装 VNC、Xvfb 或 x11vnc 等软件；Quectel Pi L1 当前使用 Weston 图形环境，可通过 Weston 自带的 RDP backend 提供远程桌面服务。

备注

M1 使用 RDP 远程桌面连接时，需保持图形桌面会话处于登录状态。L1 的 RDP 建议使用 Weston rdp-backend.so。

准备工作

  1. 确认设备环境：

    • Quectel Pi M1 / L1 已启动 Debian 系统；

    • Windows 主机和开发板处于同一网段或同一局域网内的可达网络；

    • Windows 主机已安装或启用"远程桌面连接"工具。

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

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

hostname -I

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

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

若计划使用普通用户 q 启动 RDP 服务（L1），可先创建用户并设置密码：

adduser --disabled-password --gecos "" q
echo 'q:q' | chpasswd

若系统中已经存在可用普通用户，也可直接复用现有用户，无需重复创建。

M1：GNOME 远程桌面

软件安装

Quectel Pi M1 Debian 系统的 GNOME 桌面环境已集成远程桌面相关功能。通常无需额外安装 VNC、Xvfb 或 x11vnc 等软件。

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

which grdctl

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

软件配置

  1. 进入远程桌面设置界面。 通过 Quectel Pi M1 图形界面依次进入：设置 > 系统 > 远程桌面

  2. 打开远程桌面功能。 在远程桌面设置界面中，可根据实际使用需求打开以下开关：

    • 桌面共享：允许其他设备通过 RDP 协议查看当前桌面。

    • 远程控制：允许远程连接端控制鼠标和键盘。

../../../_images/image_GuDzbXkcmooDPdx7JxtcdGbGnme.webp

  1. 查看连接信息。 在远程桌面设置界面中，可查看以下信息：主机名（用于局域网内识别设备）、端口（默认 RDP 端口为 3389）、用户名、密码。若需要修改登录密码，可点击密码区域右侧的编辑按钮，并按照界面提示重新设置。

保持远程桌面登录密码

若仅在系统设置的远程桌面页面中修改登录密码，设备重启或重新登录后可能需要再次设置。若希望远程桌面登录密码保持可用，可通过 密码与密钥 工具修改 Login 钥匙环密码。

  1. 在应用列表中打开 实用工具，点击 密码和密钥。

../../../_images/image_P0hUbdoUTo7mnMxugwdclFpRnNh.webp

  1. 在 密码 分类中选择 Login，右键点击远程桌面凭据，选择 更改密码。

../../../_images/image_WNPfbb63NoKycUxnMoDcUvMinSg.webp

  1. 输入旧密码。旧密码为前面在远程桌面设置中配置的远程登录密码，例如本文测试环境中设置的 q。

../../../_images/image_LLHebvic4o80hJx2kTecHlUknQg.webp

  1. 设置新的 Login 钥匙环密码。若希望系统登录后自动读取远程桌面凭据，可将新密码留空并点击 Continue。

  2. 若新密码留空，系统会提示密码将以未加密方式保存，确认后点击 Continue。

../../../_images/image_XW5KbnPh5o2d6bxQfdHcAW1inbb.webp

备注

将 Login 钥匙环密码设置为空会降低凭据安全性，仅建议在开发调试环境中使用。若设备用于生产环境或多人共用环境，建议设置非空密码，并按需手动解锁钥匙环。

软件启动

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

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

grdctl status --show-credentials

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

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

grdctl rdp enable

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

grdctl rdp disable-view-only

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

grdctl rdp enable-view-only

备注

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

L1：Weston RDP Backend

软件安装

检查 Weston 是否支持 RDP backend：

env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --help | grep -i rdp
find /usr/lib* -name 'rdp-backend.so' 2>/dev/null

若能看到 rdp-backend.so，说明当前系统已包含 Weston RDP backend。

备注

Quectel Pi L1 当前镜像中的 weston 依赖 /opt/qcom/lib 下的运行库。若直接执行 weston 提示 libweston-10.so.0: cannot open shared object file，需在命令前补充 LD_LIBRARY_PATH=/opt/qcom/lib:/lib。

软件配置

配置RDP证书

Weston RDP backend 需要 TLS 证书和私钥。可根据启动用户选择证书保存位置。

若使用 root 启动 RDP 服务，可生成证书到 /etc/weston：

mkdir -p /etc/weston
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /etc/weston/rdp.key \
  -out /etc/weston/rdp.crt \
  -days 365 \
  -subj "/CN=quectel-pi-l1"
chmod 600 /etc/weston/rdp.key
chmod 644 /etc/weston/rdp.crt

若使用普通用户 q 启动 RDP 服务，可生成证书到 /home/q：

mkdir -p /home/q
openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout /home/q/weston-rdp.key \
  -out /home/q/weston-rdp.crt \
  -days 365 \
  -subj "/CN=quectel-pi-l1"
chown q:q /home/q/weston-rdp.key /home/q/weston-rdp.crt
chmod 600 /home/q/weston-rdp.key
chmod 644 /home/q/weston-rdp.crt

若系统中已经存在可用证书，也可直接复用现有证书路径。

软件启动

推荐方式：共享当前物理屏幕

若希望 RDP 连接后看到的是本地 MIPI/HDMI 屏幕上的同一个 Weston 画面，应启用 Weston 的 screen-share.so 模块。该方式会由本地 Weston 自动拉起 RDP 共享进程，适合远程查看和操作当前物理屏幕。

可执行以下命令修改 /etc/xdg/weston/weston.ini：

python3 - <<'PY'
from pathlib import Path

p = Path("/etc/xdg/weston/weston.ini")
s = p.read_text()

s = s.replace("#modules=screen-share.so", "modules=screen-share.so")
s = s.replace("--rdp-tls-cert=/data/misc/display/tls.crt", "--rdp-tls-cert=/etc/weston/rdp.crt")
s = s.replace("--rdp-tls-key=/data/misc/display/tls.key", "--rdp-tls-key=/etc/weston/rdp.key")
s = s.replace("start-on-startup=false", "start-on-startup=true")

p.write_text(s)
PY

修改后重启系统：

reboot

系统重启后检查 Weston 和 RDP 共享进程：

ps -ef | grep weston
netstat -ltnp | grep 3389
cat /tmp/weston-rdp-share.log

若能看到类似以下进程，表示本地 Weston 已自动启动 RDP 共享：

weston --idle-time=0 --log=/tmp/weston.log --config=/etc/xdg/weston/weston.ini --tty=1
weston --backend=rdp-backend.so --no-config --shell=fullscreen-shell.so --no-clients-resize --address=0.0.0.0 --rdp-tls-cert=/etc/weston/rdp.crt --rdp-tls-key=/etc/weston/rdp.key --log=/tmp/weston-rdp-share.log

此时 Windows 主机可直接使用远程桌面连接开发板的 IP 地址。该方式共享的是当前物理屏幕画面，不需要再手动执行 weston --backend=rdp-backend.so。

备注

screen-share 方式依赖本地 Weston 配置中的 [screen-share] 段。若系统中证书路径不同，请将命令中的 /etc/weston/rdp.crt 和 /etc/weston/rdp.key 替换为实际路径。

临时启动RDP服务

Weston RDP backend 也可使用 root 或普通用户 q 临时启动一个独立的 RDP 桌面：

  • root 启动：适合 L1 初始环境、串口 root 登录后的快速验证。

  • q 启动：适合已创建普通用户后的日常使用。

该方式会创建一个新的 Weston RDP 桌面，不会镜像本地 MIPI/HDMI 物理屏幕。若需要远程共享当前物理屏幕，请优先使用上一节的 screen-share 方式。

同一时间只启动一个 Weston RDP 实例即可，不要同时执行多个启动命令，否则会抢占 3389 端口。

使用root启动

前台启动：

env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --backend=rdp-backend.so \
  --socket=wayland-rdp-root \
  --idle-time=0 \
  --rdp-tls-cert=/etc/weston/rdp.crt \
  --rdp-tls-key=/etc/weston/rdp.key \
  --width=1280 \
  --height=800

后台启动：

nohup env LD_LIBRARY_PATH=/opt/qcom/lib:/lib weston --backend=rdp-backend.so \
  --socket=wayland-rdp-root \
  --idle-time=0 \
  --rdp-tls-cert=/etc/weston/rdp.crt \
  --rdp-tls-key=/etc/weston/rdp.key \
  --width=1280 \
  --height=800 \
  >/tmp/weston-rdp.log 2>&1 &

使用普通用户启动

启动前准备运行目录。若当前已登录为 q 用户，可跳过 chown 命令；若当前为 root 用户，可完整执行以下命令：

mkdir -p /run/user/1007
chown q:q /run/user/1007
chmod 700 /run/user/1007

以下命令需在 q 用户下执行。若当前提示符已经是 q@...，直接执行即可，不需要再添加 runuser -u q --。

runuser -u q -- 只在当前登录用户是 root 时使用，用于从 root shell 临时切换到 q 用户身份执行后面的命令。若当前已经登录为 q 用户，再添加 runuser -u q -- 可能会因为环境中没有该命令而执行失败。

前台启动：

env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800

后台启动：

nohup env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800 \
  >/tmp/weston-rdp.log 2>&1 &

若当前是在 root 用户下执行，也可以在上述启动命令的 env -i 前增加 runuser -u q --，切换到 q 用户启动 RDP 服务。例如：

runuser -u q -- env -i \
  HOME=/home/q \
  USER=q \
  LOGNAME=q \
  SHELL=/bin/bash \
  PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
  XDG_RUNTIME_DIR=/run/user/1007 \
  LD_LIBRARY_PATH=/opt/qcom/lib:/lib \
  weston --backend=rdp-backend.so \
  --socket=wayland-rdp \
  --idle-time=0 \
  --rdp-tls-cert=/home/q/weston-rdp.crt \
  --rdp-tls-key=/home/q/weston-rdp.key \
  --width=1280 \
  --height=800

检查 RDP 端口监听：

netstat -ltnp | grep 3389

若看到类似输出，表示 RDP 服务已启动：

tcp        0      0 0.0.0.0:3389            0.0.0.0:*               LISTEN      <PID>/weston

停止RDP服务

若需要停止临时启动的 Weston RDP 服务，可执行：

pkill -f 'weston.*rdp-backend'

远程桌面连接

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

  2. 在"计算机"输入框中填写开发板的 IP 地址，例如 10.66.84.106。如需手动指定端口，可填写 10.66.84.106:3389。

../../../_images/image_DXnmbWHiUoPDPbx6m9Rcp99FnKh.webp

  1. 点击"连接"，并根据提示输入远程桌面设置界面中显示的用户名和密码。若 Windows 安全中心提示输入凭据，可点击 更多选项，选择 使用其他帐户，然后输入远程桌面设置界面中配置的用户名和密码。

../../../_images/image_KKpkb0vBioaRVwxNIfPcP1ebnZd.webp

  1. 连接成功后，即可在 Windows 主机中查看并操作 Debian 桌面。L1 连接成功后可远程查看并操作 Weston RDP 桌面。

../../../_images/image_DxSGbI33YoDhiyxyx7Sc8tFUn7d.webp ../../../_images/image_JWNXb8tNHohz0xxMSffcJlTTnDh.webp

疑难解答

问题现象

可能原因

处理方法

weston --help | grep -i rdp 无输出（L1）

Weston 未编译或未安装 RDP backend

检查系统是否包含 /usr/lib/libweston-*/rdp-backend.so

weston --help 或启动 RDP 时提示 libweston-10.so.0: cannot open shared object file（L1）

未设置 Weston 运行所需动态库路径

在执行 Weston 相关命令前增加 LD_LIBRARY_PATH=/opt/qcom/lib:/lib

启动提示证书或私钥错误（L1）

证书路径错误、文件不存在或私钥权限不正确

确认 --rdp-tls-cert 和 --rdp-tls-key 指向有效文件

netstat -ltnp | grep 3389 无输出（L1）

Weston RDP backend 未成功启动

查看 /tmp/weston-rdp.log 中的错误信息

Windows 远程桌面无法连接（L1）

没有可达 IP、3389 未监听或网络不通

在 L1 执行 hostname -I、netstat -ltnp | grep 3389，并确认 Windows 与 L1 网络互通

连接时提示证书不受信任（L1）

使用的是本机自签证书

确认 IP 无误后继续连接，或替换为受信任证书

Windows 远程桌面无法连接（M1）

Windows 主机和 M1 不在同一局域网

确认两端网络连接，重新获取 M1 的 IP 地址

Windows 远程桌面无法连接（M1）

IP 地址或端口填写错误

在 M1 上执行 hostname -I 确认 IP，端口使用默认 3389

Windows 远程桌面无法连接（M1）

桌面共享 未开启

进入 设置 > 系统 > 远程桌面，打开 桌面共享

只能查看桌面，无法控制鼠标和键盘（M1）

远程控制 未开启，或当前为只读模式

打开 远程控制，或执行 grdctl rdp disable-view-only

登录提示用户名或密码错误（M1）

输入的凭据与远程桌面设置中显示的不一致

使用远程桌面设置界面中显示的用户名和密码，必要时重新生成或手动修改密码

重启或重新登录后远程桌面密码失效（M1）

Login 钥匙环未保持远程桌面凭据

按照"保持远程桌面登录密码"章节修改 Login 钥匙环密码

连接后画面异常或无法刷新（M1）

图形桌面会话状态异常

确认 M1 已登录图形桌面，断开后重新连接

网络切换后无法连接（L1/M1）

设备 IP 地址发生变化

重新执行 hostname -I 获取当前 IP 地址，并在 Windows 远程桌面中更新连接地址