# 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-CN/docs/install-rk3588