CVAT在AWS EC2上部署失败的排查与解决方案

问题背景

CVAT（Computer Vision Annotation Tool）是一款开源的计算机视觉标注工具。许多用户在尝试将CVAT部署到AWS EC2实例时遇到了404页面无法访问的问题。本文将详细分析该问题的原因，并提供完整的解决方案。

问题现象

用户在AWS EC2实例上部署CVAT后，通过浏览器访问实例的公共IP地址加8080端口时，系统返回"404 page not found"错误。检查安全组规则确认8080端口已开放，但服务仍然无法正常访问。

根本原因分析

通过检查Traefik日志和容器配置，发现问题的核心在于CVAT_HOST环境变量未正确设置。CVAT默认配置中，Traefik的路由规则将主机名限制为localhost：

Host('localhost') && PathPrefix('/api/', '/static/', '/admin', '/documentation/', '/django-rq')

这意味着即使服务在运行，外部请求也会因为主机名不匹配而被拒绝，导致404错误。

解决方案

1. 正确设置CVAT_HOST环境变量

在启动CVAT容器前，必须正确设置CVAT_HOST环境变量，将其指向EC2实例的公共IP地址或域名：

export CVAT_HOST=your-ec2-public-ip

2. 重新部署服务

设置环境变量后，需要重新部署CVAT服务以确保配置生效：

docker compose up -d

3. 验证配置

可以通过以下命令验证Traefik路由规则是否已更新：

docker inspect --format '{{ index .Config.Labels "traefik.http.routers.cvat.rule"}}' cvat_server

正确的输出应显示您设置的EC2公共IP或域名，而非localhost。

深入技术细节

CVAT使用Traefik作为反向代理，Traefik的路由规则决定了哪些请求可以被转发到后端服务。当CVAT_HOST未正确设置时：

1. 默认使用localhost作为主机名限制
2. 外部请求的主机头不匹配路由规则
3. Traefik无法找到匹配的路由，返回404错误

最佳实践建议

1. 持久化环境变量：将CVAT_HOST添加到shell配置文件中(~/.bashrc或~/.zshrc)，避免每次登录都需要重新设置
2. 使用域名：建议配置DNS记录并使用域名而非IP地址，便于后续维护
3. HTTPS配置：生产环境应考虑配置SSL证书启用HTTPS
4. 自动化部署：考虑使用Terraform或CloudFormation脚本自动化整个部署过程

总结

在AWS EC2上部署CVAT时遇到404错误通常是由于CVAT_HOST环境变量未正确设置导致的。通过正确配置该变量并重新部署服务，可以解决此问题。理解Traefik的路由机制对于排查类似问题非常有帮助。对于生产环境部署，建议采用更完善的配置管理和自动化部署方案。