萬盛學電腦網

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

PHP 實作 IP 白名單/黑名單存取控制

前言

API 存取限制、後台管理介面保護常需 IP 白名單/黑名單機制。本文提供支援 CIDR 網段、萬用字元比對的完整實作。

核心函式:is_safe_ip()

<?php
/**
 * 檢查 IP 是否在允許/封鎖清單中
 *
 * @param string $ip       要檢查的 IP,空值自動取得客戶端 IP
 * @param string|array $list 白名單或黑名單,支援 "192.168.1.0/24", "10.0.*.*", "192.168.1.100" 格式
 * @param string $mode     'whitelist' 或 'blacklist'
 * @return bool            true=允許存取(白名單模式)或 true=阻擋(黑名單模式)
 */
function is_safe_ip($ip = '', $list = [], $mode = 'whitelist') {
    if (!$ip) {
        $ip = get_client_ip();
    }

    if (empty($list)) {
        // 無清單視為全開放(白名單模式)或全阻擋(黑名單模式)
        return $mode === 'whitelist';
    }

    if (is_string($list)) {
        $list = array_map('trim', explode(',', $list));
    }

    foreach ($list as $pattern) {
        if (match_ip_pattern($ip, $pattern)) {
            return $mode === 'whitelist'; // 白名單:符合即允許;黑名單:符合即阻擋
        }
    }

    return $mode === 'blacklist'; // 白名單:不符合即阻擋;黑名單:不符合即允許
}

/**
 * IP 模式比對:支援 CIDR、萬用字元、完整 IP
 */
function match_ip_pattern($ip, $pattern) {
    $pattern = trim($pattern);

    // 完整 IP 直接比對
    if ($ip === $pattern) {
        return true;
    }

    // CIDR 格式:192.168.1.0/24
    if (strpos($pattern, '/') !== false) {
        return ip_in_cidr($ip, $pattern);
    }

    // 萬用字元:192.168.*.*, 10.*.*.*
    if (strpos($pattern, '*') !== false) {
        $regex = '^' . str_replace(
            ['.', '*'],
            ['\.', '(?:\\d{1,3})'],
            preg_quote($pattern, '/')
        ) . '$';
        return (bool)preg_match("/$regex/", $ip);
    }

    return false;
}

/**
 * CIDR 比對
 */
function ip_in_cidr($ip, $cidr) {
    list($net, $mask) = explode('/', $cidr);
    $ipLong = ip2long($ip);
    $netLong = ip2long($net);
    $maskLong = ~((1 << (32 - $mask)) - 1);
    return ($ipLong & $maskLong) === ($netLong & $maskLong);
}

/**
 * 取得客戶端真實 IP(支援 Proxy、CDN)
 */
function get_client_ip() {
    $headers = [
        'HTTP_CF_CONNECTING_IP',     // Cloudflare
        'HTTP_X_FORWARDED_FOR',      // 標準代理
        'HTTP_X_REAL_IP',            // Nginx proxy
        'HTTP_CLIENT_IP',
        'REMOTE_ADDR'
    ];

    foreach ($headers as $header) {
        if (!empty($_SERVER[$header])) {
            $ips = array_map('trim', explode(',', $_SERVER[$header]));
            foreach ($ips as $ip) {
                if (filter_var($ip, FILTER_VALIDATE_IP, FILTER_FLAG_NO_PRIV_RANGE | FILTER_FLAG_NO_RES_RANGE)) {
                    return $ip;
                }
            }
            // 若無公網 IP,回傳第一個有效 IP
            foreach ($ips as $ip) {
                if (filter_var($ip, FILTER_VALIDATE_IP)) {
                    return $ip;
                }
            }
        }
    }
    return '0.0.0.0';
}
?>

使用範例

<?php
// 白名單模式:只有清單內 IP 能存取
$whitelist = '192.168.1.0/24, 10.0.0.1, 203.*.*.*';
if (!is_safe_ip('', $whitelist, 'whitelist')) {
    http_response_code(403);
    die('存取被拒絕:您的 IP 不在白名單中');
}

// 黑名單模式:清單內 IP 被阻擋
$blacklist = '192.168.1.100, 10.0.0.0/8';
if (is_safe_ip('', $blacklist, 'blacklist')) {
    http_response_code(403);
    die('存取被拒絕:您的 IP 在黑名單中');
}

echo '存取允許';
?>

整合到 Laravel 中介層

<?php
namespace App\Http\Middleware;

use Closure;

class IpWhitelist
{
    public function handle($request, Closure $next)
    {
        $whitelist = config('security.ip_whitelist', '');
        if (!is_safe_ip($request->ip(), $whitelist, 'whitelist')) {
            abort(403, 'IP 不在白名單中');
        }
        return $next($request);
    }
}
?>

總結

此實作支援 CIDR、萬用字元、多 IP 清單,並正確處理 Proxy 標頭,可直接用於專案中介層或獨立腳本。

copyright © 萬盛學電腦網 all rights reserved