树莓派 Connect

介绍

提示

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

通过 Raspberry Pi Connect，您可以从世界任何地方安全地访问您的 Raspberry Pi。

在 Raspberry Pi OS Desktop 和 Raspberry Pi OS Full（带推荐软件的桌面版）中，Connect 默认已安装。而在 Raspberry Pi OS Lite 中，默认安装的是 Connect 的另一个 Lite 版本，该版本仅支持远程 shell 访问，不支持屏幕共享。

使用 Connect 时，请参阅 将设备与 Connect 账户关联。访问 connect.raspberrypi.com，即可在浏览器窗口中访问运行于树莓派上的桌面环境或 shell 终端。

个人 Connect 账户仅供单一用户使用。如需与多位用户共享设备访问权限（例如团队或企业场景），请升级至 Connect for Organisations。创建首个组织即可自动开始为期四周的免费试用。

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

提示

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

手动启动和停止 Connect

您可以在桌面或命令行中开启或关闭 Connect：

桌面

要开启 Connect：

从菜单栏中的 Connect 图标中，选择 开启 Raspberry Pi Connect。

如果您尚未使用 Raspberry Pi ID 登录，系统将自动打开浏览器并提示您立即登录。登录后，您的 Raspberry Pi 便会与您的 Connect 账户关联。

要关闭 Connect：

从菜单栏中的 Connect 图标中，选择 关闭 Raspberry Pi Connect。

这将停止 Connect 的运行。

命令行

要开启 Connect，请运行以下命令：

rpi-connect on

要停止 Connect，请运行以下命令：

rpi-connect off

将 Raspberry Pi 设备与 Connect 账户连接起来

在树莓派设备上启动 Connect 后，您必须将设备与 Connect 账户关联。

若您使用树莓派映像工具在设备上安装树莓派操作系统，则可能已完成设备与 Connect 账户的绑定。更多信息请参阅 使用映像工具安装。

桌面

从菜单栏的"连接"图标中，选择开启树莓派连接。这将打开您的浏览器，系统会提示您使用树莓派ID登录：

若您已开启Connect功能，请从下拉菜单中选择登录...：

若您尚未拥有树莓派ID，请选择免费创建以创建一个。

终端

使用以下命令生成一个链接，将设备连接到 Connect 帐户：

rpi-connect signin

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

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

要将您的设备与Connect账户关联，请在任意设备上访问验证网址，并使用您的树莓派ID登录。

使用授权密钥

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

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

提示

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

提示

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

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

若以字符串形式提供密钥，请执行以下命令：

rpi-connect signin --auth-key=rpuak_123456

若将密钥保存至文件，可通过在路径前添加 @ 符号传递完整路径：

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

若将认证密钥保存至用户主目录下的 .config/com.raspberrypi.connect/auth.key，Connect 将自动检测到该文件。

完成连接您的 Raspberry Pi

完成身份验证后，为您的设备命名。请选择一个能唯一标识该设备的名称。

若您是 组织 的管理员，请选择将此设备添加至个人账户或特定组织。

点击创建设备并登录按钮继续。

您现在可以远程连接至您的设备。菜单栏中的 Connect 图标将变为蓝色，表示您的设备已登录 Connect 服务。您应收到一封电子邮件通知，告知有新设备已关联至您的Connect账户。

注意

若收到邮件提示有未知设备登录Connect，请立即更改树莓派ID密码。请按照 从Connect移除设备 中的说明操作，永久解除该设备与您账户的关联。建议启用 启用双因素身份验证 以保障账户安全。

通过选择菜单栏中的 Connect 图标打开 Connect 菜单。该菜单允许您开启或关闭 Connect 功能、进行登录或注销操作，以及允许或禁止远程访问方式。

提示

Connect 使用设备序列号登录通信。在设备之间移动 SD 卡将会退出 Connect。

访问你的 Raspberry Pi 设备

