在 Yii2 中实现黑名单 IP 过滤最直接有效的方式是在控制器的 beforeAction() 方法中拦截，发生在动作执行前，可及时终止非法请求；也可封装为 ActionFilter 类通过 behaviors 复用，或结合 AccessControl 扩展实现细粒度控制，生产环境需注意真实 IP 解析、黑名单查询性能及日志记录。
在 Yii2 中实现黑名单 IP 过滤，最直接有效的方式就是在控制器的 beforeAction() 方法中做拦截。它发生在动作执行前，能及时终止非法请求，且无需引入额外组件或中间件概念。
在控制器中重写 beforeAction 拦截
这是最轻量、最可控的做法。所有请求进入具体 action 前都会经过这个方法，适合做全局性安全检查。
- 在控制器类中重写
beforeAction($action)，先调用父类逻辑确保框架正常流程 - 获取客户端真实 IP（注意处理代理头，如
X-Forwarded-For） - 比对预设的黑名单数组或从数据库/缓存读取的黑名单列表
- 匹配成功则直接返回 403 响应，不继续执行后续逻辑
示例代码：
public function beforeAction($action)
{
if (!parent::beforeAction($action)) {
return false;
}
$ip = Yii::$app->request->getUserIP();
$blacklist = ['192.168.1.100', '203.0.113.5']; // 可替换为 DB 查询或 Redis 获取
if (in_array($ip, $blacklist)) {
Yii::$app->response->setStatusCode(403);
echo 'Access denied';
Yii::$app->end();
}
return true;
}
封装成可复用的过滤器类
如果多个控制器都需要 IP 黑名单功能，建议封装为自定义 ActionFilter，通过 behaviors 统一挂载。
Ainative React Sdk
下载
使用 @ainative/react-sdk 为 React 应用添加 AI 聊天和积分。适用于 (1) 安装 @ainative/react-sdk，(2) 使用 useChat hook 实现聊天完成。
- 继承
yii\base\ActionFilter，覆盖beforeAction() - 支持配置黑名单来源（硬编码、配置项、回调函数）
- 支持白名单优先逻辑（例如运维 IP 不受限制）
- 在控制器中声明 behaviors 即可启用，清晰解耦
使用方式示例：
public function behaviors()
{
return [
'ipFilter' => [
'class' => IpBlacklistFilter::class,
'blacklist' => ['192.168.1.100'],
'whitelist' => ['10.0.0.1'],
],
];
}
结合 AccessControl 实现更细粒度控制
Yii2 的 AccessControl 本身不直接支持 IP 匹配，但你可以扩展它的规则判断逻辑。
- 继承
yii\filters\AccessRule或直接在AccessControl::checkAccess()中注入 IP 判断 - 把 IP 检查作为访问控制的一环，和用户角色、登录态等条件组合使用
- 适合需要“仅对未登录用户限制某 IP”或“对后台模块全局限制某网段”的场景
注意：不要依赖 AccessControl 默认规则字段（如 ips），它在 Yii2 核心中并不存在；必须自行扩展或改用 beforeAction 方案。
生产环境注意事项
实际部署时，有几个关键点容易被忽略：
- 代理环境务必正确解析真实 IP，避免只读
REMOTE_ADDR导致绕过 - 黑名单数据量大时，别用 PHP 数组
in_array，改用 Redis 的SISMEMBER或数据库索引查询 - 记录拦截日志（IP、时间、请求路径），便于事后审计，但注意日志性能影响
- 避免在 beforeAction 中做耗时操作（如远程 HTTP 请求），否则拖慢所有请求
