CVAT Docker部署深度排障：从数据库连接超时到管理员创建的完整解决方案

最近在帮助团队部署CVAT时遇到一个典型问题——服务启动后无法创建管理员账户，错误提示数据库连接超时。这个问题看似简单，实则涉及Docker网络配置、服务依赖关系和CVAT初始化流程等多个技术层面。本文将带您深入剖析这个问题的根源，并提供一套完整的诊断和解决方案。

1. 问题现象与初步诊断

当执行 docker-compose up -d 后，所有容器都显示"done"状态，表面上看服务已经正常启动。但尝试通过 localhost:8080 访问Web界面时却遭遇失败，更关键的是在创建管理员账户时出现以下错误：

django.db.utils.OperationalError: could not connect to server: Connection timed out
Is the server running on host "cvat_db" (172.28.0.3) and accepting TCP/IP connections on port 5432?

这个错误信息揭示了几个关键点：

• CVAT应用容器(cvat)无法连接到数据库容器(cvat_db)
• 连接目标是主机名"cvat_db"，解析到的IP是172.28.0.3
• 超时发生在PostgreSQL默认端口5432

常见误判 ：很多开发者第一反应是数据库服务没启动，但通过 docker ps 检查会发现cvat_db容器确实在运行。这提示我们问题可能出在网络连通性上。

2. 深入排查网络连通性问题

要确认网络问题，我们需要进入容器内部进行测试。以下是详细的诊断步骤：

2.1 检查容器间网络连通性

首先进入cvat容器测试到数据库的连接：

docker exec -it cvat bash
ping cvat_db

如果ping不通，说明容器间网络通信存在问题。接着检查数据库端口是否开放：

nc -zv cvat_db 5432

2.2 验证数据库服务状态

进入数据库容器检查PostgreSQL服务：

docker exec -it cvat_db bash
ps aux | grep postgres

确认服务运行后，测试本地连接：

psql -U postgres -h localhost

注意：如果容器内能连接但外部不能，问题可能出在PostgreSQL的监听配置上

2.3 分析Docker网络配置

检查Docker网络详情：

docker network inspect cvat_default

重点关注以下配置项：

• Subnet和Gateway设置
• 容器IP分配情况
• 网络驱动类型

3. 解决方案：修复IP地址冲突

通过上述排查，最常见的问题是Docker网络子网冲突。以下是具体修复步骤：

3.1 修改docker-compose.yml

找到CVAT项目中的 docker-compose.yml 文件，修改网络配置部分：

networks:
  default:
    ipam:
      config:
        - subnet: 172.18.0.0/16

同时检查 docker-compose.serverless.yml 中的相关配置：

networks:
  default:
    external: true
    name: cvat_default

3.2 清理并重建环境

执行以下命令彻底清理旧环境：

docker-compose down
docker network prune
sudo systemctl restart docker

然后重新启动服务：

docker-compose up -d

3.3 验证修复效果

再次尝试创建管理员账户：

docker exec -it cvat bash -ic 'python3 ~/manage.py createsuperuser'

成功创建后，通过 localhost:8080 访问Web界面应该就能正常登录了。

4. 高级配置与优化建议

4.1 自定义Docker网络

为避免IP冲突，可以预先创建自定义网络：

docker network create --subnet=172.18.0.0/16 cvat_net

然后在docker-compose.yml中指定使用该网络：

networks:
  default:
    external: true
    name: cvat_net

4.2 数据库连接参数调优

在CVAT的配置文件中调整数据库连接参数：

# cvat/settings/production.py
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'HOST': 'cvat_db',
        'PORT': '5432',
        'NAME': 'cvat',
        'USER': 'root',
        'PASSWORD': '',
        'OPTIONS': {
            'connect_timeout': 10,
            'options': '-c statement_timeout=30000'
        }
    }
}

4.3 健康检查配置

为容器添加健康检查，确保服务完全就绪：

services:
  cvat:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
  cvat_db:
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 30s
      timeout: 5s
      retries: 3

5. 常见问题与替代方案

5.1 防火墙与SELinux问题

如果问题依旧，考虑系统级限制：

# 检查防火墙规则
sudo iptables -L
# 临时关闭测试
sudo systemctl stop firewalld
# 或针对Docker添加规则
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0

5.2 替代连接方式

如果容器间DNS解析有问题，可以尝试使用link方式：

services:
  cvat:
    links:
      - cvat_db:db

然后在代码中使用 db 作为主机名连接数据库。

5.3 数据库持久化配置

确保重要数据不会丢失：

services:
  cvat_db:
    volumes:
      - cvat_db_data:/var/lib/postgresql/data
volumes:
  cvat_db_data:

在多次部署CVAT的过程中，我发现网络配置问题是最常见的故障点。特别是在企业环境中，当主机已经存在多个Docker网络时，子网冲突的概率会大大增加。预先规划好网络方案，能节省大量故障排查时间。