树莓派 Connect

介绍

提示

本站提供了同类远程管理工具 PiDoc，具有更丰富的功能。服务器位于国内，提供更稳定的连接，更高的传输带宽。欢迎免费使用！

通过 Raspberry Pi Connect，您可以从世界任何地方安全地访问您的树莓派。它的工作原理是将您的设备与 Connect 账户关联。

在 Raspberry Pi OS Desktop 和 Raspberry Pi OS Full（带推荐软件的桌面版）中，Connect 默认已安装。

而在 Raspberry Pi OS Lite 中，默认安装的是另一个 Lite 变体，该版本仅支持远程 shell 访问，不支持屏幕共享。

备注

要使用 Connect，您的树莓派必须运行 Raspberry Pi OS Bookworm 或更高版本。

Connect 服务功能

将树莓派设备关联到 Connect 账户后，您可以通过以下方式与它们交互：

屏幕共享界面
远程shell
远程更新

Connect 菜单

Connect 菜单允许您开启和关闭 Connect、登录和注销，以及启用或禁用两种远程访问方式（shell 和屏幕共享）。

安全与数据存储

Connect 使用安全的加密连接。

默认情况下，Connect 会在您的树莓派和浏览器之间直接通信。但是，当 Connect 无法在您的树莓派和浏览器之间建立直接连接时，我们会使用中继服务器。在这种情况下，Raspberry Pi 只保留运行 Connect 所需的元数据。

Connect 账户类型

Connect 账户有两种类型：个人账户和组织账户。

个人账户为单一用户提供其 Connect 账户下所有已关联设备的视图。该账户类型免费。

组织账户允许多个用户查看关联到共享 Connect 账户的设备。该账户类型按月计费。更多信息请参阅 Connect for Organisations。

开始使用

开始使用 Connect 需要三个步骤：

使用您的 Raspberry Pi ID 登录 connect.raspberrypi.com。更多信息请参阅创建 Raspberry Pi ID。
在您的树莓派设备上开启 Connect 服务，然后将其关联到您的 Connect 账户。
在您的 PC、Mac 或其他设备上访问 connect.raspberrypi.com，在网页浏览器中远程访问已关联的设备。

开启 Connect 服务并关联设备

完整版 Raspberry Pi OS 已包含 Connect，但该服务默认处于禁用状态。因此您必须在首次使用前将其开启。

您可以通过桌面、命令行或授权密钥开启 Connect 并将其关联到您的树莓派设备。

备注

Connect 使用设备序列号对通信进行签名。在设备之间移动 SD 卡会导致您退出 Connect。

桌面
命令行
授权密钥

要启用 Connect 并关联您的设备：

为您的树莓派设备通电。
从系统托盘中的 Connect 图标，选择 开启 Raspberry Pi Connect。

如果这是您首次开启 Connect 服务，或者您尚未使用 Raspberry Pi ID 登录，浏览器将会打开。
输入您的 Raspberry Pi ID 邮箱和密码，然后选择登录。
按照屏幕提示为您的树莓派设备命名，并选择要关联到哪个 Connect 账户。

如果您是组织的管理员，请选择是将此设备添加到您的个人账户还是特定组织。
选择 创建设备并登录。

完成这些步骤后，树莓派设备系统托盘中的 Connect 图标将变为蓝色，表示它已登录 Connect 服务。

系统还会向您的注册邮箱发送通知，告知有新设备已关联到您的 Connect 账户。

运行以下命令开启 Connect：
```
rpi-connect on
```
这会开启 Connect 服务，但不会让您登录。

运行以下命令登录：

rpi-connect signin

此命令将输出类似以下内容：

Complete sign in by visiting https://connect.raspberrypi.com/verify/XXXX-XXXX

在任意设备上访问该验证网址，并使用您的 Raspberry Pi ID 登录，以完成关联过程。

完成这些步骤后，树莓派设备系统托盘中的 Connect 图标将变为蓝色，表示它已登录 Connect 服务。系统还会向您的注册邮箱发送通知，告知有新设备已关联到您的 Connect 账户。

您也可以在命令行输入 rpi-connect status 来检查连接状态。

授权密钥是一种一次性临时令牌，可让您自动将设备与 Connect 账户关联（无需使用网页界面）。个人授权密钥在创建后 6 小时过期；组织授权密钥在创建后 1 至 90 天过期（默认 1 天）。

创建和使用授权密钥最便捷的方式是使用 Imager 中的自定义选项。您也可以在个人或组织 Connect 账户的设置页面手动创建授权密钥，组织管理员还可以使用管理 API 创建授权密钥。

备注

个人账户每次仅能激活一个授权密钥；组织账户可同时激活多个授权密钥。每台设备都需要一个唯一的授权密钥。

提示

要使用授权密钥，请确保在 Raspberry Pi Connect 网站显示的到期时间之前启动您的树莓派并连接网络。

创建授权密钥后，可通过 rpi-connect signin 命令提供给设备，或将其写入用户主目录下的文件中。

或者，将其保存到用户主目录下的 .config/com.raspberrypi.connect/auth.key，这样 Connect 会自动检测到它。

以字符串形式提供授权密钥，请运行以下命令：

rpi-connect signin --auth-key=rpuak_123456

如果您已将授权密钥保存到文件，可以在路径前加上 @ 将其完整路径传给该命令：

rpi-connect signin --auth-key=@/home/alice/auth.key

完成这些步骤后，树莓派设备系统托盘中的 Connect 图标将变为蓝色，表示它已登录 Connect 服务。

系统还会向您的注册邮箱发送通知，告知有新设备已关联到您的 Connect 账户。

安全最佳实践

如果您收到关于不认识的设备的通知邮件：

立即更改您的 Raspberry Pi ID 密码。
按照从 Connect 移除设备中的说明操作，永久解除该设备与您账户的关联。
考虑启用双因素身份验证以保障账户安全。

查看已关联的设备

Connect 会在设备选项卡中列出所有已关联的设备。

要查看您的设备：

在任意设备上登录 connect.raspberrypi.com。
选择设备选项卡。Connect 将显示已关联设备的列表。

如果您拥有组织账户，您可以搜索和筛选此列表，并为设备添加标签。

访问你的 Raspberry Pi 设备

将您的树莓派设备关联到 Connect 账户后，您只需使用网页浏览器即可从任何地方访问它。

您可以通过以下任一方式实现：

屏幕共享
远程 shell

备注

