Medusa下载处理器失效问题分析与解决方案

问题现象

在使用Medusa媒体管理工具时，用户遇到了下载处理器(Download Handler)功能失效的问题。具体表现为：

1. 从SABnzbd下载完成的文件无法被自动识别和处理
2. 剧集状态停留在"已抓取(Snatched)"阶段
3. 文件长期滞留在下载目录中不被移动

环境信息

• 运行环境：Docker容器(LinuxServer.io镜像)
• Medusa版本：1.0.22
• Python版本：3.12.9
• 下载工具：SABnzbd和Transmission

问题分析

从日志中可以观察到几个关键点：

1. Transmission连接测试：日志显示Medusa每5分钟会尝试连接Transmission服务(17:07:01和17:12:02)，虽然能成功连接(返回状态码200)，但随后又会出现409冲突状态。

2. SABnzbd处理缺失：虽然用户主要遇到的是SABnzbd下载不被处理的问题，但日志中完全没有SABnzbd相关的处理记录，这表明下载处理器可能根本没有检测到SABnzbd的下载任务。

3. 配置检查：用户确认已启用下载处理器选项，并关闭了计划后处理功能，排除了基本配置错误。

根本原因

根据用户最后的回复，问题最终定位到下载路径设置不正确。当Medusa配置的下载路径与实际下载工具使用的路径不一致时，会导致下载处理器无法正确识别和定位已完成的下载文件。

解决方案

1. 路径一致性检查：

   • 确保Medusa中配置的下载路径与SABnzbd/Transmission的实际下载路径完全一致
   • 在Docker环境中特别注意卷映射和路径解析问题

2. 配置验证步骤：

   • 在Medusa设置中检查"下载设置"→"下载处理器"配置
   • 核对SABnzbd的API密钥和服务器地址是否正确
   • 确认SABnzbd的"已完成下载目录"与Medusa配置匹配

3. 日志监控：

   • 修改配置后，观察Medusa日志中是否出现SABnzbd相关的处理记录
   • 确保下载处理器能正确识别下载完成状态

预防措施

1. 在容器化部署时，建议使用环境变量统一管理路径配置
2. 定期检查下载工具的目录设置是否发生变化
3. 启用详细的调试日志，便于及时发现处理异常

总结

Medusa下载处理器失效通常是由于配置不一致导致的。在容器化环境中，路径映射问题尤为常见。通过仔细核对各项路径配置，确保Medusa与下载工具使用相同的路径定义，可以有效解决此类问题。对于Docker用户，建议在容器配置中明确标注所有关键路径的映射关系，避免因路径解析差异导致的功能异常。