OpenWRT 中 AdGuard Home 插件更新核心失败的排查与修复
1. 当AdGuard Home核心更新失败时，你的路由器可能遇到了什么？
那天晚上我正想给家里的网络做个全面体检，突然发现AdGuard Home插件显示"未启动未重定向"。点开日志一看，核心更新失败了。这种情况就像你给手机系统升级时突然断网——新功能用不了，旧版本还可能出问题。
AdGuard Home在OpenWRT上的工作流程其实很有意思。它每次启动时都会检查核心版本，如果发现本地版本过时，就会自动从GitHub拉取最新版本。但问题就出在这里：GitHub在国内的访问就像早高峰的地铁，时快时慢还经常被拦截。更糟的是，很多软路由设备的存储空间本来就小，更新过程中很容易出现空间不足的情况。
我遇到过最典型的三种报错：
- 网络连接超时：通常伴随着"connection timeout"之类的提示
- 证书验证失败：常见于使用了代理但配置不正确的情况
- 磁盘空间不足：系统会明确提示"No space left on device"
2. 从零开始的故障排查手册
2.1 第一步：检查网络连接状态
先登录OpenWRT的SSH，运行这个命令看看能不能访问GitHub：
ping github.com如果发现丢包严重或者根本ping不通，说明网络连接确实有问题。这时候可以试试用curl测试具体下载链接：
curl -I https://github.com/AdguardTeam/AdGuardHome/releases/latest我自己的经验是，晚上8-10点这个时间段GitHub特别难连。有一次我换了手机热点马上就连上了，这说明确实是宽带运营商的问题。
2.2 第二步：检查存储空间状况
运行这个命令查看磁盘使用情况：
df -h重点看/usr目录的使用率。有次我发现/usr/bin空间只剩2MB，难怪更新会失败。OpenWRT的overlay文件系统设计很特别，根目录看似很大，实际可用空间可能只有几十MB。
2.3 第三步：验证下载链接有效性
AdGuard Home默认使用这两个下载源：
- GitHub官方源
- AdGuard官方CDN
可以手动测试下载速度：
time wget https://static.adguard.com/adguardhome/release/AdGuardHome_linux_armv5.tar.gz如果CDN源也慢，可能需要考虑镜像方案。
3. 六种实测有效的解决方案
3.1 更换下载镜像源（推荐新手）
把默认的GitHub链接替换为国内镜像源是最简单的办法。比如在"更新核心"的设置里，把URL改成：
https://ghproxy.com/https://github.com/AdguardTeam/AdGuardHome/releases/download/v0.107.7/AdGuardHome_linux_armv5.tar.gz注意要把v0.107.7替换成实际的最新版本号。我测试过几个镜像站，ghproxy.com的速度相对稳定。
3.2 修改工作目录（解决空间不足）
如果报错提示空间不足，可以这样操作：
- 登录OpenWRT网页后台
- 找到AdGuard Home设置页面
- 把"工作目录"从/usr/bin/AdGuardHome改为/tmp/AdGuardHome
- 保存并重启服务
记得先创建目标目录：
mkdir -p /tmp/AdGuardHome chmod 777 /tmp/AdGuardHome3.3 手动下载并安装核心
当自动更新怎么都失败时，可以手动操作：
cd /tmp wget [镜像URL] tar xzvf AdGuardHome_*.tar.gz cp AdGuardHome/AdGuardHome /usr/bin/这样虽然麻烦点，但成功率很高。我帮朋友排查问题时，十次有八次都是手动更新解决的。
3.4 清理日志文件释放空间
AdGuard Home的日志文件可能占用大量空间。通过SSH执行：
echo "" > /usr/bin/AdGuardHome/querylog.json echo "" > /usr/bin/AdGuardHome/stats.json或者在网页端："设置"→"常规设置"→最底部点击"清除查询日志"和"清除统计数据"。
3.5 调整overlay分区大小
对于进阶用户，可以考虑扩容overlay：
opkg update opkg install block-mount然后通过fdisk调整分区。不过这个操作有风险，建议先备份配置。
3.6 使用UPX压缩二进制文件
如果空间实在紧张，可以用UPX压缩可执行文件：
opkg install upx upx --best /usr/bin/AdGuardHome这样通常能节省30%-50%的空间，但可能会轻微影响性能。
4. 那些年我踩过的坑与经验分享
有一次更新失败后，我直接删除了整个AdGuardHome目录想重装，结果导致所有配置丢失。后来才知道应该先备份/etc/AdGuardHome.yaml这个配置文件。
还有个常见问题是架构不匹配。比如路由器是armv7，但下载了armv5的版本。可以通过以下命令查看正确架构：
uname -m最坑的一次是证书问题。更新核心时提示SSL验证失败，最后发现是系统时间不对。用这个命令同步时间就解决了：
ntpd -q -n -p pool.ntp.org建议大家在修改配置前，先执行：
uci show adguardhome这样能查看当前所有设置，方便出问题时恢复。