云端连接 · Linker Dashboard

云服务地址

https://doc.linkerhub.work/linker-dashboard/cloud

本页从一台尚未部署的树莓派开始，依次完成网络与 SSH、蓝牙依赖、系统服务安装、Android App 配网绑定。树莓派连接 CAN 适配器和灵巧手，手机作为操作端；云服务已由公司部署，树莓派只需安装 Dashboard。

操作端与控制器使用同一云服务。安装程序和局域网控制无需云账号；新账号由管理员提供邀请码注册，已登录的普通账号即可关联控制器。

原 IP 网站 https://39.106.139.73/linker-dashboard/ 继续可访问；云地址 https://39.106.139.73/linker-dashboard/cloud 和旧版根路径 https://39.106.139.73 也保留，连接同一云服务。已有控制器可继续使用原地址，网站更新不会自动迁移其云配置。

1. 准备网络与 SSH

准备带 Wi-Fi 和支持 BLE 广播的蓝牙适配器的树莓派，安装 64 位 Raspberry Pi OS、Debian 或 Ubuntu，并使用 systemd。以下安装命令适用于这些 Debian 系系统；其他 ARM64 Linux 需要按发行版准备依赖。仅 CPU 支持 ARM64 不够，操作系统也必须是 64 位。

烧录 Raspberry Pi OS 时，在 Imager 中设置主机名、登录用户和密码或 SSH 公钥，并开启 SSH；不要假定默认账号是 pi。其他镜像按系统说明开启 SSH。已安装系统但未启用 SSH 时，先通过屏幕和键盘在树莓派本地完成设置。

让树莓派在安装时能上网

已有联网路由器时，让电脑和树莓派接入该路由器，由路由器分配地址即可。若使用电脑网线直连树莓派，电脑应通过 Wi-Fi 或另一张网卡联网，并向连接树莓派的专用网口开启网络共享。

Windows 电脑：开启网线共享

确认电脑本身能打开公司下载站，按 Win + R，输入 ncpa.cpl。
打开已经联网的网卡的“属性 → 共享”，勾选“允许其他网络用户通过此计算机的 Internet 连接来连接”，选择连到树莓派的以太网网卡。
让树莓派的以太网使用自动获取地址，重新连接网线或更新租约。用 ipconfig 查看电脑共享网口地址；它是网关，不是树莓派地址。

Windows Internet 连接共享负责地址分配、DNS 和转发，通常无需额外下载 DHCP 软件。若没有“共享”选项或被组织策略禁用，使用联网路由器，或由系统管理员启用共享。

Linux 电脑：使用 NetworkManager 共享

以下命令在电脑执行。先查看网卡和当前上联网口，确认哪一个物理网口只连树莓派：

nmcli device status
nmcli connection show --active
ip -4 route show default

若已存在正常共享连接，沿用即可。新建时，将示例 enp3s0 替换为实际的专用网口；不要选上联网口或连接公司局域网的网口：

sudo nmcli connection add type ethernet ifname enp3s0 con-name linker-pi-share ipv4.method shared ipv4.never-default yes ipv6.method disabled
sudo nmcli connection up linker-pi-share
ip -4 address show dev enp3s0

shared 模式负责 DHCP、DNS 和互联网转发；也可在图形网络设置中把该网口的 IPv4 方法设为“与其他计算机共享”。若激活时报缺少 dnsmasq，Debian/Ubuntu 电脑可安装其辅助程序后重试：

sudo apt-get update
sudo apt-get install -y dnsmasq-base
sudo nmcli connection up linker-pi-share

如果 nmcli 不存在，或该网口由其他网络管理器管理，优先使用联网路由器；需要改用 NetworkManager 时，在电脑本地按发行版说明迁移，不通过当前远程连接直接停用原网络服务。

撤销本节新建的共享连接时执行下面两条命令；依赖这条网线的树莓派会随即断网：

sudo nmcli connection down linker-pi-share
sudo nmcli connection delete linker-pi-share

找到树莓派并登录

从路由器租约列表、树莓派本地终端的 hostname -I，或已配置且支持 mDNS 的 主机名.local 找到地址。电脑上的 ip neigh（Linux）或 arp -a（Windows）可辅助查看已发现的邻居，但列表为空不代表没有设备，也不要猜测树莓派地址是网关后的某个固定数字。

在电脑执行，将用户名和 IP 替换为实际值，首次连接时核对树莓派的 SSH 主机指纹：

ssh 用户名@树莓派IP

登录后，后续终端命令均在树莓派执行：

cat /etc/os-release
uname -m
getconf LONG_BIT
ip -4 address
ip -4 route
getent hosts doc.linkerhub.work
sudo apt-get update
sudo apt-get install -y curl ca-certificates
curl -fL --connect-timeout 10 --max-time 30 https://doc.linkerhub.work/linker-dashboard/latest-version.txt

ARM64 树莓派应显示 aarch64 和 64；系统软件源更新成功，最后一条命令返回稳定版本号，才说明下载链路可用。DNS 失败先检查共享连接提供的 DNS；没有默认路由先检查网关；HTTPS 证书错误同时核对系统时间。失败时先修好网络，再继续安装。

