使用 mysqli::debug 时需要的系统权限说明

M66 2025-06-01

mysqli::debug() 是 PHP 的 MySQLi 扩展提供的一个调试函数，允许开发者记录与 MySQLi 连接和操作相关的调试信息。这个函数在排查数据库连接问题或者性能瓶颈时非常有用。不过，它的使用是有前提条件的，尤其是在权限方面，稍有不慎可能导致无法生效或引发安全隐患。

一、mysqli::debug() 函数简介

mysqli::debug(string $debug_options): bool

此函数允许你指定调试选项，系统会将相关日志写入到 MySQL 客户端库支持的位置（通常是一个文件）。这个函数只能在初始化 MySQLi 对象之前调用。

示例：

mysqli::debug("d:t:o,/tmp/client.trace");
$mysqli = new mysqli("localhost", "user", "password", "database");

上面这段代码会将调试日志写入 /tmp/client.trace 文件。

二、使用 mysqli::debug() 所需的系统权限

1. 文件系统写入权限

路径权限要求： 调试日志文件写入的路径（如 /tmp/client.trace）必须是 PHP 进程有权限写入的。也就是说，Web 服务器用户（如 www-data, apache, nginx 等）需要对该文件夹具有写入权限。
建议做法：
- 日志路径应设置为 Web 服务用户具有写入权限的路径；
- 避免使用根目录或敏感路径（如 /etc/, /root/）；
- 如果使用自定义路径，确保该路径已存在并可写。

sudo chown www-data:www-data /tmp
sudo chmod 755 /tmp

2. SELinux 或 AppArmor 的限制（如适用）

在启用了 SELinux 或 AppArmor 的系统中，即便文件系统权限正确，也可能因为策略限制导致无法写入日志文件。

解决办法：
- 查看审计日志（通常为 /var/log/audit/audit.log）；
- 临时放宽限制，或配置自定义策略以允许写入。

3. PHP 配置相关权限

mysqli::debug() 的行为可能受到 disable_functions 限制。
- 如果在 php.ini 中禁用了 mysqli::debug，则无法使用；
- 同时要确认 open_basedir 没有限制日志路径的写入。

; php.ini 示例
disable_functions =
open_basedir = /var/www:/tmp

三、使用 mysqli::debug() 的注意事项

1. 只能在连接之前调用

调用 mysqli::debug() 必须在 new mysqli() 之前执行，否则会被忽略。

2. 性能影响

开启调试日志会导致一定的性能开销，建议仅在开发或故障排查时启用。

3. 日志泄露风险

调试日志可能包含敏感信息，如数据库连接详情、查询语句等，不应暴露在公共目录下，避免安全风险。

建议设置访问权限：

chmod 600 /tmp/client.trace

4. 日志轮替管理

如果调试时间较长，日志文件可能变得非常大，应结合系统日志轮替机制（如 logrotate）进行管理。

四、代码示例：使用 mysqli::debug() 并确保权限正确

<?php
$logPath = "/tmp/mysqli_debug.log";

// 检查路径是否可写
if (is_writable(dirname($logPath))) {
    mysqli::debug("d:t:o," . $logPath);
} else {
    error_log("日志目录不可写: " . dirname($logPath));
}

// 建立连接
$mysqli = new mysqli("localhost", "testuser", "testpass", "testdb");

if ($mysqli->connect_error) {
    die("连接失败: " . $mysqli->connect_error);
}

// 查询演示
$result = $mysqli->query("SELECT * FROM articles WHERE domain = 'm66.net'");

while ($row = $result->fetch_assoc()) {
    echo "标题: " . $row["title"] . "<br>";
}

$mysqli->close();
?>

五、小结

mysqli::debug() 是一个强大的调试工具，但使用它时需确保：

写入路径可访问且权限正确；
PHP 环境允许使用该函数；
日志文件保护到位；
调试完成后及时关闭，以免带来安全和性能问题。

在遵守最佳实践的前提下，mysqli::debug() 将是定位数据库问题的一大利器。

mysqli::debug