CVAT 安装和配置指南

CVAT 简介

CVAT（Computer Vision Annotation Tool）是一个用于计算机视觉的交互式视频和图像标注工具。它被全球数以万计的用户和公司使用，旨在帮助开发人员、公司和组织通过数据中心化的 AI 方法解决实际问题。CVAT 支持多种标注任务，包括图像和视频的标注，并且可以与多种深度学习框架集成，以加速标注过程。

当前版本: v2.40.0 (2024 年最新版本)

主要特性

多种标注类型：矩形框、多边形、点、线条、标签、椭圆、立方体等
视频标注：支持视频帧标注和关键帧插值
团队协作：支持多用户协作标注，角色权限管理
格式支持：支持 COCO、YOLO、Pascal VOC、Datumaro、LabelMe 等 50+ 种格式
API 接口：提供 REST API 和 Python SDK
自动化标注：支持 AI 辅助标注和模型训练
3D 标注：支持点云和 3D 数据标注
实时协作：支持多人同时标注同一任务
云原生：支持 Kubernetes 部署
插件系统：支持自定义插件扩展功能

应用场景

目标检测数据集标注
语义分割数据集标注
实例分割数据集标注
关键点检测数据集标注
视频分析数据集标注
3D 点云数据标注
机器学习模型训练数据准备
自动驾驶数据标注
医疗影像标注
工业质检数据标注

系统要求

硬件要求

CPU: 至少 4 核心，推荐 8 核心以上
内存: 至少 8GB RAM，推荐 16GB 以上
存储: 至少 20GB 可用空间（SSD 推荐）
显卡: 可选，支持 CUDA 11.8+ 的显卡可加速 AI 辅助标注
网络: 稳定的网络连接，推荐千兆网络

软件要求

操作系统:
- Linux: Ubuntu 20.04+, CentOS 8+, RHEL 8+
- macOS: 11.0+ (Big Sur)
- Windows: 10/11 (WSL2 推荐)
Docker: 版本 24.0+
Docker Compose: 版本 2.20+
Git: 版本 2.30+
Python: 3.9+ (用于 SDK 和自定义脚本)

网络要求

稳定的互联网连接（用于下载 Docker 镜像和依赖包）
如果在内网环境，需要配置代理或镜像源
推荐带宽：100Mbps 以上

CVAT 安装

CVAT 支持多种安装方式：

Docker 安装（推荐）：简单快速，适合大多数用户
Kubernetes 安装：适合大规模生产环境
源码安装：适合开发者或需要自定义配置的用户
云服务安装：支持 AWS、Azure、GCP 等云平台

1. 安装 Docker 和 Docker Compose

Ubuntu/Debian 系统

# 更新包索引
sudo apt-get update

# 安装必要的包
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg lsb-release

# 添加Docker官方GPG密钥
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# 添加Docker仓库
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 安装Docker Engine
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 验证安装
docker --version
docker compose version

# 将当前用户添加到docker组
sudo usermod -aG docker $USER

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker

# 重新登录以应用组权限
newgrp docker

CentOS/RHEL 系统

# 安装必要的包
sudo yum install -y yum-utils

# 添加Docker仓库
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装Docker Engine
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 验证安装
docker --version
docker compose version

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker

# 将当前用户添加到docker组
sudo usermod -aG docker $USER

# 重新登录以应用组权限
newgrp docker

2. 克隆 CVAT 仓库

# 克隆CVAT官方仓库（v2.40.0版本）
git clone https://github.com/cvat-ai/cvat.git
cd cvat

# 切换到稳定版本
git checkout v2.40.0

# 或者使用国内镜像（如果访问GitHub较慢）
git clone https://gitee.com/mirrors/cvat.git
cd cvat
git checkout v2.40.0

3. 配置环境变量(可选,可跳过)

# 复制环境变量模板
cp docker-compose.yml docker-compose.override.yml

# 编辑配置文件（可选）
nano docker-compose.override.yml

3.1 docker-compose.yml 文件详解

CVAT v2.40.0 的 docker-compose.yml 文件定义了整个系统的服务架构，包含以下主要服务：

3.1.1 核心服务配置

# docker-compose.yml 主要服务说明 (v2.40.0)
version: "3.8"