屏幕共享需要 Wayland 窗口服务器。Raspberry Pi OS Bookworm 及更高版本默认使用 Wayland。屏幕共享与 Raspberry Pi OS Lite 或使用 X 窗口服务器的系统不兼容。

备注

无论您的树莓派与浏览器处于同一网络还是不同网络，屏幕共享和远程 shell 都能工作。但是，直接的本地连接比通过互联网或中继服务器的连接更快、响应也更及时。

屏幕共享界面

Connect 的屏幕共享界面适用于桌面和移动设备。

您可以通过界面左下角的按钮模拟常见的键盘功能：

键盘。切换屏幕键盘。仅在移动设备上显示。
Ctrl。模拟在物理键盘上按住此键。
Super 键。模拟在物理键盘上按住此键。
Alt。模拟在物理键盘上按住此键。
Esc。模拟单击此键（按下后松开）。
Tab。模拟单击此键（按下后松开）。

您还可以使用浏览器窗口顶部的按钮完成其他实用操作：

从远程复制。将设备远程剪贴板中的文本传输到您的本地剪贴板。
粘贴到远程。将您本地剪贴板中的文本传输到设备的远程剪贴板。
进入全屏。将浏览器窗口展开至全屏。
断开连接。终止共享会话。

开始屏幕共享

要开始屏幕共享会话：

确保您的树莓派设备已关联到 Connect 账户、已通电，并且 Raspberry Pi OS 已启动。
在您的 PC、Mac 或其他设备上登录 connect.raspberrypi.com。

如果您的浏览器或操作系统请求在本地网络上查找或连接设备的权限，请允许。如果您拒绝，Connect 仍然可用，但与本地网络设备的会话无法使用本地路由。
选择设备选项卡。

可进行屏幕共享的设备会在名称下方显示灰色的 Screen sharing 徽章。
选择您要访问的设备右侧的 Connect via 按钮。
从菜单中选择 Screen sharing 选项。

此时会打开一个浏览器窗口，显示您设备的桌面，您现在可以像使用本地设备一样使用它。

屏幕共享开始后，Connect 控制面板中 Screen sharing 徽章旁边会出现一个绿点。这表示存在活动的屏幕共享会话。将鼠标悬停在绿点上可查看当前屏幕共享会话的数量。

屏幕共享会话进行期间，系统托盘中的 Connect 图标会旋转。每次屏幕共享会话开始时，都会出现桌面通知。

停止屏幕共享

要停止屏幕共享：

选择显示屏幕共享的浏览器窗口。
选择左上角的 Disconnect 按钮。

禁止和重新允许屏幕共享

您可以通过界面或命令行在树莓派设备上禁止屏幕共享。

注意

如果您通过 shell 或屏幕共享会话同时禁止了 shell 访问和屏幕共享，则必须使用 SSH 等其他常见的远程访问方案，才能在无需亲临现场的情况下访问该设备。

界面
命令行

要禁止屏幕共享：

在您的树莓派设备上，选择系统托盘中的 Connect 图标，然后取消勾选 Allow Screen Sharing。

您的设备仍保持登录 Connect 的状态，但屏幕共享现已被禁止。
（可选）验证屏幕共享已被禁止：
1. 在您的 PC、Mac 或其他设备上登录 connect.raspberrypi.com。
2. 选择设备选项卡并在列表中找到该树莓派设备：Screen sharing 徽章与 Connect via 菜单中的 Screen sharing 选项现已划掉。

要禁止屏幕共享：

在您的树莓派设备上，打开终端。
输入以下命令：
```
rpi-connect vnc off
```
您的设备仍保持登录 Connect 的状态，但屏幕共享现已被禁止。
（可选）验证屏幕共享已被禁止：
1. 在您的 PC、Mac 或其他设备上登录 connect.raspberrypi.com。
2. 选择设备选项卡并在列表中找到该树莓派设备：Screen sharing 徽章与 Connect via 菜单中的 Screen sharing 选项现已划掉。

要重新允许屏幕共享：

在您的树莓派设备上，打开终端。
输入以下命令：
```
rpi-connect vnc on
```

远程shell

要访问远程 shell：

在您的 PC、Mac 或其他设备上登录 connect.raspberrypi.com。

如果您的浏览器或操作系统请求在本地网络上查找或连接设备的权限，请允许。如果您拒绝，Connect 仍然可用，但与本地网络设备的会话无法使用本地路由。
选择设备选项卡，并在列表中找到您的树莓派设备。

可进行远程 shell 访问的设备会在名称下方显示灰色的 Remote shell 徽章。
选择您要访问的设备右侧的 Connect via 按钮。
从菜单中选择 Remote shell 选项。这将在您的设备上打开一个 shell 会话。

您现在可以像使用本地设备一样使用它。

提示

在某些操作系统上，浏览器会拦截 Ctrl+Shift+C 和 Ctrl+C 等组合键。您可以改用右键菜单，或使用 Ctrl+Insert 复制、Shift+Insert 粘贴。

每次远程 shell 会话开始时都会出现桌面通知。连接期间，Connect 控制面板中 Remote shell 徽章旁边会出现一个绿点，表示远程 shell 会话处于活动状态。将鼠标悬停在绿点上可查看当前远程 shell 会话的数量。

Connect 界面，显示设备列表中带有绿点的 Remote shell 图标。这表示远程 shell 会话正在进行中。

提示

每个远程 shell 连接都会创建一个全新的连接，就像 SSH 一样。要在多个会话之间保持后台命令和配置，请使用 screen 或 tmux。

提示

CONNECT_TTY 环境变量表示会话使用的是 Connect 提供的远程 shell。

结束远程shell会话

要关闭远程 shell 会话，请在命令行中运行 exit 命令，或关闭浏览器窗口。

禁止和重新允许远程shell访问

您可以通过界面或命令行禁止 shell 访问。

注意

界面
命令行

要禁止远程 shell 访问：

在您的树莓派设备上，选择系统托盘中的 Connect 图标。
取消勾选 Allow Remote Shell Access。

您的设备仍保持登录 Connect 的状态，但您无法通过 Connect 控制面板创建远程 shell 会话。

要禁止远程 shell 访问：

在您的树莓派设备上，打开终端。
输入以下命令：
```
rpi-connect shell off
```

在 Connect 控制面板中，Remote shell 徽章与 Connect via 菜单中的 Remote shell 选项会显示为划掉状态。

要重新允许远程 shell 访问：

界面
命令行

在您的树莓派设备上，选择系统托盘中的 Connect 图标。
选择 Allow Remote Shell Access。

