# 云瞰 SkyView

> SkyView (云瞰) is a self-hosted, privacy-first AI NVR / VMS for home and small-business RTSP, ONVIF and GB/T 28181 IP cameras. It is a Chinese-friendly alternative to Frigate, BlueIris, Shinobi, Scrypted and ZoneMinder, with native Android / iOS / Web clients, an official Home Assistant integration (HACS) and on-device AI — including natural-language video search powered by a local VLM, and a built-in annotation plus cloud fine-tuning loop that makes detection more accurate on your own cameras over time. All processing stays on your own box: no cloud, no API key, data never leaves the device.

SkyView ships as a single Docker image (CPU / Intel OpenVINO / NVIDIA CUDA / NVIDIA TensorRT / Rockchip RK3588 NPU variants) and runs on plain Linux, Synology, Unraid, fnOS, UGOS, TrueNAS, Proxmox VE LXC, RK3588 ARM boards and as a Home Assistant OS add-on. Licensing is per household, never per camera. The UI and marketing site are available in Simplified Chinese, Traditional Chinese, English, Japanese and French; the product documentation is currently authored in Chinese.

本文件汇总云瞰全部产品文档(中文),供 AI 引擎一次性摄取。规范见 https://llmstxt.org。

---

# 安装部署

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

## 系统要求

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

> **ℹ️ 架构支持:x86_64 与 RK3588**
>
> 云瞰主要发布 x86_64 镜像;ARM 平台目前支持**瑞芯微 RK3588**(NPU 加速的 rknn 变体,见 [RK3588 部署](/docs/install-rk3588))。其它 ARM 设备(树莓派 / 香橙派非 RK3588 型号 / Apple Silicon 等)暂不支持。

## 镜像变体怎么选

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 / 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
- [RK3588 板](/docs/install-rk3588) — 瑞芯微 NPU 加速的低功耗 ARM 小盒子(Orange Pi 5 / Radxa Rock 5 等);推荐 4GB 板,8G+ 实验性

> **💡 没你的平台？**
>
> 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 接口 + 直播 | **必须** |
| **23515** / UDP + TCP | 实时画面低延迟通道 | **建议开**,不开会降级为 HLS(延迟约 2.5 秒) |
| **23880** / TCP | RTSP 直连出(VLC / 第三方 NVR 用) | 可选 |
| **23443** / TCP | 公网直连(HTTPS),默认关闭 | 只在需要外网访问时开 |
| **24214** / TCP | 内部流媒体服务 | 不用开 |

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

## 环境变量参考

以下环境变量全部可选——host 网络的标准部署一个都不用设，只有桥接网络、反向代理、固定内部密钥等进阶场景才用得到。在 compose 文件的 `environment:` 段（或各 NAS 平台的环境变量表单）里设置。

| 环境变量 | 默认 | 用途 |
| --- | --- | --- |
| `SKYVIEW_WEBRTC_EXTERN_IPS` | 自动探测局域网 IP | 实时画面（WebRTC）对外通告的 IP / 域名，逗号分隔。桥接网络或多层 NAT 下客户端连不上实时画面时设置 |
| `SKYVIEW_PUBLIC_PORT` | `23406` | 客户端实际访问网页后台的端口。只在桥接网络把 23406 映射为其它宿主端口时设置，否则分享链接和局域网发现会带错端口 |
| `SKYVIEW_PUBLIC_TCP_PORT` | 关闭 | 公网直连的 HTTPS 端口。通常在网页后台里设置即可；用环境变量设置后以它为准，网页后台对应项锁定 |
| `SKYVIEW_PUBLIC_TLS_CERT` / `SKYVIEW_PUBLIC_TLS_KEY` | 自动申请 | 公网直连改用自备证书：容器内证书链 / 私钥 PEM 的路径，必须成对设置 |
| `SKYVIEW_MEDIA_SECRET` | 首次启动自动生成 | 内部流媒体接口密钥（32 字节十六进制）。仅进阶集成需要固定密钥时设置 |
| `SKYVIEW_MDNS_ENABLED` | `1` | 设为 `0` 关闭局域网发现通告（`yun-kan.local`）。宿主系统已自带 mDNS 服务时使用 |
| `SKYVIEW_DB_TYPE` 等（`_SOCKET` 或 `_HOST` / `_PORT`，加 `_USER` / `_PASSWORD` / `_NAME`） | 未设 | 由部署模板固定数据库（编排自带数据库容器时用）。设了后数据库配置以环境变量为准：向导跳过数据库步骤，设置页的在线迁移停用 |

## 升级

**最方便：网页后台一键升级。** 浏览器进 网页后台 → 设置 → 系统 → 检查更新，发现新版本点 "升级" 即可——系统会自动拉取新镜像并重建容器（升级前自动备份数据库，新版本启动异常会自动回滚到升级前版本），几分钟后页面自动重连到新版本。

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

```bash
cd ~/skyview
docker compose -f compose.yml pull
docker compose -f compose.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.yml down
docker rmi registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-cpu:latest
# 录像 / 数据库继续保留，需要彻底清理：
rm -rf ~/skyview
```

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

---

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


# 群晖 Synology DSM 部署

群晖 Intel + 核显机型(DS920+ / DS423+ / DS1522+ / DS224+ 等)走 openvino 变体效果最好。本页一步步带你从 SSH 装好到浏览器 Setup。AMD/ARM 机型(DS223j / DS723+)无 /dev/dri,只能跑 cpu 变体,推理速度降一档但功能不变。

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

| 机型 | CPU | 推荐变体 | 备注 |
| --- | --- | --- | --- |
| DS920+ / DS1522+ / DS923+ | Intel J4125 / R1600 | openvino | Intel 核显 + 4-8 路 1080p 可用 |
| DS423+ / DS224+ | Intel N100 / N5105 | openvino | Alder Lake-N 集显,2-4 路 |
| DS1621+ / DS1821+ (Ryzen) | AMD V1500B | cpu | 无核显,推理慢 |
| DS223j / DS723+ (ARM) | Realtek / AMD R1600 | **不支持** | ARM 机型云瞰仅 amd64;Ryzen 无 iGPU |

## 2. 准备工作

1. **确认 DSM 版本**

   控制面板 → 信息中心 → DSM 版本 ≥ 7.2;低于此版本先升级

2. **装 Container Manager**

   套件中心搜 "Container Manager" 装好(老版本叫 Docker,7.2 起改名)

3. **建项目目录**

   File Station → /docker → 新建文件夹 yunkan;最终路径形如 /volume1/docker/yunkan/

4. **启用 SSH**

   控制面板 → 终端机和 SNMP → 启用 SSH;后面用 SSH 跑 docker compose(Container Manager GUI 不支持 devices 字段)

## 3. 获取 compose 文件

三种方式任选其一——浏览器直接下载、SSH 用 wget、或复制最小版手工粘贴:

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

群晖 DSM 7.2+ 专用模板 · openvino 变体 · 含完整注释

或在群晖 SSH 里直接 wget:

```bash
ssh admin@<群晖IP>
sudo -i
cd /volume1/docker/yunkan
wget https://yun-kan.com/compose/synology.yml -O compose.yml
```

> **💡 或者一键复制粘贴(最小版本)**
>
> 不想 wget 也可以复制下面的最小 compose,vi compose.yml 粘贴保存。同样能跑,只是少了详细注释。

```yaml
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:
      - ./data:/app/data
      - ./recordings:/app/data/recordings
      - /etc/machine-id:/etc/machine-id:ro
      - /sys/class/dmi/id/product_uuid:/sys/class/dmi/id/product_uuid:ro
    environment:
      - TZ=Asia/Shanghai
      - SKYVIEW_SELF_CONTAINER_NAME=yunkan
```

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

## 4. 启动云瞰

```bash
cd /volume1/docker/yunkan
docker compose up -d
# 看启动日志(Ctrl-C 退出):
docker logs -f yunkan
```

等约 30-60 秒各服务就绪,浏览器打开 `http://<群晖IP>:23406/` 进入 [Setup 向导](/docs/quickstart)。

## 5. 端口和防火墙放行

群晖默认 80/443/5000/5001 是 DSM 自己的网页,云瞰用 23406 系列(偏移到 2xxxx 区间)避免冲突。如果你开了 **控制面板 → 安全性 → 防火墙**,需要放行这 5 个端口:

- **23406/tcp** — 云瞰网页 + API + 直播(必须)
- **23515/udp + tcp** — 实时画面低延迟通道(**不开会自动降级到 HLS,延迟约 2.5 秒**)
- **23880/tcp** — RTSP 直连出(VLC / 第三方 NVR 用,可选)
- **24214/tcp** — 内部流媒体服务,局域网访问不需要开放

## 6. 常见问题

> **⚠️ Container Manager GUI 装不出来 iGPU 透传**
>
> Container Manager 的 "映像 → 启动 → 设备" 没有添加 `/dev/dri` 的入口。必须用 compose 文件(本页教程)或者用 SSH 跑 `docker run --device /dev/dri:/dev/dri ...`。

> **ℹ️ DS920+ / N100 机型 OpenVINO iGPU 失败回退**
>
> 部分群晖内核对 Alder Lake-N 的 i915 驱动支持不全,OpenVINO GPU plugin 可能初始化失败 → 自动回退到 CPU 推理。检测启动日志含 "GPU plugin failed, falling back to CPU" 即此情况,功能不受影响只是慢一点。

> **⚠️ License 激活报 SLOTS_FULL**
>
> 部分机型 DMI 里 product_uuid 没填,容器读到空值。云瞰会回退到只用 `/etc/machine-id` 算指纹,通常没事;若激活仍失败邮件 support@yun-kan.com 截图错误码处理。

**升级方式**:DSM Container Manager 限制 docker socket 访问,网页后台一键在线升级在群晖不可用(增量补丁不受影响)。手动升级:`docker compose pull && docker compose up -d --force-recreate yunkan`。

---

来源:https://yun-kan.com/zh-CN/docs/install-synology


# Unraid 部署

Unraid 用户**优先走 Community Applications 一键装**(Apps 搜 'yunkan' 即可,体验对齐 HA 加载项);需要自定义端口 / 旧版 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 socket)。**走下方 docker compose 路径**只有两种情况:(1) 需要自定义端口(镜像 hardcode,不能在容器面板改);(2) 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** 即可拉新镜像并重建容器;也可以直接在云瞰网页后台 → 设置 → 系统升级 一键升级(升级失败自动回滚)。两种方式效果一致,任选其一。

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

下面是手写 compose 的传统部署路径,**适用于需要自定义端口、或 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 变体 · 支持网页后台在线升级

或 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
```

*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/tcp(必须)、23515/udp + tcp(实时画面)、23880/tcp(RTSP,可选);24214/tcp 是内部服务,不需要对外开放。

> **⚠️ 不要公网暴露**
>
> 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。

**升级方式**:Unraid 上 docker socket 权限正常,网页后台一键在线升级开箱可用;也可手动 `cd /mnt/user/appdata/yunkan && docker compose pull && docker compose up -d`。

---

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


# 飞牛 fnOS 部署

飞牛 fnOS 基于 Debian 12,docker 一等公民。本页提供两种安装方式:应用中心上传 fpk 一键安装(最省事),或 docker compose 手动部署(N100 / N305 / N355 等 Intel 机型可走核显加速)。

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

| 机型 | CPU | 推荐变体 |
| --- | --- | --- |
| 飞牛官方主推机 | Intel N100 / N305 / N355 | openvino |
| DIY 机 | 11/12/13 代 i3-i5 + Iris Xe | openvino |
| DIY 机 | NVIDIA GTX/RTX | cuda 或 trt(显存 ≥ 8GB) |
| 纯 CPU | 无核显 | cpu |

## 2. 选哪种安装方式

| 安装方式 | 入口 | 适合人群 | 核显 / 独显加速 |
| --- | --- | --- | --- |
| fpk 一键安装 | 应用中心 → 本地安装 → 上传 fpk | 普通家庭用户 · 不想折腾 | 暂不支持(推理走 CPU) |
| docker compose | docker → 自定义项目 → 上传 compose | 想用核显 / 独显加速 · 需灵活改配置 | 支持(/dev/dri 透传) |

> **💡 怎么选**
>
> 图省事、N100 / N305 用 CPU 跑得动就选 **fpk 一键安装**;想让核显 / 独显真正参与推理加速,或需要自定义 compose,就用下面的 **docker compose** 方式。受飞牛应用包机制限制,fpk 的 compose 模板是静态的,无法注入 `/dev/dri` 设备透传,所以核显加速只能走 docker compose。

## 3. 方式一:应用中心一键安装(fpk · 推荐)

[下载飞牛应用包 yunkan-latest.fpk](https://cdn.yun-kan.com/yunkan-latest.fpk)

飞牛应用中心安装包 · 上传即装 · 镜像在安装时自动在线拉取

1. **下载 fpk**

   点上方按钮把 `yunkan-latest.fpk` 下载到电脑(也可直接在飞牛自带浏览器里下到 NAS)。

2. **打开应用中心 → 本地安装**

   飞牛桌面 → **应用中心** → 右上角 **本地安装**(部分版本叫「手动安装」)。

3. **上传 fpk 安装**

   选择刚下载的 `yunkan-latest.fpk`,确认上传,飞牛开始解析安装包。

4. **填写安装向导**

   弹出向导收集 3 个字段:**变体**(cpu / openvino,默认 openvino)、**镜像版本**(默认 latest)、**公网域名**(只有走反代公网部署才填,内网直接留空)。

5. **等待自动部署**

   飞牛自动 `docker pull` 镜像 + 建数据共享目录 + `docker compose up`,完成后桌面出现云瞰图标。首次拉镜像视网络耗时几分钟。

6. **进入 Setup 向导**

   点云瞰图标,或浏览器打开 `http://<飞牛IP>:23406/` 走 [Setup 向导](/docs/quickstart) 建管理员账号。

> **ℹ️ 数据放哪**
>
> fpk 自动建两个飞牛共享文件夹:`yunkan-data`(数据库 / 配置 / 日志)和 `yunkan-recordings`(录像)。两者在飞牛文件管理和 SMB 都可见;录像盘可在飞牛系统设置里单独移到大容量卷,不动状态盘。

> **⚠️ fpk 方式的两点限制**
>
> ① 不挂载核显 `/dev/dri`,推理走 CPU(openvino 变体会 fallback CPU 路径);② 不支持 NVIDIA cuda / trt 变体。需要核显 / 独显加速,请改用下面的 **docker compose** 方式。

## 4. 方式二:docker compose 手动部署(可走核显加速)

走飞牛「docker → 自定义项目」,compose 里直接 `/dev/dri` 透传,N100 / N305 等 Intel 机型让核显真正参与推理;后续也方便灵活改配置。

