萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHP 獲取系統環境資訊完整指南:$_SERVER、getenv、php_uname 與實戰應用

核心獲取方法對比

方法優點缺點推薦場景
$_SERVER超全域陣列、效能最佳、資訊最完整鍵名大小寫敏感、部分鍵視 SAPI 而定Web 請求上下文、大多數場景
getenv()跨平台一致、可獲取系統環境變數PHP-FPM 需設定 clear_env=no、效能稍遜CLI 腳本、容器環境、CI/CD
php_uname()作業系統級資訊(核心、主機名、架構)不含 Web 請求資訊系統資訊收集、診斷報表
PHP 常數編譯期常數、零開銷僅限編譯時已知資訊版本判斷、路徑常數

$_SERVER 關鍵鍵值完整速查

<?php
// 伺服器身份與網路
$_SERVER['SERVER_NAME']        // 伺服器主機名 (ServerName 指令)
$_SERVER['SERVER_ADDR']        // 伺服器 IP (有時為空,建議 gethostbyname($_SERVER['SERVER_NAME']))
$_SERVER['SERVER_PORT']        // 伺服器端口 (80/443/其他)
$_SERVER['SERVER_SOFTWARE']    // 伺服器軟體版本 (Apache/2.4.52, nginx/1.20.1)
$_SERVER['SERVER_PROTOCOL']    // 協議版本 (HTTP/1.1, HTTP/2.0)
$_SERVER['DOCUMENT_ROOT']      // 網站根目錄絕對路徑

// 請求資訊
$_SERVER['REQUEST_METHOD']     // GET, POST, PUT, DELETE...
$_SERVER['REQUEST_URI']        // 完整請求 URI (/path?query=string)
$_SERVER['REQUEST_TIME']       // 請求開始 Unix 時間戳 (整數)
$_SERVER['REQUEST_TIME_FLOAT'] // 請求開始浮點時間戳 (微秒精度)
$_SERVER['QUERY_STRING']       // 查詢字串 (query=string)
$_SERVER['HTTP_HOST']          // Host 標頭 (含端口,最可靠的域名來源)
$_SERVER['HTTP_REFERER']       // 來源頁面 (不可信,可偽造)
$_SERVER['HTTP_USER_AGENT']    // 瀏覽器 UA 字串
$_SERVER['HTTP_ACCEPT']        // Accept 標頭
$_SERVER['HTTP_ACCEPT_LANGUAGE'] // 語言偏好
$_SERVER['HTTP_ACCEPT_ENCODING'] // 支援壓縮 (gzip, deflate, br)
$_SERVER['HTTP_X_FORWARDED_FOR'] // 代理鏈客戶端 IP (需信任代理)
$_SERVER['HTTP_X_REAL_IP']     // 真實客戶端 IP (Nginx proxy_set_header)
$_SERVER['REMOTE_ADDR']        // 直接客戶端 IP (可能是代理 IP)
$_SERVER['REMOTE_PORT']        // 客戶端端口
$_SERVER['REMOTE_HOST']        // 客戶端主機名 (罕見)

// 腳本資訊
$_SERVER['SCRIPT_FILENAME']    // 當前執行腳本絕對路徑
$_SERVER['SCRIPT_NAME']        // 腳本路徑 (相對 DocumentRoot)
$_SERVER['PHP_SELF']           // 當前腳本路徑 (含 path_info)
$_SERVER['argv']               // CLI 參數陣列
$_SERVER['argc']               // CLI 參數個數

// HTTPS 判斷
$_SERVER['HTTPS']              // 'on' 表示 HTTPS (Apache)
$_SERVER['HTTP_X_FORWARDED_PROTO'] // 'https' (Nginx 代理常用)
?>

實用工具函數庫

1. 統一獲取客戶端真實 IP

<?php
function get_client_ip(): string {
    // 信任的代理 IP 列表(負載均衡器、CDN、Nginx 代理)
    $trustedProxies = ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '127.0.0.1'];
    
    $headers = [
        'HTTP_X_FORWARDED_FOR',  // 標準代理頭,可能包含多個 IP
        'HTTP_X_REAL_IP',        // Nginx 常用
        'HTTP_CLIENT_IP',        // 部分 CDN
        'HTTP_CF_CONNECTING_IP', // Cloudflare
        'REMOTE_ADDR',           // 最後防線
    ];
    
    foreach ($headers as $header) {
        if (!empty($_SERVER[$header])) {
            // X-Forwarded-For 可能包含多個 IP:client, proxy1, proxy2...
            $ips = array_map('trim', explode(',', $_SERVER[$header]));
            
            // 從左至右找第一個不在信任代理名單中的 IP
            foreach ($ips as $ip) {
                if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE)) {
                    return $ip;
                }
                // 若全部是私有 IP,回傳第一個
            }
            return $ips[0];
        }
    }
    return '0.0.0.0';
}

// CIDR 匹配輔助
function ip_in_range(string $ip, string $cidr): bool {
    list($rangeIp, $mask) = explode('/', $cidr);
    $mask = ~((1 << (32 - $mask)) - 1);
    return (ip2long($ip) & $mask) === (ip2long($rangeIp) & $mask);
}
?>

