使用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