如何用Rack::Attack的Fail2Ban实现基于失败次数的IP封禁与自动解封？

Rails应用上线后，几乎都会遇到同一类问题：有人拿着脚本对你的登录接口发起暴力破解，或者某些爬虫高频抓取你的付费内容。如果直接上Nginx层面的封禁规则，配置繁琐且难以动态调整；而Rack::Attack提供的Fail2Ban机制恰好解决了这个痛点——它完全运行在应用层，通过统计每个IP的失败请求次数，自动完成封禁和解封的整个生命周期，配置只需几行代码。

Fail2Ban的工作原理是什么

Fail2Ban这个名字源自Linux下著名的防火墙工具fail2ban，其核心思想一脉相承：监听失败事件，累计失败次数，超过阈值就封禁。Rack::Attack把这个思想移植到了Rack中间件层，使得每一次HTTP请求在进入你的Controller之前，就已经完成了拦截判断。

它的运作依赖三个关键参数：maxretry定义允许的最大失败次数，findtime是统计失败次数的时间窗口，bantime则是封禁时长。举个例子，如果设置maxretry为5、findtime为60秒、bantime为3600秒，含义就是：某个IP在60秒内失败了5次，就会被封禁1小时，1小时后自动解封，计数器清零，一切重新开始。

内部实现上，Fail2Ban维护了两个计数器。一个是失败计数器，key通常是rack::attack:#{discriminator}这种形式，每次匹配到失败条件就自增，并按findtime设置过期时间；另一个是封禁标记，一旦失败次数达到maxretry，就写入一个带bantime过期时间的封禁key。后续请求进来时先检查封禁key是否存在，存在就直接拒绝，根本不会执行后面的业务逻辑。

在Rails项目中完整配置Fail2Ban

首先在Gemfile中加入gem并安装：

# Gemfile
gem 'rack-attack'

# 执行 bundle install 后，还需要在 config/application.rb 中启用中间件
config.middleware.use Rack::Attack

接着创建初始化文件config/initializers/rack_attack.rb，写入Fail2Ban的核心配置。下面的例子针对登录接口做防护：

# config/initializers/rack_attack.rb
class Rack::Attack
  # 使用Redis作为缓存存储，重启应用后封禁状态不会丢失
  Rack::Attack.cache.store = ActiveSupport::Cache::RedisCacheStore.new(
    url: ENV.fetch("REDIS_URL", "redis://127.0.0.1:6379/0")
  )

  # 配置白名单，本地开发环境和内网监控探活不被封禁
  safelist("allow-localhost") do |req|
    req.ip == "127.0.0.1" || req.ip == "::1"
  end

  # 核心配置：对登录接口启用Fail2Ban
  Rack::Attack.fail2ban("login protection", maxretry: 5, findtime: 60, bantime: 3600) do |req|
    # 只拦截POST到/sessions的请求，且IP尚未被封禁时返回true进行计数
    req.path == "/sessions" && req.post?
  end

  # 被封禁后返回429状态码和友好的错误信息
  self.fail2ban_responder = lambda do |req|
    [429, {"Content-Type" => "application/json"}, [JSON.generate({error: "请求过于频繁，请稍后再试"})]]
  end
end

这里有一个非常容易被误解的点需要重点说明：fail2ban代码块返回true的含义是“这个请求值得被计数”，而不是“这个请求失败了”。也就是说，上面配置的实际效果是——任何POST到/sessions的请求都会被计数，无论登录成功还是失败。5次之后就会被封禁，哪怕这5次登录全部成功。这显然不是我们想要的。

正确的做法是让失败判断更精细。可以在登录失败的Controller里手动调用Rack::Attack::Fail2Ban.fail(discriminator)来精确计数：

# app/controllers/sessions_controller.rb
class SessionsController < ApplicationController
  def create
    user = User.find_by(email: params[:email])
    if user&.authenticate(params[:password])
      # 登录成功，清空该IP的失败计数
      Rack::Attack::Fail2Ban.reset(request.ip, "login protection")
      session[:user_id] = user.id
      redirect_to root_path
    else
      # 登录失败，手动登记一次失败
      Rack::Attack::Fail2Ban.fail(request.ip)
      flash.now[:alert] = "邮箱或密码错误"
      render :new, status: :unprocessable_entity
    end
  end
end

而初始化文件中的fail2ban块则只负责封禁判断本身，可以配合请求头做更宽松的预过滤，例如只对不带合法CSRF token的请求生效，或者干脆只做最基本的路径匹配。手动fail的方式能准确区分成功与失败，是生产环境更推荐的模式。

封禁后的响应定制与运维管理

默认情况下被封禁的请求会收到403 Forbidden，但语义上更准确的是429 Too Many Requests。通过设置fail2ban_responder可以完全自定义响应体，比如返回JSON格式的错误信息，方便前端统一处理。也可以在响应头中加入Retry-After告知客户端封禁剩余秒数，体现出更规范的API设计。

运维层面，最常见的需求是手动解封某个误伤的IP。如果使用Redis作为存储，直接用命令行操作即可。先查出对应的key，再用DEL删除：

# 连接Redis后查看所有Fail2Ban相关的key
KEYS *rack::attack*

# unban的原理就是删除这两个key
# 失败计数key：rack::attack::fail2ban:counter:login protection:1.2.3.4
# 封禁标记key：rack::attack::fail2ban:ban:login protection:1.2.3.4
DEL "rack::attack::fail2ban:ban:login protection:1.2.3.4"
DEL "rack::attack::fail2ban:counter:login protection:1.2.3.4"

也可以在Rails的console里用一行代码解封：Rack::Attack::Fail2Ban.reset("1.2.3.4", "login protection")，效果相同。建议给团队内部的运维后台预留一个解封入口，避免每次都要登录服务器操作Redis。

还有几个实践中的注意点值得留意。第一，如果应用部署在负载均衡或反向代理后面，务必正确配置ActionDispatch::RemoteIp相关的受信代理设置，否则所有请求的IP都会是代理IP，一旦触发封禁就是把全部用户一起封掉，这是非常严重的事故。第二，bantime不宜设置得过长，对于登录场景，1小时到24小时通常足够；可以采用递增策略，第一次封1小时，惯犯封24小时，通过多层fail2ban配置叠加实现。第三，safelist要谨慎使用，只放行确定安全的来源，不要图省事把整个内网段都加进去，因为攻击者可能伪造内网请求头。

最后要明确Fail2Ban的定位：它是应用层的第一道防护墙，配置简单、无需额外组件，对付低强度的暴力破解和恶意扫描绰绰有余。但如果面对的是大规模分布式攻击，还是需要结合CDN的WAF规则、云厂商的高防IP等基础设施层面的手段，多层防御才能保证服务的稳定可用。

Rack::AttackFail2BanIP封禁修改时间：2026-09-08 23:59:02