Jellyseerr 连接超时问题分析与解决方案

问题背景

Jellyseerr 是一款基于 Overseerr 的媒体请求管理工具，用于管理 Plex/Jellyfin 媒体库的内容请求。近期有用户反馈在 Kubernetes 环境中部署 Jellyseerr 2.2.3 版本时遇到了严重的连接问题，表现为无法获取 TMDB 元数据和本地 API 调用失败。

问题现象

用户部署后发现以下异常现象：

1. 界面中所有电影/剧集显示"Series not available"
2. 日志显示无法访问 TMDB 获取元数据
3. 出现本地 API 调用超时错误（ConnectTimeoutError）
4. 容器最终崩溃并被 Kubernetes 重启

关键错误日志显示：

ConnectTimeoutError: Connect Timeout Error (attempted address: localhost:5055, timeout: 10000ms)
[TMDB] Failed to fetch all trending: fetch failed

根本原因分析

经过深入排查，发现问题由两个关键因素导致：

1. Node.js DNS 解析问题：

   • Jellyseerr 2.2.3 使用的 Node.js 版本存在 IPv6 和 DNS 解析的兼容性问题
   • 当 Kubernetes 集群 DNS 解析链复杂时（特别是经过节点本地 DNS 缓存），会导致特定域名解析失败

2. Kubernetes DNS 配置问题：

   • 用户的 CoreDNS 配置将非集群查询转发到节点本地 DNS 缓存
   • 节点 DNS 缓存服务对某些域名（如 api.themoviedb.org）解析异常
   • 但其他域名（如 google.com）却能正常解析，表现出选择性解析失败

解决方案

临时解决方案

对于急于解决问题的用户，可以采取以下临时措施：

1. 修改 CoreDNS 配置：

   • 绕过节点本地 DNS 缓存，直接转发到上游 DNS 服务器
   • 在 CoreDNS 的 ConfigMap 中添加转发规则：

     forward . 8.8.8.8 8.8.4.4
     

2. 使用预览版本：

   • 部署时使用 :preview-nodejs_22 标签的镜像
   • 该版本包含了 Node.js 运行时的改进

永久解决方案

Jellyseerr 开发团队在 2.3.0 版本中彻底解决了此问题，改进包括：

1. Node.js 运行时升级：

   • 更新到更稳定的 Node.js 版本
   • 优化了 DNS 解析处理逻辑

2. IPv4/IPv6 兼容性增强：

   • 改进了双栈网络环境下的连接处理
   • 增加了连接超时和重试机制

3. DNS 解析策略优化：

   • 提供更多 DNS 解析控制选项
   • 增强了错误处理和日志记录

技术细节

Kubernetes DNS 解析流程

在 Kubernetes 环境中，DNS 解析通常遵循以下路径：

Pod → CoreDNS → Node本地缓存 → 局域网DNS → ISP DNS

问题发生时，这种多级转发机制在某些特定配置下会导致解析失败。特别是当：

1. 节点本地 DNS 缓存服务存在 bug 或配置问题
2. 中间环节对 IPv6 支持不完善
3. DNS 查询超时设置不合理

Node.js 网络栈特性

Node.js 的网络栈有一些独特行为：

1. 默认会同时尝试 IPv4 和 IPv6 连接
2. DNS 解析结果缓存策略较为激进
3. 在某些版本中存在 DNS 解析器选择问题

这些特性在与复杂的 Kubernetes 网络环境交互时，可能产生意想不到的问题。

最佳实践建议

对于在 Kubernetes 中部署 Jellyseerr 的用户，建议：

1. 版本选择：

   • 始终使用最新稳定版（当前为 2.3.0+）
   • 避免使用存在已知问题的中间版本

2. DNS 配置：

   • 简化 DNS 解析链，减少中间环节
   • 监控 CoreDNS 日志，确保解析正常
   • 考虑使用可靠性高的上游 DNS（如 8.8.8.8）

3. 网络策略：

   • 确保 Pod 有足够的网络权限
   • 检查网络插件是否限制特定协议（如 IPv6）

4. 资源监控：

   • 设置适当的资源请求/限制
   • 监控 Pod 的内存和 CPU 使用情况

总结

Jellyseerr 的连接超时问题是一个典型的环境兼容性问题，涉及应用运行时、网络协议栈和基础设施配置多个层面。通过升级到 2.3.0 版本并优化 DNS 配置，用户可以彻底解决这一问题。这也提醒我们在复杂环境中部署应用时，需要全面考虑网络栈各层次的兼容性和配置。