echo 框架原生不提供 ip 白名单/黑名单中间件，需手写 echo.middlewarefunc 结合 c.realip() 实现；echo.ipwhitelist() 不存在，属误传。
直接说结论：Echo 的 MiddlewareFunc 可以轻松实现 IP 限流，但原生不带 IP 白名单/黑名单中间件，得自己写或组合 echo.MiddlewareFunc + c.RealIP() + 简单逻辑判断。
为什么不能直接用 echo.IPWhitelist()？
Echo v4.x 和 v5.x 都没有内置的 IP 白名单/黑名单中间件。官方只提供了 echo.Logger()、echo.Recover() 这类通用中间件，IP 控制必须手写——这不是缺陷，而是框架保持轻量的设计取舍。
常见错误是搜到过时博客里写的 echo.IPWhitelist，那属于早期第三方扩展或旧版 Echo 的误传，实际运行会报 undefined: echo.IPWhitelist。
- 真正可用的是
c.RealIP()，它会按X-Forwarded-For、X-Real-IP等头自动解析客户端真实 IP（需确保反向代理如 Nginx 正确设置了这些 header） - 如果服务直连公网（无 Nginx），
c.Request().RemoteAddr也能用，但要注意带端口（如192.168.1.100:54321），需用strings.Split()截取 - 别依赖
c.Request().Header.Get("X-Forwarded-For")手动取值——绕过RealIP()会导致 IPv6 或多级代理解析出错
怎么写一个带白名单的中间件？
核心就是判断 c.RealIP() 是否在允许列表中，不是就调用 c.NoContent(403) 并 return。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
func IPWhitelist(ips ...string) echo.MiddlewareFunc {
allowed := make(map[string]bool)
for _, ip := range ips {
allowed[ip] = true
}
return func(next echo.Handler) echo.Handler {
return echo.HandlerFunc(func(c echo.Context) error {
ip := c.RealIP()
if !allowed[ip] {
return c.NoContent(http.StatusForbidden)
}
return next.ServeHTTP(c.Response(), c.Request())
})
}
}
使用时：e.Use(IPWhitelist("127.0.0.1", "2001:db8::1"))。注意：IPv6 地址必须用标准格式（如双冒号缩写），且 RealIP() 返回的就是已标准化的字符串，无需再做转换。
- 白名单建议存配置文件或环境变量，避免硬编码；若需动态更新，可把
allowed map改成*sync.Map并加锁 - 该中间件放在
e.Use()链最前面，否则后续中间件（如 JWT 验证）可能先报错，导致 IP 检查被跳过 - 测试时用
curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:1323/api，确保 Nginx 或测试工具确实透传了头
黑名单和请求频率限制怎么叠加？
黑名单逻辑和白名单对称，只是判断条件取反；但真要控频（比如每分钟最多 10 次），就不能只靠内存 map，得引入计数器存储，例如用 golang.org/x/time/rate（适合单机）或 Redis（分布式场景）。
简单黑名单示例：
func IPBlacklist(ips ...string) echo.MiddlewareFunc {
denied := make(map[string]bool)
for _, ip := range ips {
denied[ip] = true
}
return func(next echo.Handler) echo.Handler {
return echo.HandlerFunc(func(c echo.Context) error {
ip := c.RealIP()
if denied[ip] {
return c.String(http.StatusForbidden, "IP blocked")
}
return next.ServeHTTP(c.Response(), c.Request())
})
}
}
- 黑白名单可以同时用：
e.Use(IPWhitelist(...))和e.Use(IPBlacklist(...))，但顺序很重要——白名单应放在黑名单之前，优先放行可信 IP - 高频访问检测别用
time.Now()做时间窗口切分，容易因并发导致计数偏差；rate.Limiter的AllowN()更可靠 - 注意 Cloudflare、AWS ALB 等 CDN 会覆盖原始
X-Forwarded-For，需在它们后台开启「真实 IP 透传」并配置 Echo 的echo.HTTPErrorHandler日志打印c.RealIP()做验证
IP 限制看着简单，实际最常翻车的是代理链路没对齐（Nginx 没设 set_real_ip_from）、IPv6 格式处理遗漏、以及中间件注册顺序错乱。跑通前务必用 fmt.Println(c.RealIP()) 打一行日志看真实值长什么样。
