Komga项目中文件修改时间戳的时区问题解析

在Komga这个漫画服务器项目中，近期发现了一个关于文件修改时间戳时区处理的bug。这个问题主要影响API返回的fileLastModified字段值，虽然该字段被标记为UTC时间格式，但实际上返回的是本地时区时间。

问题背景

Komga作为一个漫画管理服务器，会记录每个漫画文件的最后修改时间。这个时间戳通过API暴露给客户端应用，例如Tachiyomi等漫画阅读器。在1.10.3版本中，系统错误地将本地时区的时间戳标记为UTC时间返回，导致时间显示出现偏差。

技术细节分析

当用户上传或修改漫画文件时，Komga会获取文件系统的最后修改时间。在Java中，通过Files.getLastModifiedTime()方法获取的时间戳是基于文件系统提供的原始值，通常反映的是本地时区时间。然而，Komga在构建API响应时，错误地将这个本地时间直接标记为UTC时间（通过添加"Z"时区标识符），而没有进行时区转换。

例如，如果文件在UTC-6时区的系统中于05:42:32被修改：

• 正确做法：应转换为UTC时间11:42:32并标记为"2024-02-16T11:42:32Z"
• 错误实现：直接输出本地时间"2024-02-16T05:42:32Z"

影响范围

这个bug主要影响：

1. 客户端应用中"最近添加"功能的排序和显示
2. 任何依赖fileLastModified字段进行时间比较的逻辑
3. 跨时区部署时的时间一致性

特别值得注意的是，Tachiyomi的Komga扩展插件曾因此问题在1.4.55版本中切换使用lastModified字段，但这会导致任何元数据变更都会影响"最近添加"的判定。

解决方案

该问题已在Komga 1.10.4版本中修复。修复方案主要包含：

1. 正确识别文件系统返回的时间戳时区
2. 在API响应构建前将本地时间转换为UTC时间
3. 确保所有时间戳字段的时区处理一致性

对于客户端开发者，建议：

• 优先使用created字段作为"最近添加"的判断依据
• 等待用户升级到修复版本后再考虑使用fileLastModified字段

最佳实践建议

在处理时间戳时，开发者应当：

1. 明确每个时间戳的时区来源
2. 在系统边界（如API、数据库）统一使用UTC时间
3. 只在展示层根据用户偏好进行时区转换
4. 在文档中明确说明各时间字段的时区含义

这个问题提醒我们在处理时间数据时需要格外小心，特别是在分布式系统和跨时区场景下，时区处理不当可能导致难以察觉的逻辑错误。