# 安装部署

云瞰 以单 Docker 镜像形式交付，一条命令即可起服务。本章覆盖系统要求、变体选择、安装命令、端口/卷映射、升级与卸载。

## 系统要求

| 项目 | 最低 | 推荐 |
| --- | --- | --- |
| 操作系统 | Linux 内核 ≥ 5.x（Ubuntu 22.04+ / Debian 12+） | Ubuntu 24.04 LTS |
| CPU | 4 核 x86_64 | 8 核及以上 |
| 内存 | 4 GB | 8–16 GB（多路 + AI 检测） |
| 磁盘 | 64 GB（仅录像） | 1 TB+ HDD（按保留天数估算） |
| Docker | 20.10+ | 最新稳定版 |
| GPU（可选） | 无 | Intel 11 代+ 集显 / NVIDIA 30 系+ |

> **⚠️ 仅支持 x86_64 架构**
>
> 云瞰 现阶段**只发布 x86_64 镜像**。树莓派 / 香橙派 / Apple Silicon Mac / 大多数家用 ARM NAS（绿联 DXP 系列、极空间 Z2/Z4 系列等）**暂不支持**。装机前先在目标机器上跑 `uname -m`，输出必须是 `x86_64` 才能装。

## 镜像变体怎么选

AI 检测的硬件加速分 4 个变体，对应不同硬件。装错变体只会让检测变慢或不工作，其它功能（录像、回放、对讲）不受影响。一键部署脚本会自动探测硬件帮你选对——下面这张表只是给想手动选的人参考。

| 镜像 tag | 适用硬件 | 说明 |
| --- | --- | --- |
| `cpu` | 纯 CPU | 通用兜底，性能一般，2–4 路 5fps 可接受 |
| `openvino` | Intel CPU / 集显 / NPU | 11 代酷睿及以上，性价比首选 |
| `cuda` | NVIDIA 显卡 | 需要装 nvidia-container-toolkit，GTX 16 系起步 |
| `trt` | NVIDIA 显卡 + ≥ 8GB 显存（最快） | 速度比 cuda 还快，但**显存 < 8GB 启动会失败**；首次启动会做一次 ~3 分钟模型优化 |

## 按硬件选档（详细参考）

买新机或评估现有机器时，按 CPU 算力分 5 档对照下表。给出推荐镜像、能稳定带的摄像头数、以及能流畅跑哪些 AI 检测功能（启用与否需自己在网页后台手动开）。

| 档位 | 硬件举例 | 摄像头数 | 推荐镜像 | 一句话定位 |
| --- | --- | --- | --- | --- |
| **入门** | Celeron J4125 / J4105 / J4025（老 Atom） | 1 路 | `cpu` | 老破矿渣机捡漏方案，能跑就行 |
| **家用起步** | N100 / N97 / N95（Alder Lake-N 4 核） | 1–2 路 | `openvino` | 主流家用，性价比起步档 |
| **家有老人** | N150 / N250 / N305 | 1–3 路 | `openvino` | 能开跌倒检测的最低门槛 |
| **多机位** | i5 / i7 11–13 代 + Iris Xe 集显（80EU+） | 2–4 路 | `openvino` | 多摄像头 + 全屋检测的合理上限 |
| **全功能 / 商用** | NVIDIA GTX 1060 / RTX 2060 及以上独显 | 4+ 路 | `cuda`（显存 ≥ 8GB 可上 `trt` 提速 ~2×） | 能开手势、婴儿哭声等所有功能 |

### 各档位能流畅跑的检测功能

档位越高能稳定开的功能越多。低档位机器开太多功能会让推理跟不上摄像头帧率，导致漏检事件。下表是每档**推荐打开**的检测能力——✅ 表示推荐打开、❌ 表示不建议在该硬件上开。新装默认只开物体检测，其余都需要在 网页后台 → 设置 → 检测 里按需手动启用。

| 检测功能 | 入门 J4125 | 家用 N100 | 老人 N150 | 多机 Iris Xe | 全功能 NVIDIA |
| --- | --- | --- | --- | --- | --- |
| 运动检测 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 人脸识别 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 物体识别（人/车/动物等） | ❌ | ✅ | ✅ | ✅ | ✅ |
| 跌倒检测 | ❌ | ❌ | ✅ | ✅ | ✅ |
| 车牌识别 | ❌ | ❌ | ❌ | ✅ | ✅ |
| 手势识别 | ❌ | ❌ | ❌ | ❌ | ✅ |
| 婴儿哭声识别 | ❌ | ❌ | ❌ | ❌ | ✅ |

> **💡 建议至少配子码流**
>
> AI 检测走子码流（640x360 / 480p）比走主码流（1080p）省 5–10 倍 CPU。绝大多数 ONVIF 相机都有子码流。详见 [摄像头接入](/docs/cameras)。