在您的树莓派设备上，打开终端。
输入以下命令：
```
rpi-connect shell on
```

始终启用远程shell

Connect 以用户级服务而非 root 运行。因此，只有当你的用户账户当前登录设备时，Connect 才能工作。如果在禁用自动登录的情况下重启，这可能会导致无法访问设备。要在未登录设备时继续运行 Connect，请启用user-lingering。从您的用户账户运行以下命令启用用户登录：

loginctl enable-linger

提示

我们建议在所有无头 Raspberry Pi OS Lite 设置中启用用户登录，以防止远程重启后无法访问设备。

禁用动画图标

若要在屏幕共享或远程shell会话进行时禁用动画图标，请右键点击菜单栏中的 Connect 图标，选择配置插件...。

勾选动画图标开关即可切换为备用图标。

屏幕共享或远程shell会话进行时，Connect图标将变为蓝色。

管理设备

Connect 面板列出了与您的 Connect 账号关联的所有设备，并显示了访问这些设备的各种方法。

选择设备名称可打开设备详细信息页面。此页面提供有关设备的低级信息。

要重命名或删除设备，请在设备页面上选择设置。

从 Connect 中删除设备会自动退出该设备上的连接。菜单栏中的 Connect 图标会变成灰色，菜单上只提供**Sign In...**选项。

更新

注意

升级 Connect 会断开正在进行的任何屏幕共享或远程 shell 会话。除非您以不会因断开而中断的方式运行命令（例如使用 screen 或 tmux），否则不建议使用远程 shell 升级 Connect。

要更新到最新版本的 Connect，请运行以下命令：

sudo apt update
sudo apt install --only-upgrade rpi-connect

如果安装了 Connect Lite，请将上述命令中的 rpi-connect 替换为 rpi-connect-lite。

从 Connect 中断开设备连接

在你的设备上运行以下命令退出你的 Raspberry Pi ID，这将在 Connect 屏幕上禁用你的设备：

rpi-connect signout

或者，点击菜单栏中的 Connect 图标，然后点击 Sign Out。

提示

要从 Connect 帐户中完全移除设备，请使用从 Connect 面板中移除。

卸载

运行以下命令从设备上停止并删除 Connect 软件：

sudo apt remove --purge rpi-connect

提示

如果安装了 Connect Lite，请将上述命令中的 rpi-connect 替换为 rpi-connect-lite。

卸载后，设备的序列号仍与您的 Connect 账号相关联。设备仍会出现在 Connect 面板中，但不能用于远程访问。如果在同一台设备上再次安装 Connect，即使使用不同的 SD 卡，它也会重复使用 Connect 面板中现有的设备名称。

要切断设备和 Connect 账号之间的联系，请从 Connect 面板的设备列表中删除设备。

远程更新你的设备

Connect 具备通过远程推送更新来更新树莓派设备的能力。

远程更新适用于更新防火墙后的设备，以及地理位置偏远或难以接触的设备。

Connect 支持两种类型的更新工件：

脚本工件：由 otamaker 创建，在设备上以 root 权限运行 shell 脚本。它可在标准 Raspberry Pi OS 安装上运行，适合升级软件包等维护任务。
A/B 启动更新：由 rpi-image-gen 创建，替换整个操作系统，并在更新失败时自动回退到之前的版本。它需要先为设备写入 A/B 启动布局的镜像。

无论你构建哪种类型的工件，都可以从 Raspberry Pi Connect 网站进行部署，具体说明见部署更新工件。你在部署过程中上传工件，Connect 会将其传递给接收设备。

如果你的设备属于 Connect for Organisations 账户，部署方式会略有不同。更多信息请参阅在组织中部署远程更新。

部署更新工件

当你使用 otamaker 或 rpi-image-gen 构建工件后，使用 Raspberry Pi Connect 网站将其部署到设备。

备注

如果接收设备属于某个组织，请从在组织中部署远程更新开始，该页描述了组织可用的额外选项。

部署始终从你要更新的设备开始，因此在继续之前，请确保接收设备已注册到你的个人账户，并且处于在线状态：

登录 Raspberry Pi Connect。
使用右上角的账户切换器选择个人账户。
前往设备选项卡，然后在接收设备旁选择部署。部署仅对已启用远程更新且当前在线的设备显示。

这将打开新建部署表单，该表单分两个步骤为部署创建新工件。

在步骤 1：上传工件中，上传你构建的工件：

输入工件的名称。名称无需唯一，因此可以使用有助于你日后识别该部署的内容，例如版本号。
将工件拖到文件区域，或选择浏览来选择它。该文件必须是 2 GB 或更小的 Zstandard 压缩 tar 归档文件（.tar.zst 文件）。
等待校验和和上传都显示为 Complete（完成）。

要选择其他文件，请选择 Remove（移除）。要放弃仍在上传的文件，请选择 Cancel（取消）。
选择下一步。

在步骤 2：检查并部署中，检查名称、文件和 SHA-256 校验和，然后选择部署。如果发现错误，请选择返回进行修正。

新建部署表单的步骤 2，显示要部署工件的名称、文件和校验和，以及部署按钮�。

Connect 会保留你上传的工件两小时，然后将其删除。在其工件被删除时尚未开始的部署会被标记为 Invalidated（已失效）。要再次部署该工件，请重新上传。

监控部署

当部署处于待处理或进行中状态时，部署历史记录会自动更新。部署历史记录标题旁会出现一个旋转图标，表示页面正在自动刷新。部署完成后，旋转图标消失，历史记录停止更新。

如果部署显示失败，选择它以查看错误消息，然后参阅远程更新失败。

你可以通过选择部署并选择取消来取消待处理的部署。当另一个部署排队时，待处理的部署也会自动取消。

验证部署

要验证部署，脚本工件请参阅脚本工件，A/B 启动更新请参阅 A/B 启动更新。

A/B 启动更新

A/B 启动更新可防止失败或错误的更新导致设备停止工作。

该配置设有两个独立槽位，每个槽位由一个启动分区和一个系统分区组成。槽位 A 用于现有操作系统 (OS)，槽位 B 用于更新。设备从槽位 B 启动，但如果启动失败，会自动回退到已知正常工作的分区（槽位 A）。每次后续更新都会重复此过程。

配置 A/B 启动需要能够物理接触设备，因为必须使用适当的 A/B 启动布局对设备进行镜像。但配置完成后，即可通过 Raspberry Pi Connect 进行远程更新。

