Skip to content

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 秒的超时就能拖垮体验。

对应的三条设计原则:

  1. 缓存前置:先查 ETS(read_concurrency: true,并发读不锁),命中就直接返回,不进 GenServer。
  2. 只在 miss 时进 GenServer:由它串行化 + 节流,天然满足频率限制。
  3. 失败不缓存:网络错误下次重试;只有确定结果(含确认的非法 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
end

conn.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。