2. 准备蓝牙配网依赖

在树莓派执行。BlueZ 提供蓝牙服务，NetworkManager 用于接收 App 写入的 Wi-Fi 配置。先确认系统的网络管理方式：Raspberry Pi OS Bookworm 默认使用 NetworkManager，Ubuntu 等系统需核对镜像配置。若 Wi-Fi 当前由 dhcpcd、systemd-networkd 或其他服务管理，先通过本地控制台按发行版说明迁移 Wi-Fi，并保留 SSH 网线；不要直接停止正在承载 SSH 的网络服务。

sudo apt-get install -y bluez network-manager
sudo systemctl enable --now bluetooth
sudo systemctl enable --now NetworkManager
systemctl is-active bluetooth NetworkManager
bluetoothctl list
bluetoothctl show
nmcli device status
nmcli radio wifi

两项服务应为 active；蓝牙应有适配器且显示 Powered: yes；Wi-Fi 应处于启用状态，并出现在 NetworkManager 的设备列表中。尚未配网时显示 disconnected 可以继续；显示 unmanaged 或 unavailable 时，先解决管理方式、驱动、无线开关或硬件问题。只有有线网络、仅通过蓝牙关联账号时，可以跳过 Wi-Fi 管理要求。

蓝牙或 Wi-Fi 软件开关关闭时，可分别执行 sudo bluetoothctl power on、sudo nmcli radio wifi on。没有蓝牙适配器时先检查硬件和驱动；bluetoothctl show 正常仍不能证明广播成功，安装后还要看 Dashboard 日志及 App 扫描结果。

3. 一条命令安装系统服务

在树莓派终端执行，无需源码仓库账号、Go 或 Node.js：

curl -fL https://doc.linkerhub.work/linker-dashboard/install.sh -o install-linker-dashboard.sh && bash install-linker-dashboard.sh

脚本自动选择 ARM64 / amd64 稳定包、校验 SHA-256、补齐运行依赖、安装 linker-dashboard 系统服务、启动并设置开机自启，最后检查 API 版本。安装需要树莓派的 sudo 权限。BlueZ 和 NetworkManager 由上一步准备，脚本不自动接管网络。

可先阅读下载后的脚本；运行 bash install-linker-dashboard.sh --check 只下载校验，不安装或启动。安装后检查：

systemctl is-active linker-dashboard
systemctl is-enabled linker-dashboard
curl -f --max-time 10 http://127.0.0.1:7081/api/controller/info
sudo journalctl -u linker-dashboard -n 100 --no-pager

服务应为 active、enabled，API 返回控制器信息和版本。电脑浏览器访问 http://树莓派IP:7081 可检查局域网页面。此时云端尚未绑定是正常状态；API 成功也不代表蓝牙广播成功。

升级前停止手势舞和跟随，再次执行安装命令。标准服务会备份程序、配置及数据到 /var/backups/linker-dashboard/install-*，保留原数据和云地址，失败时尝试恢复。手动启动的数据目录和自定义服务不自动迁移，详见备份与升级。

4. 用 Android App 配网并绑定

从下载页安装 Android App，向管理员获取账号邀请码，填写本页完整云地址，注册并登录。已有账号直接登录。手机此时也需要能访问云服务。
开启手机蓝牙，按系统提示授予“附近设备”权限；旧版 Android 扫描或读取当前 Wi-Fi 名称还可能要求定位权限及定位服务。蓝牙添加请在 Android App 内操作，普通浏览器页面不提供此功能。
Dashboard 每次启动默认开放 15 分钟配网窗口。在 App 选择“通过蓝牙添加”，扫描并选择 LH-… 控制器；多台设备时核对控制器名称，必要时逐台部署。
树莓派已有可长期使用的网络时，不勾选“同时配置 Wi-Fi”。如果安装时借用了电脑网线、之后要拔线，则勾选该项，选择“手机当前 Wi-Fi”或“其他 Wi-Fi”，填写树莓派可连接的网络名称和密码。
点击“配置并关联”。App 会自动申请设备接入码，通过蓝牙发送给树莓派；无需事先手动生成或粘贴接入码。等待网络配置和云端关联完成，再回到控制器列表。

App 可以读取手机当前 Wi-Fi 名称，不能读取已保存的密码。加密网络密码至少 8 位；开放网络留空。使用树莓派硬件支持的频段和普通 Wi-Fi，带网页认证的访客网络不能仅靠名称和密码完成联网。

窗口超时或补装依赖后，在停止设备动作的情况下执行以下命令，随后重新扫描。重启会中断当前控制连接：

sudo systemctl restart linker-dashboard

蓝牙只传递配网和关联信息，后续控制通过局域网或互联网进行。安装时树莓派通过网线联网下载；安装及依赖准备完成后，才可以在新的现场通过蓝牙设置 Wi-Fi。当前安装脚本不支持树莓派完全离线安装。