现在，您的设备已显示在 Connect 控制面板上，您只需使用浏览器即可随时随地访问您的设备。Connect 提供多种远程与设备交互的方式。

查看设备

Connect 在设备选项卡上列出所有关联的设备。对于组织用户，您可以按设备名称搜索此列表，或按设备特征进行过滤。

登录 connect.raspberrypi.com 并转到设备选项卡。Connect 将显示关联设备的列表。

（仅限组织版 Connect）要按设备名称搜索，请在搜索字段中输入文本。Connect 会在您输入时匹配结果。

（仅限组织版 Connect）要过滤设备列表，请选择过滤器并从可用的过滤选项中进行选择。您可以按设备型号、内存容量或已安装的操作系统过滤设备。

此功能仅适用于运行客户端版本 2.9.0 或更高版本的设备。要更新设备上的 Connect，请参阅更新。

每个设备可用的连接方式显示为设备名称下方的灰色徽章。您可以通过以下方式连接到设备：

• 屏幕共享
• 远程 shell

屏幕共享

Connect 包括在浏览器中共享设备屏幕的功能。使用以下说明共享设备屏幕。

提示

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

在任何电脑上访问 connect.raspberrypi.com。

Connect 会将您重定向到 Raspberry Pi ID 服务以登录。登录后，Connect 会显示链接设备的列表。可进行屏幕共享的设备名称下方会显示一个灰色的Screen sharing徽章。

选择您要访问的设备右侧的Connect via按钮。从菜单中选择Screen sharing选项。这将打开一个浏览器窗口，显示您设备的桌面。

现在你可以像在本地一样使用设备了。有关连接的更多信息，请将鼠标悬停在Disconnect按钮右侧的挂锁图标上。

提示

使用桌面上方的Copy from remote和Paste to remote按钮，在本地和远程剪贴板之间传输文本。

连接后，连接仪表板中的Screen sharing徽章旁边会出现一个绿点。这表示正在进行屏幕共享会话。鼠标悬停可查看当前屏幕共享会话的数量。

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

屏幕共享界面

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

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

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

禁止屏幕共享

要关闭屏幕共享会话，请选择桌面上方的Disconnect按钮。

禁止屏幕共享

要关闭屏幕共享功能，请在菜单栏中选择 Connect 图标，然后取消勾选 允许屏幕共享。您的设备仍保持登录 Connect 的状态，但无法通过 Connect 控制面板创建屏幕共享会话。

您也可以使用以下命令禁止屏幕共享：

rpi-connect vnc off

在连接仪表板中，Screen sharing徽章和Connect via连接菜单中的Screen sharing选项将被划掉。

要重新启用屏幕共享，请执行以下操作之一：

• 在菜单栏中选择 Connect 图标，然后选择允许屏幕共享
• 运行以下命令

rpi-connect vnc on

远程shell

Connect 包括从浏览器启动在设备上运行的 shell 的功能。使用以下说明访问远程 shell。

登录 connect.raspberrypi.com 并转到设备选项卡。

可用于远程 shell 访问的设备会在设备名称下方显示一个灰色的 Remote shell 徽标。

选择要访问的设备右侧的 Connect via 按钮。从菜单中选择 Remote shell 选项。这将在设备上打开一个 shell 会话。

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

提示

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

连接后，连接仪表板中的Remote shell徽章旁边会出现一个绿点。这表示远程 shell 会话处于活动状态。鼠标悬停可查看当前远程 shell 会话的数量。

提示

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

菜单栏中的 Connect 图标在远程shell会话进行时会旋转。每次启动远程shell会话时，都会出现桌面通知。

提示

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

结束远程shell会话

要关闭远程 shell 会话，请运行 exit 命令或关闭窗口。

禁止远程shell访问

要关闭远程shell访问功能，请在菜单栏中选择 Connect 图标，然后取消勾选允许远程shell访问选项。您的设备仍将保持登录Connect的状态，但无法通过Connect控制面板创建远程shell会话。

