Hoarder项目容器健康检查异常问题分析与解决方案

问题现象

在使用Hoarder项目（版本0.18.0）的Docker容器部署时，发现容器健康状态持续显示为"unhealthy"。虽然应用功能本身运行正常，但健康检查始终无法通过。

问题排查过程

1. 基础健康检查测试
   通过进入容器执行wget --spider http://127.0.0.1:3000/api/health命令测试，发现连接被拒绝。但使用容器实际IP地址（如172.24.0.5）测试却能成功响应。

2. 网络环境验证
   确认容器运行在自定义的bridge网络模式下，排除了host网络模式的干扰因素。测试localhost连接同样失败，表明服务绑定地址存在问题。

3. 深入分析
   检查发现项目代码中服务绑定逻辑为const hostname = process.env.HOSTNAME || '0.0.0.0'。当用户自定义了HOSTNAME环境变量时，服务将只绑定到指定主机名对应的地址，而非默认的0.0.0.0。

根本原因

用户部署时在docker-compose文件中设置了HOSTNAME: hoarder-app环境变量，导致：

1. 服务未绑定到0.0.0.0
2. 健康检查使用的127.0.0.1/localhost无法访问服务
3. 只有通过容器实际IP才能访问

解决方案

1. 移除docker-compose中自定义的HOSTNAME环境变量
2. 或者显式设置HOSTNAME: 0.0.0.0

技术启示

1. 环境变量冲突：常见系统/框架环境变量（如HOSTNAME）可能影响应用行为
2. 服务绑定策略：生产环境服务应明确绑定地址（0.0.0.0或特定IP）
3. 健康检查设计：应考虑容器网络环境的多样性

最佳实践建议

1. 避免使用可能冲突的环境变量名
2. 在Dockerfile中显式指定服务绑定地址
3. 健康检查端点应测试实际服务可达性
4. 日志中记录服务启动时绑定的地址信息

通过这个案例，我们可以更好地理解容器环境下网络配置与服务绑定的重要性，以及环境变量可能带来的潜在影响。