Hoarder项目移动端网络连接问题分析与解决方案

问题背景

Hoarder是一款自托管内容管理应用，近期多位用户报告其移动端应用出现"Network Request Failed"错误。该问题主要出现在以下场景：

1. 使用自签名证书的HTTPS连接
2. HTTP明文连接
3. 反向代理环境（如Traefik/Nginx）

技术分析

根本原因

Android系统对网络安全有严格限制，主要涉及两个层面：

1. 证书验证机制：默认不信任用户安装的CA证书
2. 明文传输限制：Android 9+默认禁止非加密HTTP连接

具体表现

1. 自签名证书场景下，即使已将CA证书安装到设备信任库，应用仍报"Trust anchor for certification path not found"错误
2. HTTP连接时意外尝试HTTPS升级导致证书验证失败
3. 反向代理配置不当可能导致连接问题

解决方案

应用层修复

项目维护者通过以下方式解决了该问题：

1. 在AndroidManifest.xml中添加网络安全配置：

android:networkSecurityConfig="@xml/network_security_config"
android:usesCleartextTraffic="true"

2. 创建network_security_config.xml配置文件：

<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
            <certificates src="user" />
        </trust-anchors>
    </base-config>
</network-security-config>

用户临时解决方案

在官方修复发布前，用户可尝试：

1. 确保URL包含正确的协议头（http://或https://）
2. 对于自签名证书，检查证书链是否完整
3. 反向代理环境检查SSL终止配置

最佳实践建议

1. 生产环境：建议使用正规CA签发的证书
2. 开发/测试环境：
   • 如需使用自签名证书，确保证书已正确安装到设备信任库
   • 考虑在应用调试版本启用更宽松的安全配置
3. 网络配置：
   • 保持协议一致性（避免HTTP/HTTPS混用）
   • 反向代理需正确配置SSL终止和证书传递

版本更新

该修复已包含在Hoarder移动端v1.6.8及后续版本中，用户更新应用后即可解决大部分网络连接问题。对于特殊网络环境，建议结合连接测试功能进行诊断。

总结

Hoarder项目的这一案例展示了移动应用在复杂网络环境下面临的典型连接问题。通过合理配置网络安全策略，可以在保证基本安全性的同时，兼顾自托管场景下的灵活性。这为同类自托管应用的移动端开发提供了有价值的参考。