从CVAT“无法连接服务器”到根治磁盘危机——一次完整的Docker问题排查实录
当您满怀期待地启动CVAT，却被一个冰冷的“无法连接到服务器”弹窗挡住去路时，一天的坏心情可能就此开始。但这不仅仅是一个简单的网络问题，它背后可能隐藏着更深层次的系统瓶颈。
本文将详细记录一次解决CVAT连接失败问题的全过程，从初步诊断到发现深层原因，再到实施根本性解决方案，以及在过程中遇到的新问题和最终的修复方法。这不仅是一份问题解决指南，更是一次关于系统诊断和Docker管理的深度实践。
第一章：初步诊断 - “Up”状态下的迷雾
问题现象: CVAT前端界面弹窗提示“无法连接到服务器”，并建议检查后端、数据库、Redis等服务是否正常运行。
按照软件工程的常识，第一反应是检查服务状态。CVAT由一系列Docker容器构成，因此我们首先想到的就是 docker-compose。
操作1：检查容器状态
docker-compose ps
结果分析:
终端输出显示，包括 cvat_server、cvat_db、cvat_redis_inmem 在内的所有服务，其 STATUS 均为 Up。
这是一个典型的“陷阱”。服务“Up”仅代表容器进程已经启动，但并不意味着服务内部是健康的。应用可能在启动后因无法连接到依赖项、配置错误或其他内部问题而崩溃或无法正常工作。
操作2：深入日志，寻找线索
要了解服务内部发生了什么，日志是唯一可靠的真相来源。我们重点检查核心后端服务 cvat_server 的日志。
docker-compose logs cvat_server
第二章：拨云见日 - 两个致命的错误浮出水面
cvat_server 的日志非常丰富，但在大量的启动信息中，我们精准地捕获到了两条关键的 ERROR 记录：
错误1：OPA健康检查失败
ERROR health-check: unknown error: 500 Server Error: Internal Server Error for url: http://opa:8181/health?bundles
这表明 cvat_server 在尝试访问其依赖的 opa (Open Policy Agent) 服务的健康检查接口时，收到了500服务器内部错误。这直接导致 cvat_server 自身的健康状态变为不健康，从而让前端认为“无法连接”。
错误2：磁盘空间严重不足
ERROR health-check: warning: 97cdbd19e335 94.1% disk usage exceeds 90%
这是一个更根本、也更严重的问题！日志反复警告，Docker容器所在的文件系统磁盘使用率已高达 94.1%。
根本原因分析:
至此，整个问题的逻辑链条变得清晰：
- 根源: 服务器的根分区磁盘空间即将耗尽。
- 直接影响: 像OPA这样的服务在运行时可能需要写入临时文件或日志，磁盘空间不足会导致其内部功能异常，从而在健康检查时返回500错误。
- 连锁反应: cvat_server 因为无法确认OPA服务的健康而将自己标记为不健康。
- 最终表现: 前端UI在轮询后端健康检查接口时得到失败响应，最终显示“无法连接到服务器”。
而磁盘空间的“罪魁祸首”，正是日益增多的Docker镜像和容器数据。
第三章：釜底抽薪 - 迁移Docker的“家”
治标不如治本。清理一些Docker镜像（docker system prune）只能临时缓解问题，只要我们继续使用，空间迟早会再次被占满。
根本解决方案: 将整个Docker的数据目录从默认的系统分区 (/var/lib/docker) 迁移到一个容量更大的独立分区（例如，挂载在 /data 的数据盘）。
原理: Docker引擎允许通过其配置文件 daemon.json 中的 data-root 参数来指定其数据存储的根目录。这是一个对上层应用（如 docker-compose 和容器本身）完全透明的底层改动，因此无需修改任何项目代码或docker-compose.yml文件。
操作步骤：
1. 创建新目录
sudo mkdir -p /data/docker
2. 停止Docker服务: 必须完全停止Docker引擎及其套接字，以防在迁移过程中有新的数据写入。
sudo systemctl stop docker.service
sudo systemctl stop docker.socket
3. 配置daemon.json: 编辑（或创建）/etc/docker/daemon.json 文件，告诉Docker新的数据目录位置。
# 使用你喜欢的编辑器，如 nano 或 vim
sudo nano /etc/docker/daemon.json
写入以下内容：
{
"data-root": "/data/docker"
}
4. 迁移数据: 使用 rsync 将旧目录的所有内容（包括文件权限和属性）完整地复制到新目录。
sudo rsync -aP /var/lib/docker/ /data/docker/
5. 备份旧目录: 为安全起见，先重命名旧目录作为备份，而不是直接删除。
sudo mv /var/lib/docker /var/lib/docker.old
6. 重启Docker:
sudo systemctl start docker
docker info | grep "Docker Root Dir"
docker info 的输出确认了新的根目录为 Docker Root Dir: /data/docker。
总结与启示
最后，回到CVAT项目目录，执行 docker-compose up -d，服务顺利启动。再次访问Web界面，熟悉的标注工具终于出现，问题圆满解决。
这次排查经历带给我们几个深刻的启示：
- 日志是根本: 任何“无法连接”的背后都有原因，而日志是揭示真相的唯一途径。
- 洞察根本原因: 不要满足于解决表面问题（如重启OPA服务），要深入挖掘导致问题的根源（磁盘空间不足）。
- 掌握工具原理: 理解 docker 的 data-root 配置等核心原理，能让你采取更优雅、更彻底的解决方案。
- 细心与验证: 配置文件中的一个字符错误就可能导致整个服务瘫痪。每一步操作后都应进行验证。
- 学会调试: systemctl status 和 journalctl 是调试 systemd 管理的系统服务的两大神器。
希望这篇详细的实录，能为您在未来的系统维护和问题排查中提供一份有价值的参考。
