Kimai反向代理配置中TRUSTED_PROXIES环境变量失效问题解析

在Kimai时间跟踪系统的生产部署中，使用中间服务器是一种常见的架构模式。近期发现了一个关于TRUSTED_PROXIES环境变量在Docker容器中失效的重要问题，这会影响系统在HTTPS环境下的正常运行。

问题现象

当Kimai通过中间服务器（如Traefik）部署时，即使正确设置了TRUSTED_PROXIES环境变量，系统仍然会出现重定向问题。具体表现为：

• 通过HTTPS访问的请求被错误地重定向到HTTP
• 登录/注销流程无法正常工作
• 部分资源加载异常

技术背景

Kimai基于Symfony框架构建，在中间服务器场景下需要正确处理X-Forwarded-*头部。Symfony框架提供了trusted_proxies配置项来定义可信的中间服务器IP地址范围。

问题根源

通过代码审查发现，这个问题源于Kimai从Symfony 4升级到6的过程中，trusted_proxies的配置传递出现了遗漏。虽然文档中提到了TRUSTED_PROXIES环境变量的使用，但实际上该变量在代码中未被正确处理。

解决方案

正确的解决方法是在Kimai的框架配置文件中显式设置trusted_proxies。具体操作如下：

1. 编辑配置文件：/opt/kimai/config/packages/framework.yaml
2. 添加或修改以下配置：

framework:
    trusted_proxies: '%env(TRUSTED_PROXIES)%'

影响范围

这个问题主要影响以下部署场景：

• 使用Docker容器部署
• 采用中间服务器架构
• 启用了HTTPS终止
• 未配置HSTS或其他强制HTTPS的机制

最佳实践建议

对于生产环境部署，建议采取以下措施：

1. 确保trusted_proxies配置正确
2. 在中间服务器层启用HSTS
3. 配置HTTP到HTTPS的自动重定向
4. 定期检查系统日志中的重定向错误

总结

这个问题的发现和解决过程展示了开源社区协作的价值。虽然问题存在时间较长，但由于多种变通方案的存在，直到现在才被发现。对于使用Kimai的企业用户，建议在升级时特别注意中间服务器相关的配置验证。