network-infra-utility 0.6.0 → 0.8.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7104fdb4e0af5c22afd54d3668e4ffc76641fbe81960c8f846140cdfd5e31c7b
-  data.tar.gz: bf059325d90e039e8902e0619593737dee159790a448561c5df2f9c7e3a939df
+  metadata.gz: 47ea2aa6788e6fcf4256ca20f32bb21933d45ac19ba9775d9234b8839413e435
+  data.tar.gz: 1b9393d9081bd78e93e1895e2002695eee940775cba0779a721ab72af8690668
 SHA512:
-  metadata.gz: ff00412f6b6deb87dbf766f7a84022ea2bd57a6f337e437cdb36931e4b67f8d373d4ee0dd6097141f927a4889c96e8a472ff4b793d131e3c3363248b8a321681
-  data.tar.gz: 5e84775da10cd26e0750dbca13dfa8ec5a731db56175192cc96b2d217660078d4c04d1a737d8731415f9a487afd748c1da33fac74fa21771b1aef1122d23c241
+  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

@@ -1,212 +1,201 @@
----
-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） |
+# 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]