# 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 精靈](/docs/quickstart) 建庫 + 建管理員 + 加第一台相機。

## 5. 或者手動 compose

想自己控制設定,用 RK3588 專屬 compose 範本(已配好 5 個裝置節點 + /sys 唯讀 + 硬體指紋掛載;ARM 無 DMI,所以不掛 x86 那份 product_uuid):

[下載 RK3588 compose 範本](/compose/rknn.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 精靈](/docs/quickstart)。

## 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`。

---

来源:https://yun-kan.com/zh-TW/docs/install-rk3588