ActualBudget 项目在 Authentik 代理后 Token 过期问题的分析与解决

问题背景

在 ActualBudget 项目的实际部署中，当通过 Authentik 作为代理提供程序(Proxy Provider)进行身份验证保护时，用户遇到了一个典型的问题：当 Authentik 颁发的令牌(token)过期后，前端应用无法重新连接到后端实例，表现为服务器显示离线状态，直到用户清除浏览器 cookies 并重新登录。

技术环境分析

该问题出现在以下技术栈环境中：

• 后端服务：ActualBudget 服务器(v25.2.0)运行在 Docker 容器中
• 认证层：Authentik 作为 OAuth 提供程序和反向代理
• Web服务器：Nginx 作为前端代理
• 客户端：Chrome 浏览器

问题现象深度解析

从技术角度看，当出现以下情况时问题会重现：

1. 用户首次通过 Authentik 认证成功访问 ActualBudget 应用
2. Authentik 颁发的访问令牌在预设的有效期(如5分钟)后过期
3. 前端应用尝试与后端通信时失败
4. 服务器状态显示为"离线"
5. 只有清除浏览器 cookies 后重新认证才能恢复连接

值得注意的是，当将 Authentik 中的"token validity"(令牌有效期)设置为极长时间(如120,000小时)时，问题不会出现，这直接表明问题与令牌生命周期管理机制相关。

根本原因诊断

经过技术分析，该问题主要由以下因素共同导致：

1. CORS(跨源资源共享)配置缺失：当令牌过期需要重新认证时，前端应用无法正确处理跨域重定向请求，因为缺少必要的 CORS 头部信息。

2. 认证流程中断：Nginx 代理层未能正确处理认证失败后的重定向流程，导致前端应用无法感知到需要重新认证的状态。

3. 令牌刷新机制缺失：系统缺乏自动刷新令牌的机制，当初始令牌过期后，没有建立获取新令牌的流程。

解决方案实施

1. 完善 Nginx CORS 配置

在 Nginx 配置中添加以下关键 CORS 头部信息：

add_header 'Access-Control-Allow-Origin' '*' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
add_header 'Access-Control-Allow-Headers' 'Origin, X-Requested-With, Content-Type, Accept, Authorization' always;
add_header 'Access-Control-Allow-Credentials' 'true' always;

同时需要处理预检(OPTIONS)请求：

if ($request_method = OPTIONS) {
    add_header 'Access-Control-Allow-Origin' '*' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS, PUT, DELETE' always;
    add_header 'Access-Control-Allow-Headers' 'Origin, X-Requested-With, Content-Type, Accept, Authorization' always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Content-Length' '0';
    add_header 'Content-Type' 'text/plain';
    return 204;
}

2. 调整 ActualBudget 环境变量

在 Docker 容器环境变量中增加：

environment:
  - CORS_ALLOWED_ORIGINS=*
  - CORS_ALLOW_CREDENTIALS=true

3. 认证流程优化建议

虽然 ActualBudget 已内置多用户功能，但对于仍需使用外部认证的系统，建议：

1. 实现令牌自动刷新机制
2. 在前端应用中添加认证状态监控
3. 优化错误处理流程，确保认证失败时能正确重定向

实施效果验证

实施上述解决方案后，系统应表现出以下改进：

1. 当令牌过期时，前端应用能正确接收认证失败响应
2. 系统会自动重定向到认证页面，而不会显示"离线"状态
3. 用户完成重新认证后能无缝返回原操作界面
4. 不再需要手动清除 cookies 来恢复连接

总结

在将 ActualBudget 部署于 Authentik 等认证代理后的场景中，正确处理跨域请求和认证流程是确保系统稳定运行的关键。通过完善 CORS 配置和优化认证流程，可以有效解决令牌过期导致的连接中断问题。对于类似系统的部署，建议在初期就充分考虑认证生命周期管理和错误处理机制的设计。

对于更复杂的部署场景，建议参考 ActualBudget 官方文档或参与社区讨论获取针对特定环境的优化建议。随着 ActualBudget 功能的不断完善，内置的多用户支持可能成为更简单可靠的替代方案。