树莓派 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 会在 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 界面，显示‘开启 Raspberry Pi Connect’下拉菜单选项。

要关闭 Connect：

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

这将停止 Connect 的运行。

Connect 界面，显示'关闭 Raspberry Pi Connect'下拉菜单选项。

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

rpi-connect on

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

rpi-connect off

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

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

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

桌面
终端
使用授权密钥

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

Connect页面会提示您使用 Raspberry Pi ID 登录 Connect。

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

Connect页面，显示从 Raspberry Pi Connect 下拉菜单中选中的登录选项

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

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

rpi-connect signin

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

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

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

授权密钥是一种一次性临时令牌，可让您自动将设备与Connect账户关联（无需使用网页界面）。

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

提示

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

tip: Raspberry Pi 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）要按设备名称搜索，请在搜索字段中输入文本。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。

可用于远程 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 面板的设备列表中删除设备。

组织版 Connect

组织版 Connect 支持多名用户共享设备访问权限。创建组织后，该组织将自动启动为期四周的免费试用。

创建组织

创建新组织时，请先登录您的 Raspberry Pi Connect 账户，然后点击导航菜单左上角的账户切换图标。

选择新建组织并输入名称，点击开始免费试用。您的Connect账户将自动加入该组织并成为管理员。

如果您的个人账户中已有关联的设备，可以将它们全部转移到刚创建的组织。操作步骤：

在提示中选择*将它们全部转移到此组织？*链接。
选择转移 x 台设备（其中"x"为设备数量），确认将计费设备添加到组织账户。

管理用户

您必须是管理员才能邀请用户加入、从组织中移除用户或更改用户在组织中的角色。

邀请用户的步骤：

登录您的 Raspberry Pi Connect 账户。
点击导航菜单左上角的账户切换图标（两个相对的箭头），然后从列表中选择您的组织。
选择页面顶部的用户选项卡，然后点击邀请他人。
从下拉菜单中选择角色。

组织成员可选两种角色：
- 成员：可远程访问组织内所有设备，但无法对组织进行任何修改。
- 管理员：可远程访问组织内所有设备并修改组织设置。该角色还将接收涉及敏感操作的全局通知邮件，例如新增设备或新的管理 API 访问令牌。
输入您要发送邀请的邮箱地址。
选择发送邀请。

邀请邮件会发送至您在第 5 步提供的邮箱地址。用户可通过邮件中的邀请链接加入，并可使用该邮箱或任何有效的 Raspberry Pi ID 登录。

移除用户的步骤：

登录您的 Raspberry Pi Connect 账户。
点击导航菜单左上角的账户切换图标（两个相对的箭头），然后从列表中选择您的组织。
选择页面顶部的用户选项卡。

此处会显示组织的所有成员。
在要移除的用户旁边，点击更多选项图标（三个垂直排列的点），然后选择移除...。

弹出确认窗口。
如果您确认要移除该用户，请选择移除用户。

该用户会立即从组织中移除，其与贵组织的 shell 与屏幕共享会话会在几分钟内终止。

更改用户角色的步骤：

登录您的 Raspberry Pi Connect 账户。
点击导航菜单左上角的账户切换图标（两个相对的箭头），然后从列表中选择您的组织。
选择页面顶部的用户选项卡。

此处会显示组织的所有成员。
在要更改角色的用户旁边，点击更多选项图标（三个垂直排列的点），然后选择更改角色...。
从下拉菜单中为该用户选择要分配的角色，然后选择更改角色。

用户角色已更改，并显示确认页面。

将树莓派设备关联至组织

仅管理员可将设备关联至组织。操作步骤：

若设备未关联Connect账户，请参阅将树莓派设备关联至Connect账户。
若设备已关联Connect账户，请参阅转移设备。

转移设备

您必须是管理员才能在账户间转移设备。操作步骤如下：

点击导航菜单左上角的账户切换图标。
切换至当前拥有该设备的账户（个人账户或组织账户）。.
选择需要转移的设备。.
在设备页面右上角打开设置下拉菜单。
选择转移...
选择目标接收账户。
点击转移。

标记设备

标签帮助您对组织中的设备进行分类和查找。例如，您可以按位置（london、leeds）、环境（production、staging）或功能（point-of-sale、kiosk）对设备打标签。

标签会显示在设备页面和设备列表中设备名称下方。

您必须是管理员才能添加或移除标签。

要为设备添加或移除标签：