5. 验收并开始使用

服务：树莓派 Dashboard 为运行、自启状态，本机 API 和电脑的局域网页面可访问。
蓝牙：App 能发现目标 LH-…，配置和关联成功。
云端：App 中该控制器显示在线，选中后能看到适配器及设备状态。
独立联网：若计划拔掉网线，先通过 nmcli device status 确认 Wi-Fi 已连接；停止设备动作后拔线，再确认云端仍在线。Wi-Fi 显示已连接不等于互联网可用，这一步才能验证不依赖电脑共享。
重新开机：在不执行动作时重启树莓派，确认 Dashboard 自启、Wi-Fi 恢复和云端重新上线。控制器身份已保存在本机，无需每次配对或重新注册。

拔线可能结束原有 SSH 会话，电脑后续可通过同一 Wi-Fi 下的新 IP 登录。云端控制要求树莓派持续联网；同一局域网控制不要求公网或云账号。共享给其他账号时，由已关联账号生成控制器共享码，对方先登录再关联。

已有主机或不使用蓝牙

已安装并关联的控制器可以直接登录并选择在线设备。需要首次接入且不用蓝牙时，在操作端生成设备接入码，然后在连接 CAN 适配器的主机配置启动参数。浏览器“更换控制服务”只决定操作端连接哪里，不会为主机写入接入配置。

终端手动运行的主机使用：

./linker-dashboard --cloud-url https://doc.linkerhub.work/linker-dashboard/cloud --cloud-enrollment-code <设备接入码>

Windows 使用 linker-dashboard.exe 和相同参数。已安装系统服务的主机不要同时启动第二个实例：停止动作后，用 sudoedit /etc/linker-dashboard.env 设置 LINKER_CLOUD_URL 和 LINKER_CLOUD_ENROLLMENT_CODE，再重启 linker-dashboard。确认接入成功、身份已保存后从环境文件移除一次性 LINKER_CLOUD_ENROLLMENT_CODE，保留云地址及数据目录。环境文件应仅 root 可读。

已有控制器改用新云地址需要新的设备接入码；保留原 IP 地址也能继续使用同一公司服务。不要通过删除数据目录重新尝试，这会改变控制器身份。

系统服务启动时，/etc/linker-dashboard.env 中的 LINKER_CLOUD_URL 优先于已保存的地址。通过蓝牙切换云地址时，还要同步该文件中的旧地址；否则本次配网可能成功，重启后却因地址不一致而离线。终端启动时同样核对 --cloud-url。

按阶段排查

找不到 IP 或 SSH 失败: 检查供电、网线、地址租约和 SSH 是否启用。认证失败核对镜像中设置的账号或密钥；超时检查 IP、网段和防火墙。需要时接屏幕在树莓派本地查看地址。
能 SSH，但下载失败: 在树莓派检查默认路由、DNS、时间和 HTTPS 请求。电脑直连方案还要确认电脑持续联网、共享服务与转发工作正常。只有 DHCP 不足以保证上网。
服务不启动或网页打不开: 查看 sudo journalctl -u linker-dashboard -n 100 --no-pager。本机 API 正常、电脑打不开时，核对树莓派 IP 和 TCP 7081 防火墙规则；不要把局域网控制端口转发到公网。
App 找不到 LH 设备: 确认手机蓝牙权限、树莓派适配器及 BlueZ 状态、15 分钟窗口和 Dashboard 日志中的蓝牙配网启动结果。先停止动作，再重启 Dashboard 并在 App 重新扫描；正常退出的配网窗口不会让局域网服务停止。
发现设备，但配置 Wi-Fi 失败: 核对名称、密码、频段和信号，并在树莓派检查 nmcli device status 及 sudo journalctl -u NetworkManager -n 100 --no-pager。先解决 unmanaged、无线禁用或驱动异常，再重新提交。
Wi-Fi 成功，云端关联失败或控制器离线: 分别确认手机和树莓派能访问完整云地址。在树莓派执行下方健康检查，并查看 Dashboard 日志；健康接口正常仅证明服务可达，仍需核对账号、接入凭据及持续连接。App 重试“配置并关联”会申请新的接入码，无需删除数据；持续连接失败时请管理员核对 HTTPS / WebSocket 代理。
拔掉网线后离线: 确认之前勾选并完成了“同时配置 Wi-Fi”。重新接线排查 Wi-Fi 的默认路由、DNS 和互联网访问；沿用现有网络选项不会替树莓派创建 Wi-Fi 连接。
配网成功，重启后离线: 先确认服务自启和网络恢复；若日志提示云地址已变化，按已有主机接入说明核对环境文件或启动参数是否仍强制使用旧地址。保留控制器数据目录。

curl -f --connect-timeout 10 --max-time 15 https://doc.linkerhub.work/linker-dashboard/cloud/healthz

求助时提供系统版本、架构、失败阶段、时间及对应日志；分享前移除 Wi-Fi 密码、邀请码和令牌。灵巧手供电、CAN 接线和适配器问题见使用手册故障排查。