RK3588 部署(瑞芯微 NPU)

RK3588 是目前唯一支持的 ARM 平台——用板载 6 TOPS NPU 硬件加速 AI 检测、VPU 硬解多路视频,低功耗、无需独显,适合想要常开低功耗小盒子的用户。⚠ 硬件门槛比 x86 高:必须是带厂商 BSP 内核、设备节点齐全的 RK3588 板;现阶段推荐 4GB 内存板,8GB+ 为实验性。

1. 适用机型 & 硬件要求

常见板子有 Orange Pi 5 / 5 Plus、Radxa Rock 5A / 5B、firefly 等 RK3588 / RK3588S 开发板。硬件门槛比 x86 高,必须满足下表:

项目	要求
SoC	RK3588 / RK3588S(6 TOPS NPU)
内存	4GB(推荐,已充分验证稳定);8GB / 16GB 目前实验性(见下方警告)
系统	厂商 BSP 内核——Armbian(选 vendor kernel)/ 官方 Rockchip / 板厂系统;不能用 vanilla Debian / Ubuntu 主线内核
存储	系统盘 / eMMC ≥ 16GB;录像建议单独挂 NVMe 或大盘
设备节点	/dev/dri、/dev/dma_heap、/dev/rga、/dev/mpp_service 必须齐全

>4GB 内存目前是实验性的

8GB / 16GB 板在部分 BSP 内核上,AI 检测负载会触发 RGA 相关的内核 panic 整机重启(根因是 RK3588 在 4GB 物理地址线以上的一个内核 bug,我们正在修复)。现阶段请优先选 4GB 板——已充分验证稳定。已有 8G / 16G 板的用户可以先只跑少量相机、或等待修复版本。

必须用厂商 BSP 内核

RK3588 的 NPU(rknpu)、硬解(MPP)、2D 加速(RGA)驱动只在瑞芯微 BSP 内核里有;vanilla Debian / Ubuntu 主线内核不含这些驱动,装了云瞰也无法用 NPU。请刷 Armbian(镜像选 vendor kernel 那版)或用板厂官方系统。

成品 NAS / 整机慎选

部分成品 NAS 的锁定固件裁剪了 BSP、缺设备节点或不允许改内核参数,可能装不上或不稳定。优先用开放的开发板系统(Orange Pi / Radxa / firefly 官方镜像或 Armbian)。

2. 前置检查:设备节点齐不齐

SSH 进板子,确认 NPU / 硬解 / RGA 的设备节点都在(一键脚本会自动查,手动部署必须先确认):

bash

for d in /dev/dri /dev/dma_heap /dev/rga /dev/mpp_service; do
  [ -e "$d" ] && echo "OK  $d" || echo "缺  $d"
done
cat /sys/kernel/debug/rknpu/version 2>/dev/null || echo "无 rknpu 驱动"

全部 OK + rknpu 有版本号 = BSP 内核正常,可以往下装。出现「缺」或「无 rknpu 驱动」= 内核裁过或不是 BSP 内核,先换系统再来。

3. 装 docker

bash

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# 注销重登让 docker 组生效;或临时 newgrp docker

4. 一键脚本部署(推荐)

云瞰一键脚本会自动识别 RK3588、选 rknn 变体、预检设备节点、拉镜像、起容器,5–15 分钟搞定:

bash

curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash

脚本完成后直接给浏览器访问地址(类似 http://192.168.1.10:23406/),进 Setup 向导建库 + 建管理员 + 加第一台相机。

5. 或者手动 compose

想自己控制配置,用 RK3588 专属 compose 模板(已配好 5 个设备节点 + /sys 只读 + 硬件指纹挂载;ARM 无 DMI,所以不挂 x86 那份 product_uuid):

下载 RK3588 compose 模板

务必存成 compose.yml —— 网页后台在线升级靠这个固定文件名定位

compose.yml

或 SSH 用 wget 拉取再起:

bash

mkdir -p ~/yunkan && cd ~/yunkan
wget https://yun-kan.com/compose/rknn.yml -O compose.yml
docker compose -f compose.yml up -d

个别内核缺 /dev/rk_dma_heap

部分 BSP 内核没有 Rockchip 专属的 /dev/rk_dma_heap 节点(通用 /dev/dma_heap 已够用)。如果 docker compose up 报 no such file or directory: /dev/rk_dma_heap,把 compose 里那一行 - /dev/rk_dma_heap:/dev/rk_dma_heap 注释掉再起即可。

起来后浏览器打开 http://<板子IP>:23406/ 进 Setup 向导。

6. 常见问题

跑着跑着整机重启 / 死机

大概率是 >4GB 内存板触发的 RGA 内核 panic(见上方「硬件要求」)。现阶段解法:换 4GB 板,或先只跑 1–2 路相机、关掉 AI 检测里较重的功能。这个坑我们正在从根上修。

检测一直显示「待启用 AI 识别」

多半是设备节点缺失(内核裁过 / 不是 BSP 内核)或没装成 rknn 变体。回到第 2 步重跑设备节点检查;确认容器用的是 yunkan-rknn 镜像。

升级:网页后台 → 设置 → 系统 → 检查更新一键升级;或 SSH cd ~/yunkan && docker compose -f compose.yml pull && docker compose -f compose.yml up -d。