network-infra-utility 0.5.0 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52f005e254e4a41adb347cddd9ce08ab179fd7999e5f79db2de0171ba34a4284
-  data.tar.gz: d2cb8a65fec8e793de56c340305c7a545a6e5dd4e080128a2b1683bf2b606e3f
+  metadata.gz: 47ea2aa6788e6fcf4256ca20f32bb21933d45ac19ba9775d9234b8839413e435
+  data.tar.gz: 1b9393d9081bd78e93e1895e2002695eee940775cba0779a721ab72af8690668
 SHA512:
-  metadata.gz: 54793aea84005bb72d73e5e7806148ecda0ca2bf3ad01e710252936a81922e6b129fedaaf5259e6233380af3eb18d6948b87a80ef5c9c1a077d821f364784b5a
-  data.tar.gz: dea8ac4214edf3f206f92e9586219b70363d10d4fb63d5c72dddbd223c933e38c6167cd015c02f69aefedb0a1db2ef7fdaa29fa28d2e6d7a559e57720cd8c8f1
+  metadata.gz: 0ff7d883a36bf28a873a871c14cb5b8c2fd42ef5ef07263adbd6bbe850bd6b787e00603217232e3d8b1b9c2d33aecf2a27b0fe4285451de34d9460783f581a36
+  data.tar.gz: 9db0ae3bb4f4b74965439f192570de14346a82950c3460494c69941e2621a62de3a97458a27102cef16f850c6d8a1e53049c61d31ad1caa1b2733811e82d1457

data/.gitignore

@@ -1,3 +1,8 @@
+
+# SPEC
+document/example/ssh/config_login_example.rb
+document/example/ssh/login_config.yml
+
 *.gem
 *.rbc
 /.config
@@ -10,6 +15,7 @@
 /test/version_tmp/
 /tmp/
 .temp
+.workbuddy
 
 # Used by dotenv library to load environment variables.
 # .env

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: '88e1794b-cd8d-483e-b3d2-ee4485fccf96'
+  PropagateID: '88e1794b-cd8d-483e-b3d2-ee4485fccf96'
+  ReservedCode1: '20f6bf17-f91c-4c4c-b721-e45f1eb19345'
+  ReservedCode2: '20f6bf17-f91c-4c4c-b721-e45f1eb19345'
+---
 
 # Changelog
 
