network-infra-utility 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52f005e254e4a41adb347cddd9ce08ab179fd7999e5f79db2de0171ba34a4284
-  data.tar.gz: d2cb8a65fec8e793de56c340305c7a545a6e5dd4e080128a2b1683bf2b606e3f
+  metadata.gz: 7104fdb4e0af5c22afd54d3668e4ffc76641fbe81960c8f846140cdfd5e31c7b
+  data.tar.gz: bf059325d90e039e8902e0619593737dee159790a448561c5df2f9c7e3a939df
 SHA512:
-  metadata.gz: 54793aea84005bb72d73e5e7806148ecda0ca2bf3ad01e710252936a81922e6b129fedaaf5259e6233380af3eb18d6948b87a80ef5c9c1a077d821f364784b5a
-  data.tar.gz: dea8ac4214edf3f206f92e9586219b70363d10d4fb63d5c72dddbd223c933e38c6167cd015c02f69aefedb0a1db2ef7fdaa29fa28d2e6d7a559e57720cd8c8f1
+  metadata.gz: ff00412f6b6deb87dbf766f7a84022ea2bd57a6f337e437cdb36931e4b67f8d373d4ee0dd6097141f927a4889c96e8a472ff4b793d131e3c3363248b8a321681
+  data.tar.gz: 5e84775da10cd26e0750dbca13dfa8ec5a731db56175192cc96b2d217660078d4c04d1a737d8731415f9a487afd748c1da33fac74fa21771b1aef1122d23c241

data/GUIDE.md

@@ -0,0 +1,212 @@
+---
+AIGC:
+  ContentProducer: '001191110102MAD55U9H0F10002'
+  ContentPropagator: '001191110102MAD55U9H0F10002'
+  Label: '1'
+  ProduceID: '6a4e300b-498c-4b8e-aca3-75d6bf706299'
+  PropagateID: '6a4e300b-498c-4b8e-aca3-75d6bf706299'
+  ReservedCode1: '322e695f-ea2e-4e18-a164-50a935a6be6d'
+  ReservedCode2: '322e695f-ea2e-4e18-a164-50a935a6be6d'
+---
+
+# 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/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/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/network-infra-utility.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |spec|
   # bin/ 既放对外命令 (geo-api) 也放开发脚本 (console/setup)，
   # executables 显式声明，避免把开发脚本当作系统命令安装到用户 PATH。
   spec.bindir       = "bin"
-  spec.executables  = %w[geo-api geo-get geo-load geo-doc]
+  spec.executables  = %w[geo-api geo-get geo-load geo-doc geo-update dns-query]
   spec.require_paths = ["document", "service", "service/ssh/lib", "support", "tool", "."]
 
   # geo-api 命令行服务依赖的运行时 gem

data/service/ssh/README.md

@@ -1,13 +1,3 @@
----
-AIGC:
-  ContentProducer: '001191110102MAD55U9H0F10002'
-  ContentPropagator: '001191110102MAD55U9H0F10002'
-  Label: '1'
-  ProduceID: '327b0e14-d4aa-4064-bd5a-c596fad52e74'
-  PropagateID: '327b0e14-d4aa-4064-bd5a-c596fad52e74'
-  ReservedCode1: 'c77ee856-ff93-4d59-bbda-652be5dd5d7b'
-  ReservedCode2: 'c77ee856-ff93-4d59-bbda-652be5dd5d7b'
----
 
 # SSH 连接客户端
 
@@ -19,33 +9,56 @@ Ruby + 双引擎架构的 SSH 连接客户端。SSH 协议核心由**可插拔
 
 ## 目录
 
