Vikunja单容器部署问题分析与解决方案

问题背景

Vikunja是一个开源的任务管理平台，最新版本将API和前端合并为单一容器部署。在从多容器架构迁移到单容器架构的过程中，用户遇到了502错误、数据库连接失败等问题。

问题现象

用户在升级到最新版Vikunja单容器版本后，出现了以下症状：

1. 前端访问返回502错误
2. Nginx日志显示"no live upstreams"和"Connection reset by peer"错误
3. Vikunja容器日志显示数据库迁移失败："dial tcp 172.28.0.2:3306: connect: connection refused"

技术分析

架构变更影响

从多容器架构(API和前端分离)迁移到单容器架构时，需要注意以下变化：

1. 端口映射变化：单容器版本使用3456端口同时提供API和前端服务
2. 代理配置简化：不再需要区分API和前端的不同路径
3. 服务发现机制变化：容器间通信方式需要调整

具体问题原因

1. 数据库连接失败：容器网络配置不当导致Vikunja无法连接到MariaDB容器
2. Nginx配置错误：保留了旧版的多路径代理配置，导致请求无法正确路由
3. 端口映射冲突：同时映射了3456和6080端口，但单容器版本只需要3456端口

解决方案

1. 简化Nginx配置

正确的Nginx反向代理配置应简化为：

location / {
    proxy_pass http://localhost:3456;
}

不再需要区分API路径和前端路径的特殊处理，因为单容器版本已经统一处理这些请求。

2. 检查容器网络

确保以下几点：

1. 所有容器在同一个Docker网络中
2. 数据库容器名称与VIKUNJA_DATABASE_HOST环境变量匹配
3. 网络连接测试正常

3. 验证端口映射

单容器版本只需要映射3456端口：

ports:
  - 3456:3456

可以移除6080端口的映射。

最佳实践建议

1. 升级前备份：在进行架构变更前，备份数据库和配置文件
2. 分阶段验证：先验证数据库连接，再测试API，最后检查前端
3. 日志监控：密切关注容器日志和Nginx日志，及时发现连接问题
4. 环境变量检查：确保所有必要的环境变量已正确设置

总结

Vikunja从多容器架构迁移到单容器架构时，主要需要调整Nginx配置和端口映射。通过简化代理配置、确保正确的网络连接和端口映射，可以解决502错误和数据库连接问题。这种架构变更实际上简化了部署流程，减少了维护复杂度，一旦正确配置将提供更稳定的服务。