Yii框架无全局IP防火墙，IP限制须通过AccessControl过滤器或模块allowedIPs显式配置；漏配即放行，且IP白名单仅为第一道安全栅栏，不能替代认证与授权。
Yii 框架没有全局开关式的“IP防火墙”，所有 IP 限制都必须通过 AccessControl 过滤器或模块级配置显式声明，漏配即放行。
用 AccessControl 配置控制器动作级 IP 白名单
这是最常用、也最灵活的方式，适用于保护登录、后台接口等关键动作。核心是把 ips 字段写进 rules 数组里，且必须配合 allow => true 才生效。
-
ips支持通配符，比如'192.168.*'或'::1'（IPv6 回环），但不支持 CIDR 表示法（如10.0.0.0/8） - 多个 IP 要写成数组：
['127.0.0.1', '192.168.1.100']，空数组或未设置等同于允许所有 IP - 如果同时设置了
roles和ips，两者是“与”关系：用户既要满足角色条件，也要在 IP 列表中 - 注意顺序：规则按数组顺序匹配，遇到第一条匹配的就终止；拒绝规则（
allow => false）要放在允许规则之后，否则可能被提前拦截
示例：
public function behaviors()
{
return [
'access' => [
'class' => \yii\filters\AccessControl::className(),
'only' => ['admin-panel', 'export-data'],
'rules' => [
[
'actions' => ['admin-panel'],
'allow' => true,
'roles' => ['@'],
'ips' => ['10.0.1.*', '127.0.0.1'],
],
[
'actions' => ['export-data'],
'allow' => true,
'roles' => ['admin'],
'ips' => ['192.168.5.0/24'], // ❌ 错误！不支持 CIDR，会被当字面量匹配失败
],
],
],
];
}
给 debug/gii 等开发模块加 IP 锁
这类模块默认只允许本地访问，但生产环境若意外开启，必须靠 allowedIPs 配置兜底。它不是过滤器行为，而是模块自身的白名单字段，优先级高于路由层逻辑。
- 必须在
main-local.php或对应环境配置文件中设置，线上环境（YII_ENV_PROD）绝对不要启用debug或gii -
allowedIPs是严格匹配，不支持通配符，只认完整 IP 或 IPv6 地址（如'::1'） - 如果填了不存在的 IP，模块将对所有人返回 403，且无日志提示，排查时容易卡住
- 调试时临时放开，改完务必删掉或注释掉，避免提交到版本库
配置片段：
if (!YII_ENV_TEST) {
$config['bootstrap'][] = 'gii';
$config['modules']['gii'] = [
'class' => 'yii\gii\Module',
'allowedIPs' => ['192.168.32.100', '::1', '127.0.0.1'],
];
}
自定义 IP 匹配逻辑绕过 ips 字段限制
当需要动态判断（比如读数据库白名单、结合用户身份）、或要支持 CIDR、正则等高级匹配时，ips 字段不够用，得用 matchCallback。
- 回调函数接收两个参数：
$rule（当前规则对象）和$action（当前动作实例），返回布尔值 - 获取客户端 IP 必须用
Yii::$app->request->getUserIP()，不能直接读$_SERVER['REMOTE_ADDR']，否则会绕过 Yii 的代理头处理逻辑 - 回调里可调用 RBAC：
Yii::$app->user->can('manage-ip-whitelist')，实现“管理员能从任意 IP 访问后台”的需求 - 别在回调里做重 IO 操作（如每次请求查一次 DB），性能损耗明显；建议预加载或加缓存
示例（支持 CIDR）：
[
'allow' => true,
'actions' => ['maintenance'],
'matchCallback' => function ($rule, $action) {
$ip = Yii::$app->request->getUserIP();
$whitelist = ['10.0.0.0/8', '172.16.0.0/12'];
foreach ($whitelist as $cidr) {
if ($this->ipInCidr($ip, $cidr)) {
return true;
}
}
return false;
},
]
真正容易被忽略的是：IP 限制永远无法替代认证与授权。一个被放行的 IP 仍可能携带伪造的 X-Forwarded-For，也可能已被入侵。所有敏感操作，IP 白名单只是第一道栅栏，后面还得跟 session 校验、CSRF Token、RBAC 权限检查。
