Raspberry Pi Connect (测试版)
介绍
在 GitHub 上修改
Raspberry Pi Connect提供从世界任何地方安全访问您的Raspberry Pi。
要使用 Connect，请在 Raspberry Pi 上 安装 Connect 软件 和 将设备与帐户链接。然后访问 connect.raspberrypi.com，在浏览器窗口中访问 Raspberry Pi 上运行的桌面或 shell。
Connect使用安全、加密的连接。默认情况下，Connect在您的Raspberry Pi和浏览器之间直接通信。但是，当Connect无法在您的Raspberry Pi和浏览器之间建立直接连接时，我们使用中继服务器。在这种情况下，Raspberry Pi只保留操作Connect所需的元数据。
Connect目前处于Beta开发阶段。
|
Note
|
要使用Connect，您的Raspberry Pi必须运行 Bookworm 或更高版本。 |
安装
在 GitHub 上修改
如果您的Raspberry Pi OS版本中尚未安装Connect，请打开终端窗口。运行以下命令来更新您的系统和软件包：
$ sudo apt update
$ sudo apt full-upgrade在Raspberry Pi上运行以下命令来安装Connect：
$ sudo apt install rpi-connect您还可以从推荐的软件应用程序安装Connect。
安装后，使用 rpi-connect 命令行界面为当前用户启动Connect：
$ rpi-connect on或者，单击菜单栏中的连接图标打开下拉框并选择 Turn On Raspberry Pi Connect：
远程shell
我们分发了Connect的替代 Lite 变体，它仅支持远程shell访问，无法进行屏幕共享。
在Raspberry Pi上运行以下命令以安装Connect Lite：
$ sudo apt install rpi-connect-lite安装后，使用 rpi-connect 命令行界面为当前用户启动Connect：
$ rpi-connect onEnable user-lingering 使您的设备即使在您的用户帐户未登录时也可以访问。
|
Tip
|
Lite命令使用与Connect完整版相同的 rpi-connect 名称。rpi-connect-lite 只是一个包名称。
|
将 Raspberry Pi 设备与 Connect 账户连接起来
在 GitHub 上修改
现在您已经在Raspberry Pi设备上安装并启动了Connect，您必须将您的设备与您的Connect帐户相关联。
- 桌面
-
如果您使用菜单栏的Connect插件，首次单击 “Turn On Raspberry Pi Connect” 将打开您的浏览器，提示您使用Raspberry Pi ID登录：
或者，您可以从下拉框中选择"Sign In…"：
如果您还没有Raspberry Pi ID，请单击 create one for free 到 创建一个。 CLI::
+ 使用以下命令生成将您的设备与Connect帐户连接的链接：
+
$ rpi-connect signin+ 此命令应输出如下内容：
+
Complete sign in by visiting https://connect.raspberrypi.com/verify/XXXX-XXXX
+ 访问任何设备上的验证URL并使用您的Raspberry Pi ID登录以将您的设备与您的Connect帐户链接。
完成连接 Raspberry Pi
身份验证后，为您的设备分配一个名称。选择唯一标识设备的名称。单击 Create device and sign in 按钮继续。
您现在可以远程连接到您的设备。菜单栏中的连接图标将变为蓝色，表示您的设备现在已登录到连接服务。您应该会收到一封电子邮件通知，表明新设备已链接到您的连接帐户。
|
Warning
|
如果您收到一封电子邮件，显示您不认识的设备已登录 Connect，请立即更改您的 Raspberry Pi ID 密码。从 Connect 中移除设备 可将该设备从您的帐户永久移除。考虑 启用双因素身份验证，以确保账户安全。 |
单击菜单栏中的连接图标以打开连接菜单。此菜单允许您打开和关闭连接、登录和退出以及允许或禁止远程访问方法。
|
Tip
|
Connect使用您的设备序列号签署通信。在设备之间交换SD卡会使您退出Connect。 |
访问您的 Raspberry Pi 设备
现在您的设备出现在Connect仪表板上，您可以仅使用浏览器从任何地方访问您的设备。Connect提供多种方式与您的设备远程交互。
屏幕共享
Connect包括在浏览器中共享设备屏幕的功能。使用以下说明共享设备屏幕。
|
Note
|
屏幕共享需要 Wayland 窗口服务器。Raspberry Pi OS Bookworm 和以后默认使用Wayland。屏幕共享与Raspberry Pi OS Lite或使用X窗口服务器的系统 不 兼容。 |
在任何计算机上访问 connect.raspberrypi.com。
Connect会将您重定向到Raspberry Pi ID服务进行登录。登录后，Connect会显示链接设备列表。可用于屏幕共享的设备在设备名称下方显示灰色屏幕共享图标。
单击您要访问的设备右侧的 Connect via 连接按钮。从菜单中选择 Screen sharing 选项。这将打开一个显示设备桌面的浏览器窗口。
您现在可以像在本地一样使用您的设备。有关连接的更多信息，请将鼠标悬停在 Disconnect 按钮右侧的锁图标上。
|
Tip
|
使用桌面上方的 从远程(Copy from remote) 复制和 粘贴到远程(Paste to remote) 按钮在本地和远程剪贴板之间传输文本。 |
连接后，连接仪表板中的 屏幕共享(Screen sharing) 图标旁边会出现一个绿点。这表示活动的屏幕共享会话。悬停以查看当前屏幕共享会话的数量。
当屏幕共享会话正在进行时，系统托盘中的连接图标变为紫色并显示一个关闭的圆圈。每当屏幕共享会话开始时，都会出现桌面通知。
禁止屏幕共享
要关闭屏幕共享，请单击菜单栏中的连接图标并取消选择 允许屏幕共享(Allow Screen Sharing)。您的设备仍登录到连接，但您将无法从连接仪表板创建屏幕共享会话。
或者，您可以使用以下命令禁止屏幕共享：
$ rpi-connect vnc off在连接仪表板中，屏幕共享(Screen sharing) 图标和 通过连接 菜单中的 屏幕共享 选项将显示为划线。
要重新启用屏幕共享，请执行以下操作之一：
-
click the Connect icon in the menu bar and select Allow Screen Sharing
-
run the following command:
$ rpi-connect vnc on
远程 shell
Connect包括从浏览器启动在您的设备上运行的shell的能力。使用以下说明访问远程shell。
在任何计算机上访问 connect.raspberrypi.com。
Connect会将您重定向到Raspberry Pi ID服务进行登录。登录后，Connect会显示链接设备列表。可用于远程shell访问的设备在设备名称下方显示灰色 Remote shell 图标。
单击您要访问的设备右侧的 通过连接(Connect via) 按钮。从菜单中选择 Remote shell 选项。这会在您的设备上打开一个shell会话。
您现在可以像在本地一样使用您的设备。
|
Tip
|
在某些操作系统上，浏览器会拦截 Ctrl+Shift+C 和 Ctrl+C 等组合键。相反，您可以使用右键菜单或 Ctrl+Insert 复制和 Shift+Insert 粘贴。 |
连接后，Connect仪表板中的 Remote shell 图标旁边会出现一个绿点。这表示活动的远程shell会话。悬停以查看当前远程shell会话的数量。
每个远程shell连接都会创建一个全新的连接，就像SSH一样。要在多个会话中持久化后台命令和配置，请使用 screen 或 tmux。
当远程shell会话正在进行时，菜单栏中的连接图标变为紫色并显示一个关闭的圆圈。每当远程shell会话开始时，都会出现桌面通知。
|
Tip
|
CONNECT_TTY 环境变量表示会话使用Connect提供的远程shell。
|
禁止远程 shell 访问
要关闭远程shell访问，请单击菜单栏中的连接图标并取消选择 允许远程shell访问(*Allow Remote Shell Access)。您的设备仍登录到连接，但您将无法从连接仪表板创建远程shell会话。
或者，您可以使用以下命令禁止远程shell访问：
$ rpi-connect shell off在Connect仪表板中，Remote shell 图标和 Connect via 菜单中的Remote shell 选项将显示为划掉。
要重新启用远程shell访问，请执行以下操作之一：
-
click the Connect system tray icon and select Allow Remote Shell Access
-
run the following command:
$ rpi-connect shell on
始终启用远程 shell
Connect作为用户级服务运行，而不是以root身份运行。因此，Connect仅在您的用户帐户当前登录到您的设备时才有效。如果您在禁用自动登录的情况下重新启动，这可能会使您的设备无法访问。即使您没有登录到设备，要继续运行Connect，请启用 user-lingering。从您的用户帐户运行以下命令以启用user-lingering：
$ loginctl enable-linger|
Tip
|
我们建议在所有无显示器Raspberry Pi OS Lite设置上启用用户逗留，以防止您的设备在远程重启后变得无法访问。 |
管理设备
Connect仪表板列出了与您的Connect帐户链接的所有设备，并向您展示了访问它们的各种方式。
单击设备名称以打开设备详情页。此屏幕提供有关您的设备的低级信息。您还可以编辑设备名称或从连接中删除设备。
从连接中删除设备会自动使您退出设备上的连接。菜单栏中的连接图标变为灰色，菜单仅提供 登录…(Sign In…) 选项。
更新
要更新到最新版本的Connect，请运行以下命令：
$ sudo apt update
$ sudo apt install --only-upgrade rpi-connect|
Tip
|
如果您安装了Connect Lite，请在上述命令中将 rpi-connect 替换为 rpi-connect-lite。
|
断开连接设备
在您的设备上运行以下命令以注销您的Raspberry Pi ID，这将在连接屏幕上禁用您的设备：
$ rpi-connect signout或者，单击菜单栏中的连接图标，然后单击“退出(Sign Out)”。
|
Tip
|
要从您的Connect帐户中完全删除设备，从控制台中移除。 |
卸载
运行以下命令从设备中停止和删除Connect：
$ sudo apt remove --purge rpi-connect|
Tip
|
如果您安装了Connect Lite，请在上述命令中将 rpi-connect 替换为 rpi-connect-lite。
|
卸载后，设备的序列号仍然与您的Connect帐户相关联。该设备仍然出现在Connect仪表板中，但不能用于远程访问。如果您在同一设备上再次安装Connect，即使使用不同的SD卡，它也会重复使用Connect仪表板中的现有设备名称。
若要从Connect帐户删除设备，请从Connect仪表板中的设备列表中删除该设备。
问题分析
在 GitHub 上修改
已知问题
-
屏幕共享仅支持共享 Raspberry Pi 的单个主显示屏。当 Raspberry Pi 连接到多个 HDMI 屏幕时，Connect 有时会共享副屏幕的内容。你可以右键单击桌面，在 Desktop Preferences… 中更改任务栏的位置来解决这个问题。
-
Connect 不支持屏幕键盘。要实现全部功能，请使用实体键盘。
-
Connect 需要使用实现 ECMAScript2020（ES11）的浏览器，因为它使用了旧版浏览器无法使用的 功能。
-
浏览器会拦截某些键和组合键。因此，你无法在连接窗口中输入这些按键。屏幕共享包括一个工具栏，可以模拟一些最常用的快捷键。
-
要从版本 1 升级到版本 2，必须先升级当前安装的软件包，然后再在
rpi-connect和rpi-connect-lite之间切换。这将确保 Connect 服务正确迁移到版本 2 格式。如果当前已安装rpi-connect，请运行以下命令：$ sudo apt install --only-upgrade rpi-connect或者，如果您当前安装了
rpi-connect-lite，请运行以下命令：$ sudo apt install --only-upgrade rpi-connect-lite您应该会在升级期间看到类似于以下内容的输出，表明Connect的服务已迁移到版本2格式：
Replacing globally-enabled rpi-connect services with user-enabled ones...
常见问题
无法使用共享屏幕
如果 Connect 提示屏幕共享不可用，则表明不符合屏幕共享支持的一个或多个要求。为帮助调试问题，rpi-connect 和 rpi-connect-lite 包含`doctor`命令。使用 rpi-connect doctor 找出屏幕共享的问题。
运行以下命令：
$ rpi-connect doctor如果一切正常，你应该可以看到类似下面的输出：
Screen sharing is supported by this version of rpi-connect ✓ Wayland compositor available ✓ Screen sharing services enabled and active ✓ Communication with Raspberry Pi Connect API ✓ Authentication with Raspberry Pi Connect API ✓ Peer-to-peer connection candidate via STUN ✓ Peer-to-peer connection candidate via TURN
如果有问题，你应该会看到类似这样的输出：
Screen sharing is supported by this version of rpi-connect ✓ Wayland compositor available ✗ Screen sharing services enabled and active - Please run rpi-connect on to enable and start all required services ✓ Communication with Raspberry Pi Connect API ✓ Authentication with Raspberry Pi Connect API ✓ Peer-to-peer connection candidate via STUN ✓ Peer-to-peer connection candidate via TURN ✗ Some checks failed
如果在运行 Connect 所需服务时反复出现问题，请运行以下命令详细检查它们的状态：
$ systemctl --user status rpi-connect-wayvnc.service rpi-connect-wayvnc-watcher.path
$ journalctl --user --follow --unit rpi-connect-wayvnc.service --unit rpi-connect-wayvnc-watcher.path如果服务启动失败或不存在，请确保您的环境符合以下条件：
-
您使用
rpi-connect版本1.1.0或更高版本。 -
您没有使用
rpi-connect-lite，它缺乏屏幕共享支持。 -
您使用Wayland合成器，如wayfire或labwc，而不是X。您可以通过
raspi-config的高级选项控制此设置。 -
您使用WayVNC支持的桌面环境，例如Raspberry Pi Desktop。例如，使用KDE将您的Wayland合成器切换到不支持的kwin。
-
您有一个活动的图形桌面会话以与您登录的用户相同的用户身份运行。对于大多数人来说，这意味着通过
raspi-config的系统选项启用“桌面自动登录”。
Can’t connect after restarting or ending SSH session
Connect作为用户级服务运行，因此只有当登录到服务的用户有活动会话时才可用。如果您希望远程shell访问而不同时运行另一个登录会话，请为您的用户提供 enable user-lingering，这将使Connect始终运行。
对于屏幕共享，Connect只能共享现有的图形桌面会话：它不会创建全新的会话。必须已经有一个桌面会话正在进行中。要在启动时自动启动此类会话，请通过 raspi-config 的系统选项启用桌面自动登录。
网络及防火墙问题
Connect通常在设备之间进行通信，而无需更改网络或防火墙。但是，特别严格的网络有时会阻止Connect通信。为了帮助调试此类网络的问题，rpi-connect 和 rpi-connect-lite 包含 rpi-connect doctor 命令。rpi-connect doctor 运行一系列测试来检查Connect通信在您的网络上是否正常运行。
要在您的设备上运行这些测试，请运行以下命令：
$ rpi-connect doctor如果Connect可以在您的网络上正常通信，您应该会看到类似于以下内容的输出：
Screen sharing is supported by this version of rpi-connect ✓ Wayland compositor available ✓ Screen sharing services enabled and active ✓ Communication with Raspberry Pi Connect API ✓ Authentication with Raspberry Pi Connect API ✓ Peer-to-peer connection candidate via STUN ✓ Peer-to-peer connection candidate via TURN
如果Connect无法在您的网络上正确通信，您将在失败的测试用例旁边看到“x”而不是检查。请您的网络管理员在您的网络上启用以下连接：
-
通过
api.connect.raspberrypi.com的 443 端口向 Raspberry Pi Connect API 发送 HTTPS 请求 -
通过以下所有 UDP 端口 3478 向 Raspberry Pi Connect STUN 或 TURN 服务器发出请求：
-
stun.raspberrypi.com. -
turn1.raspberrypi.com. -
turn2.raspberrypi.com
-
turn3.raspberrypi.com
-
-
向下列所有 TCP 端口 3478 或 443 上的 Raspberry Pi Connect TURN 服务器发出请求：
-
turn1.raspberrypi.com`turn2.raspberrypi.com -
turn2.raspberrypi.com. -
turn3.raspberrypi.com
-
-
通过 UDP 端口 3478、443 或 49152 → 65535 向树莓派连接 TURN 服务器发出以下所有请求：
-
turn1.raspberrypi.com. -
turn2.raspberrypi.com
-
turn3.raspberrypi.com
-
查看 Connect 状态
要查看Connect服务的当前状态，请运行以下命令：
$ rpi-connect status您应该会看到类似于以下内容的输出：
Signed in: yes Screen sharing: allowed (0 sessions active) Remote shell: allowed (0 sessions active)
该命令的输出会显示您当前是否已登录 Connect，以及 Raspberry Pi 上已启用的远程服务。
如果您看到包括“Raspberry Pi Connect未运行，请运行rpi-connect on”在内的输出，请运行 rpi-connect on 以启动Connect。
启用增强型日志记录
您可以为 rpi-connect 及其专用WayVNC服务器启用调试日志记录，以详细了解Raspberry Pi上的本地操作。
Enable enhanced logging in rpi-connect
使用以下命令重写 rpi-connect 服务定义：
$ systemctl --user edit rpi-connect在注释之间输入以下配置行：
[Service]
ExecStart=
ExecStart=/usr/bin/rpi-connectd -socket %t/rpi-connect-wayvnc.sock -v|
Note
|
您需要两行以 ExecStart= 开头的配置行。
|
最后，使用以下命令重新启动Connect：
$ rpi-connect restart
Enable enhanced logging in the dedicated wayvnc server
使用以下命令覆盖 rpi-connect-wayvnc 服务定义：
$ systemctl --user edit rpi-connect-wayvnc在注释之间输入以下配置行（包括 -Ldebug 标志）：
[Service]
ExecStart=
ExecStart=/usr/bin/rpi-connect-env /usr/bin/wayvnc --config /etc/rpi-connect/wayvnc.config --render-cursor --unix-socket --socket=%t/rpi-connect-wayvnc-ctl.sock -Ldebug %t/rpi-connect-wayvnc.sock|
Note
|
您需要两行以 ExecStart= 开头的配置行。
|
最后，使用以下命令重新启动Connect：
$ rpi-connect restart