2. 判斷 HTTPS

<?php
function is_https(): bool {
    return (!empty($_SERVER['HTTPS']) && $_SERVER['HTTPS'] !== 'off')
        || (!empty($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https')
        || (!empty($_SERVER['HTTP_X_FORWARDED_SSL']) && $_SERVER['HTTP_X_FORWARDED_SSL'] === 'on')
        || (isset($_SERVER['SERVER_PORT']) && $_SERVER['SERVER_PORT'] == 443);
}
?>

3. 獲取完整當前 URL

<?php
function get_current_url(): string {
    $protocol = is_https() ? 'https' : 'http';
    $host = $_SERVER['HTTP_HOST'] ?? $_SERVER['SERVER_NAME'];
    $uri = $_SERVER['REQUEST_URI'] ?? '/';
    return "{$protocol}://{$host}{$uri}";
}

function get_base_url(): string {
    $protocol = is_https() ? 'https' : 'http';
    $host = $_SERVER['HTTP_HOST'] ?? $_SERVER['SERVER_NAME'];
    $script = dirname($_SERVER['SCRIPT_NAME']);
    return "{$protocol}://{$host}{$script}";
}
?>

4. 系統環境資訊收集(診斷/回報用)

<?php
function get_system_info(): array {
    return [
        'php' => [
            'version' => PHP_VERSION,
            'sapi' => PHP_SAPI, // 等同 php_sapi_name()
            'os' => PHP_OS,     // 編譯時目標 OS
            'runtime_os' => php_uname('s'), // 實際運行 OS
            'release' => php_uname('r'),    // 核心版本
            'machine' => php_uname('m'),    // 硬體架構
            'node' => php_uname('n'),       // 主機名
            'ini_path' => php_ini_loaded_file(),
            'extensions' => get_loaded_extensions(),
        ],
        'server' => [
            'software' => $_SERVER['SERVER_SOFTWARE'] ?? 'CLI',
            'addr' => $_SERVER['SERVER_ADDR'] ?? 'N/A',
            'name' => $_SERVER['SERVER_NAME'] ?? 'N/A',
            'port' => $_SERVER['SERVER_PORT'] ?? 'N/A',
            'document_root' => $_SERVER['DOCUMENT_ROOT'] ?? 'N/A',
        ],
        'request' => [
            'method' => $_SERVER['REQUEST_METHOD'] ?? 'CLI',
            'uri' => $_SERVER['REQUEST_URI'] ?? '',
            'time' => $_SERVER['REQUEST_TIME_FLOAT'] ?? microtime(true),
            'client_ip' => get_client_ip(),
            'user_agent' => $_SERVER['HTTP_USER_AGENT'] ?? 'CLI',
        ],
        'limits' => [
            'memory_limit' => ini_get('memory_limit'),
            'max_execution_time' => ini_get('max_execution_time'),
            'post_max_size' => ini_get('post_max_size'),
            'upload_max_filesize' => ini_get('upload_max_filesize'),
        ],
    ];
}

// 輸出 JSON 供監控系統收集
header('Content-Type: application/json; charset=utf-8');
echo json_encode(get_system_info(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
?>

容器化環境特殊處理

<?php
// Docker/K8s 環境常見問題與解決

// 1. 獲取容器真實 IP (而非宿主機 IP)
function get_container_ip(): string {
    // 讀取網卡資訊
    $output = shell_exec('ip route get 1.1.1.1 2>/dev/null | awk \'{print $7}\'');
    return trim($output) ?: 'unknown';
}

// 2. 從環境變數獲取配置 (12-factor app)
$dbHost = getenv('DB_HOST') ?: 'localhost';
$dbPass = getenv('DB_PASSWORD') ?: '';
$appEnv = getenv('APP_ENV') ?: 'production';

// 3. PHP-FPM clear_env 設定
; /etc/php-fpm.d/www.conf
; clear_env = no  ; 允許傳遞系統環境變數給 PHP 進程
; env[DB_HOST] = $DB_HOST  ; 顯式傳遞

安全性警示

  • 不可信任:`HTTP_*` 開頭的鍵值來自客戶端 Header,**可任意偽造**
  • 驗證代理:只有確認請求來自受信任代理(Nginx、ALB、Cloudflare)時,才信任 `X-Forwarded-*`
  • 最小權限:僅暴露必要資訊給前端/日誌,避免洩露伺服器內部結構
  • 清理輸出:日誌記錄前對 `$_SERVER` 敏感鍵(如 `HTTP_AUTHORIZATION`、Cookie)進行遮罩

總結

掌握 PHP 系統資訊獲取的核心在於:

  1. **首選 `$_SERVER`** 獲取請求上下文,效能最好、資訊最全
  2. **善用 `getenv()`** 處理容器化部署與 CI/CD 環境變數
  3. **理解代理鏈路**,正確提取真實客戶端 IP
  4. **區分編譯時/運行時** 環境差異(`PHP_OS` vs `php_uname()`)
  5. **安全第一**:所有來自 `HTTP_*` 的資料視為不可信輸入
copyright © 萬盛學電腦網 all rights reserved