从设备列表中选择设备。
从设备页面右上角打开设置下拉菜单。
选择编辑标签...
- 要添加标签，请在文本框中输入。您可以从下拉菜单中选择已有标签，或输入新标签名称并选择创建选项。
- 要移除标签，请选择标签旁的 x。
完成后选择完成。

每台设备最多支持 10 个标签。标签名称不得超过 30 个字符，且只能包含小写字母、数字、连字符和下划线。

设备列表顶部的搜索栏让您可以结合自由文本搜索和结构化筛选查找设备。

要按设备名称或序列号搜索，在搜索栏中输入任意文本。结果会随输入自动更新。

要按特定属性筛选，输入限定符后跟冒号和值。可用的限定符有：

限定符	说明
`model:`	按树莓派型号筛选（例如 `model:5`、`model:4b`）
`memory:`	按 RAM 大小筛选（例如 `memory:4gb`、`memory:512mb`）
`os:`	按操作系统筛选（例如 `os:raspios-13`）
`tag:`	按标签筛选（例如 `tag:kiosk`、`tag:production`）

备注

model:、memory: 和 os: 限定符仅能查找运行 Connect 客户端 2.9.0 及更高版本的设备。要更新设备上的 Connect，请参阅更新。

您可以在一次查询中组合多个筛选和自由文本。例如，model:5 tag:production dashboard 可查找名称中带有 "dashboard"、标签为 production 的树莓派 5 设备。

当您开始在搜索栏中输入时，下拉菜单会建议可用的限定符和值。从下拉菜单中选择一个限定符可查看其可用值，然后选择一个值将其作为筛选添加。已应用的筛选会显示在搜索栏中。

要移除筛选，选择它旁边的 x 或按 Backspace。

多次使用 tag: 限定符可查找同时具有所有指定标签的设备。例如，tag:production tag:kiosk 仅返回同时具有 production 和 kiosk 标签的设备。

提示

在列表中任何设备上选择标签可快速将其添加为筛选。

设置订阅服务

组织版Connect订阅将在四周试用期结束后自动生效，此后按月延后计费。

仅管理员可设置订阅。操作步骤：

点击页面顶部标签栏下方试用横幅中的设置计费.
输入用于接收账单通知（如发票）的邮箱地址.
填写支付方式信息并提交
- 若试用期未结束，按钮显示为开始试用 试用期将延续，之后按月计费。
- 若试用期已结束，按钮显示为支付并订阅。此操作将启动月度订阅。

免费试用结束后，若未设置订阅，您将无法远程访问组织内的设备。

查看审计日志

审计日志按时间顺序显示过去90天内的所有活动，最新事件优先显示。事件包括设备变更、组织成员变更、API访问令牌变更以及远程访问会话等。超过90天的事件将自动删除。

仅管理员可查看组织过去90天的活动记录。要查看审计日志，请打开页面顶部的审计日志选项卡。

列表中的每个事件包含以下信息：

时间戳：事件发生的时间。
来源：事件发生于仪表板还是通过API触发。
操作：具体操作（例如API访问令牌创建）及相关细节。
对象：操作涉及的对象，如特定设备、组织或访问令牌。
执行者：执行事件的用户，包含事件发生所在国家/地区。

您可按操作类型（如远程shell会话启动）筛选事件。筛选列表时，请点击列表左上角筛选器旁的操作下拉菜单。

点击列表右上角的下载CSV即可下载事件列表的CSV格式文件。

修改组织设置

组织管理员可在页面顶部的设置选项卡中配置以下内容。

重命名组织

若需更改组织名称，请在常规部分输入新名称。此操作不会影响您的设备或组织成员。

要求双因素认证

您可以要求组织的所有成员在其 Raspberry Pi ID 上启用双因素认证（2FA）。这能为贵组织设备的访问增加一层保护，防止成员账户被泄露后被用于访问组织设备。

启用 2FA 要求的步骤：

登录 Raspberry Pi Connect。
在左上角的账户切换图标中选择您的组织账户。
选择设置选项卡，然后选择要求双因素认证。

页面会显示通知，确认组织设置已成功更新。

这会启动 14 天的宽限期。在宽限期内，我们会向尚未启用 2FA 的组织成员显示横幅。

宽限期结束后，仍未启用 2FA 的成员将被阻止访问贵组织。在他们启用 Raspberry Pi ID 的 2FA 之前，他们将无法访问组织的设备或其他资源。

在宽限期结束后，面向未启用 2FA 的成员显示的双因素认证要求页面，并包含启用 Raspberry Pi ID 2FA 的链接。

禁用 2FA 要求的步骤：

