在Linux服务器上安装CVAT (Docker 28.5.1)
基于Docker 28.5.1和CVAT的稳定版本组合，确保最佳兼容性。
推荐稳定版本组合
| 组件 | 推荐版本 | 说明 |
|---|---|---|
| Docker | 28.5.1 | 当前稳定版本 |
| CVAT | 2.48.0 | 兼容Docker 28.x |
| Docker Compose | v2.40.3 | Docker 28.x内置compose |
系统要求
Ubuntu 22.04/20.04 LTS
至少 4GB RAM（推荐8GB+）
至少 20GB 可用磁盘空间
网络连接（用于下载镜像）
第一步：安装Docker
1.1 卸载旧版本（可选）
sudo apt-get remove docker docker-engine docker.io containerd runc1.2 更新系统并安装依赖
sudo apt-get update
sudo apt-get install ca-certificates curl1.3 创建密钥目录并添加Docker官方GPG密钥
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc1.4 添加Docker仓库到APT源
echo \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \sudo tee /etc/apt/sources.list.d/docker.list > /dev/null1.5 更新包列表并安装Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin1.6 锁定Docker版本防止自动升级（可选）
sudo apt-mark hold docker-ce docker-ce-cli containerd.io第二步：配置Docker国内镜像源加速
2.1 配置Docker国内镜像源
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<EOF
{"registry-mirrors": ["https://docker.xuanyuan.me","https://docker.1ms.run","https://hub.rat.dev","https://docker.hpcloud.cloud","https://docker.m.daocloud.io","https://docker.tbedu.top/","https://docker.registry.cyou","https://docker-cf.registry.cyou","https://dockercf.jsdelivr.fyi","https://docker.jsdelivr.fyi","https://dockertest.jsdelivr.fyi","https://mirror.aliyuncs.com","https://dockerproxy.com","https://mirror.baidubce.com","https://docker.nju.edu.cn","https://docker.mirrors.sjtug.sjtu.edu.cn","https://docker.mirrors.ustc.edu.cn","https://mirror.iscas.ac.cn","https://docker.rainbond.cc"]
}
EOF2.2 重启Docker服务
sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl enable docker2.3 创建docker用户组并添加当前用户
sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker2.4 验证Docker安装
docker --version
docker compose version应该显示：
Docker version 28.5.1
Docker Compose version v2.40.3第三步：安装CVAT
3.1 克隆CVAT 2.48.0
cd ~
git clone -b 2.48.0 https://github.com/cvat-ai/cvat
cd cvat3.2 设置CVAT访问地址
# 获取本机IP地址
export CVAT_HOST=$(hostname -I | awk '{print $1}')
echo "export CVAT_HOST=$CVAT_HOST" >> ~/.bashrc# 设置CVAT版本环境变量
echo "export CVAT_VERSION=2.48.0" >> ~/.bashrc
source ~/.bashrcecho "CVAT将可通过 http://$CVAT_HOST:8080 访问"第四步：启动CVAT服务
4.1 启动CVAT
根据自己的需求启动方式二选一
4.1.1 启动预构Docker镜像
运行 docker 容器。下载最新的 CVAT 需要一些时间以及其他所需的映像，如 Postgres、Redis 和 Start 容器。
docker compose up -d如果提示超时可以多运行几遍，
4.1.2 本地编译构建
docker compose -f docker-compose.yml -f docker-compose.dev.yml build本地构建也可能会报关于网络超时的问题，多试几次（此处耗时较多）。
关于本地构建需要修改的几处代码：
在Dockerfile中添加国内镜像源配置（以下为修改后完整的Dockerfile文件，可直接复制）
ARG PIP_VERSION=24.2
ARG BASE_IMAGE=ubuntu:22.04FROM ${BASE_IMAGE} AS build-image-base# 配置pip国内镜像源
ENV PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV PIP_TRUSTED_HOST=pypi.tuna.tsinghua.edu.cn
ENV PIP_EXTRA_INDEX_URL=https://pypi.org/simple
ENV PIP_TIMEOUT=300
ENV PIP_RETRIES=10# 完全重写sources.list使用清华大学镜像源
RUN echo "deb http://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse" > /etc/apt/sources.list && \echo "deb http://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse" >> /etc/apt/sources.list && \echo "deb http://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse" >> /etc/apt/sources.list && \echo "deb http://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-security main restricted universe multiverse" >> /etc/apt/sources.list# 配置apt下载优化
RUN echo 'Acquire::Retries "5";' > /etc/apt/apt.conf.d/80-retries && \echo 'Acquire::http::Timeout "120";' >> /etc/apt/apt.conf.d/80-retriesRUN apt-get update && \DEBIAN_FRONTEND=noninteractive apt-get --no-install-recommends install -yq \curl \g++ \gcc \git \libgeos-dev \libldap2-dev \libsasl2-dev \make \nasm \pkg-config \python3-dev \python3-pip \libxml2-dev \libxmlsec1-dev \libxmlsec1-openssl \libhdf5-dev \cargo \wget \# 添加完整的FFmpeg开发包ffmpeg \libavcodec-dev \libavformat-dev \libavdevice-dev \libavutil-dev \libavfilter-dev \libswscale-dev \libswresample-dev \libpostproc-dev \libopenh264-dev \libx264-dev \&& rm -rf /var/lib/apt/lists/*# 配置pip使用国内源
RUN python3 -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \python3 -m pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn && \python3 -m pip config set global.timeout 300 && \python3 -m pip config set global.retries 10# 配置Git使用国内镜像
RUN git config --global url."https://gitclone.com/github.com/".insteadOf "https://github.com/"ARG PIP_VERSION
ENV PIP_DISABLE_PIP_VERSION_CHECK=1
RUN --mount=type=cache,target=/root/.cache/pip/http \python3 -m pip install -U pip==${PIP_VERSION}# We build OpenH264, FFmpeg and PyAV in a separate build stage,
# because this way Docker can do it in parallel to all the other packages.
FROM build-image-base AS build-image-av# 确保使用国内镜像源
RUN python3 -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \python3 -m pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn && \python3 -m pip config set global.timeout 300 && \python3 -m pip config set global.retries 10# 使用系统包管理器安装视频编解码器
ARG PREFIX=/opt/ffmpeg
ARG PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfigENV FFMPEG_VERSION=8.0 \OPENH264_VERSION=2.6.0# 安装完整的FFmpeg开发包
RUN apt-get update && \DEBIAN_FRONTEND=noninteractive apt-get --no-install-recommends install -yq \ffmpeg \libavcodec-dev \libavformat-dev \libavdevice-dev \libavutil-dev \libavfilter-dev \libswscale-dev \libswresample-dev \libpostproc-dev \libopenh264-dev \libx264-dev \&& rm -rf /var/lib/apt/lists/*# 创建符号链接到指定目录（为了兼容原有路径）
WORKDIR /tmp/openh264
RUN echo "使用系统openh264库" && \mkdir -p ${PREFIX}/lib ${PREFIX}/include && \# 复制openh264库文件cp /usr/lib/x86_64-linux-gnu/libopenh264.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/include/openh264/* ${PREFIX}/include/ 2>/dev/null || true && \# 确保库文件存在(test -f ${PREFIX}/lib/libopenh264.so || ln -sf /usr/lib/x86_64-linux-gnu/libopenh264.so ${PREFIX}/lib/libopenh264.so) 2>/dev/null || trueWORKDIR /tmp/ffmpeg
RUN echo "使用系统ffmpeg" && \mkdir -p ${PREFIX}/bin ${PREFIX}/lib ${PREFIX}/include && \# 复制ffmpeg二进制和库文件cp /usr/bin/ffmpeg ${PREFIX}/bin/ 2>/dev/null || true && \cp /usr/bin/ffprobe ${PREFIX}/bin/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libavcodec.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libavformat.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libavdevice.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libavutil.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libavfilter.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libswscale.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libswresample.so* ${PREFIX}/lib/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/libpostproc.so* ${PREFIX}/lib/ 2>/dev/null || true && \# 复制头文件cp -r /usr/include/x86_64-linux-gnu/libav* ${PREFIX}/include/ 2>/dev/null || true && \cp -r /usr/include/x86_64-linux-gnu/libsw* ${PREFIX}/include/ 2>/dev/null || true && \# 创建pkg-config文件目录mkdir -p ${PREFIX}/lib/pkgconfig && \# 复制pkg-config文件cp /usr/lib/x86_64-linux-gnu/pkgconfig/libav*.pc ${PREFIX}/lib/pkgconfig/ 2>/dev/null || true && \cp /usr/lib/x86_64-linux-gnu/pkgconfig/libsw*.pc ${PREFIX}/lib/pkgconfig/ 2>/dev/null || true# 设置pkg-config路径
ENV PKG_CONFIG_PATH=${PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH}COPY utils/dataset_manifest/requirements.txt /tmp/utils/dataset_manifest/requirements.txt# Since we're using pip-compile-multi, each dependency can only be listed in
# one requirements file. In the case of PyAV, that should be
# `dataset_manifest/requirements.txt`. Make sure it's actually there,
# and then remove everything else.
RUN grep -q '^av==' /tmp/utils/dataset_manifest/requirements.txt
# 修改PyAV版本为兼容系统FFmpeg的版本
RUN sed -i 's/^av==15.1.0/av==12.0.0/' /tmp/utils/dataset_manifest/requirements.txt
RUN sed -i '/^av==/!d' /tmp/utils/dataset_manifest/requirements.txtRUN --mount=type=cache,target=/root/.cache/pip/http-v2 \python3 -m pip wheel --no-binary=av \-r /tmp/utils/dataset_manifest/requirements.txt \-w /tmp/wheelhouse# This stage builds wheels for all dependencies (except PyAV)
FROM build-image-base AS build-image# 确保build-image阶段也使用国内源 - 使用阿里云镜像
RUN python3 -m pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/ && \python3 -m pip config set global.trusted-host mirrors.aliyun.com && \python3 -m pip config set global.timeout 600 && \python3 -m pip config set global.retries 15COPY cvat/requirements/ /tmp/cvat/requirements/
COPY utils/dataset_manifest/requirements.txt /tmp/utils/dataset_manifest/requirements.txt# Exclude av from the requirements file
RUN sed -i '/^av==/d' /tmp/utils/dataset_manifest/requirements.txt# 更新所有文件中的numpy版本以解决依赖冲突
RUN sed -i 's/^numpy==.*/numpy==1.24.3/' /tmp/cvat/requirements/production.txt && \sed -i 's/^numpy==.*/numpy==1.24.3/' /tmp/cvat/requirements/base.txt 2>/dev/null || true && \sed -i 's/^numpy==.*/numpy==1.24.3/' /tmp/utils/dataset_manifest/requirements.txt# 修正PyYAML版本冲突
RUN sed -i 's/^PyYAML==6.0.3/PyYAML==6.0.2/' /tmp/cvat/requirements/base.txt && \sed -i 's/^PyYAML==6.0.3/PyYAML==6.0.2/' /tmp/cvat/requirements/production.txtARG CVAT_CONFIGURATION="production"RUN --mount=type=cache,target=/root/.cache/pip/http-v2 \DATUMARO_HEADLESS=1 python3 -m pip wheel --no-deps --no-binary lxml,xmlsec \-r /tmp/cvat/requirements/${CVAT_CONFIGURATION}.txt \-w /tmp/wheelhouseFROM golang:1.24.4 AS build-smokescreen# 使用国内镜像下载smokescreen
RUN git clone --filter=blob:none --no-checkout https://gitclone.com/github.com/stripe/smokescreen.git
RUN cd smokescreen && git checkout master && go build -o /tmp/smokescreenFROM ${BASE_IMAGE}ARG http_proxy
ARG https_proxy
ARG no_proxy
ARG socks_proxy
ARG TZ="Etc/UTC"ENV TERM=xterm \http_proxy=${http_proxy} \https_proxy=${https_proxy} \no_proxy=${no_proxy} \socks_proxy=${socks_proxy} \LANG='C.UTF-8' \LC_ALL='C.UTF-8' \TZ=${TZ}# 配置pip国内镜像源（最终镜像）- 添加阿里云源
ENV PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
ENV PIP_TRUSTED_HOST=mirrors.aliyun.com
ENV PIP_EXTRA_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
ENV PIP_TIMEOUT=600
ENV PIP_RETRIES=15ARG USER="django"
ARG CVAT_CONFIGURATION="production"
ENV DJANGO_SETTINGS_MODULE="cvat.settings.${CVAT_CONFIGURATION}"# Install necessary apt packages
RUN apt-get update && \DEBIAN_FRONTEND=noninteractive apt-get --no-install-recommends install -yq \bzip2 \ca-certificates \curl \git \libgeos-c1v5 \libgl1 \libgomp1 \libldap-2.5-0 \libpython3.10 \libsasl2-2 \libxml2 \libxmlsec1 \libxmlsec1-openssl \nginx \p7zip-full \poppler-utils \python3 \python3-venv \supervisor \tzdata \unrar \wait-for-it \# 安装运行时视频编解码器库ffmpeg \libavcodec58 \libavformat58 \libavdevice58 \libavutil56 \libavfilter7 \libswscale5 \libswresample3 \libpostproc55 \&& ln -fs /usr/share/zoneinfo/${TZ} /etc/localtime && \dpkg-reconfigure -f noninteractive tzdata && \rm -rf /var/lib/apt/lists/* && \echo 'application/wasm wasm' >> /etc/mime.types# Install smokescreen
COPY --from=build-smokescreen /tmp/smokescreen /usr/local/bin/smokescreen# Add a non-root user
ENV USER=${USER}
ENV HOME /home/${USER}
RUN adduser --uid=1000 --shell /bin/bash --disabled-password --gecos "" ${USER}ARG CLAM_AV="no"
RUN if [ "$CLAM_AV" = "yes" ]; then \apt-get update && \apt-get --no-install-recommends install -yq \clamav \libclamunrar9 && \sed -i 's/ReceiveTimeout 30/ReceiveTimeout 300/g' /etc/clamav/freshclam.conf && \freshclam && \chown -R ${USER}:${USER} /var/lib/clamav && \rm -rf /var/lib/apt/lists/*; \fi# Install wheels from the build image
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:${PATH}"# 配置虚拟环境中的pip使用国内源
RUN /opt/venv/bin/python3 -m pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple && \/opt/venv/bin/python3 -m pip config set global.trusted-host pypi.tuna.tsinghua.edu.cn && \/opt/venv/bin/python3 -m pip config set global.timeout 300 && \/opt/venv/bin/python3 -m pip config set global.retries 10# Prevent security scanners from finding vulnerabilities in whatever version of setuptools
# is included in Ubuntu by default.
RUN python -m pip uninstall -y setuptools
ARG PIP_VERSION
ARG PIP_DISABLE_PIP_VERSION_CHECK=1RUN python -m pip install -U pip==${PIP_VERSION}
RUN --mount=type=bind,from=build-image,source=/tmp/wheelhouse,target=/mnt/wheelhouse \--mount=type=bind,from=build-image-av,source=/tmp/wheelhouse,target=/mnt/wheelhouse-av \python -m pip install --no-index /mnt/wheelhouse/*.whl /mnt/wheelhouse-av/*.whlENV NUMPROCS=1
COPY --from=build-image-av /opt/ffmpeg/lib /usr/lib# These variables are required for supervisord substitutions in files
# This library allows remote python debugging with VS Code
ARG CVAT_DEBUG_ENABLED
RUN if [ "${CVAT_DEBUG_ENABLED}" = 'yes' ]; then \python3 -m pip install --no-cache-dir debugpy; \fi# Removing pip due to security reasons. See: https://scout.docker.com/vulnerabilities/id/CVE-2018-20225
# The vulnerability is dubious and we don't use pip at runtime, but some vulnerability scanners mark it as a high vulnerability,
# and it was decided to remove pip from the final image
RUN python -m pip uninstall -y pip# Install and initialize CVAT, copy all necessary files
COPY cvat/nginx.conf /etc/nginx/nginx.conf
COPY --chown=${USER} supervisord/ ${HOME}/supervisord
COPY --chown=${USER} backend_entrypoint.d/ ${HOME}/backend_entrypoint.d
COPY --chown=${USER} manage.py rqscheduler.py backend_entrypoint.sh wait_for_deps.sh ${HOME}/
COPY --chown=${USER} utils/ ${HOME}/utils
COPY --chown=${USER} cvat/ ${HOME}/cvat
COPY --chown=${USER} components/analytics/clickhouse/init.py ${HOME}/components/analytics/clickhouse/init.pyARG COVERAGE_PROCESS_START
RUN if [ "${COVERAGE_PROCESS_START}" ]; then \echo "import coverage; coverage.process_startup()" > /opt/venv/lib/python3.10/site-packages/coverage_subprocess.pth; \fi# RUN all commands below as 'django' user.
# Use numeric UID/GID so that the image is compatible with the Kubernetes runAsNonRoot setting.
USER 1000:1000
WORKDIR ${HOME}RUN mkdir -p data share keys logs /tmp/supervisord staticEXPOSE 8080
ENTRYPOINT ["./backend_entrypoint.sh"]修改./cvat/requirements/base.txt
# 完全移除版本限制，让pip选择兼容版本
sed -i 's/==/>=/g' cvat/requirements/base.txt清理缓存
# 如果遇到损坏的包或者不匹配的包需要清理缓存，重新构建
docker builder prune -f# 也可以使用docker build直接构建特定阶段
docker build \--target build-image \--no-cache \-t cvat_server_build_image \-f Dockerfile .# 然后继续使用compose构建
docker compose -f docker-compose.yml -f docker-compose.dev.yml build cvat_server4.2 监控启动过程
# 实时查看启动日志（可选）
docker compose logs -f &# 等待服务完全启动（重要！）
echo "等待CVAT服务启动，这可能需要3-5分钟..."
sleep 1804.3 检查所有服务状态
docker compose ps预期正常状态：
NAME SERVICE STATUS PORTS
cvat_db cvat_db Running
cvat_redis cvat_redis Running
cvat_server cvat_server Running 8080/tcp
cvat_ui cvat_ui Running 80/tcp
... 所有服务都是Running状态4.4 如果服务异常的处理
# 如果服务没有正常启动，执行清理重启
docker compose down
docker system prune -f
docker volume prune -f# 重新启动
docker compose up -d
sleep 180
docker compose ps第五步：创建管理员账户
5.1 等待数据库完全就绪
# 检查数据库状态
until docker logs cvat_db 2>&1 | grep -q "database system is ready to accept connections"; doecho "等待数据库启动..."sleep 10
done
echo "数据库已就绪"5.2 创建超级用户
# 方法1：直接创建
docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'# 方法2：如果方法1失败，先进入容器再创建
docker exec -it cvat_server bash
# 在容器内执行：
python3 ~/manage.py createsuperuser
# 创建完成后输入 exit 退出容器按照提示输入管理员信息：
用户名: admin
电子邮件: admin@example.com
密码: ******** (建议使用强密码)
密码确认: ********
Superuser created successfully.第六步：验证安装和访问
6.1 最终状态检查
# 检查所有服务状态
docker compose ps# 检查CVAT服务日志
docker logs cvat_server | tail -10# 获取最终访问信息
echo "==========================================="
echo "CVAT安装完成！"
echo "访问地址: http://$CVAT_HOST:8080"
echo "管理员用户名: admin"
echo "使用您设置的密码登录"
echo "==========================================="6.2 浏览器访问测试
在浏览器中访问 http://您的服务器IP:8080：
使用
admin和您设置的密码登录确认可以正常进入CVAT界面
尝试创建一个测试任务验证功能正常
访问方式详解
7.1 局域网内直接访问
http://服务器IP:8080示例：如果服务器IP是 192.168.1.100，则访问 http://192.168.1.100:8080
7.2 外部网络访问（SSH隧道）
# 在您的笔记本电脑上执行
ssh -L 8080:localhost:8080 用户名@服务器IP -N# 后台运行版本
ssh -L 8080:localhost:8080 用户名@服务器IP -N -f# 然后浏览器访问
# http://localhost:80807.3 浏览器要求
✅ Google Chrome (90+，推荐)
✅ Microsoft Edge (90+)
✅ Brave (基于Chromium)
⚠️ Firefox (可能部分功能不兼容)
❌ Safari (不推荐)
维护和管理命令
8.1 日常管理
# 停止CVAT服务
cd ~/cvat && docker compose down# 启动CVAT服务
cd ~/cvat && docker compose up -d# 查看服务状态
cd ~/cvat && docker compose ps# 查看服务日志
cd ~/cvat && docker compose logs8.2 数据备份
# 备份数据库
docker exec cvat_db pg_dump -U root cvat > cvat_backup_$(date +%Y%m%d).sql# 备份上传的文件
tar -czf cvat_data_backup_$(date +%Y%m%d).tar.gz ~/cvat/data8.3 问题诊断
# 查看详细服务状态
docker compose ps -a# 查看特定服务日志
docker compose logs cvat_server
docker compose logs cvat_db# 检查资源使用
docker system df
docker stats故障排除指南
9.1 端口冲突
# 检查端口占用
sudo netstat -tulpn | grep 8080# 修改CVAT端口
# 编辑 docker-compose.override.yml 修改端口映射9.2 磁盘空间不足
# 清理Docker资源
docker system prune -a -f
docker volume prune -f# 检查空间使用
df -h
docker system df9.3 服务启动失败
# 查看详细错误
docker compose logs cvat_server
docker compose logs cvat_db# 完全重置
cd ~/cvat
docker compose down -v
docker system prune -a -f
CVAT_VERSION=2.12.0 docker compose up -d重要提醒
不要随意升级：避免单独升级某个组件导致兼容性问题
定期备份：重要标注数据定期备份到安全位置
监控资源：关注磁盘空间，CVAT运行会占用较多资源
安全考虑：生产环境建议配置防火墙和HTTPS