services:
  # CVAT 主服务器
  cvat_server:
    image: cvat/server:v2.40.0
    container_name: cvat_server
    restart: always
    depends_on:
      - cvat_db
      - cvat_redis
    environment:
      DJANGO_SETTINGS_MODULE: cvat.settings.production
      CVAT_HOST: localhost
      CVAT_PORT: 8080
      CVAT_BASE_URL: http://localhost:8080
      CVAT_REDIS_URL: redis://cvat_redis:6379/0
      CVAT_POSTGRES_HOST: cvat_db
      CVAT_POSTGRES_DBNAME: cvat
      CVAT_POSTGRES_USER: cvat
      CVAT_POSTGRES_DBPASS: cvat
      CVAT_POSTGRES_PORT: 5432
      # 新增 v2.40.0 配置
      CVAT_USE_HTTPS: false
      CVAT_SSL_CERT: ""
      CVAT_SSL_KEY: ""
      CVAT_ENABLE_ANALYTICS: false
      CVAT_ENABLE_METRICS: false
    volumes:
      - cvat_data:/home/django/data
      - cvat_keys:/home/django/keys
      - cvat_logs:/home/django/logs
      - cvat_models:/home/django/models
      - cvat_share:/home/django/share
    ports:
      - "8080:8080"
    networks:
      - cvat
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: "2.0"

  # CVAT UI 前端
  cvat_ui:
    image: cvat/ui:v2.40.0
    container_name: cvat_ui
    restart: always
    depends_on:
      - cvat_server
    ports:
      - "80:80"
    networks:
      - cvat

  # PostgreSQL 数据库 (升级到 PostgreSQL 15)
  cvat_db:
    image: postgres:15-alpine
    container_name: cvat_db
    restart: always
    environment:
      POSTGRES_USER: cvat
      POSTGRES_DB: cvat
      POSTGRES_PASSWORD: cvat
      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
    volumes:
      - cvat_db:/var/lib/postgresql/data
    networks:
      - cvat
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: "1.0"

  # Redis 缓存 (升级到 Redis 7)
  cvat_redis:
    image: redis:7-alpine
    container_name: cvat_redis
    restart: always
    command: redis-server --appendonly yes --maxmemory 512mb --maxmemory-policy allkeys-lru
    volumes:
      - cvat_redis:/data
    networks:
      - cvat

  # Nginx 反向代理 (新增)
  cvat_proxy:
    image: nginx:alpine
    container_name: cvat_proxy
    restart: always
    depends_on:
      - cvat_server
      - cvat_ui
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    ports:
      - "80:80"
      - "443:443"
    networks:
      - cvat

  # CVAT 任务执行器 (新增)
  cvat_worker:
    image: cvat/server:v2.40.0
    container_name: cvat_worker
    restart: always
    depends_on:
      - cvat_redis
      - cvat_db
    environment:
      DJANGO_SETTINGS_MODULE: cvat.settings.production
      CVAT_REDIS_URL: redis://cvat_redis:6379/0
      CVAT_POSTGRES_HOST: cvat_db
      CVAT_POSTGRES_DBNAME: cvat
      CVAT_POSTGRES_USER: cvat
      CVAT_POSTGRES_DBPASS: cvat
    volumes:
      - cvat_data:/home/django/data
      - cvat_share:/home/django/share
    networks:
      - cvat
    command: python3 /opt/venv/bin/python ~/manage.py runserver 0.0.0.0:8080
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: "1.0"

volumes:
  cvat_data:
  cvat_db:
  cvat_keys:
  cvat_logs:
  cvat_models:
  cvat_share:
  cvat_redis:

networks:
  cvat:
    driver: bridge

3.1.2 环境变量配置说明 (v2.40.0)