> **ℹ️ 多摄像头时关掉非重点机位的检测**
>
> 5 路相机里只有 2 路是关键位（门口 / 客厅），剩下 3 路只录像不检测。这样就算是 N100 也能稳稳跑——把算力集中在关键位上。

## 一键部署（推荐）

运行一行命令，脚本会自动检测硬件、选最合适的镜像变体、拉镜像、起容器，全程 5–15 分钟（看网络）。

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

> **💡 想先看脚本做什么再执行**
>
> 把脚本管道送 bash 是行业惯例但不是最稳的做法。想审一遍再跑：先 `curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh -o install.sh` 下载下来 `cat install.sh` 看一遍，再 `bash install.sh`。或者加 `--detect-only` 让脚本只探测硬件、推荐变体，不实际部署。

脚本做了什么：

- 检查系统是 Linux x86_64 + Docker 已装
- 检查 `23406 / 23880 / 24214 / 24215 / 23515` 等端口空闲
- 探测硬件：NVIDIA 显卡（含显存）/ Intel 集显 / Intel NPU
- 自动选 cpu / openvino / cuda / trt 中最合适的镜像变体
- 拉镜像（默认从阿里云）+ 写 docker-compose 文件 + 自动生成强随机密钥
- 启动容器并等健康检查通过（约 60 秒）
- 输出浏览器访问地址（如 `http://192.168.1.10:23406/`）

> **ℹ️ 脚本不会动你的系统**
>
> 脚本不会主动装 Docker、也不会装 NVIDIA 驱动或 nvidia-container-toolkit。这些前置依赖如果没有，脚本会停下来给你一份针对你发行版的安装命令，自己跑完再回来重跑脚本即可。

### 常用参数

| 参数 | 用途 |
| --- | --- |
| `--variant cpu/openvino/cuda/trt` | 强制指定镜像变体，不让脚本自动选 |
| `--detect-only` | 只检测硬件 + 推荐变体，不实际部署 |
| `--offline image.tar.gz` | 离线包部署（无外网环境） |
| `--data-dir /path` | 自定义状态目录（数据库 / cookies / 日志，默认 `~/skyview/data`） |
| `--recordings-dir /path` | 把录像单独指到大盘 / NAS（默认 `~/skyview/recordings`，与 data 同级；录像可达 TB 级） |
| `--registry <url>` | 换私有镜像仓库 |
| `--version 0.6.0` | 拉指定版本（默认 latest） |
| `-y` 或 `--yes` | 不交互模式 |

```bash
# 只看推荐什么变体，不部署
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash -s -- --detect-only

# 强制用 trt 变体并跳过交互
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash -s -- --variant trt -y

# 离线部署（先把镜像 tar.gz scp 到机器上）
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh -o install.sh
bash install.sh --offline /path/to/skyview-image.tar.gz
```

*几个常用例子*

> **💡 需要公网域名访问**
>
> 如果你前面套 Caddy / Nginx 做 HTTPS 终止 + 自定义域名，脚本会**交互式问你**域名和协议（http/https），自动写入配置。纯 LAN 部署直接选 N，浏览器用 `http://<服务器 IP>:23406` 访问即可。

## 按平台部署（选你的设备）

一键脚本对通用 Linux + Docker 环境最方便，但 NAS、HA OS、PVE 等平台都有自己的容器管理 UI、网络模式、iGPU 透传方式和已知坑。下面针对常见目标平台给单独教程，包含每个平台特定的 compose 文件、UI 部署路径、防火墙配置和常见问题：

- [群晖 Synology DSM 7.2+](/docs/install-synology) — Container Manager + Intel 核显机型（DS920+ / DS423+ / DS224+ 等）
- [Unraid 6.12+](/docs/install-unraid) — Compose Manager + Intel GPU TOP / NVIDIA Driver plugin
- [飞牛 fnOS](/docs/install-fnos) — Debian 12 base + N100/N305 内置 iGPU
- [绿联 UGOS Pro](/docs/install-ugos) — x86 机型（DXP2800/DXP4800/DXP6800 等）
- [TrueNAS Scale 24.10+](/docs/install-truenas) — Custom App YAML + ZFS dataset 持久化
- [Ubuntu / Debian](/docs/install-ubuntu-debian) — apt + docker compose v2，最干净的部署路径
- [Fedora 39+](/docs/install-fedora) — dnf docker-ce + SELinux 卷标签 + firewalld 放行
- [Proxmox VE LXC](/docs/install-pve-lxc) — privileged LXC + Intel iGPU 透传（家用 N100 / N305 PVE 用户首选）
- [Home Assistant OS 加载项](/docs/install-ha-addon) — 加云瞰仓库一键装 yunkan / yunkan-openvino addon