或者，也可以使用以下命令禁止远程 shell 访问：

rpi-connect shell off

在 Connect 面板中，Remote shell 徽标和Connect via 菜单中的Remote shell 选项将被划掉。

要重新启用远程 shell 访问，请执行以下操作之一

• 单击 "连接 "系统托盘图标并选择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 面板的设备列表中删除设备。

远程更新你的树莓派设备

Raspberry Pi Connect 具备远程推送更新至树莓派设备的能力。

远程更新适用于更新防火墙后的设备、离线设备（将在下次登录 Connect 时接收更新）以及地理位置偏远或难以接触的设备。

如果你是管理设备团队的用户，Connect for Organisations 的管理员还可以使用管理 API 自动管理更新构件和部署。

A/B 启动更新

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

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

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

使用 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 命令行工具）的未来需求决定。

托管构件进行远程部署需要：

• 一台可从接收设备访问的 Web 服务器。

  远程更新支持 HTTP、HTTPS、FTP、SFTP 和文件 URI。

  该位置无需对互联网开放，但必须可从接收更新信号的树莓派设备访问。

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

• Raspberry Pi 4 或更高版本，需满足：
  • 已连接互联网。
  • 已开启 OTA 更新。
  • 已在 Connect 中注册，并带有已关联的远程更新构件。

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

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

1. 第一阶段：为接收设备（Raspberry Pi 4 及更高版本）准备远程更新，创建 A/B 启动文件，然后部署到设备。
2. 第二阶段：创建用于部署到接收设备的更新构件文件。
3. 第三阶段：托管更新构件并在 Raspberry Pi Connect 网站上注册。
4. 第四阶段：使用 Raspberry Pi Connect 的远程更新功能选择接收设备，然后将更新构件部署到该设备。

第一阶段：创建 A/B 启动 .img 文件

标准 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 或更高版本。

步骤 1：安装 rpi-image-gen

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

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

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

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

步骤 2：准备并配置镜像

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

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

准备镜像：

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

步骤 3：生成授权密钥

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

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

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

生成授权密钥：

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

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

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

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

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

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

cd rpi-image-gen

2. 运行以下命令，将 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）启动时使用。注意不要覆盖操作系统。

写入镜像：

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

sudo apt install rpi-imager

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

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

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

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

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

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

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

步骤 7：确认部署的版本

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

确认部署的镜像版本：

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

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 配置

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

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

步骤 2：构建更新

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

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

第三阶段：托管更新构件

现在你已创建了要通过 Raspberry Pi Connect 部署的更新构件，可以将其托管在 FTP/SFTP 服务器上、使用 file:// URI 本地保存、放在公共 Web 服务器、S3 存储桶或接收设备可通过 HTTP 下载的任何其他网站上。

接下来，在 Raspberry Pi Connect 中注册 URI 和 SHA-256 校验和。这样 Connect 就能告诉在第四阶段中选择的设备在哪里找到更新文件。

你提供的 URI 用于查找更新构件并将其推送至接收设备。因此，该位置必须可供接收设备访问，但无需对 Raspberry Pi Connect 服务器开放。

示例 URI：http://192.168.0.1:8080/path/to/update.tar.zst

其中包含以下必要信息：

• 主机 IP：192.168.0.1
• 端口：8080
• 路径：/path/to/update.tar.zst

以下步骤演示如何从与树莓派接收设备位于同一网络的树莓派主机上提供更新构件。

托管更新构件：

步骤 1：在主机设备上运行 HTTP 服务器

1. 在终端中运行以下命令创建服务器并托管更新构件（相应更改构件镜像目录）：

python -m http.server 8080 --directory ./work/image-myapp-1.1.0

步骤 2：计算更新文件的 SHA-256 校验和