@@ -8,6 +18,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- 新增 `gen-get` 命令行工具：调用免费互联网接口查询 IP 归属，默认 ip-api.com 及其参数（`lang=zh-CN` + `status,message,country,regionName,city,isp,as,query`，`message` 为诊断扩展），内置 45 req/min 限速（最小间隔 1.4s）与本地 JSON 缓存；互联网不通时返回明确的 `unreachable`（互联网查询不可达）空结果状态并区分于 `empty`（确认无归属，如私有地址）。
+- 新增 `ngeo-get` 命令行工具：综合 geo-get（本地 geo-api）与 gen-get（互联网）两个数据源——本地接口可用时优先使用；归属不满意（省/市/ASN 缺失）时自动补互联网查询；本地与互联网结果字段级叠加（省/城市/用途 IDC·云等准确字段择优，网段保留本地，运营商按合并后组织名归一化）。结果状态可信度链：`unreachable < local-partial < empty < local < online < merged`，互联网不可达时本地部分结果保留；连续 3 次不可达触发 60s 熔断。
+- 新增 `service/geoquery/` 服务模块：`OnlineClient`（ip-api.com 客户端）、`LocalClient`（geo-api 客户端）、`Merge`（字段叠加）、`Normalize`（运营商/用途归一化）、`Cache`（线程安全 JSON 缓存）、`NGeo`（综合查询门面），移植自 `ip_geo_lookup.py` 的多级回退 + 缓存 + 归一化设计。
+- `gen-get` / `ngeo-get` 加入 gemspec executables，`network.rb` 统一入口挂载 geoquery；新增 `spec/geoquery_spec.rb`（状态机/归一化/合并/缓存/熔断）与 `document/example/geoquery_example.rb` 功能用例；接口文档见 `service/geoquery/GeoQuery.md`。
+
+### Changed
+
+- `geo-get` 重构为 `GeoQuery::LocalClient` 的瘦封装：三接口拉取与汇总逻辑统一收口在 `service/geoquery/local.rb`（新增 `fetch_raw` 原始接口查询，保持 geo-get `-j` 输出的原始响应契约不变），geo-get 与 ngeo-get / gen-get 共享同一套客户端实现，消除双实现；CLI 选项、文字/JSON 输出格式、服务未启动提示均保持向后兼容，另支持 `GEO_API_BASE` 环境变量覆盖服务地址。
+- 合并 `geo_api_query_example.rb`（geo-api 服务三接口）与旧版 `geoquery_example.rb`（GeoQuery 查询编排）为单一 `document/example/geoquery_example.rb`：按“Part A 服务接口 → Part B 查询编排”组织为 11 个案例块，新增 LocalClient（`fetch_raw` / `lookup`）演示；Part B 复用 Part A 启动的服务实例（支持 `GEOAPI=` 覆盖为外部服务），通过 `$LOAD_PATH` 前插仓库根消除工作区与已安装 gem 的双重加载警告。
+- `example/` 目录整体移至 `document/example/`（并入文档层），`Rakefile` example 任务 pattern、gemspec 文件排除规则（新增 `document/example/`）与根 README 项目结构表同步更新。
+- 新增 `probe` 服务连通性探测工具箱（`tool/probe/`），覆盖 icmp / telnet / ssh / netconf / snmp / twamp / dns / ntp / radius 九类协议，纯 Ruby 标准库实现、零第三方运行时依赖。
+  - 统一探测框架：`Probe::Base` 基类 + `Probe::Result` 统一结果 + `Probe::Registry` 注册表，协议名从类名自动派生，支持 `Registry.register` 扩展自定义探针。
+  - 内置 BER 编码器（SNMPv1/v2c GET 请求自编码）、NTP 48 字节客户端报文、RADIUS Access-Request 报文构造。
+  - TCP 探针区分 timeout / refused / unreachable；SSH/NETCONF 附加横幅校验；ICMP 复用系统 ping 并兼容中英文输出解析 RTT。
+  - 提供 `Probe.run(protocol, host)` / `Probe.check(host, protocols:)` 代码级 API 与 `bin/probe` 命令行工具（支持 `--all` / `--json` / `--timeout` / `--community` 等选项）。
+  - `probe` 加入 gemspec executables，`tool/probe/lib` 加入 require_paths，`network.rb` 统一入口已挂载。
+
 ## [0.3.0] - 2026-07-26
 
 ### Added
@@ -44,3 +73,5 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 初始化 gem 骨架，按 document / service / support / tool 四层 require_paths 组织代码。
 - 配置 RSpec 原子能力测试（`spec/`）与功能用例（`example/`）双套结构。
 - 提供标准 gem 文件：gemspec / Gemfile / Rakefile / .rspec / bin/console / bin/setup 等。
+
+> AI生成

data/GUIDE.md