使用 EEPROM 引导的 Raspberry Pi 5 及更高版本设备也可以配置为使用 A/B 启动更新。参见 A/B bootloader 更新。

使用 rpi-image-gen 创建 A/B 启动配置（.img 文件）和更新工件（.tar.zst 文件）。使用 Raspberry Pi Imager 配置 .img 文件并将其写入存储设备，以便传输到接收更新的树莓派。

前提条件

使用远程更新和 A/B 启动配置需要满足以下条件：

创建 A/B 启动配置和更新工件（使用 rpi-image-gen）需要：

一台已安装以下软件的树莓派设备：

最新 32 位或 64 位版本的 Raspberry Pi OS (Trixie)。
rpi-image-gen。
最新版本的 Raspberry Pi Connect 或 Connect Lite。
最新版本的 Raspberry Pi Imager。

配置接收设备进行 A/B 启动需要：

一个存储设备（通常为 microSD），用于保存 A/B 启动布局，以及将存储设备连接到树莓派的方式。

至少需要 16 GB 空间，但具体所需磁盘空间需根据启动分区（固件、内核、设备树文件以及可能的 initramfs）和系统分区（内核模块及系统级软件，如标准 Linux 命令行工具）的未来需求决定。

接收更新工件的设备需要：

Raspberry Pi 4 或更高版本，需满足：
- 已连接互联网。
- 已选择加入远程更新。
- 已注册并登录你的 Raspberry Pi Connect 账户。

实施 A/B 启动并远程更新首个镜像

按照以下三个阶段实施 A/B 配置并使用 Raspberry Pi Connect 发送更新：

第一阶段：为接收设备（Raspberry Pi 4 及更高版本）准备远程更新，创建 A/B 启动文件，然后部署到设备。
第二阶段：创建用于部署到接收设备的更新工件文件。
第三阶段：使用 Raspberry Pi Connect 的远程更新功能将更新工件部署到接收设备，然后验证更新。

第一阶段：创建 A/B 启动配置

标准 Raspberry Pi OS 安装不包含 A/B 启动配置。本阶段介绍如何使用 rpi-image-gen 和 Raspberry Pi Imager 创建 A/B 启动配置。

rpi-image-gen 输出一个包含 A/B 启动镜像的 .img 文件。

然后，Raspberry Pi Imager 使用该 .img 文件将操作系统配置写入存储设备。这包括将设备加入 OTA（空中下载）更新，以便 Raspberry Pi Connect 能够对其进行远程更新。

首次更新接收设备时必须能够物理接触该设备，但配置完成后，即可通过远程方式发送后续更新。

在第3步中，你将生成一个授权密钥，以便接收设备关联到 Raspberry Pi Connect 网站。此授权密钥与单个接收设备绑定，因此请为每个要更新的接收设备创建新的密钥。

备注

你必须使用运行最新版 Raspberry Pi OS (Trixie) 的树莓派设备来创建更新。接收设备必须为 Raspberry Pi 4 或更高版本。

要使用 A/B 启动配置更新接收设备：

步骤 1：安装 rpi-image-gen

在树莓派上，从命令行运行以下命令从 GitHub 克隆 rpi-image-gen 仓库：

git clone https://github.com/raspberrypi/rpi-image-gen.git

进入克隆的目录，然后运行以下命令安装依赖项：

cd rpi-image-gen
sudo ./install_deps.sh

步骤 2：准备并配置镜像

提示

rpi-image-gen 包含一个示例应用程序，带有层和配置，可构建与远程更新兼容的镜像。

有关 .yaml 文件元数据的说明，请参阅 X 环境元数据和层。

准备镜像：

进入 rpi-image-gen 安装文件夹。
打开 examples/ota/layer/ota.yaml。
自定义以下元数据：
- X-Env-Layer-Name。
- X-Env-Layer-Category。
- X-Env-Layer-Desc。
- X-Env-Layer-Reqs。
打开 examples/ota/config/ota.yaml。
设置以下环境变量：
- Version。用于确定启动镜像版本。现在设置一个起始版本号，以后每次创建更新工件时相应递增。如不指定版本号，默认为 1.0.0。
- Device hostname。用于此设备创建的所有镜像。必须唯一。如不指定设备主机名，每次构建将默认创建值 ota-device-1。
（可选）打开 examples/ota/config/ota.yaml 并：
- 定义构建时要安装的额外软件包。更多信息请参阅软件包。
- 添加无线网络凭证。更多信息请参阅无线网络。

步骤 3：生成授权密钥

在此步骤中，创建授权密钥并将其复制下来，供步骤 4 使用。

当你在 A/B 启动更新（步骤 6）后启动接收设备时，设备会用授权密钥交换一个访问令牌，该令牌保存在用户数据分区中。此密钥在未来的更新中持续有效，因此只需生成一次。

有关为组织创建授权密钥的更多信息，请参阅 Connect for Organisations 文档中的创建授权密钥。

生成授权密钥：

登录 Raspberry Pi Connect。
从右上角的账户切换器中选择你的组织或个人账户。
前往 Provisioning 选项卡（组织）或设置选项卡（个人），然后在授权密钥部分选择新建（组织）或创建新授权密钥（个人）。
填写表单，然后选择创建授权密钥。
复制下密钥。

Raspberry Pi Connect 中的授权密钥页面，显示一个可供复制粘贴的授权密钥。

步骤 4：构建 A/B 启动配置镜像

现在你已设置好应用程序并创建了授权密钥，使用 rpi-image-gen 创建启动配置镜像。

这将创建一个 .img 文件，将在步骤 5 中使用 Raspberry Pi Imager 写入存储设备。

构建 A/B 启动配置镜像：

从命令行切换到 rpi-image-gen 文件夹。

cd rpi-image-gen

运行以下命令，将 rpuak_XXX 替换为你在步骤 3 中复制的授权密钥（组织授权密钥以 rpoak_ 开头）。

Raspberry Pi 5 及更高版本：

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_connect_authkey=rpuak_XXX

Raspberry Pi 4：

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml -- IGconf_device_layer=rpi4 IGconf_connect_authkey=rpuak_XXX

应用程序将生成文件并保存在 /rpi-image-gen/work/image-x.x.x 文件夹中（其中 x.x.x 对应你在步骤 2 中设置的版本环境变量）。

步骤 5：写入镜像

接下来，使用 Raspberry Pi Imager 创建操作系统配置并保存到存储设备。

注意

以下示例目标 (/dev/mmcblk0) 仅在你从其他设备（如 NVMe SSD）启动时使用。注意不要覆盖操作系统。

