AdGuardHome中基于DoH查询字符串的客户端ID识别问题分析

问题背景

在DNS-over-HTTPS(DoH)服务中，客户端ID通常可以通过查询字符串路径进行传递，例如/dns-query/client-id的形式。AdGuardHome作为一款流行的DNS服务软件，支持通过这种方式识别客户端并应用相应的过滤规则。然而，在实际部署中，部分用户发现客户端ID识别存在不一致性问题。

技术现象

当用户通过iOS设备配置DoH服务，并在URL中指定客户端ID时（如/dns-query/iphone-andrey），AdGuardHome的查询日志界面出现了以下异常现象：

1. 大部分查询请求被识别为"新客户端"，显示的是蜂窝网络IP的反向解析名称
2. 少量查询请求能够正确显示预设的客户端名称
3. 查询日志JSON文件中记录了正确的客户端ID，但Web界面未能正确展示

根本原因分析

通过深入分析日志和技术实现，发现问题的核心在于：

1. 客户端配置误解：用户在配置中将iphone-andrey设置为客户端名称(name)，而非客户端ID(ids列表中的一项)。AdGuardHome需要明确的客户端ID配置才能正确识别。

2. 识别逻辑限制：系统日志显示"no clients with ip 111.111.111.111 and clientid 'iphone-andrey'"，表明服务端虽然获取到了查询字符串中的客户端ID，但在客户端数据库中找不到匹配项。

3. 混合识别机制：AdGuardHome会同时检查客户端IP和客户端ID，当蜂窝网络IP频繁变化时，这种双重验证机制可能导致识别失败。

解决方案

要解决这个问题，需要采取以下配置措施：

1. 正确配置客户端ID：

   clients:
     - name: "iPhone User"
       ids: 
         - "iphone-andrey"  # 这是关键的客户端ID配置
         - "192.168.1.25"
         - "192.168.2.148"
   

2. 验证配置有效性：

   • 通过AdGuardHome管理界面检查客户端列表
   • 确认客户端ID是否出现在"ids"列表中而非仅作为名称

3. 理解识别优先级：

   • 当查询字符串包含客户端ID时，系统会优先尝试匹配ID
   • 仅当ID匹配失败时，才会回退到IP地址识别

技术建议

1. 对于移动设备用户，建议：

   • 优先使用客户端ID而非IP地址进行识别
   • 考虑结合设备MAC地址或DHCP保留地址进行辅助识别

2. 对于网络管理员，建议：

   • 定期审核客户端配置
   • 在变更网络拓扑时更新客户端配置
   • 利用标签(tags)功能对移动设备进行分类管理

总结

AdGuardHome的客户端识别功能虽然强大，但需要正确的配置才能发挥最佳效果。通过本文分析的技术现象和解决方案，用户应该能够更好地理解如何利用查询字符串中的客户端ID来实现精确的客户端识别和策略应用。正确的配置不仅能解决显示问题，还能确保过滤规则被准确应用到目标设备。

对于高级用户，还可以考虑结合AdGuardHome的API实现自动化客户端管理，特别是在设备频繁更换网络环境的场景下，这种自动化管理可以显著提高运维效率。