# RK3588 Deployment (Rockchip NPU)

RK3588 is currently the only supported ARM platform — it uses the on-board 6 TOPS NPU to hardware-accelerate AI detection and the VPU to hardware-decode multiple video streams, with low power draw and no discrete GPU required, making it ideal for users who want an always-on, low-power mini box. ⚠ The hardware bar is higher than x86: you need an RK3588 board with a vendor BSP kernel and all device nodes present; at this stage a 4GB board is recommended, and 8GB+ is experimental.

## 1. Supported Models & Hardware Requirements

Common boards include Orange Pi 5 / 5 Plus, Radxa Rock 5A / 5B, firefly and other RK3588 / RK3588S development boards. The hardware bar is higher than x86 — you **must** meet the table below:

| Item | Requirement |
| --- | --- |
| SoC | RK3588 / RK3588S (6 TOPS NPU) |
| Memory | **4GB (recommended, thoroughly validated as stable)**; 8GB / 16GB is currently experimental (see the warning below) |
| System | **Vendor BSP kernel** — Armbian (choose the vendor kernel) / official Rockchip / board-vendor system; **you cannot use a vanilla Debian / Ubuntu mainline kernel** |
| Storage | System disk / eMMC ≥ 16GB; for recordings we recommend mounting a separate NVMe or a large disk |
| Device nodes | /dev/dri, /dev/dma_heap, /dev/rga, /dev/mpp_service must all be present |

> **🛑 >4GB of memory is currently experimental**
>
> On some BSP kernels, 8GB / 16GB boards trigger an RGA-related **kernel panic that reboots the whole machine** under AI detection load (the root cause is an RK3588 kernel bug above the 4GB physical address line, which we are fixing). **For now please prefer a 4GB board** — it has been thoroughly validated as stable. Users who already have an 8G / 16G board can start by running only a few cameras, or wait for the fixed release.

> **⚠️ You must use the vendor BSP kernel**
>
> The RK3588's NPU (rknpu), hardware decode (MPP) and 2D acceleration (RGA) drivers only exist in the Rockchip BSP kernel; a vanilla Debian / Ubuntu mainline kernel does not include these drivers, so even with SkyView installed you cannot use the NPU. Please flash Armbian (pick the vendor kernel image) or use the board vendor's official system.

> **⚠️ Be cautious with turnkey NAS / appliances**
>
> Some turnkey NAS units ship locked-down firmware that strips the BSP, lacks device nodes, or disallows changing kernel parameters, so installation may fail or be unstable. Prefer an open development-board system (Orange Pi / Radxa / firefly official images or Armbian).

## 2. Pre-flight Check: Are the Device Nodes Present?

SSH into the board and confirm the NPU / hardware-decode / RGA device nodes are all there (the one-click script checks automatically; for a manual deployment you must confirm this first):

```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 驱动"
```

Everything OK + rknpu showing a version number = the BSP kernel is fine, you can continue installing. Seeing `缺` (missing) or `无 rknpu 驱动` (no rknpu driver) = the kernel has been trimmed or is not a BSP kernel; switch systems first, then come back.

## 3. Install docker

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

## 4. One-Click Script Deployment (Recommended)

The SkyView one-click script automatically detects RK3588, picks the rknn variant, pre-checks the device nodes, pulls the image and starts the container — done in 5–15 minutes:

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

When the script finishes it prints the browser address directly (something like `http://192.168.1.10:23406/`); open it to enter the [Setup wizard](/docs/quickstart) to create the database, create an admin, and add your first camera.

## 5. Or Deploy Manually with compose

If you want to control the configuration yourself, use the RK3588-specific compose template (it already has the 5 device nodes + /sys read-only + hardware-fingerprint mounts configured; ARM has no DMI, so it does not mount the x86 product_uuid):

[Download the RK3588 compose template](/compose/rknn.yml)

Be sure to save it as compose.yml — the web console's online upgrade relies on this fixed filename to locate it

Or pull it over SSH with wget and start it:

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

> **ℹ️ Some kernels lack /dev/rk_dma_heap**
>
> Some BSP kernels don't have the Rockchip-specific `/dev/rk_dma_heap` node (the generic `/dev/dma_heap` is enough). If `docker compose up` reports `no such file or directory: /dev/rk_dma_heap`, comment out the `- /dev/rk_dma_heap:/dev/rk_dma_heap` line in the compose file and start again.

Once it's up, open `http://<板子IP>:23406/` in a browser to enter the [Setup wizard](/docs/quickstart).

## 6. Common Issues

> **🛑 The whole machine reboots / hangs while running**
>
> Most likely the RGA kernel panic triggered by a >4GB memory board (see “Hardware Requirements” above). For now the fix is: switch to a 4GB board, or run only 1–2 cameras and turn off the heavier features in AI detection. We are fixing this issue at the root.

> **ℹ️ Detection keeps showing “Waiting to enable AI recognition”**
>
> Most likely a missing device node (kernel trimmed / not a BSP kernel) or the rknn variant wasn't installed. Go back to step 2 and re-run the device-node check; confirm the container is using the yunkan-rknn image.

**Upgrade**: Web console → Settings → System → Check for updates for a one-click upgrade; or over SSH `cd ~/yunkan && docker compose -f compose.yml pull && docker compose -f compose.yml up -d`.

---

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