写入镜像：

如果尚未安装 Raspberry Pi Imager，从命令行运行：

sudo apt install rpi-imager

从图形界面的附件菜单中打开 Raspberry Pi Imager。如提示输入密码，请输入。
选择接收设备类型：Raspberry Pi 4 或 Raspberry Pi 5，然后选择下一步。

Raspberry Pi Imager 打开后，显示设备页面，其中包含一系列可供选择的树莓派设备。

在 OS 选项卡上，滚动到底部并选择使用自定义镜像。
导航到你在步骤 4 中创建的 .img 文件，选中后选择打开。
选择下一步，然后选择要保存 A/B 启动配置的存储设备。
选择写入，然后按照屏幕上的提示完成写入过程。
当 Raspberry Pi Imager 完成操作系统写入后，选择完成。

现在你可以安全地移除存储设备，为步骤 6 做准备。

步骤 6：将 `.img` 文件部署到接收设备

关闭接收设备电源。
连接步骤 5 中的存储设备。
开启接收设备电源，等待其使用新镜像启动。
登录 Raspberry Pi Connect，然后前往设备。

设备将出现在 Raspberry Pi Connect 面板中，设备下方将显示远程更新标签。

设备现已准备好使用 Raspberry Pi Connect 进行远程更新。

步骤 7：确认部署的版本

确认设备上部署的镜像版本与你在步骤 2 中配置的版本一致。

确认部署的镜像版本：

在 Raspberry Pi Connect 中选择该设备。
选择连接。
在命令行中输入：

cat /etc/rpi-issue

命令行返回类似以下内容：

Generated using rpi-image-gen e3828f885c860f15991468883d3b8484b0eaf9d8 on 2025-12-09
Artefact version: 1.0.0

第二阶段：创建更新工件

现在设备已配置好 A/B 启动，可以使用 Raspberry Pi Connect 向其交付更新工件。

更新工件由 rpi-image-gen 创建，为 .tar.zst 文件。这些文件比你在第一阶段创建的 .img 文件小得多，将在第三阶段由 Raspberry Pi Connect 部署到接收设备。

为便于说明，这里继续使用第一阶段的示例更新。请根据你自己的更新 .yaml 文件路径和命名调整这些步骤。

构建更新工件：

步骤 1：更新 `ota.yaml` 配置

递增配置 ota.yaml 文件中的 Version 环境变量：

${EDITOR:-vi} ./examples/ota/config/ota.yaml

步骤 2：构建更新

在终端中运行以下命令构建更新：

./rpi-image-gen build -S ./examples/ota/ -c ota.yaml

第三阶段：远程更新

使用 Raspberry Pi Connect 将更新工件部署到接收的树莓派设备。

步骤 1：将工件部署到接收设备

上传你在第二阶段构建的 .tar.zst 文件，从 Raspberry Pi Connect 网站部署工件，具体步骤参阅部署更新工件。

如果接收设备属于组织，请先托管工件，然后使用其 URI 和校验和进行部署，具体说明见在组织中部署远程更新。

步骤 2：验证更新

当部署显示为 Succeeded 时，使用 Raspberry Pi Connect 连接到接收设备，并按照第一阶段步骤 7 的方式确认部署的版本：

cat /etc/rpi-issue

命令行返回类似以下内容，表明 Artefact version 号已更改：

Generated using rpi-image-gen e3828f885c860f15991468883d3b8484b0eaf9d8 on 2025-12-09
Artefact version: 1.1.0

脚本工件

脚本工件打包了一个 shell 脚本，Raspberry Pi Connect 会在接收设备上以 root 权限运行它。脚本工件适用于维护任务，例如升级软件包、更改配置或安装软件。

与 A/B 启动更新不同，脚本工件不需要特殊的分区布局，因此您可以将其部署到任何运行标准 Raspberry Pi OS 安装的设备上。但是，如果脚本失败，不会自动恢复，因此在部署到远程设备之前，请仔细测试您的脚本。

使用 otamaker 来创建脚本工件。

前提条件

创建和部署脚本工件需要满足以下条件：

对于接收更新工件的设备：

一台树莓派设备，需要满足以下条件：

已连接到互联网。
已注册并登录您的 Raspberry Pi Connect 账户。
运行最新版本的 Raspberry Pi Connect 或 Connect Lite，并安装了 rpi-connect-ota 软件包：

sudo apt update
sudo apt install rpi-connect rpi-connect-ota

如果使用 Connect Lite，请安装 rpi-connect-lite 而不是 rpi-connect。

已选择加入远程更新，由 rpi-connect 通过其 ota（over-the-air）子命令进行管理：

rpi-connect ota on

对于使用 otamaker 创建更新工件：

otamaker 工具，包含在 rpi-connect-ota 软件包中。

提示

要在树莓派以外的计算机上构建工件，请从 GitHub 上的 utils 仓库下载 otamaker。

第 1 步：创建脚本

编写要在接收设备上运行的 shell 脚本。脚本以 root 身份运行，因此具有对设备文件系统的完全访问权限。

使用脚本的退出代码向 Raspberry Pi Connect 报告更新结果：

0：更新成功。
1：更新失败。
2：更新成功，设备必须重新启动才能完成应用。

例如，以下脚本（保存为 aptupgradescript）会升级接收设备上安装的所有软件包，并在有升级的软件包需要重启时重启设备：

#!/bin/sh
export DEBIAN_FRONTEND=noninteractive
if ! apt update; then
    echo Package index update failed
    exit 1 # EXIT_FAILURE
fi
if apt -y -o DPKG::Options::="--force-confnew" upgrade > output.txt 2>&1; then
    if [ -r /var/run/reboot-required ]; then
        echo Rebooting to finish the upgrade
        exit 2 # EXIT_REBOOT
    fi
else
    echo Upgrade failed:
    echo
    cat output.txt
    exit 1 # EXIT_FAILURE
fi
echo Upgrade complete
exit 0 # EXIT_SUCCESS

脚本打印到标准输出或标准错误的任何内容都会记录在接收设备的 systemd 日志中，您可以在部署后查看以验证更新或诊断故障。示例脚本将 apt 的输出捕获到文件中，并仅在升级失败时打印，因此成功运行时只记录 Upgrade complete。

第 2 步：创建清单

接下来，创建一个描述工件及其包含的负载的 YAML 清单。

以下清单（保存为 aptupgrade.yaml）打包了第 1 步中的脚本：