# 环境变量详细说明 (v2.40.0)
environment:
  # Django 设置
  DJANGO_SETTINGS_MODULE: cvat.settings.production # Django 配置文件

  # CVAT 基本配置
  CVAT_HOST: localhost # CVAT 主机地址
  CVAT_PORT: 8080 # CVAT 端口
  CVAT_BASE_URL: http://localhost:8080 # CVAT 基础 URL

  # 数据库配置
  CVAT_POSTGRES_HOST: cvat_db # PostgreSQL 主机
  CVAT_POSTGRES_DBNAME: cvat # 数据库名
  CVAT_POSTGRES_USER: cvat # 数据库用户
  CVAT_POSTGRES_DBPASS: cvat # 数据库密码
  CVAT_POSTGRES_PORT: 5432 # 数据库端口

  # Redis 配置
  CVAT_REDIS_URL: redis://cvat_redis:6379/0 # Redis 连接 URL

  # 文件存储配置
  CVAT_SHARE_URL: /home/django/share # 共享文件路径
  CVAT_KEYS_PATH: /home/django/keys # 密钥文件路径
  CVAT_LOGS_PATH: /home/django/logs # 日志文件路径
  CVAT_MODELS_PATH: /home/django/models # 模型文件路径

  # 安全配置
  CVAT_SECRET_KEY: your-secret-key-here # Django 密钥
  CVAT_ALLOWED_HOSTS: localhost,127.0.0.1 # 允许的主机

  # HTTPS 配置 (v2.40.0 新增)
  CVAT_USE_HTTPS: false # 是否启用 HTTPS
  CVAT_SSL_CERT: "" # SSL 证书路径
  CVAT_SSL_KEY: "" # SSL 私钥路径

  # 邮件配置（可选）
  CVAT_EMAIL_HOST: smtp.gmail.com # 邮件服务器
  CVAT_EMAIL_PORT: 587 # 邮件端口
  CVAT_EMAIL_HOST_USER: your-email@gmail.com # 邮件用户
  CVAT_EMAIL_HOST_PASSWORD: your-password # 邮件密码
  CVAT_EMAIL_USE_TLS: true # 使用 TLS

  # 自动标注配置
  CVAT_MODEL_SERVER_URL: http://localhost:7000 # 模型服务器 URL
  CVAT_MODEL_SERVER_TIMEOUT: 30 # 模型服务器超时时间

  # 性能配置 (v2.40.0 新增)
  CVAT_WORKERS: 4 # 工作进程数
  CVAT_THREADS: 2 # 线程数
  CVAT_MAX_UPLOAD_SIZE: 1073741824 # 最大上传文件大小 (1GB)

  # 监控配置 (v2.40.0 新增)
  CVAT_ENABLE_ANALYTICS: false # 启用分析
  CVAT_ENABLE_METRICS: false # 启用指标收集

  # 缓存配置 (v2.40.0 新增)
  CVAT_CACHE_TTL: 3600 # 缓存生存时间
  CVAT_CACHE_SIZE: 1000 # 缓存大小

3.1.3 自定义配置示例 (v2.40.0)

# docker-compose.override.yml 自定义配置示例
version: "3.8"

services:
  cvat_server:
    environment:
      # 修改端口配置
      CVAT_PORT: 9090
      CVAT_BASE_URL: http://localhost:9090

      # 修改数据库配置
      CVAT_POSTGRES_DBPASS: your-strong-password

      # 启用 HTTPS (v2.40.0 新增)
      CVAT_USE_HTTPS: true
      CVAT_SSL_CERT: /home/django/keys/cert.pem
      CVAT_SSL_KEY: /home/django/keys/key.pem

      # 配置邮件服务
      CVAT_EMAIL_HOST: smtp.qq.com
      CVAT_EMAIL_HOST_USER: your-email@qq.com
      CVAT_EMAIL_HOST_PASSWORD: your-app-password
      CVAT_EMAIL_USE_TLS: true

      # 配置自动标注
      CVAT_MODEL_SERVER_URL: http://your-model-server:7000

      # 性能优化 (v2.40.0 新增)
      CVAT_WORKERS: 4 # 工作进程数
      CVAT_THREADS: 2 # 线程数
      CVAT_MAX_UPLOAD_SIZE: 2147483648 # 最大上传文件大小 (2GB)

      # 监控配置 (v2.40.0 新增)
      CVAT_ENABLE_ANALYTICS: false
      CVAT_ENABLE_METRICS: true

    ports:
      - "9090:9090" # 修改端口映射

    volumes:
      # 挂载本地目录
      - ./data:/home/django/data
      - ./models:/home/django/models
      - ./logs:/home/django/logs
      - ./ssl:/home/django/keys
      - ./share:/home/django/share

  # 添加 GPU 支持 (v2.40.0 改进)
  cvat_server:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
        limits:
          memory: 8G
          cpus: '4.0'

3.1.4 生产环境配置 (v2.40.0)

# 生产环境 docker-compose.prod.yml
version: "3.8"

services:
  cvat_server:
    environment:
      # 生产环境安全配置
      DJANGO_SETTINGS_MODULE: cvat.settings.production
      CVAT_SECRET_KEY: ${CVAT_SECRET_KEY} # 从环境变量读取
      CVAT_ALLOWED_HOSTS: your-domain.com

      # HTTPS 配置 (v2.40.0 新增)
      CVAT_USE_HTTPS: true
      CVAT_SSL_CERT: /home/django/keys/cert.pem
      CVAT_SSL_KEY: /home/django/keys/key.pem

      # 数据库配置（使用外部数据库）
      CVAT_POSTGRES_HOST: your-db-host
      CVAT_POSTGRES_DBNAME: cvat_prod
      CVAT_POSTGRES_USER: cvat_user
      CVAT_POSTGRES_DBPASS: ${DB_PASSWORD}

      # Redis 配置（使用外部 Redis）
      CVAT_REDIS_URL: redis://your-redis-host:6379/0

      # 文件存储（使用 S3 或 NFS）
      CVAT_SHARE_URL: s3://your-bucket/cvat-data
      CVAT_AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY}
      CVAT_AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_KEY}
      CVAT_AWS_S3_BUCKET: your-bucket

      # 性能配置 (v2.40.0 新增)
      CVAT_WORKERS: 8
      CVAT_THREADS: 4
      CVAT_MAX_UPLOAD_SIZE: 5368709120 # 5GB

      # 监控配置 (v2.40.0 新增)
      CVAT_ENABLE_METRICS: true
      CVAT_METRICS_PORT: 9090

    deploy:
      replicas: 3 # 多实例部署
      resources:
        limits:
          memory: 8G
          cpus: "4.0"
        reservations:
          memory: 4G
          cpus: "2.0"

  # 负载均衡器
  cvat_nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - cvat_server

