PHP 中基于黑白名单的 IP 访问控制实现教程-php教程-PHP中文网

PHP 中基于黑白名单的 IP 访问控制实现教程

本文详解如何在 PHP 中正确实现 IP 黑白名单访问控制，重点解决因类属性未声明导致的文件路径丢失、IpList 初始化失败等常见问题，并提供健壮、可扩展的完整实现方案。

本文详解如何在 php 中正确实现 ip 黑白名单访问控制，重点解决因类属性未声明导致的文件路径丢失、`iplist` 初始化失败等常见问题，并提供健壮、可扩展的完整实现方案。

在构建 Web 安全防护机制时，基于 IP 的访问控制是基础且有效的手段之一。然而，如示例代码所示，一个看似微小的疏漏——未在类中显式声明私有属性 $whitelistfile 和 $blacklistfile——会导致构造函数中对文件路径的赋值失效（PHP 会自动创建动态属性，但该属性无法被后续逻辑可靠访问），进而使 IpList 实例无法正确加载对应数据文件，最终造成白名单失效、拦截逻辑异常等问题。

要从根本上避免此类问题，必须严格遵循 PHP 面向对象编程规范：所有类成员变量需在类作用域内明确定义。以下是修复后的完整、可运行的 IpBlockList 类结构（含关键注释与增强逻辑）：

<?php class IpBlockList {
    private $statusid = ['negative' => -1, 'neutral' => 0, 'positive' => 1];
    private $whitelistfile;
    private $blacklistfile;
    private $whitelist;
    private $blacklist;
    private $message = null;
    private $status = null;

    public function __construct($whitelistfile = './security/whitelist.dat', $blacklistfile = './security/blacklist.dat') {
        // 显式赋值，确保路径可用
        $this->whitelistfile = $whitelistfile;
        $this->blacklistfile = $blacklistfile;

        // 安全检查：验证文件是否存在且可读
        if (!is_readable($this->whitelistfile)) {
            throw new RuntimeException("Whitelist file not readable: {$this->whitelistfile}");
        }
        if (!is_readable($this->blacklistfile)) {
            throw new RuntimeException("Blacklist file not readable: {$this->blacklistfile}");
        }

        // 初始化 IP 列表管理器（假设 IpList 已正确定义）
        $this->whitelist = new IpList($this->whitelistfile);
        $this->blacklist = new IpList($this->blacklistfile);
    }

    /**
     * 检查客户端 IP 是否允许访问
     * 优先级：白名单 > 黑名单 > 默认放行
     * @return bool true 表示允许访问，false 表示拒绝
     */
    public function isAllowed(): bool {
        $clientIp = $this->getClientIp();

        // 白名单优先：匹配即放行
        if ($this->whitelist->contains($clientIp)) {
            $this->status = $this->statusid['positive'];
            $this->message = "Access granted (whitelisted)";
            return true;
        }

        // 黑名单拦截：匹配即拒绝
        if ($this->blacklist->contains($clientIp)) {
            $this->status = $this->statusid['negative'];
            $this->message = "Access denied (blacklisted)";
            return false;
        }

        // 默认放行
        $this->status = $this->statusid['neutral'];
        $this->message = "Access granted (default)";
        return true;
    }

    /**
     * 获取真实客户端 IP（兼容代理环境）
     */
    private function getClientIp(): string {
        $ip = $_SERVER['REMOTE_ADDR'] ?? '127.0.0.1';
        if (!empty($_SERVER['HTTP_X_FORWARDED_FOR'])) {
            $ips = array_map('trim', explode(',', $_SERVER['HTTP_X_FORWARDED_FOR']));
            $ip = $ips[0]; // 取第一个可信代理 IP
        }
        return filter_var($ip, FILTER_VALIDATE_IP) ?: '127.0.0.1';
    }

    // 可选：提供状态与消息获取方法，便于日志或调试
    public function getStatusMessage(): string { return $this->message ?? ''; }
    public function getStatusId(): int { return $this->status ?? $this->statusid['neutral']; }
}

⚠️ 重要注意事项：

PHP

编写健壮的PHP代码，规避类型转换陷阱、数组怪癖及常见安全漏洞。

下载

IpList 类需自行实现：它应支持从 .dat 文件按行读取 IP（支持 CIDR、IPv4/IPv6），并提供 contains($ip) 方法进行高效匹配（建议使用 ip2long() + 网络掩码校验或 filter_var() 配合 inet_pton()）。
文件格式规范：whitelist.dat 与 blacklist.dat 应为纯文本，每行一个 IP 或 CIDR 段（如 192.168.1.0/24），空行和 # 开头的注释行应被忽略。
部署安全建议：将 ./security/ 目录置于 Web 根目录之外，或通过 Web 服务器配置禁止直接 HTTP 访问 .dat 文件。
性能优化：若 IP 列表较大，建议在构造时预加载至内存数组或使用 Redis 缓存，避免每次请求重复读取文件。