# Run apt upgrade on a remote device
artefact:
  name: aptupgrade
  version: 1.0
  device_type: rpi

payloads:
- name: aptupgradescript
  type: script

artefact 部分为工件命名并设置版本。payloads 部分列出要打包的文件：每个负载的 name 是运行 otamaker 时所在目录中的文件名，type 为 script 表示接收设备应执行该文件。要打包其他目录中的文件，请在负载名称后添加路径作为注释，例如 - name: aptupgradescript # scripts/aptupgradescript。

第 3 步：构建工件

通过将清单传递给 otamaker 来构建工件：

otamaker aptupgrade.yaml

这会创建一个 Zstandard 压缩的更新工件（.tar.zst 文件），其中包含清单和脚本，并输出工件的 SHA-256 校验和。

记下校验和：从 Raspberry Pi Connect 网站部署工件时需要用到。

第 4 步：部署工件

部署脚本工件的方式与其他任何更新工件相同：选择接收设备并将 .tar.zst 文件上传到该设备，具体说明见部署更新工件。

如果接收设备属于组织，请先托管工件，然后使用其 URI 和校验和进行部署，具体说明见在组织中部署远程更新。你可以跳过计算校验和的步骤：otamaker 在构建工件时已经输出了校验和。

第 5 步：验证更新

当部署显示为 Succeeded 时，使用 Raspberry Pi Connect 连接到接收设备，并在 systemd 日志中查看脚本输出：

journalctl -t rpi-ota-connector

组织版 Connect

Connect for Organisations 支持多名用户使用 Raspberry Pi Connect 共享设备访问权限。组织中的设备支持 Connect 的所有功能，包括屏幕共享、远程 shell 访问和远程更新。创建首个组织即可自动开始为期四周的免费试用。

更多信息请参阅 Connect for Organisations。

故障排除

已知问题

Connect 仅支持共享 Raspberry Pi 的单个主显示屏。当 Raspberry Pi 连接到多个 HDMI 屏幕时，Connect 有时会共享副屏幕的内容。您可以右键单击桌面，在 桌面偏好设置... 中更改任务栏的位置来解决这个问题。
Connect 需要使用实现 ECMAScript 2022 (ES13) 的浏览器，因为它使用了旧版浏览器无法使用的功能。
浏览器会拦截某些按键和按键组合。因此，您无法在 Connect 窗口中输入这些按键。Connect 提供了一个工具栏来模拟一些最常用的拦截键。
不支持使用 Connect 的远程 shell 升级 rpi-connect 和 rpi-connect-lite 。升级过程将终止所有远程 shell 会话并放弃所有连接。要在远程 shell 会话中升级 Connect，请使用 screen 或 tmux 等工具，以确保连接关闭后升级过程不会中断。
要从版本 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（此版本的 rpi-connect 支持屏幕共享）
✓ Wayland compositor available （Wayland 合成器可用）
✓ Screen sharing services enabled and active （屏幕共享服务已启用并处于活动状态）
✓ Communication with Raspberry Pi Connect WebSocket server （与 Raspberry Pi Connect WebSocket 服务器通信）
✓ Communication with Raspberry Pi Connect API （与 Raspberry Pi Connect API 通信）
✓ Authentication with Raspberry Pi Connect API （使用 Raspberry Pi Connect API 进行身份验证）
✓ Peer-to-peer connection candidate via STUN （通过 STUN 候选点对点连接）
✓ Peer-to-peer connection candidate via TURN （通过 TURN 进行点对点连接的候选程序）

如果出现问题，您将看到类似下面的内容：

Screen sharing is supported by this version of rpi-connect （此版本的 rpi-connect 支持屏幕共享）
✓ Wayland compositor available （可用的 Wayland 合成器）
✗ Screen sharing services enabled and active - Please run rpi-connect on to enable and start all required services （屏幕共享服务已启用并处于活动状态 - 请运行 rpi-connect 以启用并启动所有必需的服务）
✓ Communication with Raspberry Pi Connect WebSocket server （与 Raspberry Pi Connect WebSocket 服务器通信）
✓ Communication with Raspberry Pi Connect API （与 Raspberry Pi Connect API 通信）
✓ Authentication with Raspberry Pi Connect API （使用 Raspberry Pi Connect API 进行身份验证）
✓ Peer-to-peer connection candidate via STUN （通过 STUN 候选点对点连接）
✓ Peer-to-peer connection candidate via TURN （通过 TURN 进行点对点连接的候选程序）

✗ Some checks failed （某些检查失败）

如果在尝试运行 Connect 所需服务时反复出现问题，请运行以下命令详细检查它们的状态：

systemctl --user status rpi-connect-wayvnc.service
journalctl --follow --user-unit rpi-connect-wayvnc.service

如果服务无法启动或不存在，请确保您的环境符合以下条件：

使用 rpi-connect 1.1.0 或更高版本。
未使用不支持屏幕共享的 rpi-connect-lite。
您使用的是 Wayland 合成器，如 wayfire 或 labwc，而非 X。您可以通过 raspi-config 的高级选项控制此设置。
使用 WayVNC 支持的桌面环境，如 Raspberry Pi Desktop。例如，使用 KDE 会将 Wayland 合成器切换为 kwin，而后者是不支持的。
您有一个活动的图形桌面会话，与您登录的用户相同。对于大多数人来说，这意味着要通过 raspi-config 的系统选项启用 Desktop Autologin。

重启或结束 SSH 会话后无法连接

Connect 以用户级服务的形式运行，因此只有在用户登录服务的会话处于活动状态时才能使用。如果您希望在不运行另一个登录会话的情况下进行远程 shell 访问，请为您的用户使用启用用户登录，这将使 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 WebSocket server
✓ 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 与 ws.connect.raspberrypi.com 的 443 端口向 Raspberry Pi Connect API 与 WebSocket 服务发送 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
- turn3.raspberrypi.com
通过 UDP 端口 3478、443 或 49152 -> 65535 向树莓派连接 TURN 服务器发出以下所有请求：
- turn1.raspberrypi.com
- turn2.raspberrypi.com
- turn3.raspberrypi.com

远程更新失败

如果 A/B 启动配置或远程更新过程失败，请参阅以下常见故障及修复方案列表。

你也可以参阅 rpi-image-gen 文档，或访问树莓派故障排除论坛。

提示

如果看到错误，可以使用 Raspberry Pi Connect 的远程 shell 访问查看 systemd 日志以获取更多信息：

journalctl