### 4.1 准备工作

1. **确认 docker 已装**

   fnOS 控制台 → 应用中心 → docker(出厂预装);或 SSH `docker --version` 应有输出

2. **建数据目录**

   fnOS 文件管理 → /vol1/1000/ 下新建 yunkan/,或 SSH `mkdir -p /vol1/1000/yunkan`(/vol1/1000/ 是飞牛的用户数据习惯路径)

### 4.2 获取 compose 文件

三种方式任选其一:

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

飞牛 fnOS 专用 · openvino 变体 · 支持网页后台在线升级

或 SSH 用 wget:

```bash
ssh <用户名>@<飞牛IP>
cd /vol1/1000/yunkan
wget https://yun-kan.com/compose/fnos.yml -O compose.yml
```

> **💡 或者粘贴最小版**
>
> 也可直接用 fnOS Web UI → docker → 自定义项目 → YAML 编辑器粘贴下面这段。

```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:
      - /vol1/1000/yunkan/data:/app/data
      - /vol1/1000/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
```

*compose.yml (最小版)*

### 4.3 启动云瞰

**方式 A · SSH**:

```bash
cd /vol1/1000/yunkan
docker compose up -d
docker logs -f yunkan
```

**方式 B · Web UI**:fnOS 控制台 → docker → 项目 → 新建 → 上传 compose.yml → 启动。

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

## 5. 端口和防火墙

飞牛默认 8088 是自身 Web 面板,云瞰 23406 系列无冲突。fnOS 默认不挡端口,LAN 内直接访问即可。若公网暴露务必走反代 + HTTPS。

## 6. 常见问题

> **ℹ️ iGPU 不工作**
>
> 飞牛 SSH `ls /dev/dri/` 应有 card0 + renderD128。没有的话查 `dmesg | grep i915` 看驱动是否正常加载;部分客户机型 BIOS 关了 iGPU,进 BIOS 打开 Internal Graphics。注意:fpk 一键安装不透传核显,核显加速请走 docker compose 方式。

**升级**:fpk 安装的走飞牛**应用中心**直接升级(或在向导里改镜像版本重装);docker compose 安装的在网页后台一键在线升级,也可手动 `docker compose pull && docker compose up -d`。

---

来源:https://yun-kan.com/zh-CN/docs/install-fnos


# 绿联 UGOS Pro 部署

绿联 UGOS Pro x86 机型(DXP2800 / DXP4800 / DXP6800 / DXP8800 等 N100/N305 系列)走 openvino 变体。**绿联部分入门型号是 ARM SoC,云瞰仅提供 amd64 镜像,ARM 机型暂不支持**。

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

| 机型 | CPU 架构 | 推荐变体 | 可用 |
| --- | --- | --- | --- |
| DXP2800 / DXP4800 / DXP6800 / DXP8800 | Intel x86 + 核显 | openvino | ✅ |
| DXP480T Plus / DXP4800 Plus | Intel x86 + 核显 | openvino | ✅ |
| DX4600 Pro (老款 ARM) | ARM Cortex | — | ❌ 仅 amd64 镜像 |
| 其它 ARM 机型 | ARM | — | ❌ |

> **⚠️ 购买前先查 CPU 架构**
>
> 绿联同型号有时混用 Intel 和 ARM 主板。在 UGOS Pro Web UI → 系统信息 → CPU 一栏,Intel 字样开头才能装云瞰。

## 2. 准备工作

1. **升级 UGOS Pro**

   确保 UGOS Pro 版本含 Container Manager(2024 年后机型出厂自带);老版本 UGOS 用户先升级

2. **建数据目录**

   UGOS 文件管理器 → /volume1/docker/ 下新建 yunkan/;最终路径 /volume1/docker/yunkan/

3. **启用 SSH(可选)**

   控制面板 → 终端 → SSH 启用;不开 SSH 也能用 Web Container Manager 完成部署,但 SSH 命令更直观

## 3. 获取 compose 文件

三种方式任选其一:

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

绿联 UGOS Pro 专用 · openvino 变体 · 支持网页后台在线升级

或 SSH 用 wget:

```bash
ssh <用户名>@<绿联IP>
cd /volume1/docker/yunkan
wget https://yun-kan.com/compose/ugos.yml -O compose.yml
```

> **💡 或者 Web UI 粘贴**
>
> UGOS Pro → Container Manager → 自定义项目 → YAML 编辑器粘贴下面最小版。

```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:
      - /volume1/docker/yunkan/data:/app/data
      - /volume1/docker/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
```

*compose.yml (最小版)*

## 4. 启动云瞰

```bash
cd /volume1/docker/yunkan
docker compose up -d
docker logs -f yunkan
```

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

## 5. 端口和防火墙

UGOS Pro Web Panel 占用 80/443/9999,云瞰 23406 系列无冲突。绿联默认 iptables 不严格挡端口,LAN 内可直接访问。

## 6. 常见问题

> **ℹ️ Container Manager 显示容器运行但访问不到**
>
> SSH `ss -tnlp | grep 23406` 看进程是否在监听;如果在则是防火墙问题,放行 23406/tcp + 23515(udp 与 tcp)即可,需要 RTSP 直连再加 23880/tcp。

> **ℹ️ iGPU 透传不生效**
>
> SSH `vainfo` 看 VAAPI 是否可用;`docker exec yunkan vainfo` 看容器内能否访问 iGPU。无输出请确认机器是 Intel CPU 且 BIOS 开了核显。

**升级**:Container Manager 重新拉镜像即可;或 SSH `docker compose pull && docker compose up -d`。

---

来源:https://yun-kan.com/zh-CN/docs/install-ugos


# TrueNAS Scale 部署

TrueNAS Scale 24.10+(Electric Eel)起 SCALE-Apps 已从 k3s 切换到 Docker,云瞰通过 Custom App YAML 即可部署。**仅 24.10+ 适用**,旧版 k3s 路线请先升级 TrueNAS。

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

| 硬件 | 推荐变体 | 备注 |
| --- | --- | --- |
| Intel CPU + 核显 | openvino | TrueNAS 内核默认带 i915 驱动 |
| NVIDIA GPU(GTX/RTX) | cuda 或 trt | Apps → Settings → GPU 可看 host GPU 列表 |
| 纯 CPU | cpu | 推理速度降一档但功能不变 |

> **⚠️ TrueNAS Scale 24.10 起才支持 Docker**
>
> 24.04 及之前是 k3s/Kubernetes,本文档的 Custom App YAML 走 Docker backend,仅 24.10+ 适用。升级前请按 iX-systems 官方迁移指南做备份。

## 2. 准备工作

1. **升级 TrueNAS 到 24.10+**

   系统设置 → 更新 → 选 24.10-Electric-Eel train,等迁移完成

2. **建 ZFS dataset**

   Datasets → 选个池 → 新建 yunkan-data dataset,路径形如 /mnt/pool0/apps/yunkan/data;后面 compose 把这里挂到 /app/data

3. **查 GPU**

   Apps → Settings → GPU 看 host 上检测到的 iGPU / NVIDIA,确认要走的变体

## 3. 获取 compose 文件

TrueNAS 推荐用 Custom App YAML 部署(走 UI),也可直接 SSH 跑 docker compose。三种获取方式任选其一:

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

TrueNAS Scale 24.10+ 专用 · openvino 变体 · 注意改 dataset 路径

或 SSH 用 wget(记得修改 dataset 路径):

```bash
ssh root@<TrueNAS IP>
cd /mnt/pool0/apps/yunkan
wget https://yun-kan.com/compose/truenas.yml -O compose.yml
# ★ 文件里 /mnt/pool0/apps/yunkan/data 改成你的真实 dataset 路径 ★
```

> **💡 Custom App YAML 方式(推荐)**
>
> TrueNAS UI → Apps → Discover Apps → 右上角 Custom App → App Name 填 yunkan → 在 Workloads/YAML 编辑器粘贴下面最小版(注意把 /mnt/pool0/apps/yunkan/data 换成你的 dataset 路径)。

```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/pool0/apps/yunkan/data:/app/data
      - /mnt/pool0/apps/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
```

*compose.yml (最小版,粘贴前替换 dataset 路径)*

## 4. 启动云瞰

**方式 A · Custom App**:Apps UI 里点 Save → Install,等状态变 Running。

**方式 B · SSH**:

```bash
cd /mnt/pool0/apps/yunkan
docker compose up -d
docker logs -f yunkan
```

启动后浏览器 `http://<TrueNAS IP>:23406/`(注意 TrueNAS UI 在 80/443,不冲突)进入 [Setup 向导](/docs/quickstart)。

## 5. 端口和防火墙

TrueNAS Scale Web UI 占用 80/443,云瞰 23406 系列无冲突。Scale 默认无额外防火墙,SCALE-Apps 走 host network 直接绑端口。

## 6. 常见问题

> **⚠️ 升级 24.04 → 24.10 后 App 不在了**
>
> k3s → Docker 迁移可能让旧 Custom App 不见,需要按本文档重新部署(数据卷仍在 ZFS dataset 里,重建容器即可恢复)。

> **ℹ️ /dev/dri 在 TrueNAS Custom App YAML 里报错**
>
> 确认 TrueNAS UI → Apps → Settings → GPU 已勾选 Allow Containers to Access。

**升级**:推荐通过 Apps UI 升级(Edit → 改 image tag → Save);或 SSH `docker compose pull && docker compose up -d`。

---

来源:https://yun-kan.com/zh-CN/docs/install-truenas


# Ubuntu / Debian 部署

标准 Linux 部署最干净。Ubuntu 22.04 / 24.04 LTS 或 Debian 12 (Bookworm) 上,docker + docker compose v2 都是 apt 一行命令的事,云瞰一键脚本会处理变体探测和 GPU 加速配置。

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

Ubuntu / Debian 几乎跑在所有 x86_64 机器上,**全 4 变体均可**,按硬件选:

| 硬件 | 推荐变体 |
| --- | --- |
| Intel 11 代+ 集显 / NPU | openvino |
| NVIDIA GPU + 显存 < 8GB | cuda |
| NVIDIA GPU + 显存 ≥ 8GB | trt(比 cuda 还快) |
| 纯 CPU / AMD CPU 无独显 | cpu |

## 2. 装 docker

Ubuntu / Debian 都用 Docker 官方一键脚本:

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

