network-infra-utility 0.5.0 → 0.8.3

data/bin/geo-update

@@ -0,0 +1,429 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# geo-update — network-infra-utility 的 GeoLite2 地址库下载更新工具
+#
+# 从 MaxMind 官方下载 GeoLite2 CSV 数据库（ASN / City / Country），解压到本地。
+# 可选链路: 下载 → 解压 → geo-load 转换 JSON → 重启 geo-api 服务。
+#
+# 默认行为:
+#   - 在命令行当前目录 (CWD) 寻找 GeoIP.conf 配置文件读取 LicenseKey
+#   - 下载的 zip 压缩包和解压后的 CSV 放置在当前目录
+#   - 仅下载+解压, 不转换不重启 (除非指定 --convert / --restart)
+#
+# 用法:
+#   geo-update -T                             # 生成 GeoIP.conf 模板到当前目录
+#   geo-update                                # 下载+解压 (读当前目录 GeoIP.conf)
+#   geo-update --convert                      # 下载+解压+转换 JSON
+#   geo-update --convert --restart            # 下载+解压+转换+重启 geo-api
+#   geo-update --asn-only                     # 仅下载 ASN
+#   geo-update --output-dir=D:\geodata        # 下载到指定目录
+#   geo-update --dry-run                      # 演练, 只打印动作
+#
+# 参数规则:
+#   geo-update [options]
+#
+# 选项:
+#   -T, --template                 在当前目录生成 GeoIP.conf 模板
+#   --config=FILE                  指定配置文件路径 (默认: ./GeoIP.conf)
+#   --license-key=KEY              指定 MaxMind 许可证密钥 (覆盖配置文件)
+#   --output-dir=DIR               下载/解压目录 (默认: 当前目录)
+#   --convert                      下载后调用 geo-load 转换 CSV → JSON
+#   --restart                      转换后重启 geo-api 服务 (隐含 --convert)
+#   --local-dir=DIR                使用本地已有 CSV 目录, 跳过下载
+#   --asn-only                     仅处理 ASN
+#   --city-only                    仅处理 City
+#   --country-only                 仅处理 Country
+#   --dry-run                      演练: 只打印将执行的动作
+#   -h, --help                     显示帮助
+#   -v, --version                  显示版本
+
+require "net/http"
+require "uri"
+require "fileutils"
+require "optparse"
+require "time"
+
+require_relative "../version"
+
+# ============================================================
+# 静态设定数据
+# ============================================================
+
+# GeoIP.conf 模板 (内容脱敏, 供用户填写真实信息)
+GEOIP_CONF_TEMPLATE = <<~CONF
+  # GeoIP.conf file for `geoipupdate` program, for versions >= 3.1.1.
+  # Used to update GeoIP databases from https://www.maxmind.com.
+  # For more information about this config file, visit the docs at
+  # https://dev.maxmind.com/geoip/updating-databases.
+
+  # `AccountID` is from your MaxMind account.
+  # 注册地址: https://www.maxmind.com/en/geolite2/signup
+  AccountID YOUR_ACCOUNT_ID
+
+  # `LicenseKey` is from your MaxMind account.
+  # 登录后在 Account → GeoIP2 / GeoLite2 → Manage License Keys 生成
+  LicenseKey YOUR_LICENSE_KEY
+
+  # `EditionIDs` is from your MaxMind account.
+  EditionIDs GeoLite2-ASN GeoLite2-City GeoLite2-Country
+CONF
+
+# 三类数据与官方 edition_id 的对应关系
+EDITIONS = {
+  "city"    => "GeoLite2-City-CSV",
+  "country" => "GeoLite2-Country-CSV",
+  "asn"     => "GeoLite2-ASN-CSV",
+}.freeze
+
+BASE_URL = "https://download.maxmind.com/app/geoip_download"
+
+# ============================================================
+# 处理方法
+# ============================================================
+
+def setup_console_encoding
+  return unless RUBY_PLATFORM =~ /mswin|mingw|cyg/
+  begin
+    system("chcp 65001 > NUL 2>&1")
+    $stdout.set_encoding(Encoding::UTF_8)
+    $stderr.set_encoding(Encoding::UTF_8)
+  rescue StandardError
+    # 忽略编码设置失败
+  end
+end
+
+def log(msg)
+  puts msg
+end
+
+# 从 GeoIP.conf (geoipupdate 格式) 解析 LicenseKey / AccountID / EditionIDs
+def parse_geoip_config(path)
+  return nil unless File.exist?(path)
+  conf = { license_key: nil, account_id: nil, editions: [] }
+  File.foreach(path, encoding: "UTF-8") do |line|
+    line = line.strip
+    next if line.empty? || line.start_with?("#")
+    case line
+    when /^AccountID\s+(.+)$/i  then conf[:account_id] = $1.strip
+    when /^LicenseKey\s+(.+)$/i then conf[:license_key] = $1.strip
+    when /^EditionIDs\s+(.+)$/i then conf[:editions] = $1.strip.split(/\s+/)
+    end
+  end
+  conf
+end
+
+# 生成 GeoIP.conf 模板文件
+def generate_template(dest_path)
+  if File.exist?(dest_path)
+    abort "✗ 文件已存在: #{dest_path}\n  请先删除或重命名现有文件再生成模板。"
+  end
+  File.write(dest_path, GEOIP_CONF_TEMPLATE, encoding: "UTF-8")
+  log("已生成 GeoIP.conf 模板: #{dest_path}")
+  log("请编辑此文件, 填入真实的 AccountID 和 LicenseKey 后再执行下载。")
+  log("注册 MaxMind 账号: https://www.maxmind.com/en/geolite2/signup")
+end
+
+# 带进度显示的 HTTP 下载 (直连优先, 代理兜底, 自动跟随重定向)
+def download_file(url, dest, redirect_count = 0)
+  if redirect_count > 5
+    abort "✗ 重定向次数过多 (>5), 可能存在循环重定向"
+  end
+
+  uri = URI(url)
+  log("  下载: #{url.sub(/license_key=[^&]+/, 'license_key=***')}")
+
+  # 构建下载方式列表: 直连优先, 环境变量代理兜底
+  proxy   = ENV["HTTP_PROXY"] || ENV["HTTPS_PROXY"] || ENV["http_proxy"] || ENV["https_proxy"]
+  methods = [{ proxy: nil, label: "直连" }]
+  if proxy && !proxy.empty?
+    puri = URI(proxy)
+    methods << { proxy: { addr: puri.host, port: puri.port }, label: "代理 #{puri.host}:#{puri.port}" }
+  end
+
+  last_err = nil
+  methods.each do |m|
+    begin
+      opts = { use_ssl: uri.scheme == "https", open_timeout: 30, read_timeout: 300 }
+      if m[:proxy]
+        opts[:proxy_addr] = m[:proxy][:addr]
+        opts[:proxy_port] = m[:proxy][:port]
+      end
+      log("  [#{m[:label]}] 连接中 ...")
+      Net::HTTP.start(uri.host, uri.port, **opts) do |http|
+        req = Net::HTTP::Get.new(uri)
+        http.request(req) do |res|
+          case res
+          when Net::HTTPSuccess
+            total = res["content-length"]&.to_i
+            done = 0
+            File.open(dest, "wb") do |f|
+              res.read_body do |chunk|
+                f.write(chunk)
+                done += chunk.bytesize
+                if total && total > 0
+                  pct = (done.to_f / total * 100).round
+                  print "\r  进度: %3d%% (%s / %s 字节)  " % [pct, done, total]
+                end
+              end
+            end
+            puts
+            return File.size(dest)
+          when Net::HTTPRedirection
+            new_url = res["location"]
+            if new_url && !new_url.empty?
+              new_url = URI.join(url, new_url).to_s if new_url.start_with?("/")
+              log("  重定向 → #{new_url.sub(/license_key=[^&]+/, 'license_key=***')}")
+              return download_file(new_url, dest, redirect_count + 1)
+            end
+            abort "✗ 重定向但无 Location 头"
+          when Net::HTTPUnauthorized, Net::HTTPForbidden
+            abort "✗ 下载被拒绝 (#{res.code}): #{res.body[0, 200]}\n  请检查 license key 是否正确, 或 MaxMind 账号是否已激活 GeoLite2 下载。"
+          else
+            abort "✗ 下载失败 (HTTP #{res.code}): #{res.body[0, 200]}"
+          end
+        end
+      end
+    rescue OpenSSL::SSL::SSLError, Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
+      last_err = e
+      log("  ! [#{m[:label]}] 失败 (#{e.class}): #{e.message[0, 100]}")
+      next
+    end
+  end
+  abort "✗ 所有下载方式均失败, 最后错误: #{last_err&.class}: #{last_err&.message}"
+end
+
+# 解压 zip (用系统 tar)
+def extract_file(zip_path, dest_dir)
+  FileUtils.mkdir_p(dest_dir)
+  if zip_path.end_with?(".tar.gz", ".tgz")
+    system("tar", "-xzf", zip_path, "-C", dest_dir)
+  else
+    system("tar", "-xf", zip_path, "-C", dest_dir)
+  end
+  $?.success? || abort("✗ 解压失败: #{zip_path}")
+end
+
+# 下载三类官方 zip (同一天已存在则跳过)
+def download_editions(output_dir, license_key, editions)
+  today = Time.now.strftime("%Y%m%d")
+  editions.each do |name, edition_id|
+    zip_name = "#{edition_id}_#{today}.zip"
+    zip_path = File.join(output_dir, zip_name)
+    if File.exist?(zip_path) && File.size(zip_path) > 1000
+      log("  跳过 (已存在): #{zip_name}")
+      next
+    end
+
+    url = "#{BASE_URL}?edition_id=#{edition_id}&license_key=#{license_key}&suffix=zip"
+    download_file(url, zip_path)
+    log("  完成: #{zip_name} (#{format('%.2f', File.size(zip_path).to_f / 1_048_576)} MB)")
+  end
+end
+
+# 解压 output_dir 下所有 zip
+def extract_all(output_dir)
+  Dir.glob(File.join(output_dir, "*.zip")).each do |zip_path|
+    next if File.size(zip_path) <= 1000
+    dest = File.join(output_dir, File.basename(zip_path, ".zip"))
+    extract_file(zip_path, dest)
+  end
+end
+
+# 调用 geo-load 转换 CSV → JSON
+def run_geo_load(raw_dir, doc_dir, only = nil)
+  geo_load_script = File.expand_path("geo-load", __dir__)
+  unless File.exist?(geo_load_script)
+    abort "✗ 找不到 geo-load 脚本: #{geo_load_script}"
+  end
+  cmd = ["ruby", geo_load_script, raw_dir, doc_dir]
+  cmd << "--#{only}-only" if only
+  log("  执行: #{cmd.join(' ')}")
+  system(*cmd)
+end
+
+# Windows: 用 PowerShell 查找并停止旧 geo-api 进程, 再启动新服务
+def restart_geo_api(data_dir)
+  if RUBY_PLATFORM =~ /mswin|mingw|cyg/
+    ps_cmd = 'powershell -NoProfile -Command "Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match ''geo-api'' } | ForEach-Object { $_.ProcessId }"'
+    pids = `#{ps_cmd}`.lines.map(&:strip).reject(&:empty?)
+    unless pids.empty?
+      log("  停止旧服务 (PID: #{pids.join(', ')})")
+      pids.each { |pid| system("taskkill", "/PID", pid, "/F") }
+      sleep 2
+    end
+    geo_api_script = File.expand_path("geo-api", __dir__)
+    log("  启动服务: geo-api -d #{data_dir}")
+    system("powershell", "-NoProfile", "-Command",
+           "Start-Process ruby -ArgumentList '#{geo_api_script}','-d','#{data_dir}' -WindowStyle Hidden")
+  else
+    system("pkill", "-f", "geo-api") rescue nil
+    log("  请手动启动: geo-api -d #{data_dir}")
+  end
+end
+
+# ============================================================
+# 业务流程实例
+# ============================================================
+
+setup_console_encoding
+
+options = {
+  template: false,
+  config_file: nil,
+  license_key: nil,
+  output_dir: nil,
+  convert: false,
+  restart: false,
+  local_dir: nil,
+  only: nil,
+  dry_run: false
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BAN
+    geo-update — GeoLite2 地址库下载更新工具 (network-infra-utility)
+
+    用法:
+      geo-update -T                             # 生成 GeoIP.conf 模板
+      geo-update                                # 下载+解压 (读当前目录 GeoIP.conf)
+      geo-update --convert                      # 下载+解压+转换 JSON
+      geo-update --convert --restart            # 下载+解压+转换+重启 geo-api
+      geo-update --asn-only                     # 仅下载 ASN
+      geo-update --output-dir=D:\geodata        # 下载到指定目录
+
+    选项:
+  BAN
+  opts.on("-T", "--template", "在当前目录生成 GeoIP.conf 模板") { options[:template] = true }
+  opts.on("--config=FILE", "指定配置文件路径 (默认: 当前目录/GeoIP.conf)") { |v| options[:config_file] = v }
+  opts.on("--license-key=KEY", "指定 MaxMind 许可证密钥 (覆盖配置文件)") { |v| options[:license_key] = v }
+  opts.on("--output-dir=DIR", "下载/解压目录 (默认: 当前目录)") { |v| options[:output_dir] = v }
+  opts.on("--convert", "下载后调用 geo-load 转换 CSV → JSON") { options[:convert] = true }
+  opts.on("--restart", "转换后重启 geo-api 服务 (隐含 --convert)") { options[:restart] = true; options[:convert] = true }
+  opts.on("--local-dir=DIR", "使用本地已有 CSV 目录, 跳过下载") { |v| options[:local_dir] = v }
+  opts.on("--asn-only", "仅处理 ASN") { options[:only] = "asn" }
+  opts.on("--city-only", "仅处理 City") { options[:only] = "city" }
+  opts.on("--country-only", "仅处理 Country") { options[:only] = "country" }
+  opts.on("--dry-run", "演练: 只打印将执行的动作") { options[:dry_run] = true }
+  opts.on("-v", "--version", "显示版本") do
+    puts "geo-update #{NetworkInfraUtility::VERSION}"
+    exit 0
+  end
+  opts.on("-h", "--help", "显示帮助") do
+    puts opts
+    exit 0
+  end
+end
+parser.parse!
+
+# ---- --template: 生成 GeoIP.conf 模板然后退出 ----
+if options[:template]
+  template_path = File.expand_path("GeoIP.conf", Dir.pwd)
+  generate_template(template_path)
+  exit 0
+end
+
+# ---- 确定输出目录 (默认: 当前目录) ----
+output_dir = options[:output_dir] ? File.expand_path(options[:output_dir]) : Dir.pwd
+unless File.directory?(output_dir)
+  begin
+    FileUtils.mkdir_p(output_dir)
+  rescue SystemCallError => e
+    abort "✗ 无法创建输出目录 #{output_dir}: #{e.message}"
+  end
+end
+
+# ---- 确定 JSON 输出目录 (convert 时使用) ----
+doc_dir = File.expand_path("geodb", output_dir)
+
+# ---- 确定数据源目录 ----
+if options[:local_dir]
+  raw_dir = File.expand_path(options[:local_dir])
+  abort "✗ 本地目录不存在: #{raw_dir}" unless File.directory?(raw_dir)
+  log("数据源: 本地目录 #{raw_dir} (跳过下载)")
+else
+  # ---- 获取 license key: --license-key > --config > 当前目录 GeoIP.conf ----
+  license = options[:license_key]
+  if license.to_s.empty?
+    conf_path = options[:config_file] || File.expand_path("GeoIP.conf", Dir.pwd)
+    conf = parse_geoip_config(conf_path)
+    if conf && !conf[:license_key].to_s.empty? && conf[:license_key] != "YOUR_LICENSE_KEY"
+      license = conf[:license_key]
+      log("从 #{conf_path} 读取 LicenseKey (AccountID: #{conf[:account_id]})")
+    else
+      abort <<~MSG
+        ✗ 缺少 MaxMind license key
+          未在当前目录找到有效的 GeoIP.conf, 或文件中 LicenseKey 未填写。
+          配置文件查找位置: #{conf_path}
+
+          解决方法:
+            1. 生成模板:  geo-update -T
+            2. 编辑文件:  填入真实的 AccountID 和 LicenseKey
+            3. 重新运行:  geo-update
+
+          或直接指定:
+            geo-update --license-key=YOUR_KEY
+            geo-update --config=/path/to/GeoIP.conf
+
+          注册 MaxMind 账号: https://www.maxmind.com/en/geolite2/signup
+      MSG
+    end
+  end
+  options[:license_key] = license
+  raw_dir = output_dir
+end
+
+editions = options[:only] ? { options[:only] => EDITIONS[options[:only]] } : EDITIONS
+if options[:only] && !EDITIONS[options[:only]]
+  abort "✗ 未知类型: #{options[:only]} (可用: city/country/asn)"
+end
+
+# ---- 打印执行计划 ----
+log("╭─ geo-update #{NetworkInfraUtility::VERSION} ───────────────────────────────")
+log("│ 类型:     #{editions.keys.join(' / ')}")
+log("│ 输出目录: #{output_dir}")
+log("│ 数据源:   #{options[:local_dir] ? raw_dir : 'MaxMind 官方下载'}")
+log("│ 动作:     #{options[:dry_run] ? '(演练, 不执行)' : '执行'}")
+if options[:convert]
+  log("│ 转换:     是 (geo-load → #{doc_dir})")
+  log("│ 重启:     #{options[:restart] ? '是' : '否'}")
+end
+log("╰──────────────────────────────────────────────────")
+
+exit 0 if options[:dry_run]
+
+# ---- 1. 下载 + 解压 ----
+unless options[:local_dir]
+  log("[1/3] 下载 GeoLite2 CSV ...")
+  download_editions(output_dir, options[:license_key], editions)
+  log("")
+  log("[2/3] 解压 ...")
+  extract_all(output_dir)
+end
+
+# ---- 2. geo-load 转换 ----
+if options[:convert]
+  step = options[:local_dir] ? "[1/2]" : "[3/3]"
+  log("#{step} 转换 CSV → JSON (可能需要几十分钟~数小时) ...")
+  ok = run_geo_load(raw_dir, doc_dir, options[:only])
+  unless ok
+    log("✗ geo-load 转换失败 (exit #{$?.exitstatus})")
+    exit 1
+  end
+end
+
+# ---- 3. 重启 geo-api ----
+if options[:restart]
+  log("重启 geo-api ...")
+  restart_geo_api(doc_dir)
+end
+
+log("完成。")
+if options[:convert]
+  log("  JSON 数据: #{doc_dir}")
+  log("  验证:      geo-get 8.8.8.8 -j")
+else
+  log("  压缩包和解压目录: #{output_dir}")
+  log("  转换为 JSON:       geo-update --convert  (或 geo-load #{output_dir})")
+end

data/bin/ngeo-get

@@ -0,0 +1,253 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# ngeo-get — network-infra-utility 的 IP 归属综合查询工具 (geo 系列)
+#
+# 按 -p 顺位编排三个数据源, 满意即停, 字段叠加:
+#   cache    GEO_CACHE 外带缓存目录 (geocacheYYYYMMDD.json, -a 指定)
+#   local    本地 geo-api 服务 (GeoLite2)
+#   internet 互联网 ip-api.com (限速 + 熔断保护)
+#
+# 结果状态可信度: unreachable < local-partial < cache-partial < empty
+#                < cache < local < online < merged
+#   unreachable   各源均无结果且有不联通 (空结果状态)
+#   local-partial 本地部分结果, 无更多补充
+#   cache-partial 缓存部分结果, 无更多补充
+#   empty         各源均确认无归属 (如私有地址)
+#   cache         缓存命中且满意
+#   local         本地结果满意 (省/市/ASN 齐全)
+#   online        纯互联网结果
+#   merged        多源叠加综合
+#
+# 用法:
+#   ngeo-get 111.8.44.6                     # 默认顺位 cache,local,internet
+#   ngeo-get 111.8.44.6 -a ./GEO_CACHE      # 指定外带缓存目录
+#   ngeo-get 111.8.44.6 -p local,internet,cache   # 本地优先, 缓存兜底
+#   ngeo-get 111.8.44.6 -nc                 # 查询但不产出缓存文件
+#   ngeo-get 1.1.1.1 8.8.8.8 -j             # 多 IP (在线部分自动限速)
+#   cat ips.txt | ngeo-get -j                # 从 stdin 逐行读 IP
+#   ngeo-get -m ./GEO_CACHE                 # 合并缓存目录全部 geocache*.json
+#   ngeo-get --cache-stats                   # 查看会话缓存统计
+#
+# 选项:
+#   -t, --text          文字格式输出 (默认)
+#   -j, --json          JSON 格式输出 (多 IP 时输出数组)
+#   -a, --cache-dir DIR GEO_CACHE 外带缓存目录 (geocache*.json 文件集)
+#   -p, --priority O    查询顺位, cache/local/internet 的排列
+#                       (默认 cache,local,internet: 优先缓存, 再本地, 再互联网)
+#   -c, --cache-out     查询结果保存为 geocacheYYYYMMDD.json (默认开启)
+#   -nc, --no-cache-out 不保存查询产出
+#   -m, --merge DIR     合并 DIR 下全部 geocache*.json 为新文件后退出
+#   --refresh           忽略缓存强制重查 (会话缓存与 GEO_CACHE 均跳过)
+#   --no-local          跳过本地 geo-api
+#   --api URL           覆盖默认互联网接口 ({ip} 占位符)
+#   --geoapi URL        覆盖本地 geo-api 地址 (默认 http://127.0.0.1:9292)
+#   --timeout SEC       互联网 HTTP 超时秒数, 默认 10
+#   --cache-stats       查看缓存统计后退出
+#   -h, --help          显示帮助
+#   -v, --version       显示版本
+#
+# 产出说明:
+#   每次查询的结果 (默认) 保存到缓存目录 (未指定 -a 时为当前目录,
+#   可用环境变量 GEO_CACHE_DIR 覆盖), 命名为 geocacheYYYYMMDD.json,
+#   同一天多次查询自动归并到同一文件, 同 IP 以新结果覆盖。
+#   产出文件即后续 -a 查询 / -m 合并 / geo-api -a 服务端兜底的数据源。
+#
+# 退出码: 0 = 查询完成 (含 empty/local-partial/cache-partial);
+#         1 = IP 不合法或参数错误; 2 = 互联网不可达且其余源无结果
+
+require "optparse"
+require "json"
+require_relative "../service/geoquery/geoquery"
+
+options = { format: :text, refresh: false, no_local: false, timeout: 10,
+            api: nil, geoapi: nil, geo_cache_dir: nil, order: nil,
+            cache_out: true, merge_dir: nil }
+
+# "-nc" 为 "-c" 的反义短参组合, OptionParser 无法注册, 手动预提取
+if (idx = ARGV.index("-nc"))
+  ARGV.delete_at(idx)
+  options[:cache_out] = false
+end
+
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BAN
+    ngeo-get — IP 归属综合查询工具 (GEO_CACHE 缓存 + 本地 geo-get + 互联网 gen-get)
+
+    策略: 按顺位逐源查询 (-p, 默认 cache,local,internet), 满意即停, 字段叠加
+    用法:
+      ngeo-get <IP> [options]
+      ngeo-get 111.8.44.6 -a ./GEO_CACHE -j
+      ngeo-get -m ./GEO_CACHE
+      cat ips.txt | ngeo-get -j
+
+    选项:
+  BAN
+  opts.on("-t", "--text", "文字格式输出 (默认)")        { options[:format] = :text }
+  opts.on("-j", "--json", "JSON 格式输出")              { options[:format] = :json }
+  opts.on("-a", "--cache-dir DIR", "GEO_CACHE 外带缓存目录") { |v| options[:geo_cache_dir] = v }
+  opts.on("-p", "--priority ORDER", "查询顺位 cache/local/internet 排列 (默认 cache,local,internet)") { |v| options[:order] = v }
+  opts.on("-c", "--cache-out", "查询结果保存为 geocacheYYYYMMDD.json (默认开启)") { options[:cache_out] = true }
+  opts.on("--no-cache-out", "不保存查询产出 (同 -nc)")    { options[:cache_out] = false }
+  opts.on("-m", "--merge DIR", "合并 DIR 下全部 geocache*.json 为新文件后退出") { |v| options[:merge_dir] = v }
+  opts.on("--refresh", "忽略缓存强制重查")               { options[:refresh] = true }
+  opts.on("--no-local", "跳过本地 geo-api")              { options[:no_local] = true }
+  opts.on("--api URL", "覆盖默认互联网接口 ({ip} 占位符)") { |v| options[:api] = v }
+  opts.on("--geoapi URL", "覆盖本地 geo-api 地址")        { |v| options[:geoapi] = v }
+  opts.on("--timeout SEC", Integer, "互联网 HTTP 超时秒数 (默认 10)") { |v| options[:timeout] = v }
+  opts.on("--cache-stats", "查看缓存统计") do
+    cache = GeoQuery::Cache.new(File.join(GeoQuery::Cache.default_dir, "ngeo-cache.json"))
+    stats = cache.stats
+    puts "会话缓存: #{stats['file']}"
+    puts "缓存条目: #{stats['total']}    大小: #{stats['size_kb']} KB"
+    unless stats["states"].empty?
+      puts "状态分布: " + stats["states"].map { |k, v| "#{k}=#{v}" }.join("  ")
+    end
+    if options[:geo_cache_dir]
+      gstats = GeoQuery::GeoCache.new(options[:geo_cache_dir]).stats
+      puts
+      puts "GEO_CACHE: #{gstats['dir']}"
+      puts "缓存文件: #{gstats['files']}    条目: #{gstats['entries']}"
+      unless gstats["states"].empty?
+        puts "状态分布: " + gstats["states"].map { |k, v| "#{k}=#{v}" }.join("  ")
+      end
+    end
+    exit 0
+  end
+  opts.on("-v", "--version", "显示版本") do
+    require_relative "../version"
+    puts "ngeo-get #{NetworkInfraUtility::VERSION}"
+    exit 0
+  end
+  opts.on("-h", "--help", "显示帮助") do
+    puts opts
+    puts <<~NOTE
+
+      顺位示例:
+        -p cache,local,internet   优先缓存 → 本地库 → 互联网 (默认)
+        -p local,internet,cache   本地优先, 本地查不到才找互联网, 互联网查不到或不通再查缓存
+        -p internet,local         纯互联网优先, 不通再查本地
+
+      产出: 默认保存查询结果为 geocacheYYYYMMDD.json (缓存目录或当前目录), -nc 关闭
+    NOTE
+    exit 0
+  end
+end
+parser.parse!
+
+# ---- -m 整理模式: 合并缓存目录后退出 (优先级最高) ---------------------------
+if options[:merge_dir]
+  gc = GeoQuery::GeoCache.new(options[:merge_dir])
+  unless File.directory?(gc.dir)
+    warn "✗ 缓存目录不存在: #{gc.dir}"
+    exit 1
+  end
+  stats = gc.merge!
+  puts "合并完成: #{stats['files']} 个缓存文件 → #{stats['entries']} 条记录"
+  puts "输出文件: #{stats['output']}"
+  exit 0
+end
+
+# ---- 顺位参数校验 -----------------------------------------------------------
+order = GeoQuery::NGeo::DEFAULT_ORDER
+if options[:order]
+  order = GeoQuery::GeoCache.parse_order(options[:order])
+  if order.nil?
+    warn "✗ 无效顺位: #{options[:order]}"
+    warn "  合法源: cache / local / internet, 逗号分隔, 不重复"
+    warn "  示例: -p cache,local,internet   (默认)"
+    exit 1
+  end
+end
+
+# IP 来源: 命令行参数, 无参数且 stdin 非 TTY 时逐行读
+ips = ARGV.reject { |a| a.start_with?("-") }.map(&:strip).reject(&:empty?)
+if ips.empty? && !$stdin.tty?
+  ips = $stdin.each_line.map(&:strip).reject(&:empty?)
+end
+if ips.empty?
+  warn "用法: ngeo-get <IP> [options]  (或管道输入 IP 列表, 详见 --help)"
+  exit 1
+end
+
+ngeo = GeoQuery::NGeo.new(api: options[:api], geoapi_base: options[:geoapi],
+                          timeout: options[:timeout],
+                          geo_cache_dir: options[:geo_cache_dir], order: order)
+
+results = ips.map do |ip|
+  ngeo.lookup(ip, refresh: options[:refresh], no_local: options[:no_local])
+end
+
+ngeo.save_cache
+
+# ---- 产出: 查询结果保存为 geocacheYYYYMMDD.json -----------------------------
+# 保存目录: -a 指定目录 > ENV["GEO_CACHE_DIR"] > 当前目录; -nc 关闭
+if options[:cache_out] && !results.empty?
+  out_dir = options[:geo_cache_dir] || GeoQuery::GeoCache.default_dir
+  out = GeoQuery::GeoCache.new(out_dir).put_batch(results)
+  # 提示走 stderr, 不污染 JSON 输出
+  warn "产出: #{out['entries']} 条查询结果 → #{out['file']}" if out
+end
+
+# ---- 输出 -------------------------------------------------------------------
+STATE_LABEL = {
+  "merged" => "多源叠加综合", "online" => "纯互联网",
+  "local" => "本地满意", "local-partial" => "本地部分 (无更多补充)",
+  "cache" => "缓存命中", "cache-partial" => "缓存部分 (无更多补充)",
+  "empty" => "各源均无归属", "unreachable" => "查询不可达",
+  "invalid" => "IP 不合法",
+}.freeze
+
+SRC_DISPLAY = {
+  "cache" => "GEO_CACHE 缓存", "local" => "本地 geo-get", "online" => "互联网 gen-get",
+}.freeze
+
+ORDER_TEXT = order.join(",").freeze
+
+case options[:format]
+when :json
+  puts JSON.pretty_generate(results.size == 1 ? results.first : results)
+when :text
+  results.each do |r|
+    puts "查询 IP: #{r['ip']}    顺位: #{ORDER_TEXT} (满意即停, 字段叠加)"
+    puts "-" * 64
+    case r["state"]
+    when "unreachable"
+      puts "✗ #{r['message']}"
+      puts "状态: unreachable (#{STATE_LABEL['unreachable']}) —— 各源均无结果, 且有不联通"
+    when "invalid"
+      puts "✗ #{r['message']}"
+      puts "状态: invalid"
+    else
+      country = r["country"].empty? ? "未知" : r["country"]
+      province = r["province"].empty? ? "未知" : r["province"]
+      city = r["city"].empty? ? "未知" : r["city"]
+      puts "国家: #{country}    省份: #{province}    城市: #{city}"
+      puts "运营商: #{r['isp'].empty? ? '未知' : r['isp']}    用途: #{r['usage'].empty? ? '未知' : r['usage']}"
+      asn = r["asn"].empty? ? "未知" : "AS#{r['asn']}"
+      net = r["network"].empty? ? "" : "    网段: #{r['network']}"
+      puts "ASN: #{asn} #{r['asn_org']}#{net}"
+      cached = r["cached"] ? "缓存命中" : "实时查询"
+      puts "状态: #{r['state']} (#{STATE_LABEL[r['state']]})    来源: #{r['source']}    #{cached}"
+      unless r["message"].to_s.empty?
+        puts "提示: #{r['message']}"
+      end
+      if r["sources"].is_a?(Hash)
+        r["sources"].each do |name, info|
+          next unless info.is_a?(Hash)
+          label = SRC_DISPLAY[name] || name
+          verdict = info["verdict"] ? ", #{info['verdict']}" : ""
+          msg = info["message"].to_s.empty? ? "" : " (#{info['message']})"
+          puts "  · #{label}: #{info['state']}#{verdict}#{msg}"
+        end
+      end
+    end
+    puts
+  end
+end
+
+# 退出码取最严重: unreachable(2) > invalid(1) > 其他(0)
+exit 2 if results.any? { |r| r["state"] == "unreachable" }
+exit 1 if results.any? { |r| r["state"] == "invalid" }
+exit 0