错误	建议修复方案
`Download could not connect to server (retry).`（下载无法连接到服务器（重试中）。）	接收设备必须能够找到更新文件。打开到接收设备的远程 shell 连接，然后使用 curl 检查设备是否能访问创建部署时提供的 URI 中的 IP 地址：`curl -I http://192.168.0.1:8080`
`update file rejected.`（更新文件被拒绝。）	确保创建部署时提供的 URI 包含 `.tar.zst` 更新文件的 URL，而不是 `.img` 完整镜像文件。
Raspberry Pi Connect 中设备旁边未显示部署选项	使用以下命令启用 OTA 选择加入，然后刷新浏览器：`rpi-connect ota on`

查看连接状态

要查看 Connect 服务的当前状态，请运行以下命令：

rpi-connect status

您应该会看到与下面类似的输出：

Signed in: yes
Subscribed to events: yes
Screen sharing: allowed (0 sessions active)
Remote shell: allowed (0 sessions active)

此命令的输出会显示您当前是否已登录 Connect，以及 Raspberry Pi 上已启用的远程服务。

如果看到的输出包括 "Raspberry Pi Connect is not running, run rpi-connect on"（Raspberry Pi 连接未运行，请运行 rpi-connect on），请运行 rpi-connect on 启动连接。

启用增强日志记录

你可以启用 rpi-connect 及其专用 WayVNC 服务器的调试日志，以详细记录 Raspberry Pi 上的本地操作。

在`rpi-connect`中启用增强日志功能

将环境变量 RPI_CONNECT_VERBOSE=1 添加到 /etc/default/rpi-connect，然后使用以下命令重启Connect：

rpi-connect restart

或者，对于2.7之前的版本，使用以下命令覆盖 rpi-connect 服务定义：

systemctl --user edit rpi-connect

在注释之间输入以下配置行：

[Service]
ExecStart=
ExecStart=/usr/bin/rpi-connectd -socket %t/rpi-connect-wayvnc.sock -v

提示

您需要以 "ExecStart="开头的两行。

最后，使用以下命令重启 Connect：

rpi-connect restart

在专用 wayvnc 服务器中启用增强日志记录功能

使用以下命令覆盖 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

提示

您需要以 "ExecStart="开头 的两行 都需要。

最后，使用以下命令重启 Connect：

rpi-connect restart

查看 Connect 日志

要查看 Connect 服务及其专用 WayVNC 服务器的日志，请运行以下命令：

journalctl --follow --user-unit rpi-connect.service --user-unit rpi-connect-wayvnc.service

安全性

树莓派设备与用户浏览器之间的所有连接均采用 WebRTC：这与 Zoom、Microsoft Teams 和 Google Meet 所使用的实时通信技术相同。

端到端加密

树莓派设备与用户浏览器之间的所有屏幕共享和远程 shell 访问流量均使用 DTLS 加密。我们不会（也无法）解密这些流量，从而确保您的数据保持私密。

每次屏幕共享和远程 shell 会话都会使用一个新的 WebRTC 对等连接。对于每个连接，树莓派设备上的 Connect 客户端会在内存中生成一对全新的公钥和私钥，您的浏览器也会生成自己的一对密钥。设备绝不会将其私钥写入磁盘或发送到任何地方，并会在会话结束时丢弃该私钥。设备与浏览器交换公钥，并在二者之间直接进行的握手中派生出用于加密会话的密钥，因此我们的服务器无法派生出这些密钥。经过我们 API 的唯一与密钥相关的信息是每个公共证书的指纹，而该指纹无法用于解密。

会话中的所有内容都通过这一条加密通道传输：屏幕帧、键盘和鼠标输入、剪贴板数据、远程 shell 的输入输出，以及您在会话期间输入的任何凭据。这些内容都不会经过我们的 API。API 只交换建立连接所需的信息，并接收设备状态，例如设备是否在线、是否启用了屏幕共享以及活动会话的数量。

此外，流量大多是点对点的，这意味着加密流量不经过我们的基础设施，而是直接在您的树莓派设备与浏览器之间传输。这使我们无法观测这些流量。

中继服务器

在无法建立直接点对点连接的情况下（例如由于网络问题），只有加密数据会通过我们的某台 TURN 服务器中继。这些服务器托管在伦敦和加利福尼亚。只有您的设备和浏览器持有解密这些数据的密钥，且数据既不会被记录也不会被存储。

Connect 会依据设备和浏览器各自 IP 地址所在的洲，分别为它们选择中继。位于欧洲和非洲的设备与浏览器使用伦敦的中继；位于美洲、亚洲和大洋洲的则使用加利福尼亚的中继。如果无法确定位置，则使用伦敦。如果您的设备和浏览器被分配到不同的中继，会话可以通过其中任一或两者进行中继。

Connect 没有用于限制使用哪些中继或禁用中继的设置。如果您只要求直接的点对点连接，可以封禁网络和防火墙问题中列出的 TURN 服务器的流量。此后，Connect 只能在能够彼此直接访问的设备和浏览器之间工作。

连接建立

树莓派 Connect API 会临时存储协商连接所需的 WebRTC offer 与 answer，其中包括您设备和浏览器的 IP 地址与端口。发往该 API 的所有流量均使用 HTTP over TLS 加密，出于安全考虑仅支持 TLS 1.2 及更高版本。这确保连接信息绝不会以明文形式发送。此类元数据最多安全存储 1 分钟。

来自您浏览器的 offer 会按原样存储，绝不会被解析或改写。只有代表已登录用户运行的 Connect Web 应用程序才能创建 offer；设备不能。

会话只能由满足以下条件的用户启动：该用户使用拥有该设备、或拥有该设备所属组织的 Raspberry Pi ID 登录，并且已在此前一小时内通过 Raspberry Pi ID 完成身份验证。

数据保留

Connect 只保留运行服务所需的元数据。

数据	保留时间
IP 地址	不存储。IP 地址仅在内存中用于选择最近的中继和进行速率限制，并在新设备关联时随通知邮件发送一次。审计日志事件仅存储由 IP 地址推导出的两位国家代码。
连接建立信息（WebRTC offer 与 answer）	最多 1 分钟
设备心跳与状态	仅当前状态；不保留历史记录
设备数据（序列号、型号、操作系统名称与版本、架构、Connect 版本、主机名和最后在线时间）	只要设备关联到某个账户；随设备或账户一同删除
账户数据（姓名和电子邮件地址）	静态加密，在账户存续期间保留；随账户一同删除
组织审计日志，包括每次屏幕共享和远程 shell 会话的开始及其时间戳、用户、设备和国家代码	90 天