3.1.5 常用配置参数说明 (v2.40.0)

参数	说明	默认值	建议值
`CVAT_PORT`	CVAT 服务端口	8080	8080/9090
`CVAT_POSTGRES_DBPASS`	数据库密码	cvat	强密码
`CVAT_SECRET_KEY`	Django 密钥	自动生成	自定义强密钥
`CVAT_WORKERS`	工作进程数	1	CPU 核心数
`CVAT_THREADS`	线程数	1	2-4
`CVAT_MODEL_SERVER_URL`	模型服务器地址	-	http://localhost:7000
`CVAT_USE_HTTPS`	启用 HTTPS	false	true（生产环境）
`CVAT_MAX_UPLOAD_SIZE`	最大上传大小	1GB	根据需求调整
`CVAT_ENABLE_METRICS`	启用监控	false	true（生产环境）
`CVAT_CACHE_TTL`	缓存生存时间	3600s	根据需求调整

3.1.6 配置文件验证

# 验证 docker-compose 配置
docker compose config

# 检查服务依赖
docker compose config --services

# 验证环境变量
docker compose config --resolve-image-digests

4. 启动 CVAT 服务

4.1 快速启动 (v2.40.0)

# 使用新的 docker compose 命令 (v2.40.0 推荐)
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f cvat_server

4.2 分步启动 (推荐用于调试)

# 1. 启动数据库和缓存
docker compose up -d cvat_db cvat_redis

# 2. 等待数据库初始化完成
sleep 30

# 3. 启动主服务
docker compose up -d cvat_server

# 4. 启动前端和代理
docker compose up -d cvat_ui cvat_proxy

# 5. 启动工作进程 (可选)
docker compose up -d cvat_worker

4.3 使用 GPU 启动

# 检查 GPU 支持
nvidia-smi

# 启动支持 GPU 的服务
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d

5. 创建管理员用户

# 创建超级用户 (v2.40.0 新命令)
docker compose exec cvat_server python3 ~/manage.py createsuperuser

# 或者使用旧命令 (兼容性)
docker-compose exec cvat_server python3 ~/manage.py createsuperuser

6. 访问 CVAT

主界面: 打开浏览器访问 http://localhost:8080
API 文档: 访问 http://localhost:8080/api/docs
管理界面: 访问 http://localhost:8080/admin

使用创建的管理员账户登录即可开始使用。

7. 验证安装

# 检查所有服务状态
docker compose ps

# 检查服务健康状态
curl http://localhost:8080/api/v1/server/health

# 检查 API 版本
curl http://localhost:8080/api/v1/server/about

# 检查数据库连接
docker compose exec cvat_server python3 ~/manage.py check

8. 常见启动问题解决

8.1 端口冲突

# 检查端口占用
sudo netstat -tulpn | grep :8080

# 修改端口配置
# 编辑 docker-compose.override.yml 文件
# 将 CVAT_PORT 改为其他端口，如 9090

8.2 内存不足

# 检查系统内存
free -h

# 增加 Docker 内存限制
# 在 Docker Desktop 设置中增加内存分配
# 或修改 docker-compose.yml 中的内存限制

8.3 磁盘空间不足

# 检查磁盘空间
df -h

# 清理 Docker 缓存
docker system prune -a

# 清理 CVAT 数据 (谨慎使用)
docker compose down
docker volume rm cvat_cvat_data cvat_cvat_db

自动标注模型构建

CVAT 支持使用自定义的深度学习模型进行自动标注，这可以大大提高标注效率。本节将详细介绍如何构建、训练和部署自动标注模型。

1. 自动标注架构概述

CVAT 的自动标注系统基于以下组件：

模型服务器：运行深度学习模型的独立服务
模型管理器：管理模型的生命周期和版本
推理引擎：执行模型推理的组件
API 接口：与 CVAT 主服务通信的接口