> **💡 没你的平台？**
>
> Ubuntu / Debian 教程其实覆盖了 99% 的 Linux 发行版（CentOS Stream / Rocky / Arch / openSUSE 等只需把 `apt install` 换成对应包管理器）。SELinux 系（CentOS / Rocky / Alma）参考 Fedora 教程的 `:Z` 卷标签处理即可。

## 手动部署（高级）

想自己一步步控制部署过程的，按下面 4 步走。一键脚本本质就是把这些命令自动化了。

1. **拉镜像**

   选好上面四个变体之一：

   ```bash
   docker pull registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-cpu:latest
   ```

2. **建数据 / 录像目录**

   小状态（数据库 / cookies / 日志）落在 `data/`；录像（可达 TB 级）单独放同级的 `recordings/`，方便单独指到大盘 / NAS。

   ```bash
   mkdir -p ~/skyview/data ~/skyview/recordings && cd ~/skyview
   ```

3. **起容器**

   用 host 网络让相机直接通过宿主机端口，避免 NAT 影响视频质量。授权绑定要求 bind-mount `/etc/machine-id` 和 `product_uuid`，不要省。

   ```bash
   docker run -d --name yunkan --restart=always \
     --network host \
     -v $(pwd)/data:/app/data \
     -v $(pwd)/recordings:/app/data/recordings \
     -v /etc/machine-id:/etc/machine-id:ro \
     -v /sys/class/dmi/id/product_uuid:/sys/class/dmi/id/product_uuid:ro \
     registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-cpu:latest
   ```

4. **打开浏览器**

   首次访问跳到 `/setup` 向导，按 [首次启动](/docs/quickstart) 一章往下走。

   ```
   http://<服务器 IP>:23406
   ```

> **⚠️ 硬件信息必须 bind-mount**
>
> 授权绑定到本机硬件。如果你只挂 data 不挂这两个文件，下次重建容器时硬件指纹会变，授权失效。

## 端口和卷映射

云瞰 用 host 网络模式跑，所有端口都直接绑在宿主机上。生产端口都加了一个非常规偏移到 2xxxx 区间，避免和你机器上已有的 nginx 80/443、redis 6379、其它服务的 8080/8554/8888 冲突。

| 端口 | 用途 | 必须开吗 |
| --- | --- | --- |
| **23406** / TCP | 网页管理后台 + App 接口 | **必须**（也可放在反代后做 HTTPS） |
| **23880** / TCP | RTSP 直连出（VLC / 第三方 NVR 用） | 可选 |
| **24214** / TCP | 回放 + 兜底实时画面 | **建议开** |
| **24215** / TCP | 实时画面（低延迟通道信令） | **建议开** |
| **23515** / UDP | 实时画面（低延迟通道音视频） | **建议开**，不开会自动降级到 24214（延迟变 2–4s） |

| 容器路径 | 用途 | 建议 |
| --- | --- | --- |
| `/app/data` | 数据库 / 配置 / cookies / 日志等小状态 | **必挂**，生命周期跨容器 |
| `/app/data/recordings` | 录像（可达 TB 级，嵌套挂在 `/app/data` 之上） | **必挂**，可单独指到大盘 / NAS；模型已内置在镜像里，无需挂载 |
| `/etc/machine-id` | 硬件指纹 1/2 | **必挂**只读 |
| `/sys/class/dmi/id/product_uuid` | 硬件指纹 2/2 | **必挂**只读 |

## 升级

**最方便：网页后台一键升级。** 浏览器进 网页后台 → 设置 → 系统 → 检查更新，发现新版本点 "升级" 即可——内置 OTA sidecar (`yunkan-updater`) 会接管 `docker compose pull + up -d --force-recreate`，几分钟后页面自动重连到新版本。

想自己在 SSH 里手动升级也行：

```bash
cd ~/skyview
docker compose -f compose.all-in-one.yml pull
docker compose -f compose.all-in-one.yml up -d
```

或者重跑一键脚本（带 `-y` 不打扰）：

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

> **💡 数据自动迁移**
>
> 数据库结构升级会在容器启动时自动完成，不需要人工操作。建议升级前 `tar -czf data-backup-$(date +%F).tar.gz data/` 备份一下。

## 卸载

```bash
cd ~/skyview
docker compose -f compose.all-in-one.yml down
docker rmi registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-cpu:latest
# 录像 / 数据库继续保留，需要彻底清理：
rm -rf ~/skyview
```

> **🛑 data 目录删了无法恢复**
>
> 里面有数据库、人脸库、录像、115 登录信息。删之前请确认所有需要的录像已经下载或上传到云端。

---

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