@@ -0,0 +1,201 @@
+# GUIDE
+
+## 在 Alpine 设备上重新编译 Rust 和 Erlang 引擎
+
+项目 SSH 核心引擎有两个后端，均可在 Alpine（musl libc）上原生编译：
+
+| 引擎 | 目录 | 构建工具 | 产物 |
+|------|------|---------|------|
+| **Rust 引擎**（默认） | `service/ssh/ext/ssh_core_rs/` | cargo | `target/release/ssh_core_rs` |
+| **Erlang 引擎**（可选） | `service/ssh/ext/ssh_core/` | rebar3 | `_build/default/lib/ssh_core/ebin/*.beam` |
+
+### 2.1 安装编译依赖
+
+```bash
+# 更新包索引
+apk update
+
+# 通用编译工具链（gcc、make、musl-dev、libc Headers 等）
+apk add build-base
+
+# ── Rust 引擎依赖 ──
+apk add rust cargo
+apk add pkgconf openssl-dev     # openssl-dev 预防部分 crate 需要链接系统 OpenSSL
+
+# ── Erlang 引擎依赖 ──
+# 方式 A：Alpine 仓库安装（Alpine 3.19+ 提供 OTP 26）
+apk add erlang rebar3
+
+# 方式 B：如果仓库 OTP 版本低于 26，从源码编译 Erlang/OTP
+#   见下方 2.3 节
+```
+
+### 2.2 编译 Rust 引擎
+
+```bash
+cd service/ssh/ext/ssh_core_rs
+
+# 清理旧产物（如从其他平台拷贝过来）
+rm -rf target/
+
+# Release 编译
+cargo build --release
+
+# 验证产物
+ls -lh target/release/ssh_core_rs
+./target/release/ssh_core_rs --help 2>&1 || true
+# 引擎启动后会在 /tmp/ssh_core_<uid>.endpoint 写入端点文件
+```
+
+**说明：**
+- Alpine 默认 host triple 是 `x86_64-unknown-linux-musl`（ARM 则为 `aarch64-unknown-linux-musl`），cargo 会自动选择，无需额外配置 target。
+- `Cargo.toml` 中 russh 使用 `ring` 特性（纯 Rust 加密后端），不依赖系统 OpenSSL / NASM，musl 环境可直接编译。
+- 编译后 `bin/ssh_core_rs`（bash 启动脚本）已存在，Ruby 端 `Client.new(backend: :rust)` 会自动调用它。
+
+### 2.3 编译 Erlang 引擎
+
+> 如果 `apk add erlang` 安装的 OTP 版本 >= 26，直接跳到 2.3.2。
+
+#### 2.3.1 从源码编译 Erlang/OTP（仅当仓库版本 < 26 时需要）
+
+```bash
+# 安装 Erlang 编译依赖
+apk add build-base perl ncurses-dev openssl-dev unixodbc-dev
+
+# 下载 OTP 27（或 26）
+cd /tmp
+wget https://github.com/erlang/otp/releases/download/OTP-27.3.3/otp_src_27.3.3.tar.gz
+tar xzf otp_src_27.3.3.tar.gz
+cd otp_src_27.3.3
+
+# 编译（musl 环境，禁用 wx/mac 等 GUI 组件，保留 ssh/crypto/public_key）
+export ERL_TOP=/tmp/otp_src_27.3.3
+./configure \
+  --prefix=/usr/local/erlang \
+  --without-ssl-verify \
+  --disable-nls \
+  --without-javac \
+  --without-wx \
+  --without-debugger
+make -j$(nproc)
+make install
+
+# 加入 PATH
+export PATH=/usr/local/erlang/bin:$PATH
+echo 'export PATH=/usr/local/erlang/bin:$PATH' >> ~/.profile
+
+# 验证
+erl -version
+# Erlang (SHELL) version 27.3.3
+```
+
+#### 2.3.2 安装 rebar3
+
+```bash
+# 方式 A：Alpine 仓库已安装则跳过
+rebar3 --version
+
+# 方式 B：下载 standalone 二进制
+wget https://github.com/erlang/rebar3/releases/download/3.24.0/rebar3
+chmod +x rebar3
+mv rebar3 /usr/local/bin/
+rebar3 --version
+```
+
+#### 2.3.3 编译 ssh_core
+
+```bash
+cd service/ssh/ext/ssh_core
+
+# 清理旧产物
+rm -rf _build/ rebar3.crashdump
+
+# 编译
+# rebar.config 中 {deps, []}（无外部依赖），jsx 已内嵌为本地源码
+# （local_deps/jsx/src/src/），通过 src_dirs 直接编译，无需从 hex.pm 拉取
+rebar3 compile
+
+# 验证产物
+ls _build/default/lib/ssh_core/ebin/*.beam | head -5
+```
+
+> **常见问题**：启动时如果报 `undefined function os:getuid/0`，是因为 OTP 版本 < 26 缺少此 BIF。代码已修复为自动 fallback 到 `os:cmd("id -u")`，确保 `rebar3 compile` 重新编译即可。
+
+#### 2.3.4 创建 Unix 启动脚本
+
+项目当前只有 `bin/ssh_core.cmd`（Windows），Linux/Alpine 需要创建 `bin/ssh_core`：
+
+```bash
+cat > service/ssh/ext/ssh_core/bin/ssh_core << 'SCRIPT'
+#!/usr/bin/env sh
+# ssh_core engine launcher for Linux/macOS/Alpine
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SSH_CORE_DIR="$(dirname "$SCRIPT_DIR")"
+EBIN_DIR="$SSH_CORE_DIR/_build/default/lib/ssh_core/ebin"
+
+# Delete stale endpoint file
+ENDPOINT_FILE="/tmp/ssh_core_$(id -u).endpoint"
+rm -f "$ENDPOINT_FILE"
+
+# Start the Erlang VM
+exec erl -noshell -noinput -pa "$EBIN_DIR" \
+  -eval "application:ensure_all_started(ssh_core)"
+SCRIPT
+chmod +x service/ssh/ext/ssh_core/bin/ssh_core
+```
+
+#### 2.3.5 验证 Erlang 引擎可启动
+
+```bash
+cd service/ssh/ext/ssh_core
+./bin/ssh_core &
+# 等 2 秒后查看端点文件
+sleep 2 && cat /tmp/ssh_core_$(id -u).endpoint
+# 应输出类似：tcp://127.0.0.1:xxxxx\n<auth_token>
+
+# 停止引擎
+kill %1
+```
+
+### 2.4 编译后的 Ruby 端验证
+
+```bash
+# 在项目根目录，确认 Ruby 可连接引擎
+ruby -e '
+  $LOAD_PATH.unshift("service/ssh/lib")
+  require "network_infra_utility/ssh"
+
+  # Rust 引擎（默认）
+  client = NetworkInfraUtility::SSH::Client.new(backend: :rust)
+  client.start_engine
+  puts "Rust engine: #{client.started?}"
+  client.stop
+
+  # Erlang 引擎
+  client2 = NetworkInfraUtility::SSH::Client.new(backend: :erlang)
+  client2.start_engine
+  puts "Erlang engine: #{client2.started?}"
+  client2.stop
+'
+```
+
+### 2.5 常见问题
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `cargo build` 报 `linker cc not found` | 未安装 build-base | `apk add build-base` |
+| `cargo build` 拉 crates.io 超时 | 国内网络限制 | `~/.cargo/config.toml` 配中科大/清华镜像源 |
+| `cargo build` 报 `edition2024 is required` | Alpine 仓库 Rust 版本过旧 (< 1.85) | `apk del rust cargo` 后用 rustup 装最新稳定版 |
+| `curl https://sh.rustup.rs` 下载不动 | rustup 安装脚本在国外 | 设 `RUSTUP_DIST_SERVER` 中科大镜像，或直接下载 rustup-init 二进制 |
+| `rebar3 compile` 报 `undef ssh` 模块 | OTP 版本 < 26 | 按本文 2.3.1 从源码编译 OTP 27 |
+| Erlang 引擎报 `undefined function os:getuid/0` | OTP < 26 缺少此 BIF | 代码已修复自动 fallback，`rebar3 compile` 重新编译 |
+| Erlang 引擎启动报 `ssh_core beam not found` | `bin/ssh_core` 脚本 EBIN_DIR 路径不对 | 确认 `_build/default/lib/ssh_core/ebin/` 下有 beam 文件 |
+| Ruby 报 `Engine binary not found` | 缺少启动脚本 | Rust: 确认 `bin/ssh_core_rs` 存在；Erlang: 按本文 2.3.4 创建 `bin/ssh_core` |
+| Ruby 报 `Permission denied` 启动脚本 | Windows 拷来的脚本丢失执行位 | `chmod +x service/ssh/ext/ssh_core_rs/bin/ssh_core_rs` |
+| Ruby 报 `ECONNREFUSED` 连接引擎 | 旧引擎残留进程占用端口 | `pkill ssh_core_rs; rm -f /tmp/ssh_core_*.endpoint` |
+| `conn.connect` 超时 (60s) | 网络不通或设备 SSH 不兼容 | 先 `ping`/`nc -zv` 确认网络，再用 `RUST_LOG=debug` 定位 |
+| `auth_rejected` 认证被拒绝 | 设备只支持 keyboard-interactive | 配置文件 `auth.type` 改为 `keyboard_interactive` |
+| Rust 编译卡在 `ring` 或 `aws-lc-rs` | 误用了 aws-lc-rs 后端 | Cargo.toml 已指定 `features = ["ring"]`，确认未被覆盖 |
+| `error: musl-gcc: not found` | 部分 crate 尝试用 musl-gcc | `apk add musl-dev`（已含于 build-base） |