登录 Raspberry Pi Connect。
在左上角的账户切换图标中选择您的组织账户。
选择设置选项卡，然后选择停止要求双因素认证。

页面会显示通知，确认组织设置已成功更新。

备注

禁用后再重新启用 2FA 要求会重置 14 天宽限期。

创建授权密钥

若需通过 Connect 自动关联设备（无需网页界面）进行操作，请创建授权密钥。在授权密钥区域选择新建，填写描述及有效期（以天为单位）。

新认证密钥将显示。点击其旁的剪贴板图标即可复制。请立即复制此密钥，后续将无法再次查看。

重要提示：认证密钥仅显示一次。请立即复制，后续将无法再次查看。

创建管理API访问令牌

若需自动生成授权密钥（无需网页界面）以连接设备至Connect，可创建 Connect for Organisations管理API 的API访问令牌。在API访问令牌区域选择新建，并输入令牌描述。

新访问令牌将显示。点击其旁的剪贴板图标进行复制。请立即复制此令牌，后续将无法再次查看。

重要提示：访问令牌仅显示一次。请立即复制，后续将无法再次查看。

管理API

管理API支持您无需Connect网页界面即可自动管理组织。向管理API发送请求时，必须使用有效的管理API访问令牌进行身份验证。基础URL为 https://api.connect.raspberrypi.com。

创建设备身份

设备身份（Device identities）让您无需交互式登录即可预先将树莓派设备认证到组织。与授权密钥不同，设备身份可多次使用，并依赖存储在设备一次性可编程内存中的私钥。

创建设备身份是免费的。您仅在设备首次通过认证连接到组织的 Connect 账户时开始计费，这使得设备身份非常适合在部署前预配置 Connect 的组织场景。

请求必须包含 X-Connect-Identity-Signature 标头。要生成该标头，请构造一个以换行分隔的有效载荷，按顺序包含：

HTTP 请求方法（例如 POST）
完整的请求 URL
Authorization: <值>
Content-Type: <值>
Accept: <值>（如果您的 HTTP 客户端会发送此标头）
HTTP 请求正文的 SHA256 十六进制摘要（下面 POST 所示的 JSON 请求正文）

使用设备的私钥，以 ECDSA with SHA256 对此有效载荷进行签名，然后进行 Base64 编码。

例如，一个注册设备身份的请求会产生以下有效载荷：