-- [环境要求](#环境要求)
-- [安装与编译](#安装与编译)
-- [快速开始](#快速开始)
-- [CLI 命令参考](#cli-命令参考)
-  - [connect — 连接服务器](#connect--连接服务器)
-  - [batch — 批量执行命令](#batch--批量执行命令)
-  - [themes — 列出配色主题](#themes--列出配色主题)
-  - [version — 显示版本](#version--显示版本)
-- [连接参数详解](#连接参数详解)
-- [配置文件](#配置文件)
-  - [settings.yml](#settingsyml)
-  - [sessions.yml](#sessionsyml)
-  - [known\_hosts.yml](#known_hostsyml)
-- [凭据加密（Vault）](#凭据加密vault)
-- [终端配色主题](#终端配色主题)
-- [编程 API 使用](#编程-api-使用)
-  - [Client — 生命周期管理](#client--生命周期管理)
-  - [Session — 会话操作](#session--会话操作)
-  - [Terminal::Emulator — 终端交互](#terminalemulator--终端交互)
-  - [Automation::MacroEngine — 登录宏](#automationmacroengine--登录宏)
-  - [Security::HostKey — 主机密钥管理](#securityhostkey--主机密钥管理)
-- [RPC 方法列表](#rpc-方法列表)
-- [架构说明](#架构说明)
-  - [启动流程](#启动流程)
-  - [分工](#分工)
-  - [关键模块在运行时的角色](#关键模块在运行时的角色)
-- [项目结构](#项目结构)
+- [SSH 连接客户端](#ssh-连接客户端)
+  - [目录](#目录)
+  - [环境要求](#环境要求)
+    - [Ruby 依赖](#ruby-依赖)
+  - [安装与编译](#安装与编译)
+    - [1. 编译 Rust 核心引擎（默认）](#1-编译-rust-核心引擎默认)
+    - [2. 编译 Erlang 核心引擎（可选备选）](#2-编译-erlang-核心引擎可选备选)
+    - [3. 验证引擎可启动](#3-验证引擎可启动)
+    - [4. 验证 Ruby 端](#4-验证-ruby-端)
+  - [快速开始](#快速开始)
+    - [连接到服务器](#连接到服务器)
+    - [编程方式使用](#编程方式使用)
+  - [CLI 命令参考](#cli-命令参考)
+    - [connect — 连接服务器](#connect--连接服务器)
+    - [batch — 批量执行命令](#batch--批量执行命令)
+    - [themes — 列出配色主题](#themes--列出配色主题)
+    - [version — 显示版本](#version--显示版本)
+  - [连接参数详解](#连接参数详解)
+    - [auth 字段](#auth-字段)
+    - [jumps 字段](#jumps-字段)
+    - [proxy 字段（仅 Erlang 引擎）](#proxy-字段仅-erlang-引擎)
+  - [配置文件](#配置文件)
+    - [settings.yml](#settingsyml)
+    - [sessions.yml](#sessionsyml)
+    - [known\_hosts.yml](#known_hostsyml)
+  - [凭据加密（Vault）](#凭据加密vault)
+    - [加密存储](#加密存储)
+    - [vault.yml 格式](#vaultyml-格式)
+  - [终端配色主题](#终端配色主题)
+    - [自定义主题](#自定义主题)
+  - [编程 API 使用](#编程-api-使用)
+    - [Client — 生命周期管理](#client--生命周期管理)
+    - [Session — 会话操作](#session--会话操作)
+    - [Terminal::Emulator — 终端交互](#terminalemulator--终端交互)
+    - [Automation::MacroEngine — 登录宏](#automationmacroengine--登录宏)
+    - [Security::HostKey — 主机密钥管理](#securityhostkey--主机密钥管理)
+  - [RPC 方法列表](#rpc-方法列表)
+    - [连接管理](#连接管理)
+    - [通道管理](#通道管理)
+    - [SFTP 文件传输](#sftp-文件传输)
+    - [端口转发](#端口转发)
+    - [引擎管理](#引擎管理)
+    - [保活管理](#保活管理)
+    - [反向 RPC（引擎 → Ruby）](#反向-rpc引擎--ruby)
+    - [推送事件（引擎 → Ruby，notification）](#推送事件引擎--rubynotification)
+  - [架构说明](#架构说明)
+    - [启动流程](#启动流程)
+    - [分工](#分工)
+    - [关键模块在运行时的角色](#关键模块在运行时的角色)
+  - [项目结构](#项目结构)
 
 ---
 

data/service/ssh/ext/ssh_core/src/ssh_infra_sup.erl

@@ -24,10 +24,23 @@ generate_endpoint_file() ->
     end,
     UID = case os:type() of
         {win32, _} -> os:getenv("USERNAME");
-        _ -> integer_to_list(os:getuid())
+        _ -> get_uid()
     end,
     filename:join(Tmp, "ssh_core_" ++ UID ++ ".endpoint").
 
+%% @doc Cross-version UID retrieval.
+%% os:getuid/0 was introduced in OTP 26; fall back to os:cmd("id -u")
+%% for older OTP versions (or source-compiled musl builds where the BIF
+%% may be absent).
+get_uid() ->
+    case erlang:function_exported(os, getuid, 0) of
+        true ->
+            integer_to_list(os:getuid());
+        false ->
+            %% OTP < 26 or musl build without getuid BIF
+            string:trim(os:cmd("id -u"))
+    end.
+
 %% @doc one_for_one, intensity 5/60s.
 %% Keeping infra processes separate from conn_sup so a single connection
 %% crash never cascades to gateway/keepalive/known_hosts.

data/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NetworkInfraUtility
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: network-infra-utility
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Matt
@@ -84,10 +84,12 @@ email:
 - matthrewchains@gmail.com
 - 18995691365@189.cn
 executables:
+- dns-query
 - geo-api
 - geo-doc
 - geo-get
 - geo-load
+- geo-update
 extensions: []
 extra_rdoc_files: []
 files:
@@ -97,6 +99,7 @@ files:
 - ".ruby-version"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
+- GUIDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -108,6 +111,7 @@ files:
 - bin/geo-doc
 - bin/geo-get
 - bin/geo-load
+- bin/geo-update
 - bin/setup
 - document/ASNum模块功能说明.md
 - document/DNSQuery工具使用方法.md