# Unraid 部署

Unraid 用户**优先走 Community Applications 一键装**(Apps 搜 'yunkan' 即可,体验对齐 HA 加载项);需要自定义端口 / OTA sidecar / 旧版 Unraid 走下方 docker compose 路径。两条路径都覆盖 Intel iGPU + NVIDIA GPU。

## 推荐路径:Apps 一键安装(Community Applications)

Unraid 的 Community Applications(简称 **CA**,Apps 标签页)是社区维护的应用商店。云瞰已上架 CA 官方商店,**Unraid 用户直接在 Apps 里搜 'yunkan' 就能一键装**,无需添加任何模板仓库,体验对齐 Home Assistant 加载项。无需手写 compose,无需 SSH。

> **💡 什么时候用 CA,什么时候用 compose**
>
> **绝大多数 Unraid 用户走 CA 即可**:云瞰单容器把所有进程合在一起,CA 装出来就能跑。**走下方 docker compose 路径**只有三种情况:(1) 需要自定义端口(镜像 hardcode,不能在容器面板改);(2) 想跑 yunkan-updater sidecar 做完全后台 OTA 升级(CA 路径下用 Apps 的 'Force Update' 已经够用);(3) Unraid 版本 < 6.12 / 没装 CA 插件。

1. **确认已装 Community Applications 插件**

   Unraid 6.10+ 大多预装。Apps 标签页可见即 OK。如缺少,Plugins → Install Plugin 粘贴 `https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg` 安装。

2. **搜索并安装(三选一,**端口冲突不可同时装**)**

   Apps 标签页 → 搜索框输入 `yunkan` → 出现 3 个变体:**YunKan**(纯 CPU,无硬件依赖)/ **YunKan-OpenVINO**(Intel iGPU,需先装 Intel GPU TOP plugin)/ **YunKan-CUDA**(NVIDIA GPU,需先装 NVIDIA Driver plugin)。点对应变体的 **Install**,默认参数即可,数据目录默认 `/mnt/user/appdata/yunkan/data`。

3. **首次启动 → Setup 向导**

   容器启动后,Docker 标签页找到 yunkan 容器 → 点 **WebUI**(或浏览器直接 `http://<Unraid IP>:23406/`)→ 进入 [Setup 向导](/docs/quickstart) → 选 SQLite → 建管理员 → 加摄像头。

