API 存取限制、後台管理介面保護常需 IP 白名單/黑名單機制。本文提供支援 CIDR 網段、萬用字元比對的完整實作。
<?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 '存取允許';
?>
<?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 標頭,可直接用於專案中介層或獨立腳本。