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。