> **ℹ️ GPU plugin 依赖 & 端口 / FAQ**
>
> OpenVINO 变体需先装 **Intel GPU TOP** plugin,CUDA 变体需先装 **NVIDIA Driver** plugin —— 详细步骤见下方 [2. 准备工作](#2-%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C)。**端口占用 / 公网暴露警告 / iGPU 透传 FAQ** 在下方 compose 路径章节,CA 路径同样适用。

> **ℹ️ OTA 升级**
>
> 走 CA 路径时,Apps 标签页发现新版会标红点,点 **Update** 即可拉新镜像并重建容器,**无需 yunkan-updater sidecar**。想要完全后台无人值守升级(到点自动拉镜像 + 重启)再考虑下方 compose + sidecar 方案。

## 或:docker compose 路径(自定义 / OTA sidecar / 旧 Unraid)

下面是手写 compose 的传统部署路径,**适用于需要自定义端口、想跑 OTA sidecar、或 Unraid < 6.12 没 CA 插件的用户**。前面 CA 一键装的用户可以跳过本节,直接看 [2. 准备工作](#2-%E5%87%86%E5%A4%87%E5%B7%A5%E4%BD%9C) 里 GPU plugin 安装,或者翻到 [5. 端口和防火墙](#5-%E7%AB%AF%E5%8F%A3%E5%92%8C%E9%98%B2%E7%81%AB%E5%A2%99) / [6. 常见问题](#6-%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98)。

## 1. 适用机型 & 推荐变体

| 硬件 | 推荐变体 | 需要的 plugin |
| --- | --- | --- |
| Intel CPU + 核显(11 代+) | openvino | Intel GPU TOP |
| NVIDIA GPU(GTX 1060+ / 显存 ≥ 4GB) | cuda | NVIDIA Driver |
| NVIDIA GPU + 显存 ≥ 8GB(2060+ / 3060+) | trt | NVIDIA Driver |
| 纯 CPU(无核显 / 无独显) | cpu | 无 |

## 2. 准备工作

1. **确认 Unraid 版本**

   Tools → Update OS 看版本 ≥ 6.12.13(更老版本需要装 Docker Compose Manager plugin)

2. **装 GPU plugin**

   Apps 标签页搜对应 plugin:Intel iGPU 装 **Intel GPU TOP**,NVIDIA 装 **NVIDIA Driver**;装完会提示重启,重启后 `/dev/dri` 或 `/dev/nvidia*` 出现

3. **建 AppData 目录**

   Unraid 习惯放 `/mnt/user/appdata/yunkan/`,新建即可;cd 到该目录准备放 compose 文件

## 3. 获取 compose 文件

三种方式任选其一——浏览器直接下载、SSH 用 wget、或在 Unraid Compose Manager 里粘贴最小版:

[浏览器下载 compose.yml](/compose/unraid.yml)

Unraid 6.12+ 专用 · openvino 变体 · 含 OTA sidecar

或 SSH 进 Unraid(或用 Terminal 插件):

```bash
ssh root@<Unraid IP>
mkdir -p /mnt/user/appdata/yunkan
cd /mnt/user/appdata/yunkan
wget https://yun-kan.com/compose/unraid.yml -O compose.yml
```

> **💡 Intel iGPU 还是 NVIDIA GPU**
>
> 默认 compose 文件用 openvino 变体(Intel iGPU)。NVIDIA 用户:把 `image:` 改成 `yunkan-cuda` 或 `yunkan-trt`,并取消文件里 `deploy.resources` 注释。

```yaml
name: yunkan

services:
  yunkan:
    image: registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-openvino:latest
    container_name: yunkan
    restart: always
    network_mode: host
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - /mnt/user/appdata/yunkan/data:/app/data
      - /mnt/user/appdata/yunkan/recordings:/app/data/recordings
      - /etc/machine-id:/etc/machine-id:ro
      - /sys/class/dmi/id/product_uuid:/sys/class/dmi/id/product_uuid:ro
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Asia/Shanghai
      - SKYVIEW_SELF_CONTAINER_NAME=yunkan
  updater:
    image: registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-updater:latest
    container_name: yunkan-updater
    restart: always
    network_mode: none
    volumes:
      - /mnt/user/appdata/yunkan/data:/app/data
      - /mnt/user/appdata/yunkan/compose.yml:/app/compose.yml:ro
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Asia/Shanghai
      - COMPOSE_PROJECT_NAME=yunkan
      - STATE_FILE=/app/data/.upgrade-state
      - SKYVIEW_COMPOSE_FILE=/app/compose.yml
      - SKYVIEW_COMPOSE_SERVICE=yunkan
```

*compose.yml (最小版,粘贴保存)*

## 4. 启动云瞰

**方式 A · CLI**(推荐,功能完整):

```bash
cd /mnt/user/appdata/yunkan
docker compose up -d
docker logs -f yunkan
```

**方式 B · GUI**:Unraid Web UI → Docker 标签页 → "Compose Manager" 区块 → "Add New Stack" → 命名 yunkan → 把 compose.yml 内容粘贴进去 → "Compose Up"。

启动后浏览器打开 `http://<Unraid IP>:23406/` 进入 [Setup 向导](/docs/quickstart)。

## 5. 端口和防火墙

Unraid 默认无防火墙,所有端口直接暴露在宿主机网卡上,云瞰用 23406/23880/24214/24215/tcp + 23515/udp。

> **⚠️ 不要公网暴露**
>
> Unraid 默认监听 0.0.0.0 + 无防火墙 = 任何上行公网的设备直接能扫到你的相机。**永远走 Tailscale / Wireguard / Cloudflare Tunnel + HTTPS**。详见 [客户端 → 远程访问](/docs/clients#%E8%BF%9C%E7%A8%8B%E8%AE%BF%E9%97%AE%E8%A6%81%E7%82%B9)。

## 6. 常见问题

> **ℹ️ iGPU 透传不生效 / OpenVINO 报 GPU 找不到**
>
> 确认 Intel GPU TOP plugin 装完已重启,SSH 跑 `ls -la /dev/dri/` 应该看到 card0 / renderD128。否则装错 plugin 或机器没核显(查 `lspci | grep -i vga`)。

> **ℹ️ NVIDIA GPU 透传不生效**
>
> SSH 跑 `nvidia-smi`(NVIDIA Driver plugin 装好后可用),能看到显卡则 host 端正常;若 compose 启动后容器内 `docker exec yunkan nvidia-smi` 失败,确认 image 是 yunkan-cuda 而非 yunkan-openvino。

**升级方式**:OTA sidecar 在 Unraid 上 docker socket 权限正常可用;也可手动 `cd /mnt/user/appdata/yunkan && docker compose pull && docker compose up -d`。

---

来源:https://yun-kan.com/ja/docs/install-unraid