data/README.md

@@ -1,4 +1,3 @@
-
 # Network Infrastructure Utility
 
 重新编排 Network（`gem: network-utility`）。
@@ -17,7 +16,7 @@
 测试体系：
 
 - `spec/` —— 原子能力验证（单元规格）
-- `example/` —— 常用场景的功能用例
+- `document/example/` —— 常用场景的功能用例
 
 ## 安装
 
@@ -39,7 +38,3 @@ bundle exec rake spec      # 跑原子能力
 bundle exec rake example   # 跑功能用例
 bundle exec rake           # 两者都跑（默认）
 ```
-
-## License
-
-采用 [GNU Affero General Public License v3.0 或更高版本](https://www.gnu.org/licenses/agpl-3.0.html)（AGPL-3.0-or-later），详见 [LICENSE.txt](LICENSE.txt)。

data/Rakefile

@@ -8,7 +8,7 @@ RSpec::Core::RakeTask.new(:spec)
 
 # 功能场景用例
 RSpec::Core::RakeTask.new(:example) do |t|
-  t.pattern = "example/**/*_example.rb"
+  t.pattern = "document/example/**/*_example.rb"
 end
 
 task default: %i[spec example]

data/bin/dns-query

@@ -830,5 +830,7 @@ module DnsQuery
   end
 end
 
-# 仅作为命令行执行时运行 CLI；被 require 时只提供模块能力
-exit DnsQuery::CLI.run(ARGV) if __FILE__ == $PROGRAM_NAME
+# 仅作为命令行执行时运行 CLI；被 require 时只提供模块能力。
+# 注意: gem 安装后经 wrapper 以 load 方式加载，__FILE__ 与 $PROGRAM_NAME
+# 路径不同，须按文件名 (basename) 判断才能同时覆盖两种运行方式。
+exit DnsQuery::CLI.run(ARGV) if File.basename($PROGRAM_NAME) == File.basename(__FILE__)

data/bin/gen-get

@@ -0,0 +1,144 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# coding: utf-8
+#
+# gen-get — network-infra-utility 的互联网 IP 归属查询工具 (geo 系列)
+#
+# 调用免费互联网接口查询 IP 归属, 默认 ip-api.com 及其参数
+# (lang=zh-CN, fields=status,message,country,regionName,city,isp,as,query),
+# 内置 45 req/min 限速与本地 JSON 缓存。
+#
+# 用法:
+#   gen-get 8.8.8.8                    # 单 IP, 文字格式
+#   gen-get 8.8.8.8 -j                 # JSON 格式
+#   gen-get 1.1.1.1 8.8.8.8 ...       # 多 IP (自动限速)
+#   cat ips.txt | gen-get -j           # 从 stdin 逐行读 IP
+#   gen-get 8.8.8.8 --refresh         # 忽略缓存强刷
+#   gen-get --cache-stats              # 查看缓存统计
+#
+# 选项:
+#   -t, --text         文字格式输出 (默认)
+#   -j, --json         JSON 格式输出 (多 IP 时输出数组)
+#   --refresh          忽略缓存强制重查
+#   --no-cache         查询结果不写入缓存
+#   --api URL          覆盖默认接口 ({ip} 占位符)
+#   --timeout SEC      HTTP 超时秒数, 默认 10
+#   --cache-stats      查看缓存统计后退出
+#   -h, --help         显示帮助
+#   -v, --version      显示版本
+#
+# 退出码: 0 = 查询完成 (含确认无归属); 1 = IP 不合法; 2 = 互联网查询不可达
+#
+# 结果状态 (state):
+#   ok           互联网查询成功
+#   empty        互联网确认无归属 (如私有/保留地址)
+#   unreachable  互联网查询不可达 (网络不通/超时/限速), 返回空结果状态
+#   invalid      IP 不合法
+
+require "optparse"
+require "json"
+require_relative "../service/geoquery/geoquery"
+
+options = { format: :text, refresh: false, no_cache: false, timeout: 10, api: nil }
+parser = OptionParser.new do |opts|
+  opts.banner = <<~BAN
+    gen-get — 互联网 IP 归属查询工具 (network-infra-utility)
+
+    默认接口: ip-api.com 免费接口 (限 45 req/min, 无需 Key)
+    用法:
+      gen-get <IP> [options]
+      gen-get 8.8.8.8 -j
+      cat ips.txt | gen-get -j
+
+    选项:
+  BAN
+  opts.on("-t", "--text", "文字格式输出 (默认)")      { options[:format] = :text }
+  opts.on("-j", "--json", "JSON 格式输出")            { options[:format] = :json }
+  opts.on("--refresh", "忽略缓存强制重查")             { options[:refresh] = true }
+  opts.on("--no-cache", "查询结果不写入缓存")          { options[:no_cache] = true }
+  opts.on("--api URL", "覆盖默认互联网接口 ({ip} 占位符)") { |v| options[:api] = 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, "gen-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
+    exit 0
+  end
+  opts.on("-v", "--version", "显示版本") do
+    require_relative "../version"
+    puts "gen-get #{NetworkInfraUtility::VERSION}"
+    exit 0
+  end
+  opts.on("-h", "--help", "显示帮助") do
+    puts opts
+    exit 0
+  end
+end
+parser.parse!
+
+# 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 "用法: gen-get <IP> [options]  (或管道输入 IP 列表, 详见 --help)"
+  exit 1
+end
+
+cache = GeoQuery::Cache.new(File.join(GeoQuery::Cache.default_dir, "gen-cache.json"))
+client = GeoQuery::OnlineClient.new(api: options[:api], timeout: options[:timeout])
+
+results = ips.map do |ip|
+  result = nil
+  unless options[:refresh]
+    cached = cache.get(ip)
+    if cached
+      cached["source"] = "gen-get(cache)"
+      result = cached
+    end
+  end
+  result ||= client.lookup(ip)
+  cache.put(ip, result) unless options[:no_cache]
+  result
+end
+
+cache.save unless options[:no_cache]
+
+# ---- 输出 -------------------------------------------------------------------
+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']}    接口: ip-api.com (免费, 限 45 req/min)"
+    puts "-" * 64
+    case r["state"]
+    when "ok"
+      cached = r["cached"] ? "缓存命中" : "实时查询"
+      puts "国家: #{r['country']}    省份: #{r['province']}    城市: #{r['city']}"
+      puts "运营商: #{r['isp']}    用途: #{r['usage']}"
+      puts "ASN: #{r['asn'].empty? ? '未知' : "AS#{r['asn']}"} #{r['asn_org']}"
+      puts "状态: ok    来源: #{r['source']}    #{cached}"
+    when "empty"
+      puts "互联网确认无该 IP 归属数据 (#{r['message']})"
+      puts "状态: empty    来源: #{r['source']}"
+    when "unreachable"
+      puts "✗ 互联网查询不可达: #{r['message']}"
+      puts "状态: unreachable —— 无法连接互联网查询接口, 返回空结果"
+    when "invalid"
+      puts "✗ #{r['message']}"
+      puts "状态: invalid"
+    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

data/bin/geo-api

@@ -11,6 +11,7 @@
 # 用法:
 #   geo-api                              # 默认 ./geodb/ + 0.0.0.0:9292
 #   geo-api -d /data/ipdb                # 指定数据文件目录
+#   geo-api -d /data/ipdb -a ./GEO_CACHE # 外带 GEO_CACHE 缓存目录
 #   geo-api -p 8080                      # 指定端口
 #   geo-api -b 127.0.0.1 -p 9292 -d ./ipdb
 #   geo-api --server puma                # 指定 Rack 服务器
@@ -18,6 +19,9 @@
 #
 # 选项:
 #   -d, --data-dir DIR   IP 数据文件目录，默认 ./geodb/
+#   -a, --cache-dir DIR  GEO_CACHE 外带缓存目录 (geocacheYYYYMMDD.json,
+#                        ngeo-get -c 产出; addr 查询兑底)
+#   --priority ORDER     查询顺位 local,cache 的排列 (默认 local,cache)
 #   -b, --host HOST      监听地址，默认 0.0.0.0
 #   -p, --port PORT      监听端口，默认 9292
 #   -s, --server NAME    Rack 服务器，默认 puma
@@ -29,6 +33,13 @@
 #   country-IPv4.json / country-IPv6.json / city-IPv6.json / geo-city.json /
 #   geo-country.json)。目录不存在或没有任何 *.json 文件将直接报错退出。
 #   查询时若具体文件缺失，对应接口容错返回 404 无结果，不影响其他接口。
+#
+# 缓存目录说明:
+#   -a 指定的 GEO_CACHE 目录内存放 geocacheYYYYMMDD.json (客户端 ngeo-get
+#   查询产出)。addr 查询按 --priority 顺位 (默认 local,cache) 编排:
+#   先查本地 GeoLite2 库，查不到时用缓存定位信息兑底。目录不存在仅警告
+#   不退出 (首次使用可能尚无产出文件，后续创建自动感知); 目录内文件
+#   增删改自动感知，无需重启。缓存命中响应附 "cached": true 标记。
 
 require "optparse"
 require "rackup"
@@ -40,6 +51,8 @@ $LOAD_PATH.unshift File.join(ROOT, "service", "geodb")
 # 命令行默认值
 options = {
   data_dir: nil,
+  cache_dir: nil,
+  priority: nil,
   host: "0.0.0.0",
   port: 9292,
   server: "puma"
@@ -56,6 +69,8 @@ parser = OptionParser.new do |opts|
     选项:
   BAN
   opts.on("-d", "--data-dir DIR", "IP 数据文件目录，默认 ./geodb/") { |v| options[:data_dir] = v }
+  opts.on("-a", "--cache-dir DIR", "GEO_CACHE 外带缓存目录 (geocache*.json, 查询兑底)") { |v| options[:cache_dir] = v }
+  opts.on("--priority ORDER", "查询顺位 local,cache 排列 (默认 local,cache)") { |v| options[:priority] = v }
   opts.on("-b", "--host HOST", "监听地址，默认 0.0.0.0") { |v| options[:host] = v }
   opts.on("-p", "--port PORT", Integer, "监听端口，默认 9292") { |v| options[:port] = v }
   opts.on("-s", "--server NAME", "Rack 服务器，默认 puma") { |v| options[:server] = v }
@@ -94,10 +109,34 @@ if json_files.empty?
   exit 1
 end
 
+# ---- 缓存目录与顺位 ---------------------------------------------------------
+cache_order = options[:priority] || "local,cache"
+parts = cache_order.split(/[,\s]+/).map(&:strip).reject(&:empty?)
+unless !parts.empty? && parts.all? { |p| %w[local cache].include?(p) } && parts.uniq.size == parts.size
+  warn "✗ 无效顺位: #{cache_order} (geo-api 仅支持 local / cache 的排列)"
+  warn "  示例: --priority local,cache   (默认, 先本地库再缓存)"
+  exit 1
+end
+ENV["GEODB_CACHE_ORDER"] = parts.join(",")
+
+cache_dir = nil
+if options[:cache_dir]
+  cache_dir = File.expand_path(options[:cache_dir])
+  # 目录不存在仅警告: 首次使用可能尚无产出文件, 后续创建自动感知
+  unless File.directory?(cache_dir)
+    warn "⚠ 缓存目录不存在: #{cache_dir} (将继续启动, 目录创建后自动感知)"
+  end
+  ENV["GEODB_CACHE_DIR"] = cache_dir
+end
+
 require_relative "../version"
-puts "╭─ geo-api #{NetworkInfraUtility::VERSION} ───────────────────────────────"
+puts "╭─ geo-api #{NetworkInfraUtility::VERSION} ─────────────────────────────"
 puts "│ 数据目录: #{data_dir} "
 puts "│ #{json_files.length}个数据文件：#{json_files.map { |f| File.basename(f) }.join(' ')}"
+if cache_dir
+  n_cache = Dir.glob(File.join(cache_dir, "geocache*.json")).select { |f| /\Ageocache\d{8}\.json\z/ =~ File.basename(f) }.size
+  puts "│ 缓存目录: #{cache_dir} (#{n_cache}个缓存文件, 兑底顺位: #{parts.join(',')})"
+end
 puts "│ 监听: http://#{options[:host]}:#{options[:port]}"
 puts "│ 服务: #{options[:server]}"
 puts "╰─ Ctrl+C 退出 ─────────────────────────────────────"

data/bin/geo-get

@@ -7,6 +7,10 @@
 # 向运行中的 geo-api 服务发起查询，一次输入 IP，同时拉取 country / city /
 # asn 三类归属信息并汇总输出。默认展示文字，加 -j 则打印 JSON。
 #
+# 本命令为 GeoQuery::LocalClient (service/geoquery/local.rb) 的瘦封装：
+# 三接口拉取与汇总逻辑统一收口在 LocalClient，与 ngeo-get / gen-get
+# 共享同一套客户端实现，消除双实现。
+#
 # 用法:
 #   geo-get 1.181.240.251              # 默认三接口齐查, 文字格式
 #   geo-get 8.8.8.8 -j                 # JSON 格式输出
@@ -24,16 +28,14 @@
 #   -v, --version      显示版本
 #
 # 默认连 http://127.0.0.1:9292 (geo-api 默认监听)。
+# 可用环境变量 GEO_API_BASE 覆盖服务地址。
 # 服务未运行时给出明确提示与启动命令。
 
 require "optparse"
-require "net/http"
 require "json"
-require "uri"
+require_relative "../service/geoquery/geoquery"
 
-HOST = "127.0.0.1"
-PORT = 9292
-BASE = "http://#{HOST}:#{PORT}"
+BASE = ENV["GEO_API_BASE"] || GeoQuery::LocalClient::DEFAULT_BASE
 
 # ---- 命令行解析 -------------------------------------------------------------
 options = { format: :text, only: nil }
@@ -70,59 +72,39 @@ parser.parse!
 ip = ARGV.find { |a| !a.start_with?("-") } || "1.181.240.251"
 
 only = options[:only]
-do_country = only.nil? || only == :country
-do_city    = only.nil? || only == :city
-do_asn     = only.nil? || only == :asn
+endpoints = only ? [only] : GeoQuery::LocalClient::ENDPOINTS
 
-# ---- HTTP 取数 --------------------------------------------------------------
-# 发起一次 GET, 返回 {code:, body:}
-def fetch(base, path, params)
-  uri = URI("#{base}#{path}")
-  uri.query = URI.encode_www_form(params) unless params.empty?
-  res = Net::HTTP.get_response(uri)
-  { code: res.code.to_i, body: (JSON.parse(res.body) rescue res.body) }
-rescue Errno::ECONNREFUSED
-  abort "✗ 无法连接 #{base} —— geo-api 服务未启动。\n  启动命令: geo-api -d ./geodb"
-rescue => e
-  abort "✗ 请求失败: #{e.class}: #{e.message}"
-end
+# ---- 查询 (LocalClient 底座) ------------------------------------------------
+client = GeoQuery::LocalClient.new(base: BASE)
+raw = client.fetch_raw(ip, endpoints: endpoints)
 
-# ---- 按接口拉取 + 收集 ------------------------------------------------------
-results = {}
-results[:country] = fetch(BASE, "/geo/country", addr: ip) if do_country
-results[:city]    = fetch(BASE, "/geo/city",    addr: ip) if do_city
-results[:asn]     = fetch(BASE, "/geo/asn",     addr: ip) if do_asn
+if raw == :unreachable
+  abort "✗ 无法连接 #{BASE} —— geo-api 服务未启动。\n  启动命令: geo-api -d ./geodb"
+end
 
 # ---- 输出: --json / --text 两路分发 -----------------------------------------
 case options[:format]
 when :json
   # JSON 格式: 把每个接口的响应原样放进一个对象打印。
   # 命中的接口放解析后的 body; 404/无结果放 null, 不逐条刷错误。
-  payload = {}
-  results.each do |key, r|
-    payload[key] = (r[:code] == 200 ? r[:body] : nil)
-  end
-  puts JSON.pretty_generate(payload)
+  puts JSON.pretty_generate(raw.transform_keys(&:to_s))
 when :text
   puts "查询 IP: #{ip}    范围: #{only ? "仅 #{only}" : 'country / city / asn 三接口齐查'}    服务: #{BASE}"
   puts "-" * 60
 
   hits = []
-  if do_country && (r = results[:country]) && r[:code] == 200
-    d = r[:body]
+  if (d = raw[:country])
     g = d["geoname"]; rc = d["registered_country"]
     country = (g && g["country_name"]) || (rc && rc["country_name"]) || "未知"
     hits << "[国家] #{country} (#{(g && g["country_iso_code"]) || (rc && rc["country_iso_code"])})  网段 #{d["network"]}"
   end
-  if do_city && (r = results[:city]) && r[:code] == 200
-    d = r[:body]
+  if (d = raw[:city])
     g = d["geoname"]
     city = (g && (g["city_namezh"] || g["city_name"])) || "未知"
     coord = g && g["latitude"] && g["longitude"] ? "#{g["latitude"]}, #{g["longitude"]}" : "无"
     hits << "[城市] #{city}    坐标 #{coord}    网段 #{d["network"]}"
   end
-  if do_asn && (r = results[:asn]) && r[:code] == 200
-    d = r[:body]
+  if (d = raw[:asn])
     hits << "[ASN]  AS#{d["autonomous_system_number"]} #{d["autonomous_system_organization"]}    网段 #{d["network"]}"
   end