LANraragi文件上传API稳定性问题分析与解决方案

问题背景

在LANraragi项目中，用户通过API上传压缩包文件时存在一个稳定性问题。具体表现为：在10-20%的概率下，系统会在处理文件缩略图提取时抛出未捕获的异常，导致文件虽然已物理存储但未正确注册到数据库。这个问题会导致"僵尸文件"现象——文件存在于存储目录但系统无法识别，同时还会阻碍同名文件的重复上传。

问题现象分析

当异常发生时，系统日志会显示以下错误信息：

[Archive] [error] Failed to parse file: "" - error: fileparse(): need a valid pathname

深入调查发现：

1. 异常发生在extract_thumbnail调用链中的get_filelist和is_pdf函数
2. 出现异常时，系统尝试处理的文件ID为空字符串
3. 文件已完整上传到存储目录，但未在Redis数据库中注册
4. 系统清理功能（如重新扫描存档、清理搜索等）无法修复此问题

根本原因

经过深入排查，发现问题源于文件名冲突的特殊情况：

1. 当用户先上传文件X，再上传同名文件Y时
2. 且X和Y的文件内容不同导致计算出的LRR ID不同
3. 系统在这种情况下会触发异常，导致文件Y无法正确注册

解决方案

针对这个问题，建议从以下几个方面进行修复：

1. 增强异常处理：在文件解析和ID生成的关键路径添加更完善的异常捕获机制
2. 冲突处理优化：改进同名文件上传时的处理逻辑，确保即使ID不同也能正确处理
3. 状态一致性检查：增加后台任务定期检查文件系统与数据库的一致性，自动修复"僵尸文件"

经验总结

这个案例展示了分布式系统中常见的状态一致性问题。在文件上传这类涉及多个子系统（文件系统、数据库、缓存）的操作中，需要特别注意：

1. 事务完整性的保证
2. 异常情况的全面处理
3. 系统状态的自我修复能力

通过这次问题的分析和解决，也为LANraragi项目的稳定性提升提供了宝贵经验。开发者可以借此机会进一步完善系统的错误处理机制和状态管理策略，提高整体可靠性。

后续改进

建议在项目后续开发中考虑：

1. 实现更健壮的文件上传事务机制
2. 添加更详细的日志记录，便于问题诊断
3. 开发自动修复工具处理已存在的"僵尸文件"