接下来，提供构件的 SHA-256 校验和以确保其未被损坏或篡改，同时提供主机 IP 地址以便在第四阶段发送到接收设备。

查找校验和和 IP 地址：

1. 在终端中运行以下命令：

sha256sum ./work/image-myapp-1.1.0/update.tar.zst

2. 复制下校验和。

步骤 3：查找主机在本地网络上的 IP 地址

你必须提供更新构件的 URI，其中包含主机 IP 地址。

查找 IP 地址：

1. 在终端中运行以下命令：

hostname -I

2. 复制下 IP 地址。

步骤 4：在 Raspberry Pi Connect 网站上注册构件

现在你已经托管了更新构件，并复制了 IP 地址和校验和，在 Raspberry Pi Connect 网站 上注册这些详细信息。

要注册更新构件，请按照以下步骤操作，或者如果你想一次性完成注册和选择接收设备，请直接跳转到第四阶段步骤 1。

对于个人设备：

1. 登录 Raspberry Pi Connect。
2. 从右上角的账户切换器中选择你的组织或个人账户。
3. 前往远程更新选项卡，然后选择新建。
4. 输入构件名称，然后粘贴 URI 和 SHA-256（来自步骤 2 和步骤 3）。

第四阶段：远程更新

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

使用 Raspberry Pi Connect 网站选择将更新构件部署到哪台设备，因此在继续之前，请确保接收设备已注册到你的个人或组织账户。

注意：构件一旦部署或尝试部署后便无法删除。这是为了在账户遭到入侵时提供可追溯性。

步骤 1：选择接收设备并部署构件

1. 登录 Raspberry Pi Connect。
2. 使用右上角的账户切换器，选择接收设备注册的个人或组织账户。
3. 前往设备选项卡，然后选择接收设备。

4. 选择部署。

5. 如果你的远程更新选项卡中已有注册的更新构件，选择以下选项之一，否则选择新建：

   • 现有：从下拉列表中选择部署构件，然后选择部署。
   • 新建：按照上述第三阶段的步骤创建新的更新构件，然后选择创建并部署。

   刷新浏览器以查看部署更新。进度依次为待处理、进行中，最终为成功。

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

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

步骤 2：验证更新

当部署显示为成功时，验证更新。

验证更新：

1. 登录 Raspberry Pi Connect。
2. 从右上角的账户切换器中选择你的组织或个人账户。
3. 选择设备选项卡。
4. 找到你刚刚更新的接收设备，然后选择连接。
5. 在命令行中输入：

cat /etc/rpi-issue

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

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

Otamaker

待编写。

组织版 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...

远程更新失败

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

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

常见问题

屏幕共享不可用

如果 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

查看连接状态

要查看 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在树莓派设备与用户浏览器端进行加密。我们不会（也无法）解密这些流量，确保您的数据始终保持私密性。

此外，流量主要采用点对点传输模式，即加密数据不会经过我们的基础设施。加密流量直接在您的树莓派设备与浏览器之间传输，使我们无法进行监视。

当直接点对点连接不可行时（例如网络故障），加密数据将通过我们的TURN服务器中转。这些服务器部署于伦敦和加利福尼亚，您的流量将被路由至距离最近的中继节点。我们既不持有解密密钥，也不会记录或存储这些数据。

树莓派连接API会临时存储建立点对点连接所需的IP地址和端口。所有访问该API的流量均通过HTTP over TLS加密传输，出于安全考虑仅支持TLS 1.2及更高版本协议。这确保连接信息绝不会以明文形式发送。此类元数据最多安全存储1分钟，并在连接建立后立即删除。

树莓派连接及其API与软件组件已通过Cure53的安全渗透测试与安全分析师评估。您可以在 Cure53 网站上阅读完整报告。

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

针对 Connect for Organisations 客户，我们提供可追溯过去90天活动的审计日志。为保护隐私，通过IP地址进行地理定位时，我们仅存储国家代码。

---

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