network-infra-utility 0.3.0 → 0.6.0

data/document/SSH/350/277/236/346/216/245/345/256/242/346/210/267/347/253/257/344/275/277/347/224/250/346/226/271/346/263/225.md

@@ -0,0 +1,764 @@
+
+# SSH 连接客户端使用方法
+
+> 源码位置：`service/ssh/`（含 `bin/` CLI、`lib/` Ruby 源码、`ext/` 双引擎）
+> CLI 入口：`service/ssh/bin/ssh-client`
+> 加载方式：`require_relative 'service/ssh/lib/network_infra_utility/ssh'`
+
+Ruby + 双引擎架构的 SSH 连接客户端。SSH 协议核心由**可插拔双引擎**提供：默认 **Rust 引擎**（`ssh_core_rs`，基于 russh），可选 **Erlang 引擎**（`ssh_core`，基于 OTP ssh）；Ruby 负责调度、终端渲染、配置与自动化，与引擎通过本地 socket 上的 JSON-RPC 2.0 通信，两端 IPC 协议完全一致，切换引擎无需改动 Ruby 代码。
+
+---
+
+## 一、环境要求与编译
+
+| 组件 | 版本要求 | 说明 |
+|------|---------|------|
+| Ruby | >= 3.0 | 运行 CLI 和 Ruby 端逻辑 |
+| Rust | rustc/cargo（稳定版） | 编译默认 SSH 核心引擎（`ssh_core_rs`） |
+| Erlang/OTP | >= 26 | 编译可选 Erlang 引擎（`ssh_core`） |
+| rebar3 | 任意版本 | 编译 Erlang 引擎 |
+| OpenSSL | 系统自带 | Vault 加密 |
+
+> **说明**：默认引擎为 Rust，仅使用 Rust 即可运行全部功能；Erlang 引擎作为可插拔备选，需要时再安装 Erlang/OTP 与 rebar3。
+
+### 编译
+
+```bash
+# 1. 编译 Rust 核心引擎（默认）
+cd service/ssh/ext/ssh_core_rs
+cargo build --release
+
+# 2. 编译 Erlang 核心引擎（可选备选）
+cd service/ssh/ext/ssh_core
+rebar3 compile
+
+# 3. 验证 Ruby 端
+cd service/ssh
+ruby bin/ssh-client version   # 输出 1.0.0
+ruby bin/ssh-client themes    # 列出全部主题
+```
+
+> 启动脚本 `bin/ssh_core_rs`（Linux/macOS）与 `bin/ssh_core_rs.cmd`（Windows）会在首次启动时自动编译，也可按上述命令预先编译。
+
+---
+
+## 二、命令行用法（CLI）
+
+CLI 入口为 `bin/ssh-client`，基于 Thor 框架，提供 4 个子命令。
+
+### 1. `connect` — 连接服务器
+
+```
+ruby bin/ssh-client connect HOST [options]
+```
+
+连接到指定 SSH 服务器并进入交互终端。连接成功后输入命令回车发送，输入 `exit` 或 `quit` 断开，`Ctrl+C` 退出。
+
+| 选项 | 简写 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--user` | `-u` | String | **必填** | SSH 用户名 |
+| `--port` | `-p` | Integer | 22 | SSH 端口 |
+| `--key` | `-i` | String | — | 私钥文件路径 |
+| `--jump` | `-J` | String | — | 跳板机，格式 `user@host:port`，多个用逗号分隔（**仅 Erlang 引擎支持**，CLI 默认 Rust 引擎下不生效） |
+| `--name` | — | String | — | 会话名称 |
+| `--password` | — | Boolean | false | 使用密码认证（交互式输入，不回显） |
+| `--theme` | — | String | default | 终端配色主题 |
+| `--connect-timeout` | — | Integer | 60 | 连接超时（秒） |
+| `--keepalive-interval` | — | Integer | 30 | 保活心跳间隔（秒）；注意：引擎 `set_interval` 不接受 0 作为禁用值，设 0 时 CLI 会跳过设置并保持默认 30s |
+| `--algorithms` | — | String | — | 自定义算法，格式 `kex=algo1,algo2;cipher=aes256-ctr` |
+
+**示例：**
+
+```bash
+# 基本连接
+ruby bin/ssh-client connect 10.0.0.1 -u admin
+
+# 密钥认证
+ruby bin/ssh-client connect 10.0.0.1 -u admin -i ~/.ssh/id_ed25519
+
+# 密码认证（交互输入，不回显）
+ruby bin/ssh-client connect 10.0.0.1 -u admin --password
+
+# 指定端口、主题、连接超时
+ruby bin/ssh-client connect 10.0.0.1 -u admin -p 2222 --theme dracula --connect-timeout 30
+```
+
+### 2. `batch` — 批量执行命令
+
+```
+ruby bin/ssh-client batch FILE [options]
+```
+
+从 YAML 文件加载多个会话定义，并行（默认）或串行在所有会话上执行同一条命令。
+
+| 选项 | 简写 | 类型 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `--command` | `-c` | String | **必填** | 要执行的命令 |
+| `--serial` | — | Boolean | false | 串行执行（默认并行） |
+
+**会话文件格式（YAML）：**
+
+```yaml
+# 单条会话（Hash）
+host: 10.0.0.1
+user: admin
+port: 22
+key_path: /home/user/.ssh/id_ed25519
+
+# 多条会话（Array）
+- host: 10.0.0.1
+  user: admin
+  key_path: /home/user/.ssh/id_ed25519
+- host: 10.0.0.2
+  user: root
+  password: secret
+- host: 10.0.0.3
+  user: deploy
+  port: 2222
+  key_path: /home/user/.ssh/deploy_key
+```
+
+**示例：**
+
+```bash
+# 并行执行（默认）
+ruby bin/ssh-client batch servers.yml -c "uptime"
+
+# 串行执行
+ruby bin/ssh-client batch servers.yml -c "show version" --serial
+```
+
+### 3. `themes` — 列出配色主题
+
+```
+ruby bin/ssh-client themes
+```
+
+### 4. `version` — 显示版本
+
+```
+ruby bin/ssh-client version
+```
+
+---
+
+## 三、连接参数详解
+
+连接参数（`spec`）是一个 Hash，以下字段被引擎识别：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `host` | String | 是 | 目标主机 IP 或域名 |
+| `user` | String | 是 | SSH 用户名 |
+| `port` | Integer | 否 | SSH 端口，默认 22 |
+| `name` | String | 否 | 会话显示名称 |
+| `key_path` | String | 否 | 私钥文件路径 |
+| `key_dir` | String | 否 | 密钥搜索目录（默认 `.`，即引擎工作目录） |
+| `auth` | Hash | 否 | 认证配置，见下表 |
+| `jumps` | Array | 否 | 跳板机链（仅 Erlang 引擎） |
+| `terminal` | Hash | 否 | 终端配置，如 `{ theme: "dracula" }` |
+| `proxy` | Hash | 否 | 代理配置（仅 Erlang 引擎，SOCKS5 / HTTP CONNECT） |
+| `connect_timeout_ms` | Integer | 否 | 连接超时（毫秒），默认 60000 |
+| `inactivity_timeout_s` | Integer | 否 | 空闲断开时间（秒） |
+| `algorithms` | Hash | 否 | 自定义算法列表，如 `{ kex: [...], cipher: [...] }` |
+
+> **引擎支持差异**：`jumps`（跳板链）与 `proxy`（代理）目前仅 **Erlang 引擎**实现（OTP ssh 原生支持 + 自研 SOCKS5/HTTP CONNECT 握手）；**Rust 引擎暂未实现**，传入会被忽略。若需使用跳板机/代理，请用 `Client.new(backend: :erlang)` 切换后端。
+
+### auth 字段
+
+| 认证类型 | auth 值 | 说明 |
+|---------|---------|------|
+| 密钥认证 | `{ type: "publickey" }` | 私钥路径通过 `key_path` 指定 |
+| 密码认证 | `{ type: "password", password: "..." }` | 密码明文或 Vault 引用 |
+| 键盘交互 | `{ type: "keyboard_interactive", responses: ["..."] }` | 交互式认证 |
+
+密码字段支持 [Vault 引用](#凭据加密vault)，格式为 `~vault:<key>`。连接前由 Ruby 端自动解密替换。
+
+### jumps 字段（仅 Erlang 引擎）
+
+跳板机链，数组形式，连接顺序从前到后：
+
+```ruby
+jumps: [
+  { user: "jump", host: "10.0.0.1", port: 22 },
+  { user: "bastion", host: "192.168.1.1", port: 2222 }
+]
+```
+
+### proxy 字段（仅 Erlang 引擎）
+
+SOCKS5（默认）或 HTTP CONNECT 代理：
+
+```ruby
+proxy: {
+  type: "socks5",        # 或 "http"，默认 "socks5"
+  host: "127.0.0.1",
+  port: 1080,
+  username: "proxy_user",   # 可选
+  password: "proxy_pass"    # 可选
+}
+```
+
+---
+
+## 四、配置文件
+
+所有配置文件默认存放在 `~/.network-infra-utility/` 目录下。
+
+### settings.yml — 全局设置
+
+```yaml
+# 主密码（用于 Vault 加解密，请妥善保管）
+master_password: "your-master-password"
+
+# 日志目录（不设则默认 ~/.network-infra-utility/logs/）
+log_dir: ~/.network-infra-utility/logs
+
+# 配置目录
+config_dir: ~/.network-infra-utility
+
+# 默认终端类型
+default_terminal: xterm-256color
+
+# 默认回滚行数
+default_scrollback: 10000
+
+# 默认心跳间隔（秒）
+default_keepalive_interval: 30
+
+# 默认配色主题
+default_theme: dark
+```
+
+### sessions.yml | 会话列表
+
+会话列表持久化文件，由 `Config::Store` 管理，支持原子写入（先写 `.tmp` 再 rename）。
+
+```yaml
+version: 1
+groups:
+  - id: prod
+    name: 生产环境
+    parent: ~
+    collapsed: false
+sessions:
+  - id: sess_001
+    name: web-server-1
+    group: prod
+    host: 10.0.0.1
+    port: 22
+    user: admin
+    tags: [web, production]
+    auth:
+      type: publickey
+    terminal:
+      theme: dracula
+    macro:
+      enabled: true
+      steps:
+        - action: "enable\n"
+          wait_pattern: "#"
+          delay: 0.5
+          on_fail: continue
+        - action: "terminal monitor\n"
+          wait_pattern: "#"
+          delay: 0.3
+          on_fail: abort
+```
+
+**会话字段定义（Schema v1）：**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `host` | String | 是 | 主机地址 |
+| `user` | String | 是 | 用户名 |
+| `port` | Integer | 否 | 端口 |
+| `name` | String | 否 | 会话名称 |
+| `group` | String | 否 | 所属分组 ID |
+| `tags` | Array | 否 | 标签列表 |
+| `auth` | Hash | 否 | 认证配置 |
+| `terminal` | Hash | 否 | 终端配置 |
+| `jumps` | Array | 否 | 跳板机链 |
+| `port_forwards` | Array | 否 | 端口转发规则 |
+| `macro` | Hash | 否 | 登录宏配置 |
+| `keepalive` | Hash | 否 | 心跳配置 |
+| `auto_reconnect` | Hash | 否 | 自动重连配置 |
+
+### known_hosts.yml | 主机密钥
+
+主机密钥指纹存储。首次连接时提示用户确认，确认后自动保存。
+
+```yaml
+"10.0.0.1:22":
+  :fingerprint: "SHA256:abc123..."
+  :added_at: "2026-01-15T10:30:00+08:00"
+```
+
+**裁决逻辑：**
+
+| 场景 | 行为 |
+|------|------|
+| 首次连接 | 提示用户确认（`y/N`），确认后保存指纹 |
+| 指纹匹配 | 自动通过，无交互 |
+| 指纹变更 | 拒绝连接并告警，需手动删除条目后重连 |
+
+---
+
+## 五、凭据加密（Vault）
+
+Vault 使用 **AES-256-GCM** 加密算法保护敏感凭据（如 SSH 密码）：
+
+| 参数 | 值 |
+|------|-----|
+| 算法 | AES-256-GCM |
+| KDF | PBKDF2-HMAC-SHA256 |
+| 迭代次数 | 100,000 |
+| Salt 长度 | 32 字节（每条独立随机） |
+| Key 长度 | 32 字节 |
+| Nonce 长度 | 12 字节 |
+
+### 加密存储与引用
+
+```ruby
+client = NetworkInfraUtility::SSH::Client.new
+# client.vault 是 Vault 实例
+
+# 存储密码
+client.vault.store("web_server_pass", "MySecret123!")
+
+# 在连接参数中引用
+session = client.connect(
+  host: "10.0.0.1",
+  user: "admin",
+  auth: { type: "password", password: "~vault:web_server_pass" }
+)
+# Vault 会自动将 ~vault:web_server_pass 解密为明文密码
+```
+
+### vault.yml 格式
+
+```yaml
+web_server_pass:
+  :salt: <Base64>
+  :nonce: <Base64>
+  :tag: <Base64>
+  :data: <Base64>
+```
+
+文件权限：Linux 下 `chmod 600`，Windows 下通过 `icacls` 限制为当前用户。
+
+---
+
+## 六、编程 API 使用
+
+### 1. Client — 生命周期管理
+
+`SSH::Client` 是主入口，管理引擎生命周期和子系统协调。默认后端为 **Rust**（`ssh_core_rs`），可指定 `backend: :erlang` 切换到 Erlang 引擎。
+
+```ruby
+client = NetworkInfraUtility::SSH::Client.new                          # 默认 Rust 引擎
+client_erl = NetworkInfraUtility::SSH::Client.new(backend: :erlang)    # 切换 Erlang 引擎
+```
+
+| 方法 | 说明 |
+|------|------|
+| `start_engine` | 启动引擎子进程（按 `backend` 选择 Rust/Erlang），建立 IPC 连接，注册反向 RPC |
+| `connect(spec)` | 发起 SSH 连接，返回 `Session::Session` 对象 |
+| `stop` | 停止引擎，断开所有连接，清理资源 |
+| `started?` | 引擎是否已启动 |
+| `ipc` | `IPC::Router` 实例，用于底层 RPC 调用 |
+| `sessions` | `Session::Manager` 实例，管理所有会话 |
+| `vault` | `Security::Vault` 实例，凭据加密 |
+| `host_key` | `Security::HostKey` 实例，主机密钥管理 |
+| `settings` | `Config::Settings` 实例，全局配置 |
+| `backend` | 当前引擎后端（`:rust` 或 `:erlang`） |
+| `on_engine_exit(&block)` | 设置引擎异常退出回调（`:crashed` / `:disconnected`） |
+
+**基本用法：**
+
+```ruby
+require_relative "service/ssh/lib/network_infra_utility/ssh"
+
+client = NetworkInfraUtility::SSH::Client.new
+client.start_engine
+
+begin
+  # 终端主题通过 spec[:terminal][:theme] 传递
+  session = client.connect(
+    host: "10.0.0.1", user: "admin",
+    key_path: "~/.ssh/id_ed25519",
+    terminal: { theme: "dracula" }
+  )
+  terminal = session.open_terminal
+
+  terminal.puts("show version")
+  # ... 读取终端输出 ...
+
+  session.disconnect
+ensure
+  client.stop
+end
+```
+
+### 2. Session — 会话操作
+
+`SSH::Session::Session` 封装单个 SSH 会话。
+
+| 方法 | 说明 |
+|------|------|
+| `open_terminal(term_type:, cols:, rows:)` | 打开终端通道，返回 `Terminal::Emulator` |
+| `close_terminal` | 关闭终端通道 |
+| `add_port_forward(type, local_port, remote_host, remote_port)` | 添加端口转发，返回 `rule_id` |
+| `remove_port_forward(rule_id)` | 移除端口转发规则 |
+| `disconnect` | 断开 SSH 连接 |
+| `connected?` | 是否已连接 |
+| `on_closed(reason)` | 连接被远端关闭时的回调 |
+
+**属性：** `session_id`, `conn_id`, `spec`, `name`, `host`, `port`, `user`, `fingerprint`, `terminal`, `file_manager`, `port_forwards`, `tags`, `group`, `status`
+
+**端口转发示例：**
+
+```ruby
+session = client.connect(host: "10.0.0.1", user: "admin", key_path: "~/.ssh/id_ed25519")
+
+# 本地端口转发：将本地 8080 转发到远程 80
+rule_id = session.add_port_forward(:local, 8080, "127.0.0.1", 80)
+
+# ... 使用本地 8080 端口 ...
+
+# 移除转发
+session.remove_port_forward(rule_id)
+```
+
+### 3. Terminal::Emulator — 终端交互
+
+`SSH::Terminal::Emulator` 提供终端模拟和数据收发。
+
+| 方法 | 说明 |
+|------|------|
+| `send(data)` | 发送原始数据到 SSH 通道 |
+| `puts(text)` | 发送一行（自动追加 `\r`） |
+| `feed(data)` | 输入从 SSH 收到的原始字节（内部解析 ANSI 转义） |
+| `resize(cols, rows)` | 变更窗口大小 |
+| `theme=` | 设置配色主题（名称） |
+| `search(pattern)` | 搜索回滚缓冲区内容 |
+| `export(path)` | 导出回滚缓冲区为文本 |
+| `start_logging(path, max_size:, rotate:)` | 启动会话日志轮转 |
+| `stop_logging` | 停止日志记录 |
+
+**属性：** `conn_id`, `channel_id`, `screen`, `buffer`, `theme`, `logger`
+
+**会话日志示例：**
+
+```ruby
+terminal = session.open_terminal
+terminal.start_logging("session_20260115.log", max_size: 100 * 1024 * 1024, rotate: 10)
+
+# ... 交互过程中自动记录 ...
+# 文件达到 max_size 时自动轮转，保留最近 rotate 个文件
+
+terminal.stop_logging
+```
+
+### 4. Automation::MacroEngine — 登录宏
+
+连接后自动执行预设命令序列，支持等待匹配和失败处理。最多 50 步。
+
+```ruby
+session = client.connect(host: "10.0.0.1", user: "admin", key_path: "~/.ssh/id_ed25519")
+terminal = session.open_terminal
+
+macro = NetworkInfraUtility::SSH::Automation::MacroEngine.new(session)
+
+# 添加步骤
+macro.add_step(action: "enable\n", wait_pattern: "Password:", delay: 0.5)
+macro.add_step(action: "admin123\n", wait_pattern: "#", on_fail: :abort)
+macro.add_step(action: "terminal monitor\n", wait_pattern: "#", delay: 0.3)
+
+# 设置失败时的交互回调（on_fail: :ask 时触发）
+macro.on_ask do |step, index|
+  puts "Step #{index} timeout: #{step.action}"
+  puts "Continue? (y/n)"
+  STDIN.gets.chomp =~ /^y/i ? :continue : :abort
+end
+
+# 执行宏
+result = macro.run do |step, index, total|
+  puts "[#{index}/#{total}] #{step.action.strip}"
+end
+# result => :completed 或 :aborted
+```
+
+**Step 参数：**
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `action` | String | — | 要发送的命令 |
+| `wait_pattern` | String/Regexp/nil | nil | 等待匹配的输出，nil 不等待 |
+| `delay` | Float | 0 | 发送前延迟（秒） |
+| `on_fail` | Symbol | :continue | 超时行为：`:continue` / `:abort` / `:ask` |
+
+### 5. Security::HostKey — 主机密钥管理
+
+```ruby
+host_key = client.host_key
+
+# 手动添加信任条目
+host_key.add("10.0.0.1", 22, "SHA256:abc123...")
+
+# 查询
+entry = host_key.get("10.0.0.1", 22)
+# => { fingerprint: "SHA256:abc123...", added_at: "2026-01-15T..." }
+
+# 删除
+host_key.remove("10.0.0.1", 22)
+
+# 列出全部
+host_key.list.each do |entry|
+  puts "#{entry[:host]}:#{entry[:port]} - #{entry[:fingerprint]}"
+end
+```
+
+**自定义交互回调：**
+
+```ruby
+host_key.on_prompt do |host, port, fingerprint|
+  puts "首次连接 #{host}:#{port}"
+  puts "指纹: #{fingerprint}"
+  print "信任? (y/N) "
+  STDIN.gets.chomp =~ /^y/i ? :accept : :reject
+end
+
+host_key.on_key_changed do |host, port, old_fp, new_fp|
+  warn "警告: #{host}:#{port} 主机密钥变更!"
+  warn "  旧: #{old_fp}"
+  warn "  新: #{new_fp}"
+end
+```
+
+---
+
+## 七、终端配色主题
+
+内置 11 套配色方案：
+
+| 主题名 | 风格 | 背景色 |
+|--------|------|--------|
+| `default` | VS Code Dark | #1e1e1e |
+| `solarized-dark` | Solarized Dark | #002b36 |
+| `solarized-light` | Solarized Light | #fdf6e3 |
+| `dracula` | Dracula | #282a36 |
+| `monokai` | Monokai | #272822 |
+| `nord` | Nord | #2e3440 |
+| `gruvbox-dark` | Gruvbox Dark | #282828 |
+| `one-dark` | One Dark | #282c34 |
+| `tokyo-night` | Tokyo Night | #1a1b26 |
+| `catppuccin-mocha` | Catppuccin Mocha | #1e1e2e |
+| `github-dark` | GitHub Dark | #0d1117 |
+
+每个主题包含：背景色 `bg`、前景色 `fg`、光标色 `cursor`、16 色调色板 `palette`。
+
+### 自定义主题
+
+在 `~/.network-infra-utility/themes/<name>.yml` 创建自定义主题：
+
+```yaml
+bg: "#1a1b26"
+fg: "#a9b1d6"
+cursor: "#c0caf5"
+palette:
+  - "#15161e"  # 0  黑
+  - "#f7768e"  # 1  红
+  - "#9ece6a"  # 2  绿
+  - "#e0af68"  # 3  黄
+  - "#7aa2f7"  # 4  蓝
+  - "#bb9af7"  # 5  洋红
+  - "#7dcfff"  # 6  青
+  - "#a9b1d6"  # 7  白
+  - "#414868"  # 8  亮黑
+  - "#f7768e"  # 9  亮红
+  - "#9ece6a"  # 10 亮绿
+  - "#e0af68"  # 11 亮黄
+  - "#7aa2f7"  # 12 亮蓝
+  - "#bb9af7"  # 13 亮洋红
+  - "#7dcfff"  # 14 亮青
+  - "#c0caf5"  # 15 亮白
+```
+
+---
+
+## 八、RPC 方法列表
+
+Ruby 端通过 `IPC::Router` 向引擎发起 JSON-RPC 2.0 请求。Rust 与 Erlang 引擎实现同一套协议，方法列表完全一致。以下是全部已注册的 RPC 方法：
+
+### 连接管理
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `conn.connect` | 连接 spec（host, user, port, auth, jumps 等） | `{ conn_id, fingerprint }` | 发起 SSH 连接 |
+| `conn.disconnect` | `{ id }` | `{ ok: true }` | 断开指定连接 |
+| `conn.list` | `{}` | 连接列表 | 列出所有活动连接 |
+| `conn.reconnect` | `{ id }` | — | 重连指定连接 |
+
+### 通道管理
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `channel.open` | `{ conn_id, type, term, cols, rows }` | `{ channel_id }` | 打开通道（shell/exec） |
+| `channel.send` | `{ id, data }` | — | 发送数据（Base64 编码） |
+| `channel.close` | `{ id }` | — | 关闭通道 |
+| `channel.window_change` | `{ id, cols, rows }` | — | 变更窗口大小 |
+
+### SFTP 文件传输
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `sftp.open` | `{ conn_id }` | `{ sftp_id }` | 打开 SFTP 会话 |
+| `sftp.list_dir` | `{ sftp_id, path }` | 目录列表 | 列出远程目录 |
+| `sftp.download` | `{ sftp_id, remote, local }` | — | 下载文件 |
+| `sftp.upload` | `{ sftp_id, local, remote }` | — | 上传文件 |
+| `sftp.mkdir` | `{ sftp_id, path }` | — | 创建远程目录 |
+| `sftp.remove` | `{ sftp_id, path }` | — | 删除远程文件 |
+| `sftp.stat` | `{ sftp_id, path }` | 文件信息 | 查询文件属性 |
+
+### 端口转发
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `portfwd.add` | `{ conn_id, type, local_port, remote_host, remote_port }` | `{ rule_id }` | 添加转发规则 |
+| `portfwd.remove` | `{ conn_id, rule_id }` | — | 移除转发规则 |
+| `portfwd.list` | `{ conn_id }` | 规则列表 | 列出转发规则 |
+
+### 引擎管理
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `engine.ping` | `{}` | `{ ok: true }` | 心跳检测 |
+| `engine.stats` | `{}` | 运行时统计 | 引擎统计信息 |
+| `engine.shutdown` | `{}` | — | 关闭引擎 |
+| `bye` | `{}` | — | 断开 IPC 连接 |
+
+### 保活管理
+
+| 方法 | 参数 | 返回 | 说明 |
+|------|------|------|------|
+| `keepalive.set_interval` | `{ interval_ms }` | — | 设置心跳间隔（毫秒）。引擎无 0=禁用语义，设 0 会导致忙循环，不建议 |
+| `keepalive.get_interval` | `{}` | 当前间隔 | 查询心跳间隔 |
+| `keepalive.get_status` | `{}` | 连接保活状态 | 查询各连接保活状态 |
+
+### 反向 RPC（引擎 → Ruby）
+
+| 方法 | 触发时机 | 说明 |
+|------|---------|------|
+| `hostkey.resolve` | 引擎连接前校验主机密钥 | Ruby 返回 `accept` / `reject` / `once` |
+
+### 推送事件（引擎 → Ruby，notification）
+
+| 方法 | 说明 |
+|------|------|
+| `channel.data` | 通道收到远端数据 |
+| `channel.eof` | 通道收到 EOF |
+| `channel.extended_data` | 通道收到扩展数据（如 stderr） |
+| `conn.ready` | 连接已就绪 |
+| `conn.failed` | 连接失败 |
+| `conn.closed` | 连接被远端关闭 |
+
+---
+
+## 九、架构说明
+
+### 启动流程
+
+```
+用户执行                          Ruby 进程                         引擎进程（Rust / Erlang）
+───────                        ──────────                       ──────────
+ssh-client connect 10.0.0.1
+  -u admin
+       │                           │                                │
+       ▼                           ▼                                │
+   ┌──────────┐            ┌──────────────┐                        │
+   │ Thor CLI │──调用──▶   │ SSH::Client  │                        │
+   │ 参数解析  │            │  .new        │                        │
+   └──────────┘            └──────┬───────┘                        │
+                                   │                                │
+                          start_engine()                           │
+                                   │                                │
+                          ┌────────┴────────┐                      │
+                          │ Process.spawn   │────拉起子进程───────▶│ ssh_core_rs（Rust）
+                          │ 按 backend 选择 │                      │ 或 ssh_core（Erlang）
+                          │ 引擎二进制       │                      │ 写入端点文件
+                          └────────┬────────┘                      │
+                                   │                                │
+                           读取端点文件，建立 IPC 连接（JSON-RPC）    │
+                                   │◀════════socket════════════════▶│
+                                   │                                │
+                          vault.resolve_credentials(密码解密)       │
+                                   │                                │
+                           IPC call "conn.connect" ───────────────▶│ ssh:connect() / russh
+                                   │                                │ 建立SSH连接
+                                   │◀────返回 conn_id ──────────────│
+                                   │                                │
+                           session.open_terminal                     │
+                           IPC call "channel.open" ───────────────▶│ 打开shell通道
+                                   │◀────返回 channel_id ───────────│
+                                   │                                │
+                           进入交互循环                               │
+                           ┌──────────────┐                         │
+                           │ 用户输入命令  │──IPC──▶ channel.send ──▶│ 发往远程服务器
+                           │ 终端输出显示  │◀─IPC─── channel.data ───│ 收到服务器响应
+                           └──────────────┘                         │
+                                   │                                │
+                           输入 exit → 关闭连接 → 停止引擎进程        │
+```
+
+### 分工
+
+| | Ruby | Rust / Erlang 引擎 |
+|---|---|---|
+| **职责** | 调度、配置、终端渲染、加密 | SSH 协议、连接管理、通道复用 |
+| **进程** | 主进程 | 子进程（引擎与 Ruby 隔离，崩溃不影响 Ruby） |
+| **通信** | 发 JSON-RPC 请求，收推送事件 | 响应请求，推送 channel.data 等事件 |
+
+### 关键模块在运行时的角色
+
+- **`bin/ssh-client`** — 入口，Thor 解析参数后调 `Client`
+- **`SSH::Client`** — 总指挥，按 `backend` 拉起对应引擎、建立 IPC、组合各子系统
+- **`IPC::Router`** — 管所有 JSON-RPC 往来，含订阅/反向 RPC
+- **`Security::Vault`** — 连接前把 `~vault:xxx` 凭据引用解密成明文
+- **`Security::HostKey`** — 引擎连接时反问 Ruby"这主机密钥信不信"（双向 RPC）
+- **`Terminal::Emulator`** — 收到远端字节后输入给 `AnsiParser`，解析 ANSI 转义、驱动 `Screen` 渲染
+
+---
+
+## 十、常见问题（FAQ）
+
+### 1. CLI 的 `-J` 跳板机为什么无效？
+
+CLI 默认使用 Rust 引擎（`DEFAULT_BACKEND = :rust`），而 `jumps` 目前仅 Erlang 引擎实现，且 CLI 层暂未提供 `--backend` 选项。如需跳板机：
+
+```ruby
+client = NetworkInfraUtility::SSH::Client.new(backend: :erlang)
+client.start_engine
+session = client.connect(host: "192.168.1.100", user: "deploy",
+                         jumps: [{ user: "jump", host: "10.0.0.1", port: 22 }])
+```
+
+### 2. 引擎无法启动怎么办？
+
+检查三处：编译产物是否存在（`ext/ssh_core_rs/target/release/`）、启动脚本是否有执行权限、日志目录（`~/.network-infra-utility/logs/engine.err`）报错内容。
+
+### 3. 首次连接提示主机密钥？
+
+这是 `Security::HostKey` 的正常行为，确认指纹后自动保存到 `known_hosts.yml`。若密钥变更会拒绝连接，需手动删除条目。
+
+### 4. 命令行窗口中文乱码？
+
+Windows 下请使用 `chcp 65001` 切换到 UTF-8 代码页后再运行 CLI。
+
+---
+
+## 十一、相关文档
+
+- 设计文档：`service/ssh/design/`（功能需求文档、HLD、LLD）
+- 主 README：`service/ssh/README.md`
+- 引擎源码：`service/ssh/ext/ssh_core_rs/`（Rust）、`service/ssh/ext/ssh_core/`（Erlang）