Jellyseerr项目中DNS缓存机制引发的Kubernetes服务发现问题分析

问题背景

在Jellyseerr媒体请求管理系统的1.9.1版本更新中，开发团队引入了cacheable-lookup库来实现DNS缓存功能。这一变更在Kubernetes环境中引发了一个有趣的服务发现问题：当使用短域名(如jellyfin.media)访问Jellyfin服务时，系统会出现连接超时错误(ETIMEDOUT)，而使用完全限定域名(FQDN)如jellyfin.media.svc.cluster.local则能正常工作。

技术细节分析

这个问题揭示了Kubernetes DNS解析机制与Node.js DNS缓存实现之间的一些微妙差异：

1. Kubernetes DNS解析机制：在Kubernetes集群中，CoreDNS通常会配置搜索域(如svc.cluster.local)来自动补全短域名。容器内的/etc/resolv.conf文件通常包含多个搜索域和较大的ndots值(默认为5)，这会影响DNS查询行为。

2. cacheable-lookup的影响：虽然cacheable-lookup库旨在通过遵守DNS记录的TTL来优化性能，但它可能改变了Node.js默认的DNS查询行为。特别是在处理短域名时，可能没有正确遵循Kubernetes的搜索域补全逻辑。

3. 症状表现：用户观察到系统尝试连接一个不相关的IP地址(199.115.116.216)，这表明DNS解析可能绕过了Kubernetes的内部DNS服务(10.43.0.10)，或者没有正确应用搜索域补全。

解决方案演进

开发团队针对此问题采取了多阶段的解决方案：

1. 初步调试：添加了自定义DNS服务器配置选项，允许用户指定特定的DNS服务器地址进行测试。

2. 问题定位：确认问题与短域名解析相关，完全限定域名可以正常工作，这表明问题出在搜索域补全环节。

3. 架构决策：考虑到cacheable-lookup带来的问题比它解决的更严重，团队决定在2.0.0版本中移除了该库，回归到Node.js原生的DNS解析机制。

最佳实践建议

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

1. 使用完全限定域名(FQDN)来引用集群内服务，如jellyfin.media.svc.cluster.local。

2. 如果必须使用短域名，确保了解Kubernetes的DNS搜索域机制，并适当配置ndots参数。

3. 升级到2.0.0或更高版本，以获得更稳定的DNS解析行为。

技术启示

这个案例展示了基础设施组件(如DNS解析)在容器化环境中的复杂性。即使是看似简单的功能增强(如添加DNS缓存)，也可能因为与底层平台机制的交互而产生意想不到的副作用。开发团队对问题的快速响应和架构调整体现了良好的工程实践。