1. 为什么要在 Windows 上折腾 CVAT 这套标注系统做计算机视觉项目的人迟早会撞上一件事数据标不动了。LabelImg 单机版开三个窗口就卡团队里几个人各标各的格式对不上标完还得手动合并改一个框要来回传文件。CVAT 就是冲着这个痛点来的——它把标注做成了浏览器里的协作平台支持目标检测、关键点、多边形、语义分割、追踪等一堆任务类型还能直接导出 YOLO、COCO、VOC 这些主流格式。但 CVAT 官方主推的是 Linux 部署Windows 用户一看文档就头大。其实在 Windows 10/11 上跑 CVAT 完全可行核心路径就两条WSL2 提供 Linux 内核环境Docker Desktop 负责容器编排。这套组合的好处是你不需要装双系统不需要买服务器一台带独显的普通开发机就能把整套标注平台跑起来局域网内同事直接浏览器访问。这篇内容适合三类人一是刚接触 CVAT、想在自己电脑上先跑通再决定要不要上服务器的二是团队里负责搭环境、被 Windows 兼容性折磨过的三是已经用过 LabelImg 或 Labelme想升级到协作标注流程的。我会把 WSL2 配置、Docker 环境准备、CVAT 拉取启动、常见报错排查这几块讲透尤其是那些官方文档一笔带过、实际踩起来很疼的细节。先说结论整套流程走下来从零到能在浏览器里打开 CVAT 登录页顺利的话 40 分钟到 1 小时。卡住的地方基本集中在 WSL2 安装、Docker 资源分配、端口映射这三处。下面按实际操作顺序拆开讲。2. WSL2 环境搭建别急着敲命令先确认三件事2.1 虚拟化与系统版本的前置检查很多人一上来就wsl --install结果报错才发现 BIOS 里虚拟化没开。这一步必须先确认。打开任务管理器切到性能标签看 CPU 那一栏右下角有没有虚拟化已启用。如果是已禁用重启进 BIOS找 Intel VT-x 或 AMD-V 打开。这个开关不打开后面所有步骤都是白费。系统版本也有硬门槛。WSL2 要求 Windows 10 版本 1903 及以上内部版本 18362 以上Windows 11 全系支持。按Win R输入winver就能看到。如果是 Win10 老版本先跑 Windows Update 升上去别想着绕过。还有一个容易被忽略的点WSL2 依赖 Hyper-V 相关的虚拟化组件。如果你之前装过 VMware 或 VirtualBox 的老版本可能和 Hyper-V 冲突。VMware Workstation 15.5.5 以后、VirtualBox 6.0 以后都兼容了但保险起见装 WSL2 前把这类软件升到最新或者临时关掉。2.2 一条命令装 WSL2 与手动兜底方案Windows 10 2004 以后的版本微软把安装简化成了一条命令。以管理员身份打开 PowerShell执行wsl --install这条命令会自动启用适用于 Linux 的 Windows 子系统和虚拟机平台两个功能下载 WSL2 内核并默认装一个 Ubuntu。装完重启电脑首次进入 Ubuntu 会让你设用户名和密码。但实测下来这条命令在部分机器上会卡在下载环节或者装完默认发行版不是你要的。手动兜底更稳分三步# 第一步启用两个必需功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 第二步重启后下载并安装 WSL2 内核更新包微软官网搜 WSL2 Linux kernel update package # 第三步把默认版本设为 WSL2 wsl --set-default-version 2然后去 Microsoft Store 搜 Ubuntu 22.04 安装或者用命令行wsl --install -d Ubuntu-22.04。我推荐 Ubuntu 22.04 LTS因为 CVAT 官方镜像和依赖在这个版本上验证最充分20.04 也能用但新版本少踩坑。提示装完先跑wsl -l -v确认版本号那一列是 2。如果是 1用wsl --set-version Ubuntu-22.04 2转换转换过程会花几分钟。2.3 WSL2 的资源分配与磁盘位置调整WSL2 默认会吃掉最多一半的物理内存这在跑 CVAT 时可能不够用也可能反过来把宿主机拖卡。资源分配靠一个配置文件控制。在 Windows 用户目录下创建.wslconfig路径是C:\Users\你的用户名\.wslconfig内容如下[wsl2] memory8GB processors4 swap4GB localhostForwardingtruememory给多少取决于你机器总内存。16G 的机器给 8G 比较合适32G 的可以给到 12G 到 16G。processors建议给物理核心数的一半左右。localhostForwardingtrue这行很关键它让 WSL2 里的服务能通过 Windows 的 localhost 访问CVAT 的 Web 界面就靠它。另一个大坑是磁盘位置。WSL2 的虚拟磁盘默认放在 C 盘CVAT 的镜像加上数据动辄几十 GC 盘很快就红了。迁移方法是先导出再导入# 关闭 WSL wsl --shutdown # 导出到 D 盘 wsl --export Ubuntu-22.04 D:\wsl\ubuntu2204.tar # 注销原发行版 wsl --unregister Ubuntu-22.04 # 导入到新位置 wsl --import Ubuntu-22.04 D:\wsl\Ubuntu-22.04 D:\wsl\ubuntu2204.tar --version 2导入后默认用户会变成 root需要改回来。进 WSL 后编辑/etc/wsl.conf加上[user] default你的用户名这套操作我做过好几次唯一要注意的是导出前确保 WSL 完全关闭否则 tar 包可能损坏。3. Docker Desktop 在 Windows 上的正确打开方式3.1 安装选项里那两个勾必须打Docker Desktop 的安装包去官网下Windows 版直接双击。安装向导里有两个选项很多人一路下一步就跳过了结果后面 CVAT 起不来Use WSL 2 instead of Hyper-V必须勾。这决定 Docker 跑在 WSL2 后端还是老的 Hyper-V 后端。CVAT 的 compose 文件对 WSL2 后端兼容性更好。Add shortcut to desktop随意不影响功能。装完重启首次启动 Docker Desktop 会弹服务条款接受后等鲸鱼图标变绿。如果图标一直转圈或变红多半是 WSL2 没装好回去检查第 2 节。3.2 把 Docker 的资源限制和 WSL 集成配好Docker Desktop 默认会占用 WSL2 的全部资源和我们在.wslconfig里的设置可能打架。打开 Docker Desktop 的 SettingsGeneral确认 Use the WSL 2 based engine 是勾选状态。Resources这里能看到 CPU、内存、Swap 的分配。如果你在.wslconfig里已经限制了这里显示的是上限。建议内存给 6G 以上CVAT 的 server、db、redis 几个容器加起来吃 4G 左右留点余量。Resources WSL Integration把 Enable integration with my default WSL distro 打开下面列出你的 Ubuntu 发行版也勾上。这样你在 WSL 终端里能直接用docker命令不用切回 PowerShell。配完点 Apply Restart。验证一下在 WSL 终端里跑docker --version docker compose version两条都有输出就说明打通了。注意 CVAT 用的是docker composeV2 语法中间有空格不是老的docker-compose。Docker Desktop 现在自带 compose V2不用单独装。3.3 镜像加速与磁盘清理的实操建议国内拉 Docker 镜像慢是常态CVAT 涉及十几个镜像不配加速可能等到怀疑人生。在 Docker Desktop 的 Settings Docker Engine 里编辑 JSON 配置加上镜像源{ registry-mirrors: [ https://docker.mirrors.ustc.edu.cn, https://hub-mirror.c.163.com ] }改完 Apply Restart。镜像源地址会变用之前先确认还能用。另外提醒一句Docker 的镜像和容器数据默认存在 WSL2 的虚拟磁盘里也就是你迁移过的那个位置。定期清理没用的镜像能省不少空间docker system prune -a这条命令会删掉所有没在运行的镜像和容器跑之前确认没有需要保留的东西。我一般一个月清一次能回收十几 G。4. 拉取并启动 CVATcompose 文件里的门道4.1 获取源码与选择部署模式CVAT 的部署文件在 GitHub 上直接 clone 下来git clone https://github.com/cvat-ai/cvat.git cd cvatclone 下来的是开发分支可能带一些未稳定的改动。想要稳定版切到最新的 release taggit tag git checkout v2.14.0版本号按当时最新的来。切 tag 这步别省开发分支偶尔会有 compose 文件不匹配的情况新手排查起来很痛苦。CVAT 提供几种部署模式核心区别在docker-compose.yml和几个 override 文件模式命令适用场景基础版docker compose up -d单机使用功能完整带分析加-f docker-compose.dev.yml需要开发调试无服务器版用docker-compose.serverless.yml需要自动标注大多数人用基础版就够了。自动标注比如用模型预标注需要额外配置 serverless 函数那是另一个话题先把基础版跑通再说。4.2 启动命令与首次拉取的等待策略启动命令很简单docker compose up -d-d是后台运行。第一次执行会拉取所有镜像包括 cvat_server、cvat_ui、postgres、redis、nginx 等总共几个 G。网速正常的话十几分钟慢的话半小时以上。这时候别急着 CtrlC让它跑完。拉完镜像后容器会依次启动。用这条命令看状态docker compose ps正常情况下列出的容器状态都是Up或Up (healthy)。cvat_server和cvat_db启动最慢因为 server 要等数据库初始化。如果某个容器一直Restarting用docker compose logs 容器名看日志。启动完成后浏览器打开http://localhost:8080应该能看到 CVAT 的登录页。首次使用要创建超级用户docker exec -it cvat_server bash -ic python3 ~/manage.py createsuperuser按提示输入用户名、邮箱、密码。这个账号就是管理员登录后可以建任务、加用户。4.3 端口冲突与数据持久化的处理8080 端口被占用是高频问题。改端口不用动 compose 文件在项目根目录建一个.env文件加一行CVAT_PORT8081然后重启docker compose down docker compose up -d。这样 Web 界面就跑到 8081 了。数据持久化方面CVAT 用 Docker volume 存数据库和上传的图片、标注。这些 volume 默认在 WSL2 磁盘里docker compose down不会删但docker compose down -v会连 volume 一起删标注数据全没。这条命令千万别手滑我见过有人清理环境时顺手加了-v一周的标注成果直接归零。想备份数据用docker run --rm -v cvat_db_data:/data -v $(pwd):/backup alpine tar czf /backup/cvat_db_backup.tar.gz -C /data .volume 名字用docker volume ls查。定期备份是个好习惯尤其是团队协作场景。5. 那些官方文档不会告诉你的报错与排查5.1 WSL2 相关的典型故障故障一wsl --install卡在 Installing, this may take a few minutes 不动。这通常是网络问题WSL2 内核包下载不下来。手动去微软官网下内核更新包双击安装再跑wsl --set-default-version 2。故障二WSL2 里docker命令找不到。检查 Docker Desktop 的 WSL Integration 有没有勾上你的发行版。勾了还不行在 WSL 里跑which docker没输出说明集成没生效重启 Docker Desktop 和 WSLwsl --shutdown再进。故障三WSL2 时间不同步导致容器报证书错误。WSL2 休眠后系统时间会漂移Docker 拉镜像时报x509: certificate has expired。修复sudo hwclock -s或者直接wsl --shutdown重启 WSL。这个坑在笔记本合盖休眠后特别常见。5.2 CVAT 容器启动失败的排查链路容器起不来第一步永远是看日志别瞎猜docker compose logs --tail100 cvat_server情况一cvat_db一直 unhealthy。多半是之前的数据 volume 损坏或者磁盘满了。先df -h看空间再考虑删掉 db volume 重建会丢数据谨慎。情况二cvat_server报 migration 错误。版本升级后数据库结构没同步。跑docker exec -it cvat_server bash -ic python3 ~/manage.py migrate情况三8080 打开是 502。nginx 起来了但后端没就绪。等一两分钟再刷新或者看cvat_server日志确认它是否还在初始化。首次启动 server 要跑数据库迁移慢是正常的。排查顺序我总结成一句话先看容器状态再看具体容器日志最后看端口和网络。90% 的问题在前两步就能定位。5.3 性能调优与日常维护CVAT 跑起来后如果标注页面卡顿多半是资源不够。在 Docker Desktop 的 Resources 里把内存加到 8G 以上CPU 给 4 核以上。另外标注大图比如 4K 以上分辨率时浏览器端渲染压力大建议在 CVAT 里开启图像分块或者预先缩放。日常维护就三件事定期docker system prune清垃圾、定期备份 db volume、关注 CVAT 的 release 更新。升级版本时先git pull或切新 tag再docker compose pull docker compose up -d数据库迁移会自动跑。6. 从跑通到用顺几个提升效率的实操心得环境跑通只是开始真正用起来还有几个细节值得说。第一用户和权限要提前规划。CVAT 支持组织、项目、任务三级结构。团队用的话先建组织再按项目分任务别所有人挤在一个账号里标。管理员在 Django adminhttp://localhost:8080/admin里能精细控制权限。第二导出格式选对能省大量后处理。做 YOLO 训练就直接导 YOLO 1.1 格式它会生成 images 和 labels 两个文件夹加一个 data.yaml拿来就能训。做 COCO 就导 COCO JSON。别导成 CVAT XML 再自己转多此一举。第三善用快捷键和自动标注。CVAT 的标注界面快捷键很全比如N下一张、F上一帧、CtrlS保存。熟练后效率翻倍。如果配了 serverless 函数可以用预训练模型先自动标一遍人工只做修正工作量能砍掉一大半。第四WSL2 的保活问题。WSL2 在 Windows 空闲一段时间后会自动挂起导致 CVAT 容器断连。解决办法是在 Windows 任务计划里加一个定时任务每隔几分钟跑一次wsl -d Ubuntu-22.04 echo keepalive或者干脆在.wslconfig里关掉自动挂起部分版本支持。这个坑在长时间标注时特别烦标到一半页面失联刷新又要重连。最后分享一个我自己的习惯把整个 CVAT 目录和.wslconfig、.env这些配置文件一起放进 Git 仓库管理数据 volume 除外。换机器或者重装系统时clone 下来改改路径就能恢复比重新配一遍省事得多。环境这东西配一次记一次下次就是十分钟的事。