对于 Connect for Organisations 客户，我们提供审计日志以查看过去 90 天的活动。个人账户没有连接日志。

安全评估

2025 年 1 月，Cure53 的渗透测试人员和安全分析师评估了 Raspberry Pi Connect Web 应用程序与基础设施、Raspberry Pi ID，以及 Connect 客户端软件的 2.2 至 2.3 版本。您可以在 Cure53 网站上阅读完整报告。

有关 WebRTC 安全性的更多细节，请参阅《WebRTC 安全研究》。

子处理者

Raspberry Pi Ltd 使用以下第三方处理个人数据，以便提供 Connect。它们都无法访问屏幕共享或远程 shell 会话的内容，因为这些内容在您的树莓派设备与浏览器之间是端到端加密的。

子处理者	用途	个人数据	位置
Mythic Beasts Ltd	Connect 服务的托管，包括其数据库、电子邮件投递和 TURN 中继服务器	Connect 持有的所有账户和设备数据、IP 地址，以及使用中继时的加密会话流量	英国。加利福尼亚的 TURN 中继位于美国，但它只转发加密会话流量，不存储任何内容。
Cloudflare, Inc.	Connect 网站静态资源（图像、样式表和脚本）的缓存与投递	静态资源请求的 IP 地址与浏览器信息	全球边缘网络
Google LLC	分析数据仓库（Google Cloud）与产品分析（Google Analytics）	账户与设备记录（姓名和电子邮件地址保持加密），以及包含设备与会话标识符的匿名化使用事件	欧盟（数据仓库）和美国（分析）
Functional Software, Inc. (Sentry)	错误监控	技术错误报告，其中可能包含设备和组织标识符	美国
MaxMind, Inc.	新设备登录时通知邮件中所示 IP 地址的地理定位	IP 地址	美国
Stripe	Connect for Organisations 订阅的支付处理	账单联系人信息和支付信息	美国和爱尔兰
Freshworks, Inc. (Freshdesk)	客户支持	姓名、电子邮件地址以及支持请求的内容	美国

此列表最后更新于 2026 年 9 月 15 日。

中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。交流 Q群：498908352

介绍​

Connect 服务功能​

Connect 菜单​

安全与数据存储​

Connect 账户类型​

开始使用​

开启 Connect 服务并关联设备​

安全最佳实践​

查看已关联的设备​

访问你的 Raspberry Pi 设备​

屏幕共享界面​

开始屏幕共享​

停止屏幕共享​

禁止和重新允许屏幕共享​

远程shell​

结束远程shell会话​

禁止和重新允许远程shell访问​

始终启用远程shell​

禁用动画图标​

管理设备​

更新​

从 Connect 中断开设备连接​

卸载​

远程更新你的设备​

部署更新工件​

监控部署​

验证部署​

A/B 启动更新​

前提条件​

创建 A/B 启动配置和更新工件（使用 rpi-image-gen）需要：​

配置接收设备进行 A/B 启动需要：​

接收更新工件的设备需要：​

实施 A/B 启动并远程更新首个镜像​

第一阶段：创建 A/B 启动配置​

步骤 1：安装 rpi-image-gen​

步骤 2：准备并配置镜像​

步骤 3：生成授权密钥​

步骤 4：构建 A/B 启动配置镜像​

步骤 5：写入镜像​

步骤 6：将 .img 文件部署到接收设备​

步骤 7：确认部署的版本​

第二阶段：创建更新工件​

步骤 1：更新 ota.yaml 配置​

步骤 2：构建更新​

第三阶段：远程更新​

步骤 1：将工件部署到接收设备​

步骤 2：验证更新​

脚本工件​

前提条件​

对于接收更新工件的设备：​

对于使用 otamaker 创建更新工件：​

第 1 步：创建脚本​

第 2 步：创建清单​

第 3 步：构建工件​

第 4 步：部署工件​

第 5 步：验证更新​

组织版 Connect​

故障排除​

已知问题​

常见问题​

屏幕共享不可用​

重启或结束 SSH 会话后无法连接​

网络和防火墙问题​

远程更新失败​

查看连接状态​

启用增强日志记录​

在rpi-connect中启用增强日志功能​

在专用 wayvnc 服务器中启用增强日志记录功能​

查看 Connect 日志​

安全性​

端到端加密​

中继服务器​

连接建立​

数据保留​

安全评估​

子处理者​

介绍

Connect 服务功能

Connect 菜单

安全与数据存储

Connect 账户类型

开始使用

开启 Connect 服务并关联设备

安全最佳实践

查看已关联的设备

访问你的 Raspberry Pi 设备

屏幕共享界面

开始屏幕共享

停止屏幕共享

禁止和重新允许屏幕共享

远程shell

结束远程shell会话

禁止和重新允许远程shell访问

始终启用远程shell

禁用动画图标

管理设备

更新

从 Connect 中断开设备连接

卸载

远程更新你的设备

部署更新工件

监控部署

验证部署

A/B 启动更新

前提条件

创建 A/B 启动配置和更新工件（使用 rpi-image-gen）需要：

配置接收设备进行 A/B 启动需要：

接收更新工件的设备需要：

实施 A/B 启动并远程更新首个镜像

第一阶段：创建 A/B 启动配置

步骤 1：安装 rpi-image-gen

步骤 2：准备并配置镜像

步骤 3：生成授权密钥

步骤 4：构建 A/B 启动配置镜像

步骤 5：写入镜像

步骤 6：将 `.img` 文件部署到接收设备

步骤 7：确认部署的版本

第二阶段：创建更新工件

步骤 1：更新 `ota.yaml` 配置

步骤 2：构建更新

第三阶段：远程更新

步骤 1：将工件部署到接收设备

步骤 2：验证更新

脚本工件

前提条件

对于接收更新工件的设备：

对于使用 otamaker 创建更新工件：

第 1 步：创建脚本

第 2 步：创建清单

第 3 步：构建工件

第 4 步：部署工件

第 5 步：验证更新

组织版 Connect

故障排除

已知问题

常见问题

屏幕共享不可用

重启或结束 SSH 会话后无法连接

网络和防火墙问题

远程更新失败

查看连接状态

启用增强日志记录

在`rpi-connect`中启用增强日志功能

在专用 wayvnc 服务器中启用增强日志记录功能

查看 Connect 日志

安全性

端到端加密

中继服务器

连接建立

数据保留

安全评估

子处理者