先说结论：CVAT（Computer Vision Annotation Tool）是一款开源的图像与视频标注工具，前端基于React，后端是Django + PostgreSQL，整套系统通过Docker Compose编排运行。我在自己工作站上先后帮团队搭过好几套，版本从1.x一路折腾到现在的2.x，踩过的坑基本能凑一篇长文。这篇文章就把从零安装、图片标注、再到导出成YOLO训练集的全过程写清楚，包括那些报错和绕路的地方，希望能帮你少走半天弯路。
这篇文章适合正在准备计算机视觉训练数据集的算法工程师、数据标注团队负责人，以及刚接触CVAT但不想看英文文档的开发者。无论你打算用它标目标检测框、分割多边形，还是关键点，整个流程都是通用的。如果你用的是VMware虚拟的Ubuntu环境，同样适配，但建议内存至少给8GB，磁盘预留60GB以上，否则后面跑容器会很吃力。
1. CVAT到底是什么，为什么值得折腾
1.1 CVAT核心功能与适用场景
CVAT本质上是一个围绕“标注”这件事打造的全流程平台。它不只是一个画框工具，而是把任务管理、多人协作、数据存储、标注导出、模型预标注全链路打通。在一个团队里，有人负责上传原始图片，有人负责画框，有人负责审核，项目管理员可以实时看到每个人完成了多少任务，这种协作模式比传统的“各自用LabelImg画完再合并”要高一个量级。
功能上，CVAT支持2D目标检测框（bounding box）、多边形分割、关键点、折线、3D点云标注，还有视频跟踪标注。对做自动驾驶、安防、工业视觉场景的人来说，3D点云和视频连续帧跟踪是刚需，这也是为什么很多团队宁可多花点时间部署CVAT，也不愿用轻量小工具。它还有自动标注功能，可以接入自己训练的模型或者内置的深度学习方法，先出一版粗标结果，人工再做修正，能把标注成本压缩到原来的三分之一。
它的任务管理模型也很清晰：项目（Project）下建任务（Task），任务下分多个作业（Job），标注员在作业里干活，管理员实时审核。图片上传后系统会自动做切片，一个任务几百张图不会卡，前端页面用起来依然流畅。
1.2 Docker Compose安装与原生安装的取舍
安装CVAT目前主流有两种方式：Docker Compose部署和原生（Native）安装。先说结论：如果只是日常标注使用，不是深度二次开发，直接选Docker Compose，省心程度完全不是一个量级。
原生安装需要手动搞定Python环境、Node.js、PostgreSQL、Redis、RQLite、MinIO等一系列组件，光是版本匹配就能折腾半天。CVAT后端是Django应用，前端是React SPA，构建时还得用Yarn处理一堆依赖，任何一个组件版本不对就会出现诡异报错。我在1.x时代试过一次原生安装，最后卡在RQLite迁移上，拉了官方文档、翻了GitHub issue才解决，前后花了两天。
但Docker Compose方式也不是零成本，它要求你懂基本的Docker操作，知道镜像、容器、卷这些概念。如果你之前完全没接触过容器，第一次看到十几个容器一起启动可能会懵。我建议你先花半小时跑一遍Docker官方快速入门，再回来折腾CVAT，会顺手很多。
下面是两种方式的对比：
| 对比项 | Docker Compose | 原生安装 |
|---|---|---|
| 环境隔离 | 好，组件互不干扰 | 差，依赖容易冲突 |
| 安装速度 | 快，拉镜像即可 | 慢，需逐步编译安装 |
| 升级维护 | 改配置后一条命令重启 | 容易升级失败 |
| 二次开发 | 需要额外配置挂载 | 更方便直接改代码 |
| 适合人群 | 标注使用为主、运维小白 | 准备改后端源码的开发者 |
我个人的建议是：第一套环境务必用Docker Compose，即使后面要二次开发，也可以在这个基础上加挂载目录改代码，没必要一开始就挑战地狱模式。
2. 从零开始的安装环境准备
2.1 Linux环境与基础依赖
CVAT官方推荐Ubuntu 20.04或22.04 LTS，我用的是Ubuntu 22.04，整体兼容性很好。其他Linux发行版也能跑，但命令会有差异，这篇文章以Ubuntu为准。
装系统这一步不多说，重点说一下装完系统后必须补齐的依赖。第一个是Git，用于拉取CVAT源码，直接执行：
sudo apt update sudo apt install -y git git --version第二个是Docker和Docker Compose插件。这里特别提醒，CVAT新版本要求Docker Compose V2语法（也就是docker compose命令），旧版的docker-compose（V1）可能会在解析docker-compose.yml时直接报错。检查方法：
docker --version docker compose version如果Docker版本低于20.10，建议直接卸载重装，不要考虑升级系统源里的旧包。我踩过最大的坑就在这里：当时工作站装的Docker 19.03，CVAT的compose文件里用了新版语法，启动时直接提示services.cvat_server.environment must be a mapping，排查了半天才发现是Docker Compose版本太老。
第三个是Python环境，CVAT的迁移脚本、数据导出脚本很多需要Python 3.8以上。Ubuntu 22.04自带的Python 3.10够用，不需要额外配置。但如果你后续要跑模型预标注，最好装上Miniconda管理虚拟环境，避免和系统Python打架。
2.2 拉取CVAT源码与配置
基础依赖准备好之后，开始拉取源码：
git clone https://github.com/cvat-ai/cvat.git cd cvat进入目录后，先复制一份环境变量配置：
cp .env.dev .env这里有个关键配置需要关注：DJANGO_SECRET_KEY。CVAT用它来做Django签名和安全校验，默认值是开发用的，如果你部署在公网环境，一定要改成随机字符串。生成方法很多，可以用Python：
python3 -c "import secrets; print(secrets.token_urlsafe(64))"然后把生成的值填到.env文件的DJANGO_SECRET_KEY后面。如果不改，系统虽然能跑，但存在安全风险，尤其多人协作时，别人拿到默认配置就能构造恶意会话。
接着检查一下docker-compose.yml，重点关注端口映射。默认服务跑在8080端口，如果你想换端口，找到：
services: cvat_server: ports: - "8080:8080"把左边的8080改成你想要的端口，比如9090:8080。如果你要用GPU跑深度学习预标注模型，还要在cvat_server和cvat_worker_default服务下配置gpus: all，否则容器内无法使用CUDA。
2.3 踩坑记录：镜像拉取慢、权限、容器启动失败
这个环节是踩坑重灾区，我把常见问题按顺序列一遍。
第一类问题是镜像拉取超时或失败。CVAT的镜像比较大，cvat_server单镜像就有好几个GB，如果网络不稳定，很容易拉到一半中断。解决思路是配置Docker可用的registry mirror。修改/etc/docker/daemon.json，填入你所在网络环境下可用的镜像仓库地址，然后重启Docker服务：
sudo systemctl restart docker配置好之后重新拉取，速度会明显改善。还有个小技巧，拉镜像时别傻等，用docker compose pull按需拉取，哪个失败了单独重试哪个，比整体重来高效。
第二类是Docker权限问题。如果你执行docker ps提示权限不足，说明当前用户不在docker用户组里，执行：
sudo usermod -aG docker $USER newgrp docker不解决这个问题，后面所有compose命令都要加sudo，很容易把文件权限搞乱。
第三类是端口冲突。我遇到过8080端口被其他服务占用的情况，启动时提示Bind for 0.0.0.0:8080 failed: port is already allocated。直接用sudo lsof -i:8080查占用进程，杀完之后重新启动。如果你不想杀，改端口映射更省事。
第四类问题是启动后某个容器一直重启。用docker compose ps看到cvat_server显示Restarting，立刻看日志：
docker compose logs -f cvat_server最常见的错误是can't open file 'manage.py'或者ModuleNotFoundError，这类多半是镜像没拉全或者版本不一致。先把旧容器清干净再重来：
docker compose down -v docker compose pull docker compose up -d注意-v会连数据卷一起删掉，如果里面已经有标注数据，不要随便加这个参数。
3. 启动CVAT并完成初始配置
3.1 一键启动与容器状态检查
配置好之后，在cvat目录下执行：
docker compose up -d第一次执行会拉取并创建所有容器，包括cvat_server、cvat_worker_default、cvat_db、cvat_redis、cvat_minio等。整个过程看CPU和网速，一般需要十到二十分钟。启动完成后，检查容器状态：
docker compose ps看到所有服务状态都是Up，并且没有持续重启的，才算正常。然后打开浏览器访问http://localhost:8080，如果页面能加载出CVAT的登录界面，说明前后端服务都通了。
这里要说一下CVAT的容器分工，了解之后排查问题会快很多。cvat_server跑的是Django后端加API服务，处理登录、任务管理、标注数据读写；cvat_worker_default是后台任务队列，负责图片预处理、自动标注模型推理这些异步任务；cvat_db是PostgreSQL数据库，存所有业务数据；cvat_redis做缓存和消息队列；cvat_minio是对象存储，存原始图片和导出的数据集。这套架构和很多企业级应用类似，理解了容器职责，日志里报错你一眼就能定位到问题模块。
3.2 创建管理员账号与登录
CVAT登录界面有一个Create an account入口，可以直接注册。但管理员账号建议用命令行创建，因为后续管理标注员、查看全局任务都需要管理员角色。
进入cvat_server容器，执行：
docker exec -it cvat_server bash -c "python3 manage.py createsuperuser"按提示输入用户名、邮箱、密码。创建完成回到浏览器，用管理员账号登录。
登录进去之后，右上角点你的用户名，进入Admin页面，可以在用户管理里添加标注员账号并分配角色。CVAT的角色分三层：Admin（管理员）、User（普通用户）、Worker（标注员）。实际团队里，项目负责人用Admin账号建项目建任务，标注员用Worker账号干活，普通User角色适合需要看数据但不能改任务的算法工程师。如果你给所有人都是Admin权限，后期标注数据被误删、误改的风险会高很多。
3.3 踩坑记录：数据库迁移失败、账号无法创建、UI空白
启动过程顺利的话，到这里应该已经能登录了。但有几个问题很典型，尤其多人同时部署时经常碰到。
第一个是数据库迁移失败。执行up -d之后cvat_server日志里出现relation "django_migrations" does not exist之类的内容。这种一般是数据库还没初始化完，而server容器已经尝试连接了。解决办法是等待cvat_db容器完全就绪后，手动执行迁移：
docker exec -it cvat_server bash -c "python3 manage.py migrate"执行完重启server容器。注意CVAT部署时其实会自动跑迁移，手动补跑只是兜底，如果你自己再改过数据库配置，迁移顺序更要对齐。
第二个是账号创建后登录报错Invalid username or password。排查思路是先确认密码强度是否满足要求，CVAT默认密码策略比较严格，太短的密码会被Django直接拒绝。如果确认密码没问题，再检查浏览器是不是自动填充了旧缓存，清掉站点Cookie重新登录，大部分问题能解决。
第三个是前端UI加载出来但接口全部报错，页面白屏。此时看浏览器F12控制台，如果出现一堆401 Unauthorized，大概率是管理员会话过期，重新登录即可；如果出现502 Bad Gateway，说明cvat_server容器崩了或者还在启动中，看docker compose logs -f cvat_server输出，等容器完全起来再刷新页面。有几次我以为系统装坏了，其实只是等待时间不够。
4. 用CVAT完成一次图片标注任务
4.1 创建任务，上传图片
登录进系统后，左侧菜单有Projects、Tasks、Jobs三个模块。实际使用中我推荐先建Project，再建Task，这样不同任务可以共享同一套标签集合。
在Projects页面点击Create a new project，填写项目名称后，在Label配置里加入你要用的标签，比如person、car、bicycle。这里可以给每个标签设置颜色，方便在标注时快速区分。标签配置是核心步骤，后面任务里如果标签和项目对不上，导出数据时类别会乱。
建好项目之后，进入Tasks页面创建任务。任务名称随意，但建议包含数据批次信息，比如20250115_road_camera_batch1，方便后期管理。关联到之前建的项目后，系统会自动继承项目的标签配置，任务里不需要再重复添加。
上传图片在任务详情页的Upload data区域。这里要注意文件大小限制，CVAT默认限制单次上传文件总大小，如果图片全是高清大图，可能在服务端被拒。有两种解决办法，一是把图片压缩或裁小，二是调整docker-compose.yml里cvat_server的CLIENT_MAX_BODY_SIZE配置，默认是15mb，改成100mb再重启容器。
上传完成后系统会自动创建若干Job，每个Job包含一部分图片。标注员进入Jobs就能开始干活。
4.2 标注界面与快捷键操作
打开一个Job，进入标注界面。左侧是工具栏，有画框、画多边形、画关键点等工具；中间是大画布；右侧是标签列表和属性面板。
新手最容易忽略的是快捷键，但快捷键恰恰是提升标注效率的关键。我最常用的几个：
N：新建标注目标，按下后鼠标变成十字，拖拽画框或画点Ctrl+S：手动保存当前标注Esc：取消当前正在绘制的目标Ctrl+Z：撤销上一步Delete：删除选中的目标Q：隐藏/显示当前图片的所有标注
操作流程是这样的：选好标签类别（在右侧标签列表里点击选中，或者按数字键快速切换），然后按N开始画框，画完自动进入下一个目标的绘制状态。如果你连续标注同一类别，不需要再切换标签，直接N继续画就行。不同类别切换可以提前给标签绑定数字快捷键，比如1对应person、2对应car，这样全程键盘操作，速度能翻一倍。
CVAT默认每隔一段时间会自动保存标注结果，但我在实际使用中还是养成了边画边按Ctrl+S的习惯。原因是有几次浏览器标签页崩溃，重新打开后发现丢了最近几分钟的标注，那种感觉真的很崩溃。自动保存不是万能的，尤其在多人并发操作同一个任务时，手动保存更稳妥。
4.3 踩坑记录：标签画错、属性面板消失、自动保存
标注过程中有三个问题经常被问。
第一个是画错标签怎么办。比如本来要标car，结果标成了person。最简单的方法是选中这个标注框，直接在右侧标签列表里点击正确标签，类别就改了，不需要删除重画。如果框的位置也不对，用鼠标拖拽框的顶点调整，比删除重画更快。如果整张图的标注都乱了，可以按Ctrl+Z逐步撤销，但撤销次数多了之后，系统偶尔会卡顿，我建议大范围错误时直接刷新页面，CVAT会恢复到最近一次保存的状态。
第二个是右侧属性面板突然消失。这通常是因为浏览器窗口宽度不够，CVAT布局自动折叠了侧栏。把浏览器窗口拉大，或者点击界面顶部的“属性”图标重新展开面板。如果还是没有，按F5刷新页面，属性面板会恢复默认布局。
第三个是关于自动保存间隔的误解。很多用户以为CVAT像在线文档一样实时保存，其实它是定时批量保存，默认间隔大概几十秒到几分钟不等，取决于后端配置和任务复杂度。如果你在自动保存的间隙关闭了浏览器，这部分改动就丢了。所以工作流上我建议：每标完一张图就按一次Ctrl+S，养成肌肉记忆，能避免绝大多数数据丢失问题。
5. 导出标注结果并接入YOLO等模型训练
5.1 导出格式选型：COCO、YOLO、Segmentation mask
标完数据之后，进入任务详情页，点击Export dataset按钮，会弹出格式选择列表。列表很长，比如COCO 1.0、Ultralytics YOLO、Pascal VOC、Segmentation mask等。初次接触的人很容易懵，这里我给一个选型建议：
- 做目标检测（YOLO系列）用
Ultralytics YOLO格式，导出后直接是训练可用的图片加txt标注，省去转码步骤 - 做实例分割或关键点检测用
COCO 1.0格式，JSON结构完整，适合用mmdetection或detectron2训练 - 做语义分割用
Segmentation mask格式，会生成PNG掩码图
COCO 1.0和Ultralytics YOLO对比，YOLO格式每个图片对应一个同名txt文件，每行内容依次是类别id x_center y_center width height，坐标值都归一化到0到1之间。COCO格式则是一个超大JSON文件，包含images、annotations、categories三大部分。两种格式各有优劣，但如果你用的是Ultralytics的YOLO训练脚本，直接导出YOLO格式最省事，因为它连data.yaml文件都帮你生成好了，训练时直接引用即可。
5.2 从CVAT到YOLO训练集的实际流程
导出Ultralytics YOLO格式后，你会拿到一个zip压缩包。解压后目录结构大致如下：
dataset/ ├── data.yaml ├── images/ │ ├── frame_000001.jpg │ └── ... └── labels/ ├── frame_000001.txt └── ...data.yaml的内容类似这样：
train: images val: images nc: 2 names: ['person', 'car']不过实际使用时，train和val路径可能需要改成绝对路径或者在当前目录下运行训练脚本。另外你最好手动把图片划分一下训练集和验证集，不要让train和val完全一样，否则模型评估结果会虚高。我通常用Python脚本随机划分：
import os import random import shutil all_images = os.listdir('images') os.makedirs('train/images', exist_ok=True) os.makedirs('train/labels', exist_ok=True) os.makedirs('val/images', exist_ok=True) os.makedirs('val/labels', exist_ok=True) random.shuffle(all_images) split_idx = int(len(all_images) * 0.8) for img in all_images[:split_idx]: shutil.move(f'images/{img}', f'train/images/{img}') label = img.replace('.jpg', '.txt') shutil.move(f'labels/{label}', f'train/labels/{label}') for img in all_images[split_idx:]: shutil.move(f'images/{img}', f'val/images/{img}') label = img.replace('.jpg', '.txt') shutil.move(f'labels/{label}', f'val/labels/{label}')然后修改data.yaml中的路径指向train/images和val/images，接上Ultralytics YOLO训练命令就能开跑。
5.3 踩坑记录：坐标转换、类别顺序、空标签
导出和训练阶段有几个细节特别容易翻车。
第一个是类别顺序问题。CVAT的标签顺序取决于你在项目里添加标签的先后顺序，导出YOLO格式后，txt文件里的类别id就是这个顺序。如果你的训练脚本里model.names或data.yaml的names顺序与标签顺序不一致，模型训练时会出现张冠李戴。所以在训练前，一定先打开几个txt文件确认类别id对应的标签名，再和data.yaml中的names对齐。
第二个是坐标归一化问题。CVAT导出的YOLO格式，坐标已经是归一化后的结果，不需要你手工再除以图片宽高。但如果你导出的是COCO格式，坐标是像素值，转YOLO时才需要做归一化。有人拿COCO格式直接套YOLO训练脚本，结果损失函数爆掉，原因就是坐标范围完全不对。所以导出时选对格式，比后期转换省事得多。
第三个是空标签问题。有些图片可能没有任何目标，导出的txt文件是0字节空文件。如果图片出现在验证集里，某些检测框架会直接跳过它，但有些框架会报错。检查方法是对比images和labels目录下的文件数量，不一致就找到缺失的对应关系手动处理。我一般会在数据清洗阶段直接把空标签图片从训练集里剔除，避免训练时报奇怪的错。
6. 团队协作与日常维护的进阶建议
6.1 多账号与权限管理
当标注量变大，一个人标不完，就需要给团队分配账号。在Admin页面创建的用户默认是普通User，你可以给标注员赋予Worker角色，这样他们只能操作分配到的任务，看不到项目全局设置，也不能修改标签体系。项目管理员用Admin账号把任务通过Jobs页面分配给具体标注员，不要让人自己去所有任务里挑活，否则协作记录会乱。
在多人同时标注同一批数据时，协作规范很重要。我见过最典型的混乱：两个人在同一张图片上做了不同版本的标注，任务提交后管理员发现重复标注，数据导出后类别数量翻倍。CVAT虽然支持任务锁定，但默认没有强制限制，所以我的建议是每个Job只分配给一个人，管理员审核通过后再整理汇总。如果团队规模大，还可以用CVAT的组织管理功能，按业务线划分不同组织，数据和标签完全隔离，互不干扰。
6.2 数据备份与容器日常运维
CVAT用起来之后，数据全在Docker卷里，如果不做备份，哪天磁盘坏了或者误删容器，标注成果就全没了。数据库备份是核心，CVAT的业务数据全部在PostgreSQL里。备份命令：
docker exec -it cvat_db pg_dump -U postgres cvat > backup.sql还原时：
docker exec -i cvat_db psql -U postgres -d cvat < backup.sql图片和导出的数据集默认存在MinIO对象存储里，备份时可以连同cvat_minio的卷一起备份。最简单的做法是把整个/var/lib/docker/volumes目录定期复制到另一台机器，但前提是容器处于停止状态或数据一致状态。
日常运维最需要关注的是磁盘占用。CVAT运行时间长了，日志文件、临时文件、缓存会越来越大，尤其cvat_server容器日志，如果长期不清理，一个文件能膨胀到几十GB。建议给Docker配置日志轮转，在/etc/docker/daemon.json里加：
{ "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "5" } }重启Docker后生效。这个配置能省掉很多麻烦，别等日志把磁盘塞满才开始处理。
6.3 常见问题速查表
按我这么多年实战经验，把高频问题整理成速查表，遇到直接对照着查：
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| 启动后cvat_server不停重启 | 数据库迁移未完成或Docker版本过旧 | 看日志，执行migrate再重启 |
| 上传图片失败，提示文件过大 | 服务端body大小限制 | 改CLIENT_MAX_BODY_SIZE后重启 |
| 标注保存后刷新丢失 | 自动保存间隔未到，或浏览器崩溃 | 养成手动Ctrl+S习惯 |
| 导出YOLO格式后类别对不上 | 项目标签顺序与训练脚本names不一致 | 核对data.yaml与txt文件类别id |
| UI白屏，接口返回502 | cvat_server未完全启动或崩溃 | 看server日志，等待或重启 |
| 多人同时标同一任务冲突 | 同一Job分配给了多个人 | 恢复单人单Job分配策略 |
除了表格里的，再补充一个我最近才处理的问题：换了网络环境后，cvat_minio容器一直报连接错误。查了半天发现是MinIO的访问密钥和.env里的配置不一致，因为之前重置容器时数据卷保留了旧密钥，而.env被重新生成过。解决办法是删掉MinIO的容器和卷，重新初始化：
docker compose rm -sf cvat_minio docker volume rm cvat_cvat_minio_data docker compose up -d注意这个操作会把已上传的图片备份清掉，所以操作前先确认MinIO里没有重要数据。
还有一个经验分享：CVAT版本更新比较频繁，新版本修复边界情况和性能问题很积极。每次升级前，先备份数据库和MinIO数据卷，再执行：
git pull docker compose up -d如果升级后遇到奇怪问题，回退版本比排查要快得多。我目前稳定使用的是2.x系列，整体性能和稳定性比1.x时代提升了一个档次，尤其大分辨率图片标注的流畅度改善明显。
最后再说一个很多人问的点：CVAT不只是能标图片，视频标注同样支持。上传视频后，系统会自动抽帧，你可以用插值标注的方式标关键帧，中间帧自动拟合。我们团队做视频目标跟踪数据集时就是这么干的，效率比逐帧标注高出好几倍。如果你有视频标注需求，CVAT确实是个值得花时间研究透彻的利器。