> **💡 NVIDIA GPU 用户额外装**
>
> 想用 cuda/trt 变体先装 [nvidia-container-toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#installing-with-apt);命令大致 `sudo apt install nvidia-container-toolkit && sudo systemctl restart docker`。

## 3. 用一键脚本部署(推荐)

云瞰一键脚本会自动探测硬件、选合适的镜像变体、拉镜像、起容器,5-15 分钟搞定:

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

脚本完成后直接给浏览器访问地址(类似 `http://192.168.1.10:23406/`),进 [Setup 向导](/docs/quickstart)。

## 4. 或者手动 compose

想自己控制配置——浏览器下载、SSH wget、或复制下面最小版手工粘贴,三种任选;通用 Linux 模板默认 openvino 变体,只需把 image 改成你的硬件对应变体即可:

[浏览器下载通用 compose 模板](/compose/ubuntu-debian.yml)

通用 docker compose 模板 · 需手动改 image 标签为 yunkan-cpu / yunkan-openvino / yunkan-cuda / yunkan-trt

或 SSH 用 wget:

```bash
mkdir -p ~/yunkan && cd ~/yunkan
wget https://yun-kan.com/compose/ubuntu-debian.yml -O compose.yml
# 把 image 改成符合你硬件的变体(yunkan-cpu / yunkan-openvino / yunkan-cuda / yunkan-trt)
docker compose up -d
```

或直接复制下面最小版内容,存成 `compose.yml` 再 `docker compose up -d`(默认 openvino 变体,纯 CPU 机型把 image 改 yunkan-cpu 并删掉 devices 段):

```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:
      - ./data:/app/data
      - ./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
```

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

## 5. 防火墙(UFW)

Ubuntu 默认 UFW 关闭。如果你启用了 UFW,需要放行:

```bash
sudo ufw allow 23406/tcp
sudo ufw allow 23515
sudo ufw allow 23880/tcp
sudo ufw reload
```

## 6. 常见问题

> **ℹ️ AppArmor 拒绝设备访问(罕见)**
>
> Ubuntu 默认 AppArmor 开,云瞰容器走 docker-default profile 不踩坑。如果报错(几乎不会),compose 加 `security_opt: ["apparmor=docker-default"]`。

> **ℹ️ Debian iGPU 驱动版本旧**
>
> Bookworm 仓库 `intel-media-va-driver` 版本对 Alder Lake-N(N100/N305)支持不完整。建议 `apt install -t bookworm-backports intel-media-va-driver-non-free` 拿新版本。

**升级**:全功能可用——网页后台 → 设置 → 系统 → 检查更新 一键升级;或手动 `docker compose pull && docker compose up -d`。

---

来源:https://yun-kan.com/zh-CN/docs/install-ubuntu-debian


# Fedora 部署

Fedora 39+ 默认装的是 podman,要跑云瞰需要明示装 docker-ce。**SELinux 默认 enforce + firewalld 默认开**,卷标签和端口放行不能少。

## 1. 装 docker-ce(不是 podman)

Fedora 默认 podman,但云瞰镜像和 docker-compose 文件按 docker 兼容性测试。podman 兼容大部分但 host network 模式行为略有差异,推荐换 docker-ce:

```bash
sudo dnf -y install dnf-plugins-core
sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo
sudo dnf -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER
```

## 2. 处理 SELinux(关键)

> **⚠️ 卷挂载必须加 :Z 或 :z 标签**
>
> Fedora SELinux **强制启用 enforce 模式**,容器写入数据卷会被拒绝,除非给卷打 `:Z`(私有,推荐)或 `:z`(共享)标签。详见 compose 示例。

## 3. 放行 firewalld 端口

```bash
sudo firewall-cmd --permanent --add-port=23406/tcp
sudo firewall-cmd --permanent --add-port=23515/udp
sudo firewall-cmd --permanent --add-port=23515/tcp
sudo firewall-cmd --permanent --add-port=23880/tcp
sudo firewall-cmd --reload
```

## 4. 启动云瞰

我们为 Fedora 单独维护了一份 compose 模板(`:Z` SELinux 标签全部预置好),不用手动改:

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

Fedora 专用 · openvino 变体 · :Z 标签已预置 · 支持网页后台在线升级

或 SSH 用 wget:

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

> **💡 其它变体如何切**
>
> 本模板默认 yunkan-openvino(Intel iGPU)。纯 CPU 改 `image:` 为 `yunkan-cpu`;NVIDIA GPU 改为 `yunkan-cuda` 或 `yunkan-trt` 并取消 `deploy:` 注释。无论哪个变体,`:Z` 卷标签都必须保留(SELinux 强制)。

```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:
      - ./data:/app/data:Z
      - ./recordings:/app/data/recordings:Z
      - /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:z
    environment:
      - TZ=Asia/Shanghai
      - SKYVIEW_SELF_CONTAINER_NAME=yunkan
```

*compose.yml Fedora 版(关键行加 :Z)*

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

## 5. 常见问题

> **⚠️ 容器启动后写录像 Permission denied**
>
> 几乎肯定是 SELinux 卷标签问题。`docker compose down`,在 compose volumes 行末加 `:Z`,`docker compose up -d` 重启即可。`/etc/machine-id` 和 `/sys/class/dmi/id/product_uuid` 是只读不需要标签(也可加 `:ro,Z` 防止误拒)。

> **ℹ️ NVIDIA GPU 在 Fedora**
>
> nvidia-container-toolkit 有 Fedora 包,装好后 `runtime: nvidia` 即可。详见 [NVIDIA 官方文档](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#installing-with-yum-or-dnf)。

**升级**:全功能可用——网页后台一键升级,或手动 `docker compose pull && docker compose up -d`。

---

来源:https://yun-kan.com/zh-CN/docs/install-fedora


# Proxmox VE LXC 部署(iGPU 透传)

推荐路径:PVE host → privileged LXC 容器 → 容器内 docker → 云瞰镜像。**不要直接在 PVE host 上装 docker**(Proxmox 官方不推荐,会和 PVE 的 iptables / apt 冲突)。LXC 是 namespace 隔离,性能损耗近零,/dev/dri 透传体验和 host 跑 docker 几乎一致。

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

| 机型 | 推荐变体 | iGPU 状态 |
| --- | --- | --- |
| N100 / N305 / N355 mini PC | openvino | Alder Lake-N 核显,/dev/renderD128 可用 |
| J4125 / J4105 老 NUC | openvino | Apollo Lake 核显,/dev/renderD128 可用 |
| i3-i7 11 代+ + Iris Xe | openvino | 性价比首选 |
| NVIDIA GPU PVE 主机 | cuda 或 trt | 需 PVE host 装 NVIDIA 驱动 + LXC 透传 /dev/nvidia* |

## 2. 准备工作(在 PVE host 上)

1. **确认 host 有 /dev/dri**

   PVE shell 跑 `ls -la /dev/dri/`,应有 card0/card1 + renderD128;否则 PVE 内核没加载 i915,先 `modprobe i915`

2. **下载 Debian 12 模板**

   PVE Web UI → local → CT Templates → Templates 按钮 → 找 debian-12-standard 下载(或 `pveam download local debian-12-standard_12.x_amd64.tar.zst`)

3. **查 render/video 组的 GID**

   PVE shell 跑 `getent group render` 和 `getent group video`,记下 GID(默认 render=104, video=44),后面 pct set 要用

## 3. 建 LXC 容器

```bash
# 在 PVE host shell:建一个 vmid=101 的容器,4 核 4G 内存 40G 硬盘
pct create 101 local:vztmpl/debian-12-standard_12.12-1_amd64.tar.zst \
  --hostname yunkan \
  --cores 4 --memory 4096 --swap 1024 \
  --rootfs local-lvm:40 \
  --net0 name=eth0,bridge=vmbr0,ip=dhcp,firewall=0 \
  --unprivileged 0 \
  --features nesting=1,keyctl=1 \
  --onboot 1

pct start 101
```

> **⚠️ 必须 privileged + nesting=1 + keyctl=1**
>
> `--unprivileged 0` = privileged LXC,这是家用最简选择(unprivileged 跑 docker 需要 90+ 行 lxc.conf 调优)。`nesting=1` 让容器内能再跑 docker,`keyctl=1` 让 docker overlayfs 工作。

## 4. 透传 iGPU 给 LXC

```bash
# 在 PVE host:透传 renderD128 和 card1 给 vmid=101
pct set 101 -dev0 /dev/dri/renderD128,gid=104   # render group
pct set 101 -dev1 /dev/dri/card1,gid=44         # video group

# 重启容器让 dev 透传生效
pct reboot 101

# 验证:进容器看 /dev/dri 是否存在
pct exec 101 -- ls -la /dev/dri/
```

## 5. LXC 内装 docker + 跑云瞰

```bash
# 进 LXC
pct enter 101

# 装 docker
curl -fsSL https://get.docker.com | sh

# 跑云瞰一键脚本(自动选 openvino 变体,因为检测到 /dev/dri)
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash
```

脚本完成后给一个 LXC IP + 端口(例如 `http://10.0.0.148:23406/`)。从同网段任意机器浏览器访问进 [Setup 向导](/docs/quickstart)。

## 6. 升级

升级在 LXC 内操作(`pct enter 101` 进容器),和普通 Linux 裸机完全一样,没有 LXC 专属步骤。首选方式 A(网页后台一键升级,免登命令行);想手动锁定版本或偏好命令行时用方式 B / C。

### 方式 A:网页一键升级(推荐)

打开 Web Admin → 设置 → 系统升级,点升级即可。系统会自动拉取新镜像并重建主容器(升级瞬间会临时出现一个一次性执行容器,完成后自动消失),新版起不来还会自动回滚到上一版,全程不用登命令行。LXC 内 docker socket 正常,这条路完全可用。

### 方式 B:命令行升级

想手动控制升级时机、锁定特定版本时用。进 LXC 后到部署目录(默认 `~/skyview`)执行:

```bash
pct enter 101
cd ~/skyview

# 升到当前 tag(默认 latest)的最新镜像并重建
docker compose -p yunkan -f compose.yml up -d --pull always
```

要锁定到指定版本,先改 compose 里的 image tag 再重建(注意保持变体不变,见下方警告):

```bash
cd ~/skyview
# 把 0.9.9 换成目标版本号
sed -i 's|image: .*/yunkan-.*|image: registry.cn-hangzhou.aliyuncs.com/yunkan/yunkan-openvino:0.9.9|' compose.yml
docker compose -p yunkan -f compose.yml up -d --pull always --force-recreate
```

> **⚠️ 升级时别换错变体**
>
> image tag 里的变体(`openvino` / `cpu` / `cuda` / `trt`)必须和原来一致 —— LXC + iGPU 透传装的是 `openvino`,误填成 `cpu` 会丢硬件加速。不确定先 `docker ps` 看当前镜像名里是 `-openvino` 还是 `-cpu`。`data/` 与 `recordings/` 卷跨版本兼容,DB 迁移由新容器启动时自动跑,升级不丢数据。

### 方式 C:重跑安装脚本

一键脚本是幂等的,重跑会重新拉镜像、重新生成 compose、重建容器。适合想把老装机刷成最新标准布局(顺带清理旧版 yunkan-updater 升级容器)的场景:

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

## 7. 备份 / 恢复

- **LXC 快照**:升级前 `pct snapshot 101 pre-upgrade-$(date +%Y%m%d)`,出问题 `pct rollback 101 <快照名>` 秒回滚整个容器
- **LXC 备份**:`vzdump 101 --storage local` 把整个容器(含 docker volume)走 PVE 标准备份;或 Web UI → 选 101 → Backup
- **恢复**:`pct restore <新 vmid> <备份文件>` 从备份还原
- **不要 destroy + create 重建**:LXC 重建会让 `/etc/machine-id` 变,license 指纹漂移 → 占新 slot 死循环。要重置一律走 `pct restore` 从备份恢复,不要新建容器

## 8. 常见问题

> **ℹ️ /dev/dri 不出现在 LXC 里**
>
> 确认 pct set 命令正确(注意 gid 数字按你 host 实际查的);重启容器 `pct reboot 101`;再不行 `pct config 101 | grep dev` 看配置有没有写进去。

> **ℹ️ docker run 报 keyctl 错**
>
> 建容器时漏加 `--features keyctl=1`。可补:`pct set 101 --features nesting=1,keyctl=1`,然后 `pct reboot 101`。

> **💡 把所有 LXC 集中管理**
>
> PVE Web UI → Datacenter → 选 LXC 101 → 可视化看 CPU/内存/磁盘/网络;比直接登 host 跑 docker stats 友好。

---

来源:https://yun-kan.com/zh-CN/docs/install-pve-lxc


# Home Assistant OS 加载项部署

Home Assistant OS 或 HA Supervised 用户,通过加载项(Add-on)方式一键装云瞰。云瞰提供两个加载项:`yunkan`(CPU 通用版)和 `yunkan-openvino`(Intel iGPU 加速版)。

## 1. 适用范围

> **⚠️ 仅 amd64 架构**
>
> 云瞰加载项目前只发布 amd64 镜像。**Raspberry Pi(armv7/aarch64)/ HA Green / HA Yellow 等 ARM 主机不支持**。Intel NUC / 小主机 / x86 PC 装 HA OS 才能用。

| 加载项 | 适用硬件 | 推理速度 |
| --- | --- | --- |
| **yunkan** | 任何 amd64 HA OS 主机 | 纯 CPU |
| **yunkan-openvino** | Intel CPU + 核显(11 代+ Iris Xe / N100 / N305) | iGPU 加速,推荐 |

> **ℹ️ 只能装一个**
>
> 两个加载项端口完全相同(都是 23406 / 23880 / 24214 / 23515),**不能同时启用**。Intel 机型选 yunkan-openvino,其它选 yunkan。

## 2. 添加云瞰仓库

**推荐方式:一键跳转。** 在能访问 HA 的设备上打开本页,点下方徽章,`my.home-assistant.io` 会自动找到你的 HA 并预填仓库地址,确认即可。

[![添加到 Home Assistant](https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg)](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fmrtian2016%2Fyunkan-hassio-addons)

首次点击会要求填入你的 HA 地址(如 `http://homeassistant.local:8123`),后续会记住。如果跳转失败或没装 My Home Assistant 组件,使用下方手动方式。

**手动方式:**

1. **进入加载项商店**

   HA 网页 → 设置(Settings) → 加载项(Add-ons) → 加载项商店(Add-on Store)

2. **添加自定义仓库**

   右上角三点菜单 → 仓库(Repositories) → 粘贴下方 URL → 添加(Add)

3. **粘贴这个 URL**

   下面整段地址,直接复制粘贴:

```text
https://github.com/mrtian2016/yunkan-hassio-addons
```

添加后页面会刷新,加载项商店底部会多出 "Yunkan" 一栏,里面有 `yunkan` 和 `yunkan-openvino` 两个卡片。

## 3. 安装并启动

1. **选变体**

   Intel 机型点 `yunkan-openvino`,其它点 `yunkan`

2. **安装**

   右下角 "安装(Install)" 按钮,等下载完成(镜像 ~700MB,首次几分钟)

3. **配置(可选)**

   "配置(Configuration)" 标签页:默认设置即可工作;有特殊需求(自定义端口、时区)在这调

4. **启动**

   "信息(Info)" 标签页 → "启动(Start)" 按钮

5. **开启自启动 + Watchdog**

   下方两个开关都打开:"启动时启动" + "Watchdog";确保 HA 主机重启或加载项崩溃自动拉起

6. **打开网页**

   侧边栏会出现 "云瞰" 入口(或访问 `http://<HA 主机IP>:23406/`)进入 [Setup 向导](/docs/quickstart)

## 4. 数据持久化

加载项数据自动放到 HA 的 `/share/yunkan/` 目录(录像、数据库、模型、115 cookies 都在这)。这个目录:

- **HA OS 备份会带上** — Supervisor → Backups 做整机备份会包含 `/share/`,云瞰数据跟着走
- **外部 SMB 可访问** — HA 默认 Samba 加载项映射 `/share/`,可以从电脑/NAS 浏览录像文件
- **升级不会丢** — 加载项升级只换镜像,/share 持久化数据保留

## 5. 升级

云瞰加载项走 HA 加载项标准升级流程:HA 检测到新版本会通知(右下角 + 设置 → 加载项 → 当前加载项 → 上方黄色横条),点 "更新" 即可。云瞰网页后台会自动识别加载项环境并给出对应升级指引,无需安装任何额外升级组件。

## 6. 常见问题

> **ℹ️ 我的是 Raspberry Pi 装的 HA,怎么办?**
>
> RPi 是 ARM 架构,云瞰加载项目前不支持。买个二手 Intel mini PC(N100 / 11 代 NUC 等)装 HA OS 是常见解。或者只装 HA OS 在 RPi,云瞰单独装在另一台 x86 机器上,两端通过 [MQTT 桥接](/docs/automation#home-assistant-%E6%A1%A5%E6%8E%A5)联动。

> **ℹ️ iGPU 加速没生效(yunkan-openvino 变体)**
>
> 加载项 config 已写好 `devices: [/dev/dri:/dev/dri:rwm]`,理论上自动透传。失败原因常见:host 没核显(查 HA Supervisor → Host system → CPU 是不是 Intel)、HA OS 内核不支持机型 iGPU。回退到 yunkan(CPU)变体仍可工作。

> **⚠️ 切变体不要直接覆盖装**
>
> 想从 yunkan 切到 yunkan-openvino(反之亦然):先卸载旧的(数据保留在 /share/yunkan/) → 装新的 → 启动后会复用 /share 里的旧数据,无需重新设置。同时启用两个会端口冲突。

---

来源:https://yun-kan.com/zh-CN/docs/install-ha-addon


# 首次启动

镜像跑起来后，浏览器打开服务器 IP 的 23406 端口，会自动跳到 /setup 向导。整套首启流程通常 5 分钟内完成。

## 1. 选数据库类型

向导第一步要选 **SQLite** 还是 **MySQL/MariaDB**：

| 选项 | 适合 | 说明 |
| --- | --- | --- |
| **SQLite（默认推荐）** | 家庭单机部署 | 数据库就是一个文件，零配置零运维 |
| **MySQL/MariaDB** | 多机 / 大规模 / 已有 MySQL | 需要自己部署或选 "内置 MariaDB" 让镜像启一份 |

> **💡 选 SQLite 不丢人**
>
> SQLite 在 200 路以下摄像头、单服务器部署完全够用。性能瓶颈基本永远是磁盘 IO（录像）和 GPU（检测），不是数据库。

## 2. 创建管理员账号

用户名 + 密码（≥ 8 位，含字母和数字）。这个账号是网页后台的最高权限，能删摄像头、改全局配置，建议给一个强密码。

> **⚠️ 忘记管理员密码怎么办**
>
> 目前没有内置 CLI 重置工具。临时解决：进数据库（SQLite 用 `sqlite3 data/skyview.db`、MySQL 用 `mysql -u skyview -p`）执行 `DELETE FROM users;` 清空用户表，浏览器刷新会重新跳到 Setup 向导让你创建首位管理员，摄像头、人脸库、自动化规则等其它数据都不受影响。所以**记好密码**，或者用密码管理器存一份。

## 3. 配置完成，进入网页后台

向导写完配置后会自动重启服务并跳到登录页。用刚才创建的账号登录，进入控制台首页。

## 4. 添加第一台摄像头

左侧导航 → 摄像头 → 添加。支持两种接入：

- **ONVIF 自动发现**（推荐）：摄像头和服务器在同一局域网时点 "扫描"，几秒钟列出所有 ONVIF 设备
- **手动 RTSP**：粘贴 `rtsp://用户名:密码@相机IP:554/stream1` 这种 URL

> **ℹ️ 推荐 ONVIF 接入**
>
> ONVIF 自动拿 PTZ 能力、对讲端口、子码流地址，省去你查厂商手册。凭证加密落库。

## 5. 看到画面就成功了

添加完跳到 Live 页面，应该 3–8 秒看到画面。优先用低延迟通道（< 500ms），如果不通自动切换到稳定通道（2–4s）。

> **⚠️ 卡在缓冲圈**
>
> 看不到画面通常是：RTSP URL 不对（密码错 / 路径错）、防火墙挡了 23515 UDP 端口、相机用了私有协议（如 Tapo）。详见 [排错](/docs/troubleshooting)。

## 6. 启用录像（可选）

默认录像是开着的，按时间分段写到 data 目录下。如果要关或只录某些时段，到 摄像头详情 → 录像设置 调。

## 下一步看哪里

- 想加更多摄像头 → [摄像头接入](/docs/cameras)
- 想看回放 → 直接到网页后台的 "回放" 页用时间轴拖
- 想开 AI 检测（运动 / 人脸 / 车牌） → [AI 检测](/docs/detection)
- 出问题了 → [排错](/docs/troubleshooting)

---

来源:https://yun-kan.com/zh-CN/docs/quickstart


# 摄像头接入

云瞰 原生只接 RTSP 和 ONVIF。私有协议（Tapo / 小米 / Wyze 等）走 go2rtc 桥接成 RTSP 后再加进来。本章覆盖各种接入场景和高级特性。

## ONVIF 自动发现（首选）

如果摄像头和 云瞰 在同一局域网，且摄像头开了 ONVIF（出厂默认开）：

1. **扫描**

   网页后台 → 摄像头 → 添加 → 选 "ONVIF 自动发现"，几秒后列出局域网内所有 ONVIF 设备

2. **选目标**

   看 IP / MAC / 厂商对得上自己的相机，点选

3. **填凭证**

   ONVIF 用户名密码（不一定等于 RTSP 密码！海康/大华出厂常是 admin/12345 之类）

4. **保存**

   云瞰 自动协商主码流 / 子码流地址，并把 PTZ / 对讲端口探测出来一起存好

> **⚠️ ONVIF 返回错 IP**
>
> 某些不规范固件会返回相机内部硬编码的 IP（如 192.168.1.99）而不是局域网真实地址。云瞰 加摄像头时会自动测试主+子码流，任一不通就拒绝保存。这种情况只能改用手动 RTSP。

## 手动 RTSP

ONVIF 不支持或拿到错地址时用手动方式。需要从厂商手册或 IPC App 里找 RTSP URL，常见格式：

| 品牌 | RTSP 主码流地址示例 |
| --- | --- |
| 海康（Hikvision） | `rtsp://用户:密码@IP:554/Streaming/Channels/101` |
| 大华（Dahua） | `rtsp://用户:密码@IP:554/cam/realmonitor?channel=1&subtype=0` |
| TP-Link Vigi（IPC，非 Tapo） | `rtsp://用户:密码@IP:554/stream1` |
| 小米 / Aqara / 乐橙等私协 | **不支持**直连 RTSP，走下面 go2rtc 方案 |

> **💡 用 VLC 验证**
>
> 添加前先用 VLC（媒体 → 打开网络串流）粘贴 URL 验证能播。VLC 能播 云瞰 才能播；VLC 都播不了就不是 云瞰 的问题。

## Tapo / 小米 / Wyze 等私协 → go2rtc 桥接

TP-Link Tapo C100/C200/C220、小米米家、Wyze 这类消费级摄像头**不开标准 RTSP**，但社区项目 [go2rtc](https://github.com/AlexxIT/go2rtc) 能把它们桥接成 RTSP 让 云瞰 接入。

1. **起一个 go2rtc 容器**

   和 云瞰 同一台机器即可，端口 1984 是 go2rtc 的网页界面、8554 是它对外提供的 RTSP。

   ```bash
   docker run -d --name go2rtc \
     --restart=always \
     --network host \
     -v $(pwd)/go2rtc.yaml:/config/go2rtc.yaml \
     alexxit/go2rtc
   ```

2. **在 go2rtc.yaml 里配相机**

   Tapo 例：用 Tapo App 的访客账号即可。

   ```yaml
   streams:
     livingroom: tapo://访客密码@相机IP:554/stream1
     kitchen: tapo://访客密码@另一台IP:554/stream1
   ```

3. **在 云瞰 里加摄像头**

   用 RTSP 手动方式，URL 填 `rtsp://<go2rtc 主机IP>:8554/livingroom`，凭证留空。

> ℹ️ go2rtc 不在 云瞰 维护范围内，遇到问题去看 go2rtc 的 README。云瞰 这边只看到 RTSP 流，对接来源透明。

## 子码流的意义

ONVIF / 主流 IPC 都提供两路：**主码流**（高清，看 Live 用）和**子码流**（低清，AI 检测用）。云瞰 自动用 ONVIF 拿到子码流地址。手动 RTSP 时建议在第二个字段填子码流 URL，可以让检测节省 70%+ 带宽和 CPU。

> **💡 子码流降资源**
>
> AI 检测分辨率 416x416 就够，喂 1080p 主码流是浪费。子码流通常是 640x360 / 480p，正合适。

## 视频编码：尽量选 H.264，不要 H.265

H.265 (HEVC) 同画质下码率比 H.264 低 40~50%，看上去很省，但**浏览器播放支持很差**——大多数用户进 Web 后台看 Live 或回放会黑屏 / 转圈。开摄像头前请把编码格式改成 H.264。

| 客户端 | H.264 | H.265 (HEVC) |
| --- | --- | --- |
| Chrome / Edge (Windows / Linux) | ✅ 完美支持 | ❌ 默认不解码，黑屏 / 转圈 |
| Safari (macOS / iOS) / Chrome (macOS) | ✅ 完美支持 | ✅ 支持，但部分老机型卡顿 |
| 云瞰 Android / iOS App | ✅ 完美支持 | ✅ 原生播放器，完美支持 |

> **⚠️ 怎么改**
>
> 登录摄像头自带的网页后台 → **视频 / 编码设置** → 视频编码改成 `H.264`。**主码流和子码流都要改**。海康部分机型有 `H.264+` 这种魔改格式，选**标准 H.264** 最稳。改完用 VLC 验证一次能正常播。

> **ℹ️ 录像空间多一倍可以接受**
>
> H.264 比 H.265 占用约多一倍磁盘（1080p 约 21 GB / 路 / 天 vs H.265 约 10 GB），但换回所有浏览器后台都能直接看 Live + 回放，体验差距远大于磁盘成本。10 路保 30 天约 6.3 TB，按现在 HDD 价位完全划算。如果**只用云瞰 App、从不开网页后台**，那 H.265 也能省一半空间。

## PTZ 控制（云台）

ONVIF 接入的相机如果支持 PTZ，Live 页面右下角自动出方向 / 缩放按钮。手动 RTSP 接入的不会自动启用，需要在摄像头详情里手动填 ONVIF 端口（通常 80 / 8000）和 PTZ 凭证。

## 对讲（Talkback）

支持 ONVIF 对讲通道的相机可以双向对讲（按住 App 上的麦克风按钮讲话，对方听得到）。网页后台暂不支持发起对讲，移动端（iOS / Android）才有按住 talk 按钮。

> **⚠️ 切相机要先松手**
>
> 对讲是一个长连接喂音频。切相机时务必先松手再切，App 会自动结束旧会话再开新的——同时按住切相机会出现声音错位。

## 改 / 删摄像头注意事项

- 改 RTSP URL 后，**检测可能不会自动重启**：因为针对该相机有 "检测失败" 状态记录，需要在摄像头详情里点 "清除检测错误" 才能重新跑
- 删摄像头会同步删数据库记录和流媒体路径，但**录像文件不删**——避免误删丢证据。手动到 `data/recordings/<id>/` 删
- 改名 / 改分组都不影响录像和事件历史

## 海康 / 大华 / TP-Link Vigi（专业 IPC）

这三家是国内主流商用 IPC，全系标准 ONVIF + RTSP，云瞰 兼容性最好。出厂默认凭证：

| 品牌 | 默认账号 | 首次接入要点 |
| --- | --- | --- |
| 海康 | admin / 自定义（首启时强制改） | 如果 ONVIF 拿不到流，登录相机网页启用 ONVIF 协议 |
| 大华 | admin / admin | 默认 ONVIF 端口 80 与 HTTP 共用 |
| TP-Link Vigi | admin / 自定义 | 出厂 ONVIF 关闭，要先用 Vigi App 启用 |

## GB28181 国标接入（海康 / 大华 / 宇视 NVR·IPC·DVR）

国标（GB/T 28181）设备**主动注册**进 云瞰——不用逐台填 RTSP 地址，一台 NVR 下的多个通道也能批量导入。海康 / 大华 / 宇视的国标 IPC、NVR、DVR 绝大多数内置「国标上级平台接入」。需要 云瞰 **0.9.13 及以上**。

> **ℹ️ 默认关闭，升级无感**
>
> 国标功能默认不开启时进程空转、不占端口，从老版本升级上来不开国标的用户完全不受影响。信令端口 **25060/udp**、收流端口 **30000/udp**；host 网络（一键安装 / 单镜像 / docker-compose 默认）下局域网内自动暴露，开箱即用。

### 第一步：在 云瞰 里开启国标

1. **打开开关**

   Web Admin → **设置 → 国标（GB/T 28181）** → 打开「启用」。

2. **设注册密码**

   页面会显示要填进设备的平台参数，并让你设一个**注册密码**（所有设备共用）。默认平台参数通常直接可用。

3. **公网部署填 extern_host**

   设备和 云瞰 不在同一局域网时，把**设备能回连到的我方地址**（公网 IP 或路由器映射后的地址）填进「extern_host」；同网段裸直连可留空。

4. **保存**

   保存后国标服务开始在 25060 监听，等待设备注册。

| 平台参数 | 默认值 | 说明 |
| --- | --- | --- |
| 平台 SIP ID / 上级编号 | 34020000002000000001 | 设备里填的「上级平台国标编号」 |
| SIP 域 / Realm | 3402000000 | 留空自动取 SIP ID 前 10 位 |
| SIP 服务器地址 | 云瞰主机 LAN IP（如 192.168.1.50） | 设备要能连到这个地址 |
| SIP 服务器端口 | 25060 |  |
| 注册密码 | 自己设一个 | 所有设备共用 |

### 第二步：在设备 / NVR 里配置「国标上级平台」

进设备 Web 后台，找「平台接入 / 国标 28181 / 上级平台」（各家叫法略不同），按下表填。保存后设备会主动注册——NVR 会一并上报它下面的所有通道：

| 设备里的字段 | 填什么 |
| --- | --- |
| 上级平台 SIP 服务器 ID | 云瞰的 SIP ID（34020000002000000001） |
| SIP 服务器域 | 云瞰的 SIP 域（3402000000） |
| SIP 服务器地址 / IP | 云瞰主机地址（局域网填 LAN IP；公网填 extern_host 的地址） |
| SIP 服务器端口 | 25060 |
| 注册用户名 / 本设备国标编号 | 设备自带的 20 位国标编号，或自己编一个 |
| 注册密码 | 你在 云瞰 设的注册密码 |
| 传输协议 | UDP |

### 第三步：导入通道，当普通摄像头用

回 Web Admin → **国标** 页 → 「待导入设备 / 通道」：注册成功的设备 / NVR 通道会出现在这里。勾选要用的通道点「导入」（可批量，一台 NVR 多通道一次搞定）。导入后这些通道就是普通摄像头——直播、录像、AI 检测、快照、在线状态、云台 + 预置位、语音对讲、设备端历史回放全部可用，和 RTSP / ONVIF 相机在界面上没有区别。

> **⚠️ 公网 / 跨网段部署**
>
> 设备和 云瞰 不在同一局域网时：① 路由器 / 防火墙把 **25060/udp** 和 **30000/udp** 转发到 云瞰 主机；② 设置里 **extern_host** 必须填设备能回连的我方地址（公网 IP 或 DDNS），否则会出现「设备注册上了却没有画面」。

| 端口 | 协议 | 用途 |
| --- | --- | --- |
| 25060 | UDP | 国标 SIP 信令（注册 / 目录 / 起停流） |
| 30000 | UDP | 国标 RTP 收流（设备推流，多路共用一个端口） |

> **💡 接不上 / 没画面怎么查**
>
> **一直注册不上**：设备能否 ping 通 云瞰 主机、25060/udp 是否被防火墙拦或未做端口转发、SIP ID / 域 / 密码是否与 云瞰 一致。**注册上了但没画面**：多半是 extern_host 没填或填错（设备回连不到），再查 30000/udp 是否放行。**NVR 只出部分通道**：在线通道按周期增量同步，稍等或在国标页刷新，离线通道不会出现。

---

来源:https://yun-kan.com/zh-CN/docs/cameras


# 录像与存储

云瞰 默认本地分段录像，可选挂 115 网盘做云备份。本章讲解录像机制、保留策略、和 115 接入。

## 录像怎么写

云瞰 把每路相机的视频按时间切成一段段标准 MP4 文件，**每段固定 60 秒**。每段写完就是一个可以直接播放的完整文件，进度条能立刻拖动，不需要等待任何转码。落盘路径：

```text
data/recordings/
  <camera_id>/
    2026-05-18_14-30-00.mp4
    2026-05-18_14-31-00.mp4
    2026-05-18_14-32-00.mp4
    ...
```

> ℹ️ 分段录像让回放可以精确 seek 到任意时间点。如果一段坏了（断电、网络抖动），最多丢 60 秒，相邻段不受影响。文件名里的时间戳就是该段的起始时刻（本地时区）。

> **ℹ️ 归档后的路径**
>
> **本地存储**模式下，每段录像被入库并打上 `archived` 状态后，会被原子 `rename` 到 `data/recordings/_archive/<camera_id>/` 下，目录结构和文件名完全镜像，方便和正在写入的 inbox 区分开。`_archive/` 前缀是约定，uploader 的 discovery 扫描会跳过它，避免归档文件被反复处理。**115 网盘**模式下本地是否保留由 `delete_after_upload` 设置决定（默认上传成功即删）。

## 本地存储路径

录像写在 `/app/data/recordings`（嵌套挂载，可单独指到大盘 / NAS），数据库 / cookies / 日志等小状态在 `/app/data`，AI 模型已内置在镜像里、不落数据目录。生产部署务必把录像目录指到容量充足的大盘，不要跟系统盘挤在同一个分区——录像满了会让你的服务器开不了机。

```bash
# 推荐：录像单独挂一块大盘 / NAS（小状态留在 data/）
sudo mkdir -p /mnt/recordings
# 一键脚本：--recordings-dir 指到大盘
curl -fsSL https://cdn.yun-kan.com/yunkan-install.sh | bash -s -- --recordings-dir /mnt/recordings
# 或手动 docker run 时嵌套挂录像卷
docker run -v $(pwd)/data:/app/data -v /mnt/recordings:/app/data/recordings ...
```

## 保留策略与磁盘空间

网页后台 → 设置 → 录像保留 启用并配置自动清理（默认关闭，需手动开启）。开启后下面两条规则**同时生效**，任一命中即删，**只清理已归档（已上传成功或本地模式）的录像**，pending / uploading / failed 状态绝不动：

- **按天数**：超过保留天数（默认 30 天）的录像 → 删；填 0 = 不按时间触发
- **按容量**：磁盘使用率超过阈值（默认 90%）→ 从最旧录像开始删；填 100 = 不按空间触发

> **ℹ️ 默认关闭**
>
> 首次安装 `[cleanup]` 服务默认 enabled=false——不开就一直留着，磁盘满了写入会失败但 云瞰 不主动删。家用部署强烈建议开起来，按上面两条规则把后顾之忧交给系统。

| 分辨率 | 码率 | 1 路 24 小时大致占用 |
| --- | --- | --- |
| 1080p H.264 | 2 Mbps | 约 21 GB / 天 |
| 1080p H.265 | 1 Mbps | 约 10 GB / 天 |
| 4K H.265 | 4 Mbps | 约 42 GB / 天 |

> **💡 估容量公式**
>
> **总磁盘 ≈ 路数 × 单路日占用 × 保留天数 × 1.2（缩略图 + 数据库余量）**。10 路 1080p H.265 保 30 天 ≈ 3.6 TB。

## 115 网盘云存储（可选）

把本地录像异步上传到 115 网盘，相当于 "云端 NVR"。秒传支持下，已有的录像不耗带宽。

1. **扫码登录**

   网页后台 → 115 → 显示二维码，用 115 手机 App 扫码授权。云瞰 把登录信息加密保存到 data 目录里。

2. **选目标文件夹**

   在 115 里建一个空文件夹（例如 "云瞰录像"），返回 云瞰 选这个文件夹作为上传目的地

3. **切存储后端**

   设置 → 存储 → 选 115 → 保存。切换是热切换，**不重启进程**，下一次上传就生效

4. **验证生效**

   Web Admin 目前**没有上传队列 / 进度面板**。要确认录像在传，三种办法任选：① **设置 → 115** 页面看 VIP 状态、剩余容量是否正常；② **日志**页（侧栏 → 日志）左侧选 `uploader` 服务，能实时看到每段上传的开始 / 完成 / 失败行；③ 直接打开 115 App 或网页进目标文件夹，看新录像有没有进来。

> **⚠️ 115 登录会过期**
>
> 约 30 天左右需要重新扫码。失效时 云瞰 会发推送通知，及时重扫即可，期间录像继续往本地写不丢。

> **ℹ️ 不是 115 用户怎么办**
>
> 目前只支持本地 + 115 两种后端。后续会接阿里云盘 / S3 等，有特定云盘需求可以发工单告知优先级。

## 下载 / 导出

回放页支持「按时间区间导出」——选定起止时间，后端重编码裁剪成单 MP4 给客户端下载，起止时间**帧级精度** (<40ms 误差)。**自动选硬件**:NVIDIA NVENC(50-200x 实时,RTX 几十秒/小时)→ Intel iGPU VAAPI(25-50x,N100 一两分钟/小时)→ libx264 软编(1.5-3x,十几分钟/小时)。任何一级失败自动降级到下一级。**Web Admin、Android、iOS 三端都支持**。

1. **进回放页**

   选要导出的摄像头和日期。把时间轴拖到目标区间附近，让中心刻度落在那一段录像上。

2. **点导出按钮**

   Web Admin：播放控制条最右边的 ⬇ 图标；Android / iOS：播放控制条「速度」按钮右侧的「导出」。弹出区间选择面板，默认是当前播放位置 ±30 秒。

3. **调整起止时间 → 提交**

   面板里改起止时间，会实时算出预计大小（1080p H.264 约 250 KB/s）。单次最长 **1 小时**，超过会拒绝。点「开始导出」。

4. **看进度**

   右下角（Web）/ 控制条下方（Android/iOS）会出现进度卡片。Web 走 SSE 实时刷新，移动端走 2 秒轮询。任务一旦排上号通常几秒到几十秒完成（取决于段数 + 是否需要从 115 拉云端段）。

5. **下载**

   进度卡片变成「下载」按钮后点它：Web 直接走浏览器下载；Android 走系统 DownloadManager 保存到 `Downloads/SkyView/`，状态栏有通知；iOS 弹 ShareSheet 让你选「存到 Files / Photos」或分享给微信。

> **ℹ️ 自动选硬件加速 NVENC > VAAPI > libx264**
>
> 进程启动时自动探测,按速度从快到慢优先级排:
>
> - **NVENC**(NVIDIA 独显):需要 cuda 镜像变体 + `--gpus all`,RTX 30/40 系 1h 视频 ~30-60 秒
> - **VAAPI**(Intel/AMD 集显):需要 openvino/all-in-one 镜像 + 透传 `/dev/dri`,N100 等 1h 视频 ~1-2 分钟
> - **libx264**(纯 CPU):无 GPU 时兜底,1h 视频 ~20-40 分钟(取决于 CPU)
>
> 任何一级运行时失败(driver 不兼容、session 上限等)自动降级到下一级。手动强制走某一种走 `recording.export.hwaccel = "nvenc" / "vaapi" / "none"`。

> **ℹ️ 起止时间是帧级精度**
>
> 三条编码路径(NVENC / VAAPI / libx264)起止时间都精确到帧 (<40ms)。质量参数对齐:NVENC `qp=23` / VAAPI `qp=23` / libx264 `crf=23` —— 跨硬件输出视觉上基本一致(NVENC 文件可能略大 <10%)。配置 `recording.export.{nvenc,vaapi}_qp` 可单独调质量(0-51,越小质量越高)。

> **ℹ️ 115 网盘存储模式也支持**
>
> 如果录像在 115 上，后端会先把区间内每段从 115 流式拉到服务器临时目录再拼接，完成后清临时文件。受 115 限速影响，1 小时云端段可能要等几分钟，可以先去做别的事，导出任务在服务端独立跑，关 App 也不影响。

> **💡 导出文件保留 24 小时**
>
> 拼好的 MP4 落在服务器 `data/recordings/_exports/<job_id>.mp4`，默认 24 小时后被 cleanup 自动删（避免吃满磁盘）。这窗口内任意时刻 / 任意端可以重复点「下载」拿同一份文件。超时再要就重新发起。

> **ℹ️ 想绕过 UI 直接拿原始段**
>
> 原始 60 秒段在 `data/recordings/<camera_id>/<YYYY-MM-DD_HH-MM-SS>.mp4`（本地归档后在 `data/recordings/_archive/<camera_id>/` 下），每段都是标准 MP4。也可以 `GET /api/recordings/<id>/download` 带 JWT 拿单段。

---

来源:https://yun-kan.com/zh-CN/docs/recording


# AI 检测

云瞰 内置 8 类检测：运动 → 物体 → 人脸 / 车牌 / 跌倒 / 包裹 / 手势 / 音频（婴儿哭声）。本章讲解检测顺序、参数怎么调、人脸库管理、敏感区域、以及加速后端的选择。

## 检测顺序

每路摄像头独立检测，按 5 帧/秒 默认节流（可调）。检测顺序自上而下：前一步过不了就跳过后面所有，节省算力：

1. **运动检测**：先看帧间差异，没动跳过后面所有步骤（最便宜的滤波器）
2. **物体检测**：框出人 / 车 / 动物等 80 种常见物体
3. **目标追踪**：给每个物体打 ID，避免同一个人触发多次事件
4. **精细识别**（可选并行）：人脸识别、车牌识别、姿态 / 跌倒
5. **事件落库**：达到阈值 + 不在冷却期 → 写事件，触发推送 / 自动化

## 加速后端选哪个

镜像 tag 决定 AI 用哪种硬件加速。**安装时一次性选定**——不同变体装的是不同的 onnxruntime wheel（cpu / openvino-gpu / cuda），运行时不能热切换。要换后端就要拉对应变体的镜像重新 `docker compose up -d`。

| 后端 | 硬件 | 10 路 5fps 大致 CPU 占用 |
| --- | --- | --- |
| **cpu** | 纯 CPU | 70–90% 4 核 |
| **openvino** | Intel 集显 / NPU 11 代+ | 20–40% |
| **cuda** | NVIDIA 显卡 | 8–15% + GPU 50% |
| **trt** | NVIDIA 显卡（最快） | 5–10% + GPU 30%（首次启动需要 ~3min 模型优化） |

## 运动检测

默认开。**灵敏度** 越高越敏感，太高会被风吹树叶 / 阴影飘过触发；太低小孩慢慢走会漏。建议从默认值开始，根据误报情况往两边微调。

## 物体检测

认识 80 种常见物体，常用：人 / 车 / 自行车 / 摩托 / 公交 / 卡车 / 猫 / 狗 / 鸟。事件页面有筛选框可以只看你关心的类。

## 人脸识别

需要先建人脸库：网页后台 → 人脸 → 添加。每个人传 3–5 张正脸（不同光照 / 角度），系统提取面部特征存数据库。检测时用相似度匹配。

- **已知人脸**：识别到时事件标 "<姓名> 出现"
- **陌生人**：识别到但库里没匹配上 → 标 "陌生人"
- **无人脸**：物体检测识别到人但相机角度看不到脸 → 标 "行人"

> **⚠️ 光照差识别率会掉**
>
> 夜视红外 + 白天日光 在系统看是不同人。家门口建议白天和夜视各传 2–3 张。**人脸阈值** 提高会更严但漏识别多，降低会更松但易认错。

## 车牌识别

国内蓝牌 / 绿牌 / 黄牌都支持。车库 / 院子门口装一台对着车道方向的相机，识别率好的话可以做 "自家车回来自动开门" 之类的自动化。

## 跌倒检测（独居老人）

三层判定避免误报：

1. **单帧躺姿**：判断当前姿态像 "躺"
2. **连续多帧确认**：连续若干帧里都是躺姿，过滤短暂蹲下 / 弯腰
3. **下落速度门控**：从 "站" 到 "躺" 的速度足够快，过滤 "主动躺下"（如躺沙发睡觉）

> **💡 建议装在客厅 / 卧室**
>
> 跌倒检测对相机视角敏感：俯角 30–45° 最好。装得太高（俯角 80°）人在地上像一个圆点，检测会失败。

## 敏感区域（Zones）

默认全画面都触发检测。如果想 "只关心进入院子大门，不要管马路上路过的人"，画一个多边形 zone：

1. **进 zone 编辑器**

   摄像头详情 → 敏感区域 → 编辑

2. **在画面上画多边形**

   鼠标点击逐个顶点，闭合 ≥ 3 个点；可以画多个，每个独立配置

3. **配规则**

   每个 zone 选 "触发 / 排除"，触发=只在 zone 内的物体算，排除=zone 内的不算

4. **保存**

   立即生效，无需重启

## 阈值与冷却时间

设置 → 检测 全局调整，每个相机也可单独覆盖。常用：

| 参数 | 默认 | 调高的副作用 | 调低的副作用 |
| --- | --- | --- | --- |
| 物体置信度阈值 | person 0.40 / vehicle 0.30 / 其它 0.25 | 漏检 | 误报多 |
| 人脸相似度阈值 | 0.5 | 漏识别 | 认错人 |
| 事件冷却（秒） | 120（人脸）/ 30（音频）/ 5（手势） | 丢事件 | 刷屏 |
| 跌倒下落速率阈值 | 0.6 (bbox 高度归一化 / 秒) | 漏跌倒 | 误把躺沙发当跌倒 |

## 包裹检测（快递到家）

门口相机识别到 "快递/纸箱" 类物体并稳定停留若干秒后触发 "包裹送达" 事件；离开后触发 "包裹被取走"。配合自动化可以做 "快递到了推送通知 + TTS 喊话"。需要在 网页后台 → 设置 → 检测 手动启用（默认关闭，且需要 `skyview-package.onnx` 模型——商业镜像已内置）。

## 手势识别

在 person 物体框基础上对人手做手势识别，默认启用 6 个常用手势：like（点赞）/ ok / peace（V 手势）/ palm（手掌）/ stop（停止）/ fist（拳头）。可在 设置 → 检测 → 手势 中开关。配合自动化可以做 "对相机比 SOS 手势 → 推送报警"。

> **💡 需要 NVIDIA GPU**
>
> 手势识别推理代价较高，CPU/Intel 集显档位不建议开。商业镜像内置 `skyview-gesture.onnx` 模型，纯 CPU 跑会显著拖慢主流水线。

## 音频检测（婴儿哭声）

云瞰 内置 BC-ResNet 婴儿哭声识别（`skyview_audio_cry`），每 1 秒滑窗对 2 秒音频片段做一次推理，命中后触发 "婴儿哭声" 事件。需要相机有麦克风且 RTSP 流带音轨。默认关闭，在 设置 → 检测 → 音频 启用。

> **⚠️ 环境噪音容易误报**
>
> 猫叫、电视广告、洗碗机噪音偶尔会误报。建议把音频阈值往高调，并把 RMS 门控开起来过滤静音段。新生儿家长记得把 "婴儿哭声" 自动化的冷却调到 60s 以上避免连续推送轰炸。

## 关闭某些检测

经验值：6GB 显卡跑完整流水线（物体 + 人脸 + 跌倒 + 包裹 + 手势 + 音频）大约能稳 6–8 路 1080p 子码流。要放更多路，可以在每相机详情里关掉用不到的（比如门口相机不需要跌倒，关掉）；也可以全局关某类（设置 → 检测 → 启用项）。

---

来源:https://yun-kan.com/zh-CN/docs/detection


# 自动化

把摄像头的检测事件接到通知、喊话、智能家居。一条规则 = 触发 + 条件 + 动作。

## 什么是自动化规则

一条规则 = **触发**（被什么事件唤醒）+ **条件**（当前环境满不满足）+ **动作**（做什么）。例：「门口识别到陌生人、且当前是夜间 → 给手机推送 + 客厅摄像头喊话」。

网页后台 → 自动化 → 新建规则。内置 13 个常用预设模板（陌生人到访、已知人脸欢迎、跌倒报警、跌倒联动 HA 亮灯、婴儿哭声提醒、手势 SOS 报警、手势触发情景、车辆到达开 HA 设备、离家自动关 HA、逗留 Webhook 等），挑一个改改参数就能用；也可以从空白规则自己搭。

## 触发：什么事件唤醒规则

自动化**只由摄像头的检测事件触发**——没有「定时 / cron」触发器，也没有「收到 MQTT 消息」触发器。触发分两层：**事件类型** + **主体过滤**。

### 事件类型

- 运动、物体（人 / 车 / 猫狗等）
- 人脸识别、车牌识别
- 跌倒、婴儿哭声、手势
- 进入区域 / 离开区域 / 区域无人 / 逗留
- 画面明暗变化

### 主体过滤

在事件类型之上再挑「是谁」：

- **任意** — 不挑主体
- **人物** — 任意人 / 只家人 / 只陌生人（家人还可指定具体姓名）
- **车辆** — 任意车 / 指定车牌号
- **手势** — 指定手势（如 SOS、OK、比心）

还能限定：触发的摄像头范围、敏感区范围、最低置信度，以及冷却 / 节流时间（防止短时间内反复触发）。

## 条件：唤醒后再判断环境

规则被事件唤醒后、执行动作前，可以再加附加条件（多个条件是 AND，全部满足才执行）。目前有两种：

- **时间段** — 每天 `HH:MM`～`HH:MM` + 限定周几，支持跨零点、支持取反（「工作时间不打扰」）。注意是时间**段**，不是 cron 表达式。
- **画面明暗** — 仅当画面「暗」或「亮」时通过。典型用法：「有人进入 + 此刻天黑」才开灯。

> ℹ️ 时间是「条件」不是「触发器」——规则永远先被检测事件唤醒，再判断是否落在时间段内。所以「每天 22:00 自动做某事」这种**纯定时任务，自动化做不了**（没有对应的摄像头事件就不会触发）。

## 动作：规则做什么

一条规则可以挂多个动作，依次执行。共 5 种：

| 动作 | 说明 |
| --- | --- |
| **推送通知** | 推到手机 App + 网页后台（不含邮件 / 短信） |
| **TTS 喊话** | 合成语音，通过摄像头喇叭播出来 |
| **Webhook** | HTTP 请求推到任意 URL（接飞书机器人 / IFTTT / 自建服务） |
| **MQTT 发布** | 向 MQTT broker 发一条消息 |
| **Home Assistant 服务调用** | 直接调 HA：开灯 / 关开关 / 跑场景，见下方〈Home Assistant〉 |

## 文案变量

通知文案、TTS 文本、Webhook body、MQTT payload、HA 参数里都能用 `{{变量}}`，云瞰 执行时替换成事件的实际值。常用变量：

| 变量 | 含义 |
| --- | --- |
| `{{camera_name}}` | 触发事件的摄像头名 |
| `{{event_type}}` | 事件类型（person / fall / gesture …） |
| `{{face_name}}` | 识别到的人名（人脸事件） |
| `{{zone_name}}` | 触发的敏感区名 |
| `{{gesture_label}}` | 识别到的手势（手势事件） |
| `{{event_time_iso}}` | 事件发生时间 |
| `{{confidence}}` | 识别置信度 |

> ⚠️ 必须是**双花括号** `{{camera_name}}`。写成单花括号 `{camera}`、或用错名字（如 `{name}`）都不会被替换，会原样出现在文案里。

## TTS 喊话

云瞰 内置语音合成，整个流程在 云瞰 内部完成，不依赖外部服务。

1. **选音色**

   6 个中文声线：晓晓 / 云希 / 云扬 / 晓伊 / 云健 / 晓北（东北话），可调语速和音调；编辑规则时能在浏览器里直接试听。

2. **写文案**

   支持 `{{变量}}`（见上节），如「{{camera_name}} 识别到 {{face_name}}」。

3. **选目标摄像头**

   喊话的摄像头不一定是触发事件那台（门口检测到人、客厅摄像头喊话也行）；目标摄像头需支持 ONVIF 对讲通道。

4. **测试**

   保存后对规则点「测试」即可跑一遍看效果。

> **⚠️ 撞车保护**
>
> 如果有人正按住对讲讲话，自动化的 TTS 会被直接丢弃，不打断真人。

## Webhook 例子

推送到飞书机器人：动作选 Webhook，URL 填飞书机器人的 webhook 地址，body 模板填：

```json
{"msg_type":"text","content":{"text":"{{camera_name}} 检测到 {{event_type}}"}}
```

云瞰 会把 `{{camera_name}}` `{{event_type}}` 等替换成实际值，再发出去。

## Home Assistant

云瞰 和 Home Assistant 有**两种对接方式**，相互独立——可以只用一种，也可以都用。

### 方式一：云瞰 直接控制 HA（推荐）

让 云瞰 检测到事件后直接开灯 / 关开关 / 触发场景。**不需要 MQTT。**

1. **在 HA 生成长期访问令牌**

   Home Assistant → 左下角点你的用户名 → 安全 → 长期访问令牌 → 创建，复制那串令牌。

2. **在 云瞰 填 HA 连接**

   网页后台 → 设置 → 自动化 → 「Home Assistant」面板，填 HA 地址（如 `http://homeassistant.local:8123`）和刚才的令牌，保存。

3. **规则里加「Home Assistant 服务调用」动作**

   云瞰 会自动从 HA 拉实体和服务列表，下拉直接选（如「开客厅灯」= `light.turn_on` + 对应灯实体），不用手敲 entity_id。

### 方式二：云瞰 作为传感器接入 HA（MQTT）

想反过来——在 HA 里看到 云瞰 的区域占用传感器、在 HA 端写自动化——走 MQTT discovery。

1. **HA 装 Mosquitto**

   HA → 设置 → 加载项 → Mosquitto broker，按默认装，记下账号密码。

2. **云瞰 配 MQTT**

   网页后台 → 设置 → 自动化 → 「MQTT」面板，填 broker 地址 / 端口 / 账号密码并启用。

3. **自动注册**

   云瞰 会把每个敏感区的占用状态以 binary_sensor 形式注册到 HA，HA 端立刻能看到。

> 💡 想让 **云瞰 控制 HA**（开灯等）→ 方式一；想让 **HA 用 云瞰 的传感器** → 方式二。多数人方式一就够，而且更简单。

---

来源:https://yun-kan.com/zh-CN/docs/automation


# 客户端

云瞰 提供网页后台（管理 + 大屏）、Android、iOS 三种客户端。本章讲怎么连、远程访问要点、以及实时画面与回放的差异。

## 网页后台

浏览器打开服务器 IP:23406。功能最完整：摄像头管理、Live、回放、事件、人脸库、敏感区、115 网盘、设置全部在这里。Chrome / Edge / Safari / Firefox 最近 2 年版本都支持。移动端浏览器响应式但不如原生 App 流畅。

## Android App

目前请从官网 [下载](/download) 页拿独立 APK 直装。APK 装好后会通过 license-server 心跳自动检查新版本，发现更新可在 App 内一键升级（不需要再回官网手动下）。Google Play 和国内应用商店暂未上架。

1. **首启输入服务器地址**

   局域网填 `http://192.168.x.x:23406`；公网填 `https://your-domain.com`（必须 HTTPS，明文 HTTP 在 Android 9+ 默认禁）

2. **用管理员账号登录**

   如果还想给家人用，在网页后台创建子账号（仅查看权限）

3. **等加载相机列表**

   首次连接拉取所有摄像头、人脸库、设置；几秒钟内完成

4. **看 Live**

   默认低延迟通道（500ms 内），不通自动切稳定通道。点画面可全屏，双指捏放 PTZ 缩放

## iOS App

App Store 搜 "云瞰" 直接下载。功能与 Android 一致。iOS 16.1 起支持。

## 远程访问要点

> **⚠️ 暴露公网前必读**
>
> 云瞰 默认监听 0.0.0.0,不带防火墙规则。把 23406 / 23880 / 24214 / 23515 直接暴露到公网 = 全世界都能扫到你的相机。要在外面看,请用**公网直连**(一个 TCP 端口 + HTTPS + 登录鉴权,证书可在网页里自动申请)或**组网**,别把局域网端口裸转出去。

- **最省事**:用 Tailscale / WireGuard 组网,App 在虚拟局域网里访问内网地址,不暴露公网、零运维
- **推荐**:开**公网直连**——设置里填域名申请证书、选一个公网端口,路由器转发这一个 TCP 端口(有 IPv6 的话连转发都不用),外网也能秒开实时画面
- **局域网要开的端口**:23406/tcp(网页 + 接口 + 直播)、23515(实时画面 UDP + TCP);23880 不开也行,24214 是内部服务不用开
- **HTTPS 必须**:浏览器和 Android 9+ 不允许明文 HTTP 拿摄像头权限

公网直连、组网、反向代理三种方式的详细步骤、证书自动申请、nginx / Caddy 配置模板和端口速查表,见 [外网访问](/docs/remote-access)。

## 实时画面 vs 回放

Live 默认走低延迟通道（< 500ms），握手失败 5 秒自动切到稳定通道（2–4s）。回放永远是稳定通道（不需要超低延迟，倍速 / seek 更稳）。

> ℹ️ 如果 Live 一直卡，多半是低延迟通道走的 UDP 出口被防火墙拦了，会自动切到稳定通道——延迟变成 3 秒但能播。公网部署没开 23515 UDP 端口同理。

---

来源:https://yun-kan.com/zh-CN/docs/clients


# AI 助手

把一句话发给你的 AI 助手（OpenClaw 等），它就能接管摄像头——看画面、查事件、转云台、隔着摄像头喊话。

## 怎么用

把下面这段话发给你的 AI 助手，它会自己下载、安装调用包，并引导你完成配置：

```text
下载并解压 https://cdn.yun-kan.com/yunkan-skill-latest.tar.gz，阅读里面的 SKILL.md 和 README.md 按说明安装这个云瞰调用包，然后引导我生成 API Token 并完成连接配置。
```

## 需要准备什么

- 一个能执行命令行的 AI 助手 —— OpenClaw、Claude Code、Hermes 等都行
- 一个 API Token —— 浏览器打开网页后台 `http://服务器IP:23406` 登录后，进 **设置 → API Token → 新建 Token**，复制生成的 `skv_pat_` 开头字符串；AI 配置时会问你要

> **🛑 API Token 等于管理员密码**
>
> 拿到它就能看你家所有摄像头、转云台、喊话。别发到聊天群 / 截图 / 公开仓库。怀疑泄漏就回后台撤销该 Token 再重新生成。

## 可以这样跟 AI 说话

配置完成后，在 AI 助手里直接说人话即可，例如：

- 「看下客厅的摄像头现在什么样」——AI 拉一张实时画面描述给你
- 「昨天后院有什么事件」——AI 查事件记录并汇总
- 「把车库摄像头转向左边」——AI 控制云台转动
- 「通过门口摄像头喊一句：快递麻烦放门口，谢谢」——AI 用摄像头喇叭播报
- 「检查下系统状态，存储还剩多少」——AI 拉系统总览

---

来源:https://yun-kan.com/zh-CN/docs/ai-agent


# 外网访问

默认情况下 云瞰 只在局域网可用——出门后手机 App 连不上家里的服务器。本章给出三种把 云瞰 安全地暴露到外网的方式:**公网直连(推荐)**、组网、反向代理,并说明各自要开哪些端口。公网直连只需要一个域名和路由器上的一条规则,证书在网页里自动申请。

> **🛑 先看这一条**
>
> 把 云瞰 暴露到外网只有一条底线:**必须 HTTPS + 强密码**。云瞰 的公网直连走的是「一个 TCP 端口 + TLS 加密 + 登录鉴权」,不是把画面裸露在公网上。但摄像头自己的 RTSP / ONVIF 端口、以及 云瞰 的内部流媒体端口(`24214` / `23880`)**绝对不要**转发到公网——它们没有登录这一层,转出去等于把摄像头直接交给全网的扫描器。

## 三种方式怎么选

| 方式 | 需要准备 | 路由器上要做什么 | 实时画面延迟 | 适合谁 |
| --- | --- | --- | --- | --- |
| **公网直连** | 一个域名(可用免费子域名),证书网页里自动申请 | IPv4:转发 1 条 TCP 规则;IPv6:放行入站即可 | **WebRTC 秒开,低于 0.5 秒** | 宽带有公网 IP 或 IPv6(**推荐**) |
| 组网(VPN) | 每台要用的设备装同一款组网 App | **什么都不用做** | WebRTC 秒开 | 运营商大内网且没有 IPv6,或不想开任何端口 |
| 反向代理 + 域名 | 已经在跑 nginx / Caddy / Lucky | 转发反代用的端口 | 默认 HLS 约 2.5 秒(可透传后走 WebRTC) | 已有反代、想统一用 443 的用户 |

三者不冲突,可以同时开。拿不准就按这个顺序试:**先看宽带有没有 IPv6**——有的话公网直连连端口都不用转;没有 IPv6 但有公网 IP,同样用公网直连;两样都没有(运营商大内网)就用组网。

## 方式一:公网直连(推荐)

云瞰 把网页、App 接口和实时画面**全部收敛到一个 TCP 端口**上:同一个端口既走 HTTPS,也承载 WebRTC 的实时视频通道,由服务端自动分流。所以路由器上只有**一条**规则,不需要再为 WebRTC 单独转发 UDP 端口。

> **💡 这条路解决了什么**
>
> 以前在外面看直播只能用 HLS(延迟 2.5 秒左右):WebRTC 既要额外转发端口,又要服务器对外通告一个真正可达的地址,家庭宽带很难同时满足,握手超时后就自动降级了。现在一个端口全部搞定,外网也能秒开——对「看一眼门口是谁」这类场景,差别是决定性的。

### 第 1 步:域名与证书(网页里自动申请)

公网直连必须用 HTTPS:手机 App 会拒绝不受信任的自签证书,所以需要一个**你自己的域名**和一张真证书。在 设置 → 通用 → **HTTPS 证书** 里填域名和 DNS 服务商的 API key,保存后 云瞰 会自动向 Let's Encrypt 申请证书,并在到期前自动续期。

- **不需要开放 80 端口**:走的是 DNS-01 验证(在你的域名下临时写一条 TXT 记录),国内家宽 80 入站被运营商封禁也照样能签。
- **支持的 DNS 服务商**:阿里云、腾讯云 DNSPod、华为云、Cloudflare、AWS Route 53、Porkbun、deSEC、DuckDNS。
- **没有自己的域名也能用**:deSEC 和 DuckDNS 免费送子域名,注册后就能当自己的域名使用。
- **已经有证书**的话,把 `fullchain.pem` 和 `privkey.pem` 放进 `data/certs/` 即可,云瞰 只会用它、不会覆盖你的文件。
- 填完可以先点**自检**:它会真的写一条测试记录再删掉,确认 API key 和权限没问题,而且不消耗 Let's Encrypt 的申请次数。

> **ℹ️ 域名要你自己有**
>
> 云瞰 不提供托管域名(不自建 DDNS、也不发官方子域名):域名和解析都在你自己名下,我们只提供自动申请证书的工具,定位与 certbot / acme.sh 一致。没有域名的话,上面提到的 deSEC / DuckDNS 是免费的。

### 第 2 步:选一个公网端口

> **⚠️ 国内家庭宽带别用 443**
>
> 中国大陆的家庭宽带,**80 / 443 入站普遍被运营商封禁**(为了防止家宽跑未备案的网站)。照搬国外教程用 443,会出现「路由器规则完全正确、外网就是连不上、而且没有任何报错」这种最难查的情况。国内一律用高位端口,默认的 `23443` 就很合适;云服务器或海外宽带没有这个限制,可以用 443——好处是访问地址不用带端口号。

在同一个面板里填**公网端口**,保存即生效:后端会当场重新配置并确认端口真的进入监听状态,不需要重启容器,也不用改 compose 文件。端口如果被别的程序占用、或者和内部端口冲突,保存时就会当场拦下来告诉你,而不是存下去再悄悄失败。

### 第 3 步:路由器

- **IPv4(有公网 IP)**:加一条端口转发,把公网的 `23443/tcp` 转到 云瞰 主机的 `23443`。只要这一条——**不需要**转发 `23515` 或其它端口。
- **IPv6**:IPv6 没有 NAT,不用转发,只要在路由器的 IPv6 防火墙里放行到本机 `23443/tcp` 的入站连接。
- **域名解析**:公网 IPv4 填 A 记录、IPv6 填 AAAA 记录。家宽的 IP 会变,配一个 DDNS 客户端自动更新即可。

### 第 4 步:验证

用 `https://<你的域名>:23443/` 打开网页,登录后进实时监控。画面应该在 1 秒内出来,并且走的是 WebRTC 通道。

同一个面板里还有**公网可达性自检**:它会检查域名解析到的地址、端口通不通、证书对不对,并直接告诉你卡在哪一步——不用自己抓包猜。

> **ℹ️ 运营商没给公网 IP 怎么办**
>
> 如果自检提示你的公网地址落在运营商大内网(CGNAT)网段,那么端口转发**无论怎么配都不会通**,这不是配置问题。两条出路:**用 IPv6**(国内家宽普及率已经很高,而且连端口都不用转发),或者改用下面的**组网**。也可以打电话给运营商申请公网 IP,多数地区可以免费开通。

## 方式二:组网(不开任何端口)

组网工具(Tailscale / WireGuard / ZeroTier 等)在你的手机和家里的服务器之间建一条加密隧道,手机像在家一样用内网地址访问 云瞰——**不需要在路由器上开任何端口,服务器完全不暴露到公网**。

1. **服务器装组网客户端**

   在跑 云瞰 的那台机器(或同 LAN 的软路由)装 Tailscale,然后 `tailscale up` 登录。WireGuard / ZeroTier 同理。

   ```bash
   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up
   ```

2. **手机装同款 App 并登录同一账号**

   手机端装对应的 Tailscale / ZeroTier App,登录与服务器相同的账号,两端就进了同一个虚拟局域网。

3. **App 里填组网地址**

   云瞰 App 的服务器地址填组网分配的 IP——Tailscale 是 `100.x.x.x`,ZeroTier 是 `10.x.x.x`,端口仍然是 `:23406`,例如 `http://100.x.x.x:23406`。

4. **完成**

   出门后手机连 4G/5G 也能访问,体验和在家一样。无需公网 IP、无需域名、无需 HTTPS 证书。

> **💡 组网的取舍**
>
> 不在路由器开端口 = 对公网的攻击面为零,扫描器根本扫不到你;也不依赖公网 IP,运营商大内网照样能穿透。组网下手机视同在局域网,实时画面同样走 WebRTC 低延迟通道。代价是**每台要用的设备都要装一次组网 App 并登录**,临时分享给家人不如一个网址方便。

## 方式三:反向代理 + 域名

如果你有公网 IP + 一个域名,想用 `https://cam.example.com` 这种地址访问(方便发给不方便装组网 App 的家人),可以在 云瞰 前面架一层 nginx / Caddy 做 HTTPS 终止。云瞰 容器内部已自带一层 nginx,外层反代只需把流量整体转发给 `:23406`。

> **ℹ️ 反代场景下实时画面走什么**
>
> 普通的 HTTP 层反代只转发网页和接口,实时画面会走 HLS(延迟 2.5 秒左右),功能完全正常。想要 WebRTC 那种秒开,让反代在 **TCP 层**(nginx 的 `stream` 块、Caddy 的 layer4 插件)把某个端口整体透传给 云瞰 的公网单端口即可——两者可以共存:网页走 443 的反代,实时画面走透传端口。

### nginx 配置

把下面内容**整份**存为 `/etc/nginx/sites-available/skyview.conf`,替换 `<你的域名>` 后 `ln -s` 到 `sites-enabled/` —— 一个文件搞定,不用再单独建 snippet。两个 `location /` 里的 `proxy_set_header` 块完全一样:nginx 的 `proxy_set_header` 是覆盖不继承,每个 `location` 必须各带一份,照抄即可。

```nginx
# WebSocket Upgrade 透传 —— 必须在 http {} context
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 80;
    listen [::]:80;
    server_name <你的域名>;
    # certbot --nginx 会自动把此块改成 301 跳 https
    location / {
        proxy_pass http://127.0.0.1:23406;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Port  $server_port;
        proxy_set_header X-Forwarded-Proto $scheme;        # ★ 漏了它 HTTPS 部署会登录死循环
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        $connection_upgrade;
        proxy_buffering       off;
        proxy_connect_timeout 60s;
        proxy_send_timeout    1d;
        proxy_read_timeout    1d;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name <你的域名>;

    ssl_certificate     /etc/letsencrypt/live/<你的域名>/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<你的域名>/privkey.pem;

    # 录像导出、人脸库批量导入可能上百 MB;长 JWT cookie 较大防 414
    client_max_body_size        200m;
    client_header_buffer_size   4k;
    large_client_header_buffers 8 16k;

    location / {
        proxy_pass http://127.0.0.1:23406;
        proxy_http_version 1.1;
        # ↓ 与上面 :80 location 完全相同,逐行照抄(proxy_set_header 不继承)
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host  $host;
        proxy_set_header X-Forwarded-Port  $server_port;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        $connection_upgrade;
        proxy_buffering       off;
        proxy_connect_timeout 60s;
        proxy_send_timeout    1d;
        proxy_read_timeout    1d;
    }
}
```

*/etc/nginx/sites-available/skyview.conf*

> **⚠️ X-Forwarded-Proto / X-Forwarded-Host 必须传 + 每个 location 都要 include**
>
> 容器内 nginx 只监听 HTTP,靠 `X-Forwarded-Proto` 判断客户端真实 scheme、靠 `X-Forwarded-Host` 知道对外域名。漏 `X-Forwarded-Proto` → HTTPS 部署下登录后立刻被踢回登录页、直播画面被浏览器当 Mixed Content 拦掉;漏 `X-Forwarded-Host` → 录像回放 / 下载 / 导出的链接拼成错误地址,客户端打不开。上面的 nginx 模板和 Caddy(默认即传这两个头)都已覆盖,照抄即可——端口无需手动配 `X-Forwarded-Port`,容器内 nginx 会自动按「外层反代 / 裸 IP 直连」两种场景兜好。另外 nginx 的 `proxy_set_header` 是**覆盖不是追加**:某个 `location` 只要写了任意一条,上层的 set_header 全部失效——所以每个 `location` 都要 `include` 完整那一份 snippet。

申请证书(机器要能从公网访问 `:80`):

```bash
certbot --nginx -d <你的域名> -m <你的邮箱> --agree-tos --no-eff-email --redirect
```

### Caddy 配置(更简单)

Caddy 自动签发 / 续期 Let's Encrypt 证书,无需 certbot,配置短很多。`/etc/caddy/Caddyfile`:

```caddyfile
<你的域名> {
    reverse_proxy 127.0.0.1:23406 {
        # Caddy 默认就传 X-Forwarded-{For,Proto,Host}
        # 长连接(对讲 WS / 事件 SSE / 直播流)调大 flush + 超时
        flush_interval -1
        transport http {
            read_timeout  24h
            write_timeout 24h
        }
    }
    request_body {
        max_size 200MB
    }
}
```

*/etc/caddy/Caddyfile*

## 端口速查表

| 端口 | 协议 | 用途 | 外网是否要开 |
| --- | --- | --- | --- |
| `23443` | TCP | **公网直连**:网页 + 接口 + 实时画面(HTTPS,端口可改) | **要开**(公网直连方案下唯一要开的端口) |
| `23406` | TCP | 局域网访问入口(明文 HTTP) | 不要开(要外网访问请用上面的 `23443`) |
| `23515` | UDP + TCP | 实时画面媒体流(局域网 / 组网 / IPv6 直连) | 不用开 |
| `23880` | TCP | RTSP,供外部播放器在局域网直连 | 不用开 |
| `24214` | TCP | 内部流媒体服务 | **禁止开** |

> **🛑 别把内部端口转出去**
>
> `24214`(内部流媒体服务)和 `23880`(RTSP)**没有登录这一层**——直播流的鉴权做在 `23406` / `23443` 的入口上。把它们裸转到公网会直接绕过鉴权,等于公开你的摄像头画面。同理也不要把 `23406` 裸转出去:那是**明文 HTTP**,密码在公网上是明文传输的,浏览器和 Android 9+ 还会拒绝在明文页面里申请摄像头权限。要外网访问,用上面的公网直连(`23443`,HTTPS)。

## 配完怎么验证

```bash
# 1. HTTP→HTTPS 跳转(反代场景)
curl -sSI http://<你的域名>/healthz | head -1      # 期望 301

# 2. 健康检查
curl -sS https://<你的域名>/healthz                 # 期望 {"code":0,...}

# 3. 未登录访问受保护接口
curl -sS -o /dev/null -w '%{http_code}\n' \
     https://<你的域名>/api/cameras                 # 期望 401
```

最后用浏览器走一遍完整流程:登录 → 实时监控看到画面 → 浏览器控制台没有 Mixed Content 报错。若登录后立刻被踢回登录页、或直播画面报 Mixed Content,99% 是 `X-Forwarded-Proto` 没传对。更多排查见 [排错](/docs/troubleshooting)。

---

来源:https://yun-kan.com/zh-CN/docs/remote-access


# 授权与激活

云瞰 商用版以 "按设备授权" 模式售卖。本章讲买完授权后做什么、怎么换硬件、续费在哪看。

## 设备指纹

云瞰 把授权绑定到一台机器的硬件指纹（基于主板和系统的唯一标识组合）。指纹随硬件走，**不会随 docker 重建漂移**——前提是按 [安装](/docs/install) 一章 bind-mount 了硬件信息文件。

> **⚠️ 数据卷不算指纹**
>
> 把 data 目录拷到另一台机器**不会**让授权跟过去——这是有意为之的反作弊设计。换机请走 "重新绑定" 流程。

## 买完授权做什么

1. **在客户门户查激活码**

   [客户门户](/portal/login) → 登录 → 我的授权 → 复制激活码（一长串字符）

2. **在 云瞰 服务器粘贴**

   网页后台 → 设置 → 授权 → 粘贴激活码 → 激活

3. **验证**

   成功后顶栏出现 "已激活" 绿色徽章，对应 "路数 / 到期日" 一目了然

## 重新绑定（更换硬件）

升级服务器、主板坏了、迁机房 — 这些场景需要重新绑定把授权挪到新指纹。

1. **在客户门户申请**

   我的授权 → 选目标授权 → 申请重新绑定。需要填新机器的指纹（在新机器装好 云瞰、跑起来后到 设置 → 授权 复制）

2. **等审核**

   30 分钟到 24 小时人工审核（防滥用）。审核通过后旧机器自动失效

3. **新机器激活**

   用同一激活码在新机器激活，立即生效

> **ℹ️ 重新绑定频次限制**
>
> 30 天内最多一次（防滥用）。频繁换硬件请联系客服开白名单。

## 服务器要不要联网

**激活时**需要一次性联网（curl `license.yun-kan.com` 完成 OAuth + 取签名）。激活后服务器可以彻底断网——心跳是 best-effort，连不上不会让功能停摆。事件推送、TTS 喊话、Home Assistant 桥接、录像回放都不依赖公网。

## 续费 / 到期

授权按年订阅，到期前 30 天系统会推送提醒（推送 + 邮件）。到期后 7 天宽限期内功能不受影响，提示续费；超过 7 天检测自动停（录像和直播继续）。

- 看到期日：网页后台 → 设置 → 授权
- 续费：[客户门户](/portal/login) → 我的订单 → 续费
- 续费后 1 分钟内本地自动刷新（也可点 "刷新授权" 立即拉）

---

来源:https://yun-kan.com/zh-CN/docs/license


# 排错

遇到问题先按本章对照症状自查。如果都没命中，到末尾的 "求助渠道" 联系我们。

## 1. 看不到画面（Live 一直缓冲）

| 可能原因 | 怎么验证 | 解决 |
| --- | --- | --- |
| RTSP URL 不对 | 用 VLC 试同样 URL | 改 URL 重新保存；ONVIF 自动发现错地址时改用手动 RTSP |
| 凭证错 | 网页后台提示鉴权失败 | 回 摄像头详情 改密码；ONVIF 密码 ≠ RTSP 密码 |
| 低延迟通道被拦 | DevTools → Network 看连接错误 | 防火墙开 UDP 23515；不能开会自动切到稳定通道（延迟 2–4s） |
| 相机用私协（Tapo / 小米） | 查相机品牌不在 [摄像头](/docs/cameras) 列表里 | 走 go2rtc 桥接 |
| 流媒体网关没起来 | `docker logs yunkan` 看启动错误 | 多半是端口被占；重启容器试试 |

## 2. 看回放黑屏 / 进度条不动

- **录像没开**：摄像头详情 → 录像设置 → 开启
- **磁盘满**：`df -h` 看 data 所在分区，删旧录像或调短保留天数
- **录像段坏了**：找到对应 `data/recordings/<id>/<date>/<HH-MM-SS>.mp4` 用 VLC 试播；坏段最多丢 5 分钟
- **时间不对**：服务器时区和摄像头时区不同步，回放时间轴会错 8 小时；`timedatectl` 检查

## 3. AI 检测不工作

| 症状 | 原因 | 解决 |
| --- | --- | --- |
| 事件页一直空 | 全局检测开关关了 | 设置 → 检测 → 启用 |
| 某相机不检测 | 该相机有 "检测失败" 状态 | 摄像头详情 → "清除检测错误" |
| GPU 0 占用 | 镜像变体不对（cpu 镜像跑 GPU 卡） | 拉对应变体镜像重启 |
| 人脸总是 "陌生人" | 库里没传过这个人 / 阈值太严 | 添加人脸 / 降低人脸相似度阈值 |
| 跌倒误报多 | 下落速度阈值太低 | 把跌倒下落速度阈值调高一点 |

## 4. 容器一直重启

用 `docker logs --tail 200 yunkan` 看最后输出。常见错：

- **配置缺失**：在向导模式但健康检查失败 → 浏览器走完 /setup 向导即可
- **端口被占**：`ss -tnlp | grep 23406`，把占用的服务关掉或换端口
- **硬件文件没挂载**：bind-mount 没带 `/etc/machine-id`，授权校验崩溃；按 [安装](/docs/install) 加上
- **架构不支持**：云瞰 只发布 x86_64 镜像，在 ARM 机器上无法运行（`uname -m` 应输出 `x86_64`）

## 5. 上传 115 失败

- **登录信息过期**（30 天左右）：设置 → 115 → 重新扫码登录
- **VIP 到期**：超大文件需要 115 VIP 的秒传通道；非 VIP 走限速通道
- **目标文件夹被删**：到 115 重建文件夹后回 云瞰 重选
- **网络不稳**：上传任务自带重试，看 `docker logs yunkan` 看具体错

## 6. 自动化不触发

- **静默时段**：设置 → 通知 → 静默时段，看是不是恰好处于这段时间
- **冷却时间**：30 秒内重复事件被吞，调低冷却或换不同事件类型
- **条件不匹配**：规则里加了 "识别到的人 = 张三" 但实际识别成 "陌生人"，规则不会触发；放宽条件
- **MQTT 没连上**：设置 → 集成 → MQTT 看连接状态，地址 / 凭证检查

## 7. 升级后向导又出现 / 数据没了

升级后跳到 /setup 几乎一定是 **data 目录没正确挂载**——容器看不到上次写的配置文件就以为是新装。检查：

```bash
docker inspect yunkan | grep -A 2 Mounts
# 应该看到 Source: /home/.../data, Destination: /app/data
# 如果路径变了 / 没挂，docker rm 容器，重新 docker run 时挂对
```

> **🛑 切勿在向导里再走一遍**
>
> 直接走 setup 会写一个新空数据库，原数据库虽然还在但被停用。先停容器、把挂载修好、重启，能直接进正常模式。

## 8. 忘记密码，登不进去

先看是哪一种情况：

| 情况 | 怎么办 |
| --- | --- |
| 还记得原密码，只是想换一个 | 登录后进「设置 → 用户管理」修改 |
| 家人的账号忘了密码 | 让管理员进「设置 → 用户管理」，给这个账号重置 |
| 管理员自己忘了，谁都进不去 | 用下面的命令重置 |

云瞰装在你自己家里，没有「找回密码」邮件这条路。管理员忘了密码时，在装云瞰的那台机器上执行下面的命令即可——能操作这台机器的人，本来就拥有最高权限。

```bash
# 先看看系统里有哪些账号
docker exec -it yunkan skyview-reset-password --list

# 重置指定账号的密码，按提示输入两次（输入时屏幕上不显示字符）
docker exec -it yunkan skyview-reset-password --user admin
```

> **💡 命令的提示是英文**
>
> `New password (not shown)` 是输入新密码，`Type it again` 是再输入一次。密码要求和网页里一样：至少 8 位，同时包含字母和数字。

如果这个账号之前被停用过，光重置密码还是登不进去。命令末尾加上 `--activate`，可以在重置的同时重新启用：

```bash
docker exec -it yunkan skyview-reset-password --user admin --activate
```

> **ℹ️ 容器名不叫 yunkan 怎么办**
>
> 命令里的 `yunkan` 是一键脚本安装时的默认容器名。用 NAS 应用中心或 Home Assistant 加载项装的，名字可能不一样，先用 `docker ps` 查一下，把命令里的 `yunkan` 换成实际名字。

> **⚠️ 重置密码不会把人踢下线**
>
> 已经登录的手机和网页，在原有登录有效期内仍然可以继续用。如果是担心账号被别人拿到了，去「设置 → 用户管理」把那个账号停用或删除。

## 9. 看日志的方法

```bash
# 单镜像部署：所有功能日志混在一起
docker logs --tail 500 -f yunkan

# 想只看检测相关：
docker logs yunkan 2>&1 | grep -i detection

# 多容器部署：每个组件独立
docker compose logs -f api detection
```

## 求助渠道

- **后台工单**：[客户门户 → 我的订单 → 提工单](/portal/tickets/new)，附 `docker logs --tail 200 yunkan` 的输出，跟进最快
- **邮件**：support@yun-kan.com（24 小时内回）
- **微信群**：购买后客户门户的 "我的订单" 页面有入群二维码（仅付费用户）

---

来源:https://yun-kan.com/zh-CN/docs/troubleshooting


# 常见问题

下面是产品高频问题。购买 / 退款相关请看 [价格页 FAQ](/pricing#faq)。

### 支持哪些硬件？

现阶段**只支持 x86_64 架构**。树莓派 / 香橙派 / Apple Silicon Mac / ARM 架构 NAS（绿联 DXP、极空间 Z2/Z4 等大部分家用型号）**暂不支持**，请勿尝试。

推荐起步硬件：N100 / N305 mini-PC（约 1000 元）跑全功能 AI（移动 + 人脸 + 物体）1–3 路够用；要更多路、或加跌倒 / 车牌识别，建议上 i5 / i7 + 核显，再多就上 NVIDIA 独显。x86 架构的 NAS（如 Synology XS 系列、TerraMaster D 系列、绿联部分 x86 型号）也可以装。下单前先在目标机器执行 `uname -m`，输出 `x86_64` 才能装。

### 需要公网 IP 吗？

不需要。在家局域网或 NAS 上跑，远程访问推荐 Tailscale / Wireguard 走 VPN，零运维零暴露。需要给家人外面看就走反代 + 强密码 + HTTPS。

### 一台机器最多接几路？

瓶颈在 AI 检测，不在视频转发。检测开得越全（人脸 / 跌倒 / 车牌 / 手势 / 哭声）越吃算力。下面是全功能、1080p、5fps 下的保守估计；把不重点的相机关掉检测（仅录像）能省算力给重点机位：

- **N100 / N150 集显**：1–3 路全功能（N150 起支持跌倒检测）
- **i5 / i7 + Iris Xe 核显**：2–4 路（含车牌识别）
- **RTX 2060 / 3060 等独显**：8 路左右起步，具体看显存和开了哪些识别器
- **只录不检测**：受磁盘 IO 和带宽限制，可达十几路（看你 HDD 能写多少 MB/s）

### 能纯局域网用吗？

可以。授权激活时一次性需要联网，之后服务器可以彻底断网——心跳失败不影响功能（详见 [授权](/docs/license)）。事件推送、TTS 喊话、Home Assistant 桥接、录像回放都不需要公网。

### 为什么不让 App 直接连相机？

RTSP 单路只能少数客户端订阅。Live + 检测 + App 直连就 3 路了，廉价 ONVIF 相机会撑爆。云瞰 中转后一路相机连接分发给 N 个客户端，同时把 RTSP 转成浏览器和 App 能直接播的格式，并完成录像分段——自己实现等于重写一台 NVR。

### 支持海康 / 大华吗？

全系支持。海康 / 大华 / 宇视 / TP-Link Vigi / 华为好望 这些专业 IPC 都是标准 ONVIF，扫描即出。详见 [摄像头接入](/docs/cameras)。

### 支持 4K 录像吗？

支持。云瞰 直接转发 H.264 / H.265，4K 流量大但 CPU 消耗几乎为 0。AI 检测自动用子码流（416x416）所以不影响。注意 4K 一路一天约 42GB，规划好磁盘。

### 能跨设备同步人脸库 / 配置吗？

目前不行（单实例部署）。多机部署需要共享数据库 + 共享 NFS 录像目录，文档里没写但可行。后续会做 "配置导出 / 导入" 一键迁移。

### 出商业 SaaS 版本吗？

短期不会。云瞰 定位 "自托管" —— 数据完全在用户自己的服务器，不上传任何画面到我方。这是隐私承诺也是和大厂 IPC App 的核心差异。

### 数据会不会被上传到云端？

**不会**。云瞰 是纯自托管：所有视频、人脸、事件数据都只存在你自己的服务器上，我们的服务器不存任何画面。除了授权激活时的指纹校验心跳（仅一串硬件 hash），客户端不向我方发任何业务数据。可以在路由器层面观察出口流量验证。

### 支持双向对讲吗?

支持。基于 ONVIF backchannel,Android / iOS 都是按住讲(Hold-to-Talk),带 backchannel 的摄像头即可用。自动化还能用文字转语音(TTS)主动喊话,例如有人逗留时自动播放提示。

### 怎么接 Tapo / 小米 / Wyze 这类摄像头?

云瞰原生只接 **RTSP** 与 **ONVIF** 两类。Tapo / 小米 / Wyze / 萤石 等私有协议设备,先用 go2rtc 桥接成标准 RTSP,再当普通 RTSP 源添加即可。

### 自然语言搜录像需要联网或 API key 吗?

不需要。语义搜索由**本地 VLM(视觉语言模型)**完成,中英双向、完全离线,不调用任何外部 LLM,也不需要 OpenAI / Gemini 之类的 API key。

### 能装在 NAS 上吗(群晖 / Unraid / 飞牛 / TrueNAS)?

能。云瞰是单 Docker 镜像,支持群晖(Container Manager)、Unraid、飞牛、UGOS、TrueNAS SCALE、Proxmox VE LXC,以及 Home Assistant OS 加载项。各平台步骤见 [安装文档](/docs/install)。

### 录像存在哪?可以传到网盘吗?

录像默认存服务器本地。可选上传后端:115 网盘(扫码登录 + 秒传)或本地归档目录,由独立的上传进程异步推送,不占用实时链路。

### 和 Home Assistant 怎么集成?

通过 MQTT discovery 自动把摄像头与检测事件暴露给 Home Assistant,可在 HA 里做联动;反向也能由云瞰的自动化引擎触发 TTS 喊话等动作。详见 [自动化文档](/docs/automation)。

### 支持 Apple 家庭(HomeKit)吗?

目前不集成 HomeKit。云瞰以官方 iOS / Android App 和 Web 控制台作为主要客户端,直播走 WebRTC,握手超时自动降级 HLS。

---

来源:https://yun-kan.com/zh-CN/docs/faq


# 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


# Home Assistant 集成（HACS）

用官方自定义集成把云瞰的摄像头、检测与录像带进 Home Assistant——通过 HACS 一键安装，无需 MQTT broker。

云瞰现已提供官方 Home Assistant 自定义集成。它是一个薄客户端，通过云瞰服务器常规 API 通信，把服务器能力映射成 Home Assistant 原生实体、媒体浏览器和服务——所有录制、检测和账号逻辑都留在服务器端。

[![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=mrtian2016&repository=yunkan-hass-integration&category=integration)

以自定义仓库方式在你的 Home Assistant HACS 里打开本仓库。

## 你能得到什么

- **摄像头**：原生 WebRTC（低延迟，HLS 兜底）+ JPEG 快照——画面预览卡、区域仪表盘、导出 HomeKit、`camera.snapshot`。
- **检测传感器**（每相机）：人、车、动物、包裹、人脸、跌倒、婴儿哭声、移动——并带上识别到的姓名 / 车牌。
- **对象计数**传感器 + **识别人名 / 车牌**传感器。
- **开关**：AI 检测、录像、逐特性检测开关、PTZ 自动追踪——外加挂在 hub 上的服务器级检测开关。
- **设备页控件**：刷新快照与 PTZ 方向按钮、PTZ 预置位下拉、喊话输入框。
- **设备触发器与动作**用于自动化，另附开箱即用的通知蓝图。
- **媒体浏览器**浏览录像、事件与快照，全程经 Home Assistant 自身鉴权代理。

## 前置要求

- Home Assistant **2024.11** 或更新（原生 WebRTC 摄像头需要）。
- 一台可访问的云瞰服务器——填它的主入口地址（nginx 入口，通常端口 `23406`）。
- 一个云瞰账号。PTZ、检测开关和喊话需要 **管理员** 账号；查看用任意账号即可。

## 通过 HACS 安装

1. **在 HACS 中打开**

   点击上方 **在 HACS 中打开** 按钮（或在 HACS 里点右上角三点菜单 → 自定义仓库，填入仓库地址，类别选 *Integration*）。

2. **安装并重启**

   在 HACS 里搜索 **Yunkan** 安装，然后重启 Home Assistant。

3. **添加集成**

   进入 **设置 → 设备与服务 → 添加集成 → Yunkan**，填入服务器地址、用户名和密码。

> **ℹ️ 以自定义仓库方式安装**
>
> 云瞰还没上架 HACS 默认商店（收录申请审核中），所以以**自定义仓库**方式安装——上方按钮会帮你完成。上架后即可直接搜索安装。

## 免费档 vs Pro

摄像头、快照、事件、传感器、媒体浏览器和 PTZ 在任意云瞰服务器上都能用。**AI 检测** 和 **喊话** 是 Pro 功能；免费档下这些操作会弹升级提示，而不是静默失败。

> **💡 与 MQTT 发现并存**
>
> 如果你同时用了云瞰的 MQTT 发现，两条路线以不同实体 ID 并存。本集成是更完整、面向 Pro 的另一条路线，且不需要 MQTT broker。

---

来源:https://yun-kan.com/zh-CN/docs/home-assistant