Kimai项目中CORS预检请求问题的分析与解决

2025-06-19 03:00:44作者：廉皓灿Ida

Kimai is a web-based multi-user time-tracking application. Works great for everyone: freelancers, companies, organizations - everyone can track their times, generate reports, create invoices and do so much more. SaaS version available at https://www.kimai.cloud

项目地址：https://gitcode.com/gh_mirrors/ki/kimai

问题背景

在Kimai时间跟踪系统的API集成过程中，开发者遇到了一个典型的跨域资源共享(CORS)问题。当从基于WebAssembly的Satori应用(运行在HTTPS环境下)向Kimai API(同样运行在HTTPS)发起请求时，预检OPTIONS请求返回了400 Bad Request错误状态。

技术现象分析

这个问题表现出几个典型特征：

仅在HTTPS环境下出现，HTTP环境下工作正常
不同浏览器表现不一致：Chromium内核浏览器(Chrome/Edge)会失败，而Firefox则能正常工作
预检请求阶段就失败，阻止了后续的实际API请求

根本原因

经过深入分析，发现问题的核心在于CORS配置不完整。具体来说：

缺少必要的请求头许可：Kimai的CORS配置最初没有包含Authorization头，而现代Web框架(如Blazor)在进行跨域请求时会自动添加这个头
浏览器实现差异：不同浏览器对CORS规范的解释和处理存在细微差别，特别是对头部的处理方式不同，导致Firefox能容忍而Chromium更严格
Nginx配置缺失：在自托管环境中，Nginx反向代理缺少对OPTIONS方法的专门处理，导致预检请求无法通过

解决方案

针对上述问题，我们实施了多层次的解决方案：

1. Kimai核心配置修改

更新了Kimai的CORS配置，明确允许Authorization头：

allow_headers: ['X-AUTH-USER', 'X-AUTH-TOKEN', 'Content-Type', 'Authorization']

这个修改确保了API能够识别并接受现代Web框架自动添加的认证头。

2. Nginx服务器配置优化

对于自托管的Kimai实例，需要额外配置Nginx以正确处理OPTIONS预检请求：

location / {
    if ($request_method = 'OPTIONS') {
        add_header Access-Control-Allow-Origin $http_origin;
        add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS, PUT, PATCH, DELETE';
        add_header Access-Control-Allow-Headers 'Content-Type, Authorization, X-AUTH-USER, X-AUTH-TOKEN';
        add_header Access-Control-Allow-Credentials true;
        add_header Content-Length 0;
        add_header Content-Type text/plain;
        return 204;
    }
    try_files $uri /index.php$is_args$args;
}