Mac 安装 CVAT 完整教程：从 Docker Desktop 到本地启动

本文记录在 macOS 上部署 CVAT（Computer Vision Annotation Tool）的完整过程，适合需要进行目标检测、实例分割、关键点等数据标注的同学。

环境说明： 本教程采用 Docker Desktop + Git + Docker Compose 的方式部署 CVAT。相比直接配置 Python、PostgreSQL、Redis 等依赖，这种方式更简单，也更接近 CVAT 官方推荐的部署方式。

一、CVAT 是什么？

CVAT（Computer Vision Annotation Tool）是一款开源的计算机视觉数据标注工具，可以用于：

• 目标检测（Bounding Box）

• 多边形分割（Polygon）

• 实例分割

• 关键点（Points / Skeleton）

• 折线（Polyline）

• 图像和视频标注

• AI 辅助标注

• 标注数据导入与导出

如果你正在做 YOLO、Mask R-CNN、SAM 等计算机视觉项目，CVAT 是比较常见的一套标注工具。

CVAT 官方文档目前提供了基于 Docker Compose 的安装方式；在 macOS 上，核心思路就是先准备 Docker 环境，然后拉取 CVAT 源码并启动容器。

二、安装 Docker Desktop

CVAT 的 Docker Compose 部署依赖 Docker。

macOS 不建议只安装 Docker CLI，因为 Docker CLI 本身并不包含运行容器所需的 Docker daemon。Mac 上最直接的方案是安装 Docker Desktop。

1. 安装 Docker Desktop

进入 Docker 官方下载页面：

https://www.docker.com/products/docker-desktop/

2. 检查 Docker

打开终端：

docker –version

再执行：

docker compose version

如果能够正常显示版本号，说明 Docker 和 Docker Compose 基本安装成功。

继续测试：

docker run hello-world

如果最终出现 Docker 的欢迎信息，说明 Docker 环境可以正常运行。

注意： Docker Desktop 本身需要保持运行状态。之后启动 CVAT 时，也需要先确保 Docker Desktop 已经启动。

三、安装 Git

Mac 通常可以直接通过 Xcode Command Line Tools 获得 Git。

执行：

git –version

如果系统提示安装 Command Line Tools，按照提示完成安装。

安装完成后再次执行：

git –version

例如：

git version 2.x.x

能够正常显示版本即可。

四、下载 CVAT 源码

建议先进入一个用于存放项目的目录。

例如：

mkdir -p ~/Projects

cd ~/Projects

然后克隆 CVAT：

git clone https://github.com/cvat-ai/cvat.git

进入 CVAT 目录：

cd cvat

可以检查一下当前目录：

ls

正常情况下可以看到类似：

docker-compose.yml

Dockerfile

cvat-cli

components

server

等文件或目录。

五、启动 CVAT

确认当前目录是：

cvat

之后执行：

docker compose up -d

第一次启动可能需要较长时间。

原因是 Docker 需要下载 CVAT 以及 PostgreSQL、Redis 等相关服务所需要的镜像。

下载慢可以添加国内镜像源。 点击docker设置，找到Docker Engine，选择添加国内镜像源。 例如：

```{
"builder": {
"gc": {
"defaultKeepStorage": "20GB",
"enabled": true
}
},
"experimental": false,
"registry-mirrors": [
"https://docker.xuanyuan.me",
"https://docker.1ms.run",
"https://docker.m.daocloud.io"
]
}

可以查看当前容器状态：

docker compose ps

如果服务已经启动，会看到多个 CVAT 相关容器。

也可以使用：

docker ps

查看正在运行的容器。

六、第一次启动为什么比较慢？

第一次执行：

docker compose up -d

时，需要完成类似下面的过程：

Docker

↓

拉取 CVAT 镜像

↓

拉取 PostgreSQL

↓

拉取 Redis

↓

创建容器

↓

创建网络

↓

初始化数据库

↓

启动 CVAT Server

↓

启动 CVAT UI

因此第一次启动慢是正常现象。

以后再次启动时，因为相关镜像已经存在，一般会快很多。

七、创建 CVAT 管理员账号

CVAT 容器启动之后，还需要创建一个超级用户。

官方安装文档提供的命令是：

docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'

执行后会要求输入：

Username:

Email address:

Password:

Password (again):

例如：

Username: admin

Email address: admin@example.com

Password:

Password (again):

密码输入时终端不会显示字符，这是正常现象。

如果最后出现类似：

Superuser created successfully.

说明管理员创建成功。

八、打开 CVAT

打开 Google Chrome。

在地址栏输入：

http://localhost:8080

进入 CVAT 登录页面。

使用刚才创建的超级用户登录。

例如：

用户名：admin

密码：你刚才设置的密码

登录成功后，就可以开始创建标注任务。

九、如果 localhost:8080 打不开怎么办？

这是 Mac 安装 CVAT 时最常见的问题之一。

首先检查 Docker 容器：

docker compose ps

或者：

docker ps

重点观察：

cvat_server

cvat_ui

等服务是否处于运行状态。

方法一：查看 CVAT Server 日志

执行：

docker logs cvat_server

如果日志太多，可以使用：

docker logs –tail 100 cvat_server

实时查看：

docker logs -f cvat_server

退出日志查看：

Ctrl + C

方法二：检查端口

执行：

docker compose ps

看看是否存在类似：

0.0.0.0:8080->8080/tcp

如果没有正确映射 8080 端口，需要进一步检查 Compose 配置和容器状态。

十、检查 CVAT 健康状态

可以使用 CVAT 提供的 health check：

docker exec -t cvat_server python manage.py health_check

如果 CVAT 工作正常，可以看到数据库、缓存、磁盘等检查项目处于 working 状态。

例如可能出现：

Cache backend: default … working

DatabaseBackend … working

DiskUsage … working

MemoryUsage … working

MigrationsHealthCheck … working

OPAHealthCheck … working

如果这里全部正常，而浏览器仍然打不开，就应该重点检查端口映射和 Docker Desktop。

十一、彻底关闭 CVAT

如果想停止并移除当前 Compose 创建的容器，可以：

docker compose down

注意：

docker compose down

主要是移除容器和网络，不等于删除所有 Docker 数据。

如果只是暂时不用 CVAT，推荐优先使用：

docker compose stop

十二、更新 CVAT

如果之前是通过 Git 克隆的 CVAT，可以先进入项目：

cd ~/Projects/cvat

然后：

git pull

之后根据项目当前版本的官方文档检查更新方式。

不要在没有确认版本兼容性的情况下，直接删除数据库或 Docker volume。

参考资料

https://docs.cvat.ai/docs/administration/community/basics/installation/

Install Docker Desktop on Mac | Docker Docs

Docker Desktop | Docker Docs

本文根据当前 CVAT 与 Docker 官方文档整理。CVAT 的版本、Docker 镜像以及安装细节可能随时间变化，实际部署时建议以官方文档为准。