Fiber 官方 IPFilter 中间件基于 CIDR 解析实现路由层 IP 白/黑名单控制,需通过 app.Use() 或路由组 .Use() 注册,配置 ProxyHeader 与 TrustedProxies 才能正确解析真实客户端 IP,设 AllowList: false 可切换为黑名单模式。

用 fiber.IPFilter 中间件最直接
这是 Fiber 官方提供的 IP 白名单/黑名单中间件,底层基于 CIDR 解析和匹配,不需要自己手写正则或字符串判断。它在路由匹配前就生效,属于「路由层限制」的典型做法。
常见错误是把它放在 handler 里调用(比如在 c.Next() 后),那样已经进入业务逻辑了,起不到前置拦截作用。必须作为中间件传入 app.Use() 或路由组的 .Use()。
- 支持单个 IP(
"192.168.1.100")、IP 段("192.168.1.0/24")、多个 CIDR 列表([]string{"10.0.0.0/8", "172.16.0.0/12"}) - 默认行为是放行白名单,拒绝其余;设
AllowList: false可反转为黑名单模式 - 注意:如果前端有反向代理(如 Nginx),
c.IP()默认读的是X-Forwarded-For,但IPFilter不自动解析该头,需手动配置ProxyHeader和TrustedProxies
app := fiber.New()
// 只允许内网访问 /admin 路由
admin := app.Group("/admin")
admin.Use(fiber.IPFilter{
IPs: []string{"192.168.0.0/16", "10.0.0.0/8"},
ProxyHeader: "X-Forwarded-For",
TrustedProxies: []string{"127.0.0.1", "172.18.0.1"},
})
admin.Get("/dashboard", func(c fiber.Ctx) error {
return c.SendString("OK")
})
c.IP() + 手动判断适合细粒度控制场景
当需要结合其他条件(比如请求头、User-Agent、登录态)做复合判断,或者想返回自定义错误响应(如 403 带 JSON 提示),就不该依赖 IPFilter 的默认行为,而应手动取 IP 并判断。
关键点是:c.IP() 返回的是客户端真实 IP,但它的行为受 Fiber 的 ProxyHeader 和 TrustedProxies 配置影响。没配对的话,Nginx 后面的服务永远拿到的是 127.0.0.1 或容器 IP。
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景,三层路由架构(触发词→SAD反馈→DAG编排),recall@10=96.97%。配置驱动(chains.yaml),零代码扩展。pip install skill-weave-chains 一键安装。
- 务必在
fiber.Config中设置ProxyHeader: "X-Forwarded-For"和可信代理列表 - 用
net.ParseIP()和net.IPNet.Contains()判断是否在网段内,比字符串前缀匹配更可靠(避免"192.168.1"匹配到"192.168.100") - 别用
c.Request().RemoteAddr(),它拿的是 TCP 连接来源,不是 HTTP 层的客户端 IP
func ipInAllowedRange(ipStr string) bool {
ip := net.ParseIP(ipStr)
if ip == nil {
return false
}
_, net1, _ := net.ParseCIDR("192.168.5.0/24")
_, net2, _ := net.ParseCIDR("10.10.0.0/16")
return net1.Contains(ip) || net2.Contains(ip)
}
app.Get("/api/data", func(c fiber.Ctx) error {
if !ipInAllowedRange(c.IP()) {
return c.Status(fiber.StatusForbidden).JSON(fiber.Map{
"error": "IP not allowed",
})
}
return c.JSON(fiber.Map{"data": "sensitive"})
})
为什么 ctx.Locals 不能替代 IP 限制
有人试图把 IP 校验结果存在 c.Locals("allowed") 里,然后在后续 handler 里检查——这看似省事,但完全绕过了路由层的意义。一旦路由已匹配、handler 已执行,资源(DB 查询、鉴权、日志)可能已被消耗,攻击者仍可触发逻辑或探测接口结构。
Locals 是上下文级变量,只用于跨中间件传递数据,不是访问控制机制。真正的路由层限制必须发生在 Next() 之前,且中断后续流程(即不调用 c.Next())。
- 正确姿势:中间件里直接
return c.Status(...).Send(...)或return c.Redirect(...) - 错误姿势:存
Locals后继续c.Next(),再在 handler 里if !c.Locals("allowed") { ... } - 额外风险:如果 handler 忘记检查
Locals,限制就彻底失效
部署时容易忽略的代理链问题
本地开发时 c.IP() 可能表现正常,一上生产就失效,大概率是代理层级没对齐。比如:用户 → Cloudflare → Nginx → OpenWrt → Fiber 应用,每层都可能改写或追加 X-Forwarded-For,而 TrustedProxies 只信任最后一跳(OpenWrt),前面的 Cloudflare 和 Nginx 就成了“不可信代理”,导致 IP 解析退化为 RemoteAddr。
解决方法不是盲目加长 TrustedProxies 列表,而是确认哪些节点真正做了 IP 转发(即是否设置了 proxy_set_header X-Forwarded-For),并确保这些节点的出口 IP 在 TrustedProxies 中显式列出。
- Cloudflare 的真实 IP 是通过
Cf-Connecting-Ip头传的,Fiber 默认不识别,需自定义中间件提取 - Nginx 配置里若用了
real_ip_header X-Real-IP,Fiber 就得对应设ProxyHeader: "X-Real-IP" - OpenWrt 上若启用了 SNAT,
RemoteAddr就是 OpenWrt 自己的 LAN IP,此时必须靠X-Forwarded-For且确保 OpenWrt 信任上游
TrustedProxies 和 ProxyHeader,所有 CIDR 判断都是空中楼阁。


















