Pi-hole持久登录令牌文件损坏导致管理页面空白问题分析

问题背景

在Pi-hole网络广告过滤系统的使用过程中，当服务器磁盘空间耗尽后，可能会导致管理界面无法正常访问，表现为访问/admin/index.php时出现空白页面。这个问题主要影响运行在Ubuntu 22.04系统上的Pi-hole v5.17.1版本。

问题现象

管理员在尝试访问Pi-hole的Web管理界面时，页面完全空白，没有任何内容显示。通过检查Lighttpd的错误日志，可以发现以下关键错误信息：

PHP Fatal error: Uncaught ValueError: fread(): Argument #2 ($length) must be greater than 0

错误发生在persistentlogin_token.php文件的第48行，具体是读取持久登录令牌文件时出现了问题。

根本原因分析

经过深入分析，发现问题的根源在于：

1. 当服务器磁盘空间不足时，Pi-hole尝试更新持久登录令牌文件($token_file)可能会失败，导致生成一个零字节的空文件。

2. 当前代码在检查令牌文件时，只验证了文件是否存在和是否可读，但没有检查文件大小是否为0。

3. 当代码尝试使用fread()读取这个空文件时，由于传入的长度参数为0，触发了PHP的ValueError异常，导致整个页面加载失败。

技术细节

在persistentlogin_token.php文件中，关键的验证逻辑如下：

if ($token_file and file_exists($token_file) and is_readable($token_file)) {
    $time = fread($t_file, filesize($token_file));
    // ...
}

当filesize($token_file)返回0时，fread()函数会抛出异常，因为PHP 8.0+版本对参数进行了更严格的类型检查。

解决方案

针对这个问题，有两种解决方法：

1. 临时解决方案

对于普通用户，可以采取以下临时措施：

• 使用不同的浏览器访问Pi-hole管理界面
• 清除当前浏览器中与Pi-hole服务器相关的所有cookie

2. 永久修复方案

从代码层面修复，需要在文件检查条件中加入对文件大小的验证：

if ($token_file and file_exists($token_file) and is_readable($token_file) and filesize($token_file)) {
    // 安全的读取操作
}

这个修改确保了只有在文件非空时才会尝试读取内容，避免了空文件导致的异常。

预防措施

为了避免类似问题再次发生，建议：

1. 定期监控服务器磁盘空间使用情况
2. 设置磁盘空间告警阈值
3. 考虑在Pi-hole配置中加入磁盘空间检查逻辑
4. 保持Pi-hole系统及时更新到最新版本

总结

Pi-hole的持久登录令牌机制在磁盘空间不足时可能会出现异常，导致管理界面无法访问。通过理解问题的根本原因，我们不仅可以找到临时解决方案，还能从代码层面提出永久修复方案。这类问题也提醒我们，在编写文件操作相关的代码时，应该考虑所有可能的异常情况，包括文件为空、权限不足、磁盘空间不足等场景，确保系统的健壮性。