# macOS 部署

Mac 上的 Docker 都跑在一台 Linux 虚拟机里,Docker Desktop、OrbStack 和 Apple 自家的容器工具都是这样,因为云瞰这类 Linux 程序需要 Linux 内核。所以在 Mac 上装云瞰,区别只在用哪台虚拟机:一键脚本帮你建一台直接接入局域网的,功能最全;已经在用 UTM / Parallels / VMware Fusion 或 Docker Desktop / OrbStack 的,也可以直接用。Apple Silicon 和 Intel 芯片的 Mac 都能装,AI 检测只用 CPU。

## 装之前先知道

- **AI 检测只用 CPU**。虚拟机里用不到 Mac 的神经网络引擎、GPU 和视频硬件解码。摄像头多的话,给检测配子码流,并且只给重点机位开检测,见 [安装部署](/docs/install) 里的硬件档位说明。
- **Mac 睡眠时不录像**。当录像主机用的 Mac 要关掉自动睡眠,见下文 [让 Mac 一直在线](#keep-online)。
- **授权绑定在虚拟机上**。删掉虚拟机重装,授权会把它当成一台新设备,要走一次重新绑定(30 天内限一次),见下文 [授权与重装](#license)。

## 系统要求

| 项目 | 要求 |
| --- | --- |
| macOS | 13 Ventura 或更新 |
| 芯片 | Apple Silicon(M1 及以后)或 Intel |
| 内存 | 8 GB 起,16 GB 更从容。虚拟机默认分走一半(4–16 GB) |
| 磁盘 | 虚拟机磁盘上限默认 200 GB,按实际用量占用。系统盘空闲不到 50 GB 时,建议把录像放到外接盘(`--recordings-dir`) |
| Homebrew | 必须。没装的话先装,见下面第 1 步 |
| 网络 | 推荐网线。只有 Wi-Fi 也能装,但有些无线路由器不给虚拟机分配地址 |

## 三种装法怎么选

|  | Mac 一键脚本(推荐) | 自己装虚拟机 | OrbStack / Docker Desktop |
| --- | --- | --- | --- |
| 适合谁 | 专门拿这台 Mac 当录像主机 | 已经在用 UTM / Parallels / VMware Fusion | 已经在用 OrbStack / Docker Desktop,不想再装一套虚拟机 |
| 自动搜索摄像头(ONVIF) | 可用 | 可用(网络选桥接) | 不可用,手动填 IP 添加 |
| 手机 App 在局域网里自动找到服务器 | 可用 | 可用(网络选桥接) | 不可用,手动填地址 |
| HomeKit / 国标 GB28181 设备接入 | 可用 | 可用(网络选桥接) | 不可用 |
| 开机自启 | 开机就启动,**不用登录 macOS** | 看虚拟机软件的设置,多数要登录 macOS 后才启动 | 要登录 macOS 后才启动 |
| 要做的事 | 一行命令,中途输一次管理员密码 | 自己建虚拟机、装 Ubuntu,再跑一行命令 | 下载 compose 文件,改一处配置 |

差别都在网络:一键脚本和「自己装虚拟机 + 桥接」都让云瞰像局域网里一台独立的小主机,从路由器拿自己的 IP,用起来和 Linux 主机上装的云瞰完全一样;OrbStack / Docker Desktop 的虚拟机藏在 Mac 后面(NAT),局域网广播进不去,所以自动发现类的功能都用不了。录像、回放、AI 检测、推送、外网访问三种装法都正常。

## 一键部署(推荐)

1. **装 Homebrew(已装可跳过)**

   打开「终端」,粘贴下面这行。国内网络慢的话可以用 [Gitee 镜像版](https://gitee.com/cunkai/HomebrewCN)。

   ```bash
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   ```

2. **运行 Mac 一键脚本**

   首次要下载虚拟机系统和云瞰镜像,耗时主要看网络。

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

3. **按提示输入 Mac 登录密码**

   脚本要装一个让虚拟机接入局域网的网络组件,并写入开机启动项,这两步需要管理员权限。不想输密码可以加 `--nat`,代价是自动发现类功能不可用(同上表 OrbStack 那一列)。

4. **打开浏览器**

   脚本最后会打印访问地址,形如 `http://192.168.1.50:23406`。打开后进入 [初始化向导](/docs/quickstart)。默认的桥接模式下这是**虚拟机自己的 IP**,和 Mac 的 IP 不同,手机 App 也连这个地址;`--nat` 模式下是 Mac 的 IP。

> **💡 在路由器里给虚拟机固定 IP**
>
> 虚拟机的地址是路由器分配的。在路由器的「DHCP 静态分配 / 地址保留」里把它固定下来,以后手机 App 和书签里的地址就不会变。

脚本做了什么:

- 检查 macOS 版本、Homebrew,提示 FileVault 和自动睡眠这两个会影响无人值守的设置
- 用 Homebrew 装 Lima(轻量虚拟机工具)和网络组件 socket_vmnet
- 建一台名为 `yunkan` 的 Ubuntu 24.04 虚拟机,默认用一半的 CPU 核心(2–8 核)和一半的内存(4–16 GB),桥接到 Mac 的有线网卡
- 在虚拟机里装 Docker,再运行标准的 [Linux 一键脚本](/docs/install) 部署云瞰
- 注册开机启动项:Mac 开机就把虚拟机和云瞰拉起来,不需要登录 macOS 账户

> **ℹ️ 不会共享你的个人文件**
>
> 虚拟机看不到 Mac 的家目录。只有你用 `--recordings-dir` 指定的录像目录会挂进虚拟机。

### 常用参数

| 参数 | 用途 |
| --- | --- |
| `--recordings-dir /Volumes/盘名/yunkan` | 录像存到 Mac 的某个目录,通常是外接大盘(必须是绝对路径) |
| `--interface en0` | 指定桥接用的网卡。默认自动选有 IP 的有线网卡,没有就用 Wi-Fi |
| `--nat` | 不桥接,免管理员密码;自动发现 / HomeKit / GB28181 不可用 |
| `--cpus 4 --memory 8 --disk 300` | 指定虚拟机的核心数、内存(GB)、磁盘上限(GB) |
| `--offline 镜像包.tar.gz` | 用离线镜像包安装,不从网上拉镜像 |
| `--no-autostart` | 不注册开机自启 |
| `-y` | 全程不提问,按默认值走 |
| `--uninstall` | 卸载,见下文 |

```bash
# 录像放到外接盘
curl -fsSL https://cdn.yun-kan.com/yunkan-install-macos.sh | bash -s -- --recordings-dir /Volumes/Data/yunkan

# 给虚拟机 6 核 12 GB 内存
curl -fsSL https://cdn.yun-kan.com/yunkan-install-macos.sh | bash -s -- --cpus 6 --memory 12
```

*参数要跟在 bash -s -- 后面*

> **⚠️ 核心数、内存、网络模式要装的时候定好**
>
> 重跑脚本不会重建已有的虚拟机,所以这几个参数只在第一次安装时生效。之后想改只能卸载重装,虚拟机里的数据会一起删掉,授权也要重新绑定。

## 录像放在哪

默认录像存在虚拟机的磁盘里,也就是 Mac 的系统盘上。录像很占空间,两种做法:

- **录像放外接盘**:安装时加 `--recordings-dir`,指向外接盘上的目录。外接盘要设成开机自动挂载、一直接着。
- **留在系统盘**:装好后到 网页后台 → 设置 → 存储 设一个录像总配额,超出后自动删最旧的录像。别只靠磁盘百分比兜底,系统盘满了 macOS 自己也会出问题。详见 [保留与磁盘配额](/docs/storage-quota)。

## 让 Mac 一直在线

1. **关掉自动睡眠**

   Mac 睡着时虚拟机也停了,不录像也不检测。在 系统设置 → 能耗(笔记本是「电池 → 选项」)里打开「显示器关闭时防止自动进入睡眠」,或者在终端执行:

   ```bash
   sudo pmset -a sleep 0
   ```

2. **停电后自动开机(Mac mini / iMac / Mac Studio)**

   系统设置 → 能耗 → 打开「断电后自动启动」。

3. **留意 FileVault**

   开着 FileVault 时,Mac 开机会先停在解锁界面,有人输入密码之后系统才真正启动,云瞰也要等到那时。停电来电后没人输密码就一直不录像。计划内的重启可以用 `sudo fdesetup authrestart` 跳过这一次;要完全无人值守,只能关掉 FileVault,这是安全上的取舍,自己决定。

## 日常管理

| 要做什么 | 怎么做 |
| --- | --- |
| 升级 | 网页后台 → 设置 → 系统 → 检查更新,一键升级;或者重跑一遍一键脚本 |
| 看日志 | `limactl shell yunkan docker logs -f yunkan` |
| 停止 / 启动 | `limactl stop yunkan` / `limactl start yunkan` |
| 进虚拟机 | `limactl shell yunkan` |

## 授权与重装

一键脚本和自己装虚拟机这两种装法,授权都绑定在虚拟机上。重启 Mac、重启虚拟机、升级云瞰都不影响授权;但**删掉虚拟机重装**(包括卸载后重装、为了改核心数重装)会变成一台新设备,需要在 [客户门户](/portal/login) 申请重新绑定,30 天内限一次,见 [授权与激活](/docs/license)。

OrbStack / Docker Desktop 装法用的是这台 Mac 本身的硬件编号,删掉容器重装授权不变。

## 用自己的虚拟机软件(UTM / Parallels / VMware Fusion)

一键脚本做的事,用任何虚拟机软件都能手动做到:装一台 Ubuntu,网络设成桥接,再在里面跑 Linux 一键脚本。

1. **建一台 Ubuntu 虚拟机**

   系统选 Ubuntu Server 24.04,Apple Silicon 的 Mac 用 ARM64 版,Intel 的 Mac 用 x86_64 版。建议 4 核、8 GB 内存起步,磁盘按录像量给。

2. **网络选「桥接」**

   UTM 里是「Bridged (Advanced)」,Parallels 是「Bridged Network」,VMware Fusion 是「Bridged Networking」。选默认的共享 / NAT 网络也能用,但自动发现类功能会和 OrbStack 那一列一样不可用。

3. **在虚拟机里跑 Linux 一键脚本**

   脚本会检查 Docker,没装的话会给出安装命令。细节见 [Ubuntu / Debian 部署](/docs/install-ubuntu-debian)。

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

4. **打开浏览器**

   脚本最后会打印访问地址(虚拟机的 IP 加 `:23406`),打开后进入 [初始化向导](/docs/quickstart)。同样建议在路由器里给虚拟机固定 IP。

> **⚠️ 让虚拟机跟着 Mac 一起启动**
>
> Mac 重启后虚拟机没起来,就不录像。在虚拟机软件里打开「随 Mac 启动」一类的选项(各软件位置不同,多数要登录 macOS 后才生效),再按下文 [让 Mac 一直在线](#keep-online) 关掉自动睡眠。

## 用 OrbStack / Docker Desktop 部署(简易)

已经装了 OrbStack 或 Docker Desktop 的话,可以直接用 compose 文件起云瞰。先看一眼上面「两种装法怎么选」里不可用的功能。

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

macOS 专用 · cpu 变体(Apple Silicon 自动用 ARM 版)· 支持网页后台在线升级

1. **建目录、放 compose 文件**

   把上面下载的 compose.yml 放进去,或者:

   ```bash
   mkdir -p ~/yunkan && cd ~/yunkan
   curl -fsSL https://yun-kan.com/compose/macos.yml -o compose.yml
   ```

2. **生成设备标识**

   授权要靠它认这台 Mac。**必须在启动前生成**,否则 Docker 会建出一个同名的空目录。

   ```bash
   ioreg -rd1 -c IOPlatformExpertDevice | awk -F'"' '/IOPlatformUUID/{print $4}' \
     | tr -d '-' | tr 'A-F' 'a-f' > machine-id
   ```

3. **填上 Mac 的局域网 IP**

   先用下面的命令查 Mac 的 IP,再把 compose.yml 里 `SKYVIEW_WEBRTC_EXTERN_IPS=` 后面改成它。不填的话实时画面会退回较慢的 HLS。Mac 换了 IP 要回来改,再执行一次 `docker compose up -d`。

   ```bash
   ipconfig getifaddr en0 || ipconfig getifaddr en1
   ```

4. **Docker Desktop 要打开 host 网络(OrbStack 跳过)**

   Settings → Resources → Network → 勾选「Enable host networking」,需要 Docker Desktop 4.34 或更新。不开的话局域网和 Mac 本身都访问不到云瞰。

5. **启动**

   然后浏览器打开 `http://<Mac 的局域网 IP>:23406`,进入 [初始化向导](/docs/quickstart)。

   ```bash
   docker compose up -d
   ```

> **ℹ️ 录像目录**
>
> compose 文件把录像放在同目录的 `recordings/` 下,数据库放在 Docker 的数据卷里。想把录像放外接盘,改 `./recordings` 那一行左边的路径;Docker Desktop 还要在 Settings → Resources → File sharing 里放行那个目录。

## 卸载

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

*一键脚本装的*

卸载会把一键脚本带来的东西删干净:

- 云瞰虚拟机,连同里面的 Docker、镜像、数据库、人脸库、事件
- 开机启动项和桥接网络配置
- 脚本用 Homebrew 装的 Lima、socket_vmnet,以及 Lima 下载的系统镜像缓存

安装前你就装了的 Lima / socket_vmnet、别的虚拟机还在用的组件,都会保留。用 `--recordings-dir` 放在 Mac 上的录像目录会单独问你,默认保留。

> **🛑 虚拟机里的数据无法恢复**
>
> 数据库、人脸库、事件,以及存在虚拟机里的录像,删了就没了。卸载后再装是一台新设备,授权要重新绑定。

自己装虚拟机的:在虚拟机软件里删掉那台虚拟机即可。OrbStack / Docker Desktop 装的:在 `~/yunkan` 里执行 `docker compose down -v`(`-v` 会连数据库所在的数据卷一起删),确认录像不要了再删目录。

## 常见问题

> **⚠️ 在 Mac 上打不开访问地址,手机却能打开**
>
> 多半是 Mac 开着代理软件的增强模式 / TUN 模式(Clash、Surge 等),Mac 访问局域网地址的流量被代理接管了。用手机或别的电脑访问不受影响;Mac 上要用的话,在代理软件里把局域网网段设为直连。

> **⚠️ 脚本报「虚拟机桥接网卡 60s 内没拿到 IP」**
>
> 通常是桥接到了 Wi-Fi,而无线路由器不给虚拟机分配地址。插上网线后先 `--uninstall` 再重装,或者加 `--nat` 重装。

> **ℹ️ 搜不到摄像头**
>
> `--nat` 模式和 OrbStack / Docker Desktop 装法下,自动搜索收不到摄像头的回应。在添加摄像头时手动填摄像头的 IP 即可,见 [摄像头接入](/docs/cameras)。

> **ℹ️ Mac 上能用 GPU 或神经网络引擎加速吗**
>
> 目前不能。云瞰跑在 Linux 虚拟机里,macOS 不把这些硬件开放给虚拟机。需要硬件加速、摄像头又多的话,建议用一台 Intel 核显或 NVIDIA 显卡的 Linux 主机,见 [安装部署](/docs/install) 的硬件档位。

---

出典:https://yun-kan.com/ja/docs/install-macos