4、环境搭建：CVAT的本地部署与配置（Docker、Nginx、数据库）

好，咱们进入实操环节。

前面聊了那么多标注规范，但工欲善其事，必先利其器。CVAT 是目前业界最主流的视频目标跟踪标注工具之一。我自己的团队从 2020 年开始就用它，踩过不少坑，也积累了一些经验。今天我就把本地部署的完整流程拆开揉碎了讲给你听。

4.1 为什么选择 Docker 部署？

说白了，就是图个省心。

CVAT 依赖的东西挺多：Python、Node.js、PostgreSQL、Redis、Nginx…… 如果手动一个个装，版本冲突能让你怀疑人生。我记得第一次部署时，光解决依赖就花了一整天。

用 Docker 就简单了。所有环境打包在容器里，一键启动。你想想看，是不是省事多了？

4.2 环境准备

开始之前，先确认你的机器满足以下条件：

组件	最低要求	推荐配置
操作系统	Ubuntu 20.04 / CentOS 7	Ubuntu 22.04
CPU	4 核	8 核及以上
内存	8 GB	16 GB
磁盘	50 GB 可用	SSD 200 GB+
Docker	20.10+	24.0+
Docker Compose	v2.0+	v2.20+

4.3 安装 Docker 和 Docker Compose

如果你机器上还没有 Docker，按下面步骤来：

# 更新包索引
sudo apt update

# 安装依赖
sudo apt install -y 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

# 设置稳定版仓库
echo "deb [arch=$(dpkg --print-architecture) 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
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io

# 安装 Docker Compose 插件
sudo apt install -y docker-compose-plugin

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

嗯，这里要注意：安装完成后，记得把当前用户加入 docker 组，不然每次都要 sudo。

sudo usermod -aG docker $USER
# 然后退出终端重新登录

4.4 下载 CVAT 源码并启动

接下来就是重头戏了。我个人习惯把 CVAT 放在 /opt 目录下：

# 克隆 CVAT 仓库
cd /opt
git clone https://github.com/opencv/cvat.git
cd cvat

# 检查版本，建议用稳定版
git checkout v2.11.0  # 或者最新的 release 标签

然后修改环境变量文件 .env：

# 复制默认配置
cp .env.template .env

# 编辑 .env 文件
vim .env

关键配置项如下：

参数	说明	示例值
CVAT_HOST	服务器域名或 IP	your-server-ip
CVAT_PORT	对外暴露端口	8080
POSTGRES_USER	数据库用户名	cvat
POSTGRES_PASSWORD	数据库密码	请设置强密码
POSTGRES_DB	数据库名	cvat

配置好后，一键启动：

docker compose up -d

第一次启动会下载镜像，大概需要 5-10 分钟，取决于你的网速。我当初在公司部署时，网络慢得让人想砸键盘……后来换了国内镜像源才快起来。

4.5 Nginx 反向代理配置

默认情况下，CVAT 直接暴露端口。但在生产环境，我强烈建议用 Nginx 做反向代理。好处很明显：

• 统一管理 SSL 证书
• 负载均衡
• 静态资源缓存

下面是我常用的 Nginx 配置模板：

server {
    listen 80;
    server_name your-domain.com;

    # 重定向到 HTTPS（生产环境）
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    client_max_body_size 5000M;  # 视频文件可能很大

    location / {
        proxy_pass http://localhost:8080;
        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-Proto $scheme;

        # WebSocket 支持（CVAT 实时标注需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }

    location /static/ {
        alias /opt/cvat/cvat/apps/;
        expires 30d;
    }
}

4.6 数据库配置与优化

CVAT 使用 PostgreSQL 作为主数据库，Redis 做缓存和任务队列。默认配置就能用，但如果你想跑大规模标注项目，建议做以下优化：

4.6.1 PostgreSQL 调优

编辑 docker-compose.yml 中的数据库部分：

services:
  cvat_db:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - cvat_db:/var/lib/postgresql/data
    # 添加性能参数
    command: >
      -c shared_buffers=256MB
      -c effective_cache_size=768MB
      -c work_mem=16MB
      -c maintenance_work_mem=64MB
      -c random_page_cost=1.1
      -c effective_io_concurrency=200

这些参数怎么调？我一般按服务器内存的 25% 设置 shared_buffers。比如 16GB 内存的机器，设 4GB 比较合适。

4.6.2 Redis 配置

Redis 主要负责两件事：

• 任务队列（Celery 用）
• 会话缓存

默认配置够用。但如果标注任务特别多，可以增加连接数：

services:
  cvat_redis:
    image: redis:7-alpine
    command: redis-server --maxmemory 512mb --maxmemory-policy allkeys-lru

4.7 验证部署是否成功

启动完成后，打开浏览器访问 http://your-server-ip:8080。你应该能看到 CVAT 的登录页面。

默认管理员账号：

• 用户名：admin
• 密码：在 .env 文件中设置的 DJANGO_SUPERUSER_PASSWORD

如果没设置，默认密码是 admin。嗯，这个一定要改，不然太危险了。

4.8 常见问题排查

我整理了几个高频问题，都是实战中遇到的：

问题	原因	解决方案
容器启动后立即退出	端口被占用	lsof -i :8080 查看占用进程
数据库连接失败	密码不匹配	检查 .env 中的 POSTGRES_PASSWORD
上传视频超时	Nginx 限制	增大 client_max_body_size
WebSocket 断开	反向代理未配置	添加 Upgrade 和 Connection 头

---

公众号:蓝海资料掘金营，微信deep3321