Appearance
Elixir 怎么查询 IP 归属地?GenServer + ETS 写一个能进生产的查询模块(含限流与缓存)
用 Phoenix 做一个面向国内用户的 SaaS,迟早会遇到两类需求:审计日志里要记「这次操作来自哪个城市」,或者内容要按访客属地做分流。搜 Elixir 的中文资料,出来的几乎全是 MaxMind 离线库(locus、geolix)和国外 API(ipinfo.io 那一类)——离线库要自己维护几个月一次的数据文件,国外 API 在国内的解析质量一般,中文省份名还得自己映射。
直接调国内的在线接口最省事,但 Elixir 生态里没有现成的封装,得自己写。写这个模块有三件事绕不开:接口每分钟限 60 次、同一个 IP 会反复出现、不能在请求进程里干等。
这篇给出一份能在生产里跑的完整实现:GenServer 负责串行化和节流,ETS 负责缓存,:httpc 负责发请求(不引入 HTTP 客户端依赖),JSON 用 Jason。代码在 Elixir 1.14 / OTP 25 上实测通过。
一、先明确约束,再决定架构
免费接口的规则很朴素:GET https://ip9.com.cn/get?ip=<IP>,不用注册,60 次/分钟/IP,不传 ip 参数就查当前请求方 IP。返回字段有国家、省、市、区号、邮编、运营商、经纬度(城市中心点)、大区等。
约束翻译成设计:
- 60 次/分钟 ≈ 1.05 秒一次。意味着查询必须串行排队,不能让它随机爆发;并发调用会自己把自己限流死。
- IP 重复率高。同一栋写字楼、同一个运营商出口段会反复出现在日志里,缓存能省掉大部分调用。
- 不能阻塞业务进程。在
Plug或 LiveView 里同步等着上网,一次 3 秒的超时就能拖垮体验。
对应的三条设计原则:
- 缓存前置:先查 ETS(
read_concurrency: true,并发读不锁),命中就直接返回,不进 GenServer。 - 只在 miss 时进 GenServer:由它串行化 + 节流,天然满足频率限制。
- 失败不缓存:网络错误下次重试;只有确定结果(含确认的非法 IP)才写缓存。
二、依赖与目录
只要一个依赖:
elixir
# mix.exs
defp deps do
[
{:jason, "~> 1.4"}
]
end:inets、:ssl、:public_key 都是 OTP 自带的,记得在 application 里启用(:public_key.cacerts_get/0 需要 OTP 25+):
elixir
def application do
[
extra_applications: [:logger, :inets, :ssl]
]
end模块放在 lib/ip_geo.ex:mix deps.get 之后直接 mix run 就能验证。
三、完整实现
elixir
defmodule IPGeo do
@moduledoc """
基于 ip9.com.cn 免费接口的 IP 归属地查询客户端。
设计要点:
* ETS 缓存(24 小时 TTL):命中时直接返回,不进 GenServer,也不打接口
* GenServer 串行化 + 节流:天然满足免费版 60 次/分钟/IP 的频率限制
* 只有确定结果才缓存:网络错误下次重试,不会被"查不到"污染缓存
"""
use GenServer
@api "https://ip9.com.cn/get"
@table :ipgeo_cache
@ttl 24 * 60 * 60 * 1000
@pace 1_050
## 对外 API
def start_link(opts \\ []) do
GenServer.start_link(__MODULE__, opts, name: __MODULE__)
end
@doc "查询指定 IP;传 nil 查询当前请求方 IP"
def lookup(ip \\ nil) do
key = if ip in [nil, ""], do: :self, else: ip
now = System.system_time(:millisecond)
case cache_get(key, now) do
{:ok, result} -> result
:miss -> GenServer.call(__MODULE__, {:lookup, key}, 10_000)
end
end
@doc "把 Plug.Conn.remote_ip(:inet.ip_address 元组)或字符串统一成字符串"
def normalize(nil), do: nil
def normalize(ip) when is_tuple(ip) or is_list(ip), do: to_string(:inet.ntoa(ip))
def normalize(ip) when is_binary(ip), do: ip
## GenServer
@impl true
def init(_opts) do
if :ets.whereis(@table) == :undefined do
:ets.new(@table, [:named_table, :public, :set, read_concurrency: true])
end
{:ok, %{last_call: 0}}
end
@impl true
def handle_call({:lookup, key}, _from, state) do
now = System.system_time(:millisecond)
case cache_get(key, now) do
{:ok, result} ->
{:reply, result, state}
:miss ->
throttle(state.last_call)
ip = if key == :self, do: nil, else: key
result = http_get(ip)
if match?({:ok, _}, result), do: cache_put(key, result, now)
{:reply, result, %{state | last_call: System.system_time(:millisecond)}}
end
end
## 缓存
defp cache_get(key, now) do
case :ets.lookup(@table, key) do
[{^key, exp, result}] when exp > now -> {:ok, result}
[_expired] -> :ets.delete(@table, key); :miss
[] -> :miss
end
rescue
ArgumentError -> :miss
end
defp cache_put(key, result, now), do: :ets.insert(@table, {key, now + @ttl, result})
defp throttle(last_call) do
wait = @pace - (System.system_time(:millisecond) - last_call)
if wait > 0, do: Process.sleep(wait)
end
## HTTP + JSON
defp http_get(ip) do
url =
case ip do
nil -> @api
ip -> @api <> "?ip=" <> URI.encode_www_form(ip)
end
http_options = [
timeout: 5_000,
connect_timeout: 3_000,
ssl: [
verify: :verify_peer,
cacerts: :public_key.cacerts_get(),
depth: 3,
customize_hostname_check: [
match_fun: :public_key.pkix_verify_hostname_match_fun(:https)
]
]
]
case :httpc.request(:get, {String.to_charlist(url), []}, http_options, body_format: :binary) do
{:ok, {{_, status, _}, _headers, body}} -> decode(status, body)
{:error, reason} -> {:error, {:transport, reason}}
end
end
# 接口在非法 IP 时返回 HTTP 400,响应体是 {"ret":400,"data":[]};
# 所以这里按响应体的 ret 判定,不只看 HTTP 状态码。
defp decode(status, body) do
case Jason.decode(body) do
{:ok, %{"ret" => 200, "data" => data}} when is_map(data) ->
{:ok,
%{
ip: data["ip"],
country: data["country"],
prov: data["prov"],
city: data["city"],
isp: data["isp"],
big_area: data["big_area"],
lng: data["lng"],
lat: data["lat"]
}}
{:ok, %{"ret" => 400}} -> {:error, :invalid_ip}
{:ok, %{"ret" => 429}} -> {:error, :rate_limited}
{:ok, %{"ret" => other}} -> {:error, {:api_ret, other}}
{:ok, _} -> {:error, {:http_status, status}}
{:error, _} -> {:error, {:bad_json, status}}
end
end
end几处关键取舍值得说明:
为什么用 :httpc 而不是 Req/Finch? 只有这一个调用点、并发量被限速压到 1 次/秒的情况下,引入一个 HTTP 客户端换不来收益。:httpc 自带连接池,加上 ssl: [verify: :verify_peer, cacerts: :public_key.cacerts_get()] 就能满足校验需求——别图省事写 verify: :verify_none,那等于放弃中间人防护。
为什么把缓存读取放在 handle_call 之外? 如果 lookup/1 每次都 GenServer.call,那么命中率再高也要排队过一次单进程,吞吐被卡在 GenServer 消息队列上。现在的写法让命中路径完全不进 GenServer,只有 miss 才排队——代价是 handle_call 里要再查一次缓存(防止进入队列期间已被别的调用填上)。
节流为什么放在 GenServer 里? 因为 GenServer 是串行的,一个 Process.sleep 就能让整条查询队列的节奏稳定在 1.05 秒一次。这不会拖慢缓存命中,只会延后真正需要上网的调用——对「审计日志补属地」这类允许秒级延迟的场景完全够用。
四、跑起来看输出
elixir
# demo.exs
{:ok, _pid} = IPGeo.start_link()
IO.inspect(IPGeo.lookup("114.114.114.114"), label: "江苏南京的场景")
IO.inspect(IPGeo.lookup("100.64.1.5"), label: "CGNAT 保留段")
IO.inspect(IPGeo.lookup("300.1.1.1"), label: "非法 IP")
IO.inspect(IPGeo.lookup(), label: "当前出口 IP")
{us, _} = :timer.tc(fn -> IPGeo.lookup("114.114.114.114") end)
IO.puts("第二次查询耗时 #{div(us, 1000)} ms(走 ETS 缓存)")text
$ mix run demo.exs
江苏南京的场景: {:ok,
%{big_area: "华东", city: "南京", country: "中国", ip: "114.114.114.114",
isp: "114DNS", lat: "32.04", lng: "118.77", prov: "江苏"}}
CGNAT 保留段: {:ok,
%{big_area: "", city: "", country: "保留", ip: "100.64.1.5",
isp: "共享地址空间", lat: "", lng: "", prov: ""}}
非法 IP: {:error, :invalid_ip}
当前出口 IP: {:ok,
%{big_area: "", city: "曼谷", country: "泰国", ip: "43.133.110.148",
isp: "腾讯云", lat: "13.76", lng: "100.51", prov: "曼谷"}}
第二次查询耗时 0 ms(走 ETS 缓存)四行输出,把三个生产上最容易踩的坑都摊开了:
100.64.1.5是 CGNAT 地址(RFC 6598),接口能查,但返回的country是「保留」、isp是「共享地址空间」,省市字段是空的。这类结果不能参与地域判断,业务侧要当「未知」处理。300.1.1.1这种非法 IP 返回 HTTP 400,响应体ret也是 400、data是空数组。看清楚是 400 再判断,别把所有失败都归到限流上。- 第四行是在一台云主机上跑的:出口 IP 的归属地是「泰国 曼谷 腾讯云」。查出来的不是「我在哪」,而是「我的网络出口在哪」,机房、代理、VPN 全都算这一类。
最后一行是重点:第二次查询 0 毫秒,因为走的是 ETS 缓存。日志场景里 IP 的重复率通常在 70% 以上,缓存直接把接口调用量砍下去。
五、接到 Phoenix / Plug 上
放进监督树:
elixir
# lib/my_app/application.ex
children = [
IPGeo,
MyAppWeb.Endpoint
]取访客属地,套一层 Plug 就行:
elixir
defmodule MyAppWeb.Plug.GeoTag do
@behaviour Plug
def init(opts), do: opts
def call(conn, _opts) do
ip = IPGeo.normalize(conn.remote_ip)
Plug.Conn.assign(conn, :geo, IPGeo.lookup(ip))
end
endconn.remote_ip 是 :inet.ip_address 元组,IPGeo.normalize/1 把它转成字符串。注意真实 IP 的来源:如果前面挂了 Nginx 或 CDN,remote_ip 默认是连接方(代理)的地址,需要在 endpoint.ex 里配 plug Plug.RewriteOn, [:x_forwarded_for],并且只信任你自己那层代理写入的头——X-Forwarded-For 是客户端可以伪造的,业务侧最好在网关处覆写它,而不是追加。
写入库时建议只存需要的字段,而不是整份原始 IP:
elixir
def audit_log(conn, action) do
geo = conn.assigns[:geo] || {:error, :unavailable}
Repo.insert(%AuditLog{
action: action,
ip_prov: geo_prov(geo),
ip_city: geo_city(geo),
ip_isp: geo_isp(geo)
})
end
defp geo_prov({:ok, %{prov: prov}}), do: prov
defp geo_prov(_), do: nil
defp geo_city({:ok, %{city: city}}), do: city
defp geo_city(_), do: nil
defp geo_isp({:ok, %{isp: isp}}), do: isp
defp geo_isp(_), do: nil需要提醒一句合规:IP 地址属于个人信息,存原始 IP 要能说清用途和留存期限。只留省市和运营商、不留完整 IP,在很多场景下既不损失统计能力,也把风险降下来。
六、上生产前再确认几件事
限速层要单一。 如果集群里有 5 个节点各跑一个 GenServer,等于 5 倍并发打接口——免费版的 60 次/分钟是按 IP 算的,多节点共享同一个出口 IP 的话,配额也是共享的。要么把查询集中到一个节点(或用一个外部限流器),要么把 @pace 按节点数放大。
TTL 按业务选。 24 小时适合「同一批 IP 反复出现」的日志场景;如果业务对归属地变动敏感(比如风控要感知今天的出口变化),可以压到 1 小时。TTL 调短会线性增加接口调用量,接到 VIP 版(18 万次/分钟)之后这个顾虑基本消失。
别在请求路径上同步查。 Plug 里的 IPGeo.lookup/1 在缓存未命中时会等待最多一次节流加一次网络往返(约 1.1 秒 + 200 毫秒)。对登录、下单这类接口,建议改成把 IP 丢进队列异步补属地,页面首屏不依赖它。
用 with 串结果,别嵌套 case。 返回值的形状统一成 {:ok, map} / {:error, reason},模式匹配写起来很干净:
elixir
with {:ok, geo} <- IPGeo.lookup(ip),
prov when prov != "" <- geo.prov do
{:ok, prov}
else
"" -> {:error, :unknown_region}
{:error, :invalid_ip} -> {:error, :bad_request}
{:error, :rate_limited} -> {:error, :try_later}
{:error, reason} -> {:error, reason}
end需要更细的字段时换 VIP 版。 免费版给到省市、运营商、经纬度(城市中心点)、大区;要判断出口是家宽还是 IDC 机房(ip_type:ISP / BUS / IDC)、要做区县级定位(area)、要 AS 号(ip_asn)时,这些属于 VIP 版能力,配额与 SLA 以官网为准。
总结
Elixir 里做 IP 归属地查询,代码量并不大,难的是把「限速」和「缓存」两件事摆对位置:缓存放 ETS 且读路径不进 GenServer,限速放 GenServer 里串行节流,失败不缓存。
上面那份 IPGeo 可以直接贴进项目里,mix run demo.exs 验证一遍再上线。查询就是一次 GET:https://ip9.com.cn/get?ip=<IP>,免费版无需注册、60 次/分钟/IP,支持 IPv4 与 IPv6,字段口径见 https://www.ip9.com.cn。