POST
https://api.connect.raspberrypi.com/organisation/device-identities
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json
Accept: */*
<HTTP 请求正文的 SHA256 十六进制摘要>

在设备上，使用 rpi-fw-crypto 对有效载荷进行签名。例如，将有效载荷写入 payload.txt 后：

rpi-fw-crypto sign --in payload.txt --key-id 1 --alg ec | base64 -w 0

输出即为 X-Connect-Identity-Signature 标头的值。

要为您的组织创建设备身份，请使用管理 API 访问令牌发起以下 HTTP 请求。

请替换以下代码中的参数：

rporg_accesstokenhere：您的管理 API 访问令牌
signaturehere：此请求的 X-Connect-Identity-Signature 值
-----BEGIN PUBLIC KEY-----...：设备的 PEM 编码公钥
my-device-identity：设备身份的描述，可在组织审计日志中看到
pi5-001：交换身份时分配给设备的名称（可选，默认为设备的主机名）

POST /organisation/device-identities HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json
X-Connect-Identity-Signature: signaturehere

{
    "public_key": "-----BEGIN PUBLIC KEY-----...",
    "description": "my-device-identity",
    "device_name": "pi5-001"
}

curl 示例：

curl --header 'Authorization: Bearer rporg_accesstokenhere' --header 'X-Connect-Identity-Signature: signaturehere' --header 'Content-Type: application/json' --data '{"public_key":"-----BEGIN PUBLIC KEY-----...","description":"my-device-identity","device_name":"pi5-001"}' https://api.connect.raspberrypi.com/organisation/device-identities

若成功，您会收到 201 Created 响应，其中包含 JSON 格式的设备身份。例如：

HTTP/2 201
Content-Type: application/json; charset=utf-8

{
    "id": "096ce472-2cbd-412a-8295-6c03a1a07ba4",
    "description": "my-device-identity",
    "device_name": "pi5-001",
    "created_at": "2026-02-25T16:09:52Z",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
}

响应包含以下字段：

id：设备身份的唯一标识符。
description：用于创建设备身份的描述。
device_name：交换身份时分配给设备的名称。
created_at：创建设备身份的日期和时间（ISO 8601 格式）。
public_key：设备身份对应的 PEM 编码公钥。

如果您的管理 API 访问令牌无效，会返回 401 Unauthorized。

如果设备身份无法创建，会返回 422 Unprocessable Content 响应：

HTTP/2 422
Content-Type: application/json; charset=utf-8

{"message":"Validation failed: Public key is invalid"}

创建授权密钥

若需自动生成通过Connect连接设备的授权密钥，请使用管理API访问令牌发起以下HTTP请求。

请替换下方代码中的参数：

rporg_accesstokenhere：您的管理API访问令牌
my-auth-key：认证密钥描述
1：认证密钥有效期天数（可选，默认1天）
pi5-001：使用此密钥添加设备时使用的名称（可选，默认为设备的主机名）
production、kiosk：交换授权密钥时应用到设备的标签（可选）。每个标签只能包含小写字母、数字、连字符和下划线，最多 30 个字符。每个授权密钥最多可应用 10 个标签。

JSON
HTTP
curl

POST /organisation/auth-keys HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/json

{
    "description": "my-auth-key",
    "ttl_days": 1,
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"]
}

HTTP请求：

POST /organisation/auth-keys HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere
Content-Type: application/x-www-form-urlencoded

description=my-auth-key&ttl_days=1&device_name=pi5-001&tags[]=production&tags[]=kiosk

curl --header 'Authorization: Bearer rporg_accesstokenhere' --data-urlencode 'description=my-auth-key' --data-urlencode 'ttl_days=1' --data-urlencode 'device_name=pi5-001' --data-urlencode 'tags[]=production' --data-urlencode 'tags[]=kiosk' https://api.connect.raspberrypi.com/organisation/auth-keys

若成功，将返回201 Created响应，其中包含JSON格式的授权密钥。例如：

HTTP/2 201
Content-Type: application/json; charset=utf-8

{
    "id": "12345",
    "description": "my-auth-key",
    "device_name": "pi5-001",
    "tags": ["production", "kiosk"],
    "secret": "rpoak_123456",
    "expires_at": "2025-01-01T00:00:30Z"
}

响应包含以下字段：

id：认证密钥的唯一标识符。
description：创建认证密钥时使用的描述信息。
device_name：交换授权密钥时分配给设备的名称。
tags：交换授权密钥时应用到设备的标签。
secret：以 rpoak_ 为前缀的随机令牌。
expires_at：密钥过期日期与时间（ISO 8601格式）。

在过期前可使用 secret 进行设备与Connect的关联。

若管理API访问令牌无效，将返回401 未授权响应。

若认证密钥创建失败，将返回422 内容不可处理响应。

HTTP/2 422
Content-Type: application/json; charset=utf-8

{"message":"验证失败：描述字段不能为空"}

提示

您也可手动在组织的设置页面创建授权密钥。

列出设备

若需列出组织中的所有设备，请使用管理API访问令牌发起以下HTTP请求。

请替换下方代码中的参数：

rporg_accesstokenhere：您的管理API访问令牌

HTTP
curl

GET /organisation/devices HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices

若成功，将返回200 OK响应，其中包含最多100个按名称字母顺序排列的组织设备，采用JSON格式。例如：

HTTP/2 200
Content-Type: application/json; charset=utf-8

{
    "devices": [
        {
            "id": "69739b44-ebb2-468e-9e24-08126dec4925",
            "name": "raspberrypi5",
            "serial_number": "ea636879c4d47a37",
            "tags": ["production", "kiosk"]
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 100,
        "total_count": 1,
        "total_pages": 1
    }
}

响应包含以下字段：

devices：组织中的设备列表（每页最多100个）。 meta：分页详情。

devices 列表中的每个项目包含以下字段：

id：设备的唯一标识符。 name：设备名称。 serial_number：设备序列号。 tags：应用于该设备的标签。

meta 对象包含以下字段：

page：响应的当前页码。 per_page：每页的设备数量（最多100）。 total_count：组织中的设备总数。 total_pages：组织设备的总页数。

若管理API访问令牌无效，将返回401 未授权响应。

要获取后续页面的设备，请在查询字符串中使用 page 参数：

HTTP
curl

GET /organisation/devices?page=2 HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl --header 'Authorization: Bearer rporg_accesstokenhere' 'https://api.connect.raspberrypi.com/organisation/devices?page=2'

要更改每页返回的设备数量，请在查询字符串中使用 per_page 参数（最多100）：

HTTP
curl

GET /organisation/devices?per_page=10 HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl --header 'Authorization: Bearer rporg_accesstokenhere' 'https://api.connect.raspberrypi.com/organisation/devices?per_page=10'

删除设备

若需删除组织中的设备并将其从Raspberry Pi Connect注销，请使用管理API访问令牌发起以下HTTP请求。

请替换下方代码中的参数：

rporg_accesstokenhere：您的管理API访问令牌
device-id：设备的唯一标识符

HTTP
curl

DELETE /organisation/devices/device-id HTTP/1.1
Host: api.connect.raspberrypi.com
Authorization: Bearer rporg_accesstokenhere

curl --request DELETE --header 'Authorization: Bearer rporg_accesstokenhere' https://api.connect.raspberrypi.com/organisation/devices/device-id

若成功，将返回204 无内容响应，响应体为空。

若管理API访问令牌无效，将返回401 未授权响应。

若在组织中未找到给定的设备ID，将返回404 未找到响应。

批量配置

您可以利用管理 API 编写脚本生成认证密钥，从而无需人工干预即可配置多台设备。此方法结合了管理 API 与将设备与 Connect 关联中所述的方法。

以下示例为每台设备创建一个认证密钥，并将密钥保存到文件中。请将 rporg_accesstokenhere 替换为您自己的管理 API 访问令牌。

for DEVICE in pi5-001 pi5-002 pi5-003; do
  SECRET=$(curl --silent --fail \
    --header 'Authorization: Bearer rporg_accesstokenhere' \
    --data-urlencode "description=${DEVICE}" \
    --data-urlencode "device_name=${DEVICE}" \
    https://api.connect.raspberrypi.com/organisation/auth-keys \
    | jq -r '.secret')
  if [ -z "${SECRET}" ]; then
    echo "Failed to create auth key for ${DEVICE}" >&2
    continue
  fi
  echo "${SECRET}" > "${DEVICE}.key"
  echo "Created auth key for ${DEVICE}: ${DEVICE}.key"
done

每个 .key 文件包含一个认证密钥（前缀为 rpoak_）。组织认证密钥默认在一天后过期，因此请在设备首次开机前不久生成密钥。要配置设备：

在设备上，以您指定的用户身份运行 loginctl enable-linger 和 rpi-connect on 以启用 Connect。
将对应的 .key 文件内容复制到 ~/.config/com.raspberrypi.connect/auth.key。
从配置机器上删除 .key 文件。这些文件包含敏感密钥。

当检测到该文件时，Connect 会自动为设备完成登录，随后删除该文件。如需更多信息，请参阅将 Raspberry Pi 设备与 Connect 账户关联。

故障排除

已知问题

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

查看连接状态

要查看 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的安全渗透测试与安全分析师评估。

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

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

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

介绍​

手动启动和停止 Connect​

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

完成连接您的 Raspberry Pi​

访问你的 Raspberry Pi 设备​

查看设备​

屏幕共享​

屏幕共享界面​

禁止屏幕共享​

禁止屏幕共享​

远程shell​

结束远程shell会话​

禁止远程shell访问​

始终启用远程shell​

禁用动画图标​

管理设备​

更新​

从 Connect 中断开设备连接​

卸载​

组织版 Connect​

创建组织​

管理用户​

将树莓派设备关联至组织​

转移设备​

标记设备​

搜索和筛选设备​

设置订阅服务​

查看审计日志​

修改组织设置​

重命名组织​

要求双因素认证​

创建授权密钥​

创建管理API访问令牌​

管理API​

创建设备身份​

创建授权密钥​

列出设备​

删除设备​

批量配置​

故障排除​

已知问题​

常见问题​

屏幕共享不可用​

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

网络和防火墙问题​

查看连接状态​

启用增强日志记录​

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

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

查看 Connect 日志​

安全性​

介绍

手动启动和停止 Connect

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

完成连接您的 Raspberry Pi

访问你的 Raspberry Pi 设备

查看设备

屏幕共享

屏幕共享界面

禁止屏幕共享

禁止屏幕共享

远程shell

结束远程shell会话

禁止远程shell访问

始终启用远程shell

禁用动画图标

管理设备

更新

从 Connect 中断开设备连接

卸载

组织版 Connect

创建组织

管理用户

将树莓派设备关联至组织

转移设备

标记设备

搜索和筛选设备

设置订阅服务

查看审计日志

修改组织设置

重命名组织

要求双因素认证

创建授权密钥

创建管理API访问令牌

管理API

创建设备身份

创建授权密钥

列出设备

删除设备

批量配置

故障排除

已知问题

常见问题

屏幕共享不可用

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

网络和防火墙问题

查看连接状态

启用增强日志记录

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

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

查看 Connect 日志

安全性