net-connector 0.11.0 → 0.12.0

data/docs/templates.md

@@ -0,0 +1,53 @@
+# TextFSM 模板组织
+
+模板只描述设备输出的记录结构，不负责连接、命令执行、完整性判断或配置变更。厂商策略负责选择模板并核对记录数量，公共 TextFSM 适配器负责严格 UTF-8 与终端文本边界。
+
+## 目录与命名
+
+`lib/net/connector/templates/` 统一采用 `<平台>/<完整命令名>[_格式变体].textfsm`。命令使用小写，空格、连字符和路径分隔符转为下划线；不使用缩写命令、字段用途名或额外的命令子目录。管道的输出格式选项保留为命令词，纯分页控制 `no-more` 不进入文件名。
+
+例如，`show running-config` 对应 `show_running_config.textfsm`，`display current-configuration` 对应 `display_current_configuration.textfsm`，`/cfg/dump` 对应 `cfg_dump.textfsm`，`show configuration | display set` 对应 `show_configuration_display_set.textfsm`。PAN-OS 配置视图的命令是 `show`，其 set 输出对应 `palo_alto/show.textfsm`。H3C 同一命令的列序变体使用 `_name_first` 和 `_local_first` 后缀。
+
+| 路径 | 输入与用途 |
+| --- | --- |
+| `cisco/show_cdp_neighbors_detail.textfsm` | IOS 的详细 CDP 邻居输出 |
+| `cisco/show_running_config.textfsm` | IOS 运行配置中的接口和描述 |
+| `cisco_ios/show_ip_interface_brief.textfsm` | IOS 的接口、IP 地址与状态摘要 |
+| `cisco_nxos/show_cdp_neighbors_detail.textfsm` | NX-OS CDP 详细邻居块 |
+| `cisco_nxos/show_running_config.textfsm` | NX-OS 运行配置中的接口和描述 |
+| `cisco_nxos/show_ip_interface_brief.textfsm` | NX-OS 多 VRF 接口、IP 及 protocol/link/admin 状态 |
+| `h3c/display_current_configuration.textfsm` | Comware 运行配置中的接口和描述 |
+| `h3c/display_lldp_neighbor_information_list_name_first.textfsm` | 邻居名称位于首列的 LLDP 列表 |
+| `h3c/display_lldp_neighbor_information_list_local_first.textfsm` | 本地接口位于首列的 LLDP 列表 |
+| `hillstone/show_configuration_running.textfsm` | StoneOS 运行配置中的接口和描述 |
+| `hillstone/show_lldp_neighbor_information.textfsm` | StoneOS 的 LLDP 邻居表 |
+| `palo_alto/show.textfsm` | PAN-OS set 格式中的接口和备注 |
+| `palo_alto/show_lldp_neighbors_all.textfsm` | PAN-OS 按接口分块的 LLDP 邻居输出 |
+| `radware/cfg_dump.textfsm` | Alteon 配置转储中的端口名称 |
+| `fortinet/diagnose_lldp_rx_neighbor.textfsm` | FortiOS 改名前后 LLDP 邻居查询的共同输出 |
+| `juniper/show_lldp_neighbors_detail.textfsm` | Junos LLDP 详细邻居块 |
+| `juniper/show_configuration_display_set.textfsm` | Junos 已提交 set 配置中的物理接口描述 |
+
+H3C Wireless 沿用 H3C 模板。H3C 邻居策略检查表头后选择列顺序变体；未知表头直接拒绝，不尝试多个模板后采用碰巧解析出的部分结果。
+
+## 索引与显式选择
+
+根目录的 `index` 保持 TextFSM 的 `Template, Vendor, Command` 格式。Template 使用相对资源根目录的路径，Vendor 是连接器平台标识，Command 是命令匹配规则。一个共享模板可以被多个平台索引项引用。
+
+```ruby
+parser = Net::Connector::TextFSM.new
+rows = parser.call(output, vendor: :cisco_ios, command: "show ip interface brief")
+interfaces = parser.call(config, template: "cisco/show_running_config.textfsm")
+```
+
+命令索引处理固定输出格式。依赖输出表头或视图上下文的模板由对应厂商策略显式选择。调用方也可以提供独立的 `template_dir:`，其索引和路径遵循相同规则。
+
+## 修改与验证
+
+修改模板时保留设备命令和字段语义，使用对应设备输出夹具核对记录。空结果不能代替未知或部分输出；完整性约束仍由拓扑等领域策略维护。`net-connector.gemspec` 递归收录模板，包检查验证每个资源的字节和路径，安装冒烟测试从已安装 gem 执行解析，避免源码目录掩盖资源遗漏。
+
+## NX-OS 输出边界
+
+NX-OS 模板独立放在 `cisco_nxos/`，CDP 按邻居块清理状态并与设备块数量核对，残缺块不能借用下一条记录的字段。接口描述在空行或下一个顶层配置段结束，防止 route-map 等后续段落的描述覆盖接口描述。IP 接口摘要保留 `VRF`、`INTERFACE`、`IP_ADDRESS`、`PROTOCOL`、`LINK_STATUS`、`ADMIN_STATUS` 六个字段；`show ip interface brief` 与带 `vrf` 参数的命令共用此模板。
+
+输出字段参考 [Cisco NX-OS CDP 命令](https://developer.cisco.com/docs/nx-api-cli-reference-for-the-cisco-nexus-7000-series-platform/cdp-commands/)与 [Cisco Nexus IP 接口摘要](https://developer.cisco.com/docs/cisco-nexus-3000-and-9000-series-nx-api-rest-sdk-user-guide-and-api-reference-release-103x/querying-a-summary-of-ip-interface-status-and-configuration-information/)。测试使用脱敏合成输出，不代表真实设备及所有固件均已验证。

data/docs/usage.md

@@ -16,9 +16,14 @@ Use these vendor keys with `Net::Connector.open` or `Net::Connector.build`:
 | `:hillstone` | Hillstone StoneOS | `show configuration running` | `save all` |
 | `:radware` | Radware Alteon | `/cfg/dump` | `/cfg/save` |
 | `:palo_alto` | Palo Alto PAN-OS | Set-format export from configuration view | Unsupported |
+| `:topsec` | Topsec TopOS firewall | `show-running nostop` | Unsupported |
+| `:fortinet` | FortiGate / FortiOS | `show full-configuration` | `execute cfg save` |
+| `:juniper` | Juniper Junos OS | `show configuration \| display set \| no-more` | No implicit candidate commit |
 
 `device.supports?(:tftp_backup)` checks implemented capabilities without connecting. It does not establish firmware compatibility or account permissions. See the [capability matrix](architecture.md#厂商能力) (Chinese).
 
+See [platform details and native Junos FTP/SCP backups](vendors.md). Junos supports `remote_backup(host:, path:, username:, protocol: :scp, password: nil)`; use `supports?(:remote_backup)` to check this separately from TFTP.
+
 ## Sessions and local backups
 
 ```ruby
@@ -62,7 +67,7 @@ Explicit failure raises `:transfer_failed`; missing completion evidence raises `
 
 ```ruby
 interfaces = device.parse_command("show ip interface brief") # Cisco IOS
-rows = device.parse_config(template: "cisco_ios_running_config_interfaces.textfsm")
+rows = device.parse_config(template: "cisco/show_running_config.textfsm")
 
 saved = Net::Connector::Storage::SavedConfig.new(directory: "/var/backups/network")
 rows = saved.parse(host: "192.0.2.10", template: "/path/to/template.textfsm")

data/docs/usage.zh-CN.md

@@ -24,8 +24,13 @@
 | `:palo_alto` | Palo Alto PAN-OS | 候选视图中的 set 格式导出 | 不支持 |
 | `:huawei` | 华为 | `dis cur` | `save force` |
 | `:hillstone` | 山石 StoneOS | `show configuration running` | `save all` |
+| `:topsec` | 天融信 TopOS 防火墙 | `show-running nostop` | 未开放 |
+| `:fortinet` | FortiGate / FortiOS | `show full-configuration` | `execute cfg save` |
+| `:juniper` | Juniper Junos OS | `show configuration \| display set \| no-more` | 不隐式提交候选库 |
 
-厂商标识仅使用上表的规范名称。厂商连接器位于 `Net::Connector` 下，例如 `Net::Connector::H3cWireless::Connector`。
+厂商标识仅使用上表的规范名称。厂商连接器位于 `Net::Connector` 下，例如 `Net::Connector::Vendor::H3cWireless`。
+
+Junos 的 FTP/SCP 原生导出使用 `remote_backup(host:, path:, username:, protocol: :scp, password: nil)`，通过 `supports?(:remote_backup)` 查询。详细能力、视图及命令依据见[新增平台说明](vendors.md)。
 
 ## 登录与本地备份
 
@@ -94,7 +99,7 @@ end
 `parse_config` 采集运行配置，要求显式指定模板。内置 Cisco IOS 模板只提取接口名称和描述，并非完整配置模型：
 
 ```ruby
-interfaces = device.parse_config(template: "cisco_ios_running_config_interfaces.textfsm")
+interfaces = device.parse_config(template: "cisco/show_running_config.textfsm")
 ```
 
 两种方法都返回由模板字段名组成的哈希数组；匹配不到记录时返回 `[]`。模板缺失或无效会抛出 `ParsingError`，设备命令失败则保留原始连接器错误。可用 `template:` 指定外部模板，或用 `template_dir:` 指定含 `index` 的模板目录。每次解析使用独立解析器，批量任务之间不共享状态。已有本地备份也可离线解析：

data/docs/vendors.md

@@ -0,0 +1,50 @@
+# Topsec、Fortinet 与 Juniper
+
+三个平台使用 `Vendor` 注册表、Profile 和现有会话执行器，均支持 SSH/Telnet 命令执行、运行配置采集与本地私有备份。能力声明区分设备系统，不能仅凭品牌把 FortiMail、ScreenOS 等产品映射到 FortiOS 或 Junos。
+
+| 平台键 | 系统与登录视图 | 采集命令 | 保存 | 原生远端备份 | 拓扑读取 |
+| --- | --- | --- | --- | --- | --- |
+| `topsec` | TopOS 防火墙，`TopsecOS#` 或 `#` 管理视图 | `show-running nostop` | 未开放 | 使用本地采集备份 | 未开放 |
+| `fortinet` | FortiGate/FortiOS，当前账号授权的根或 VDOM 视图 | `show full-configuration` | `execute cfg save` | TFTP `execute backup full-config tftp` | LLDP 邻居 |
+| `juniper` | Junos OS，`user@host>` 操作视图 | `show configuration \| display set \| no-more` | 已提交配置已持久化；不隐式提交候选库 | FTP/SCP `show configuration \| save` | LLDP 邻居、物理接口描述 |
+
+这些能力通过合成会话、解析样例和安装检查验证，尚无真实设备验收记录。Topsec 只实现有检索依据的 TopOS 配置读取方言；其他系列需依据其 CLI 手册接入，不能套用 Cisco 的命令。
+
+## Junos 原生 FTP/SCP 导出
+
+```ruby
+Net::Connector.open(:juniper, host: "192.0.2.1", username: "audit",
+                    password: ENV.fetch("NC_DEVICE_PASSWORD")) do |device|
+  receipt = device.remote_backup(host: "backup.example", path: "site/srx.cfg",
+                                 username: "archive", protocol: :scp,
+                                 password: ENV["NC_ARCHIVE_PASSWORD"])
+  puts "#{receipt.protocol}: #{receipt.server}/#{receipt.path}"
+end
+```
+
+`protocol:` 接受 `:scp`（默认）或 `:ftp`。`host:` 是 IPv4 地址或 DNS 名称，`path:` 是无空格、无目录穿越的相对路径；账号单独传入，不接受含密码的 URL。`password:` 可省略以使用设备端已有认证配置，提供时仅在密码挑战中发送一次并脱敏。SCP 服务器主机密钥应事先在设备上建立信任，连接器不自动回答接受主机密钥的询问。FTP 为明文协议。
+
+导出保持在操作视图，`show configuration` 读取当前已提交配置。只有目标 URL 完全一致且写出行数大于零的 `Wrote ... lines of output to '...'` 完成行才生成 `RemoteBackup::Receipt`。回执标记 `verification: :device_reported`，不声称已读取远端文件或计算摘要。无完成证据时抛出 `transfer_unconfirmed`，设备错误保持原异常；上传确认后的收尾失败抛出 `RemoteBackup::CompletionError`，`error.receipt` 保留上传事实，不自动重传。
+
+`device.supports?(:remote_backup)` 可离线检查原生 FTP/SCP 导出能力。目前由 Junos 实现；Fleet/CLI 的本地备份与 TFTP 批次接口保持各自用途。Junos `file copy` 文档列出 FTP、HTTP、HTTPS、SCP，不提供可直接套用的 TFTP 上传接口；`save` 配置模式导出候选内容，`commit` 激活候选库，均不能冒充只读的已提交配置备份。自动接口描述提交暂未开放。
+
+## FortiOS 视图、分页与版本
+
+采集使用当前账号授权的视图；VDOM 管理账号得到所属 VDOM 的配置，不能把它当成整个设备的全局归档。分页用空格应答，不通过 `config system console` 修改设备的持久设置。`execute cfg save` 为显式保存请求；常见自动保存模式下无需另存。
+
+TFTP 导出包括默认值，不接受 `source_file:` 或 `vrf:`。成功必须包含完整的 `Send config file to tftp server OK.` 行；仅出现提示符、命令回显、通用进度或其他传输成功词不算完成。`TftpReceipt` 与已有厂商一致，默认仅为设备报告，服务器文件核验仍由现有 TFTP 核验流程负责。
+
+LLDP 查询先读取 `get system status`，明确解析版本后选择命令：7.6.2 及以前使用 `diagnose lldprx neighbor`，7.6.3 起使用 `diagnose lldp rx neighbor`。无法识别版本时直接报解析错误，不猜测命令。接口行数量与解析记录必须一致，空响应不会被当作零邻居。
+
+Junos LLDP 使用 `show lldp neighbors detail | no-more`，逐个本地接口块核对记录。残缺记录及只有标题的输出会报错；接口描述从已提交的 set 配置中读取，保留 `ge-`、`xe-`、`ae` 等原接口身份。
+
+## 命令依据
+
+- [FireMon TopSec 配置获取接口](https://docs.firemon.com/feature/Content/ADMINISTRATION/DEVICE/Offline_Import_or_Batch_Configs/Additional_Devices.htm)：TopSec 的运行配置使用 `show-running nostop`，启动配置使用 `show nostop`，两者不混用。
+- [Fortinet 配置 TFTP 备份](https://community.fortinet.com/fortigate-3/technical-tip-backup-configuration-files-via-tftp-99896)：FortiGate `execute backup full-config tftp` 参数。
+- [FortiOS execute cfg](https://docs.fortinet.com/document/fortigate/7.6.5/cli-reference/169686240/execute-cfg)：显式保存命令。
+- [Fortinet LLDP 邻居查询](https://community.fortinet.com/fortigate-3/technical-tip-use-lldp-on-fortigate-to-verify-connected-switches-210084)：7.6.3 命令改名及邻居输出字段。
+- [Juniper Junos 升级前备份指南](https://www.juniper.net/documentation/us/en/software/junos/srx-upgrade/srx-upgrade.pdf)：操作视图 `show configuration | save` 导出已提交配置。
+- [Juniper save 配置模式语义](https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/statement/save-cli-config.html)：配置模式的层级导出与远端 SCP。
+- [Juniper file copy 协议](https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/file-copy.html)：支持的远端文件传输 URL。
+- [Juniper LLDP 邻居字段](https://www.juniper.net/documentation/us/en/software/junos/cli-reference/topics/ref/command/show-lldp-neighbors.html)：接口、机箱、端口和系统名字段，`detail` 选项要求 Junos 19.1R2 或以上。

data/lib/net/connector/concurrency/observer.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Concurrency
+      # 后台观察线程属于调用作用域；停止、等待和异常交付不能盖掉前台原故障。
+      module Observer
+        # task 自行等待停止信号，stop 只负责唤醒；正常前台也必须观察后台失败。
+        def self.run(task:, stop:)
+          unless task.respond_to?(:call) && stop.respond_to?(:call) && block_given?
+            raise ArgumentError, "background task requires task, stop and a foreground block"
+          end
+
+          thread = value = failure = nil
+          completion = Queue.new
+          begin
+            # 创建与登记之间不交付异步中断；子线程恢复即时交付，捕获后同步传回所有者。
+            Thread.handle_interrupt(Exception => :never) do
+              thread = Thread.new { observe(task, completion) }
+            end
+            value = yield
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 收尾后向所有者重新抛出原故障，包括中断。
+            failure = error
+          ensure
+            begin
+              # 二次中断不能跳过 join；恢复交付时也保留已经发生的前台故障。
+              Thread.handle_interrupt(Exception => :never) do
+                cleanup_error = finish(thread, stop) if thread
+                failure ||= cleanup_error
+              end
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 保留前台故障，观察延迟到达的取消。
+              failure ||= error
+            end
+            # break 和非局部 return 也会展开作用域；异常交付必须在 ensure 内，不能绕过。
+            failure ||= completion.pop unless completion.empty?
+            raise failure, cause: failure.cause if failure
+          end
+          value
+        end
+
+        def self.observe(task, completion)
+          failure = nil
+          Thread.handle_interrupt(Exception => :immediate) { task.call }
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 不让 global abort_on_exception 将子线程故障传播到无关主线程。
+          failure = error
+        ensure
+          completion << failure
+        end
+        private_class_method :observe
+
+        def self.finish(thread, stop)
+          failure = nil
+          begin
+            stop.call
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 唤醒失败时仍必须终止并回收自有线程。
+            failure = error
+            thread.kill
+          ensure
+            begin
+              thread.join
+            rescue Exception => error # rubocop:disable Lint/RescueException -- 等待失败也不能覆盖先前故障。
+              failure ||= error
+            end
+          end
+          failure
+        end
+        private_class_method :finish
+      end
+    end
+  end
+end

data/lib/net/connector/concurrency/pool.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    module Concurrency
+      # 仅管理有限并发和线程所有权；业务层负责将普通任务故障转换为领域结果。
+      class Pool
+        DEFAULT_CONCURRENCY = 4
+        MAX_CONCURRENCY = 50
+
+        def self.validate_concurrency!(concurrency)
+          unless concurrency.is_a?(Integer) && (1..MAX_CONCURRENCY).cover?(concurrency)
+            raise ArgumentError, "concurrency must be an Integer in 1..#{MAX_CONCURRENCY}"
+          end
+
+          concurrency
+        end
+
+        # 环境只提供默认并发数；显式构造参数优先，非法值不创建线程。
+        def self.environment_concurrency(env: ENV)
+          value = env.fetch("NC_CONCURRENCY", DEFAULT_CONCURRENCY.to_s)
+          unless value.is_a?(String) && value.match?(/\A[0-9]+\z/)
+            raise ArgumentError, "NC_CONCURRENCY must be a positive integer"
+          end
+
+          validate_concurrency!(Integer(value, 10))
+        end
+
+        def initialize(concurrency: self.class.environment_concurrency)
+          @concurrency = self.class.validate_concurrency!(concurrency)
+        end
+
+        # 保序返回块的值；任何未处理异常均在调用线程抛出，停止并回收本次所有线程。
+        # 只复制任务数组，任务内容仍由业务层在下发前校验和固定，不自动重放块。
+        def map(items)
+          raise ArgumentError, "items must be an Array" unless items.is_a?(Array)
+          raise ArgumentError, "map requires a block" unless block_given?
+
+          items = items.dup
+          queue = Queue.new
+          items.each_with_index { |item, index| queue << [index, item] }
+          count = [items.size, @concurrency].min
+          count.times { queue << nil }
+          gate = Queue.new
+          finished = Queue.new
+          results = Array.new(items.size)
+          threads = []
+          completed = false
+          primary_failure = nil
+          begin
+            count.times do
+              # 仅延迟线程创建到登记的异步中断，避免尚未登记的工作线程失去所有者。
+              Thread.handle_interrupt(Exception => :never) do
+                threads << Thread.new do
+                  failure = nil
+                  exhausted = false
+                  begin
+                    # 全部线程成功建立后才允许设备操作，创建失败不能留下已发送的变更。
+                    Thread.handle_interrupt(Exception => :immediate) do
+                      gate.pop
+                      while (task = queue.pop)
+                        index, item = task
+                        results[index] = yield item
+                      end
+                      exhausted = true
+                    end
+                  rescue Exception => error # rubocop:disable Lint/RescueException -- 将中断同步交给调用线程，避免全局 abort_on_exception 波及其他线程。
+                    failure = error
+                  ensure
+                    # Thread.exit/kill 不经过 rescue；不能把尚未完成的任务伪装成合法 nil 结果。
+                    failure ||= RuntimeError.new("execution worker stopped before completing its tasks") unless exhausted
+                    finished << [Thread.current, failure]
+                  end
+                end
+              end
+            end
+            count.times { gate << true }
+            count.times do
+              thread, failure = finished.pop
+              thread.join
+              raise failure, cause: failure.cause if failure
+            end
+            completed = true
+          rescue Exception => error # rubocop:disable Lint/RescueException -- 记录取消或原任务故障，收尾中再次取消不能覆盖它。
+            primary_failure = error
+            raise
+          ensure
+            stop_threads(threads, primary_failure) unless completed
+          end
+          results
+        end
+
+        private
+
+        # kill 运行任务自身的 ensure；次级关闭故障不能盖掉已观察到的原始异常。
+        def stop_threads(threads, primary_failure)
+          # 仅回收期间延迟异步取消；交付二次中断之前必须 kill 并 join 全部拥有线程。
+          Thread.handle_interrupt(Exception => :never) do
+            threads.each(&:kill)
+            threads.each do |thread|
+              begin
+                thread.join
+              rescue Exception # rubocop:disable Lint/RescueException -- 等待全部拥有线程收尾，保留调用方原始故障或中断。
+                nil
+              end
+            end
+          end
+        rescue Exception => error # rubocop:disable Lint/RescueException -- 恢复交付时保留原故障，二次取消不改变批次失败原因。
+          # 二次取消可能已以原故障为 cause；不能反向关联形成异常原因环。
+          error = primary_failure || error
+          raise error, cause: error.cause
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/base.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
 require "forwardable"
-require_relative "../device_session"
+require_relative "scope"
 require_relative "../engine/core"
 require_relative "profile"
 require_relative "running_config"
 require_relative "save_config"
 require_relative "local_backup"
+require_relative "remote_backup"
 require_relative "tftp"
 require_relative "topology"
 require_relative "../textfsm"
@@ -19,6 +20,7 @@ module Net
       include RunningConfig::Capability
       include SaveConfig
       include LocalBackup::Capability
+      include RemoteBackup::Capability
       include Tftp::Capability
       include Topology::Capability
       include TextFSM::Capability
@@ -63,7 +65,7 @@ module Net
       def self.open(**)
         raise ArgumentError, "open requires a block" unless block_given?
 
-        value, failure = DeviceSession.call(factory: -> { new(**) }) do |device|
+        value, failure = Net::Connector::Device::Scope.call(factory: -> { new(**) }) do |device|
           device.connect
           yield device
         end
@@ -100,6 +102,8 @@ module Net
           !config_commands.empty?
         when :save_config
           !save_commands.empty?
+        when :remote_backup
+          !profile.remote_backup_strategy.nil?
         when :tftp_backup
           !profile.tftp_strategy.nil?
         when :neighbors, :interface_descriptions, :interface_description_changes

data/lib/net/connector/device/local_backup.rb

@@ -7,11 +7,15 @@ require_relative "../storage"
 module Net
   module Connector
     Backup = Data.define(:path, :bytes, :sha256, :collected_at, :change, :previous_sha256) do
-      # 保存配置备份的路径、摘要和变更状态。
+      # 完成回执拥有自己的元数据；调用方和结果回调不能原地改写已保存文件的证据。
       def initialize(path:, bytes:, sha256:, collected_at:, change: nil, previous_sha256: nil)
-        super
+        super(path: path&.dup&.freeze, bytes: bytes, sha256: sha256&.dup&.freeze,
+              collected_at: collected_at&.dup&.freeze, change: change, previous_sha256: previous_sha256&.dup&.freeze)
       end
 
+      # Ruby 3.2 的原生 Data#with 不调用初始化；更新也须重新复制并冻结元数据。
+      def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
       # 判断本次采集是否产生新的配置内容。
       def changed? = [:created, :changed].include?(change)
     end
@@ -21,14 +25,14 @@ module Net
       attr_reader :backup, :receipt, :underlying_type
 
       def initialize(backup:, write_error:, host: nil)
-        unless backup.instance_of?(Backup) && Storage::PrivateFile.receipt_error?(write_error) &&
+        unless backup.instance_of?(Backup) && Storage::AtomicFile.receipt_error?(write_error) &&
                write_error.receipt.committed? && write_error.receipt.path == backup.path
           raise ArgumentError, "backup persistence error requires a matching committed backup receipt"
         end
 
         @backup, @receipt = backup, write_error.receipt
         @underlying_type = write_error.underlying_type
-        code = if write_error.instance_of?(Storage::PrivateFile::DirectorySyncUnsupported)
+        code = if write_error.instance_of?(Storage::AtomicFile::DirectorySyncUnsupported)
                  :backup_durability_unsupported
                elsif receipt.durable?
                  :backup_finalize_failed
@@ -47,7 +51,7 @@ module Net
         raise ArgumentError, "backup must be a completed Backup" unless backup.instance_of?(Backup)
 
         @backup = backup
-        @underlying_type = ErrorMetadata.type(underlying.class.name) || "StandardError"
+        @underlying_type = Error::Metadata.type(underlying.class.name) || "StandardError"
         super("backup completed; path lock finalization failed", code: :backup_finalize_failed, host: host, phase: :backup)
       end
     end
@@ -83,7 +87,7 @@ module Net
       def collect_and_write(destination)
         contents = @device.running_config.value!
         digest = Digest::SHA256.hexdigest(contents)
-        previous = Storage::SafeFile.fingerprint(destination, missing: true, replace_symlink: true)
+        previous = Storage::FileReader.fingerprint(destination, missing: true, replace_symlink: true)
         previous_digest = previous&.sha256
         change = if previous_digest.nil?
                    :created
@@ -97,7 +101,7 @@ module Net
                             sha256: digest, collected_at: Time.now.utc, change: change,
                             previous_sha256: previous_digest)
         # 内容未变也须核对权限与目录项身份；只在两者仍有效时保留原文件和 mtime。
-        if change != :unchanged || previous.mode != 0o600 || !Storage::SafeFile.same_entry?(destination, previous)
+        if change != :unchanged || previous.mode != 0o600 || !Storage::FileReader.same_entry?(destination, previous)
           write_backup(backup, contents)
         end
         backup
@@ -105,9 +109,9 @@ module Net
 
       # 替换后失败仍交付已提交的备份回执，不能让调用方误判为没有产物。
       def write_backup(backup, contents)
-        Storage::PrivateFile.write(backup.path, contents)
-      rescue Storage::PrivateFile::WriteError => error
-        raise unless Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
+        Storage::AtomicFile.write(backup.path, contents)
+      rescue Storage::AtomicFile::WriteError => error
+        raise unless Storage::AtomicFile.receipt_error?(error) && error.receipt.committed?
 
         host = @device.host if @device.respond_to?(:host)
         raise BackupPersistenceError.new(backup: backup, write_error: error, host: host), cause: nil

data/lib/net/connector/device/profile/builder.rb

@@ -85,6 +85,12 @@ module Net
           self
         end
 
+        # 指定设备原生 FTP/SCP 导出策略；nil 明确关闭继承能力。
+        def remote_backup_strategy(klass)
+          @values[:remote_backup_strategy] = klass
+          self
+        end
+
         # 指定运行配置采集策略，覆盖继承的厂商规则。
         def running_config_strategy(klass)
           @values[:running_config_strategy] = klass

data/lib/net/connector/device/profile.rb

@@ -21,7 +21,7 @@ module Net
                   :privilege_prompt, :pager_pattern, :pager_response,
                   :authentication_error_patterns, :command_error_patterns,
                   :login_interactions, :confirmation_interactions, :legacy_ssh_arguments,
-                  :privilege_command, :command_timeout, :terminal_size, :tftp_strategy, :topology_strategy, :running_config_strategy
+                  :privilege_command, :command_timeout, :terminal_size, :tftp_strategy, :topology_strategy, :running_config_strategy, :remote_backup_strategy
 
       # 使用默认的公共规则创建空设备档案；登录和命令提示符仍由厂商声明。
       def self.default
@@ -46,7 +46,7 @@ module Net
                      authentication_error_patterns: DEFAULT_AUTHENTICATION_ERROR_PATTERNS,
                      command_error_patterns: [], login_interactions: [], confirmation_interactions: [],
                      legacy_ssh_arguments: DEFAULT_LEGACY_SSH_ARGUMENTS, privilege_command: nil,
-                     command_timeout: 25, terminal_size: nil, tftp_strategy: nil, topology_strategy: nil, running_config_strategy: nil)
+                     command_timeout: 25, terminal_size: nil, tftp_strategy: nil, topology_strategy: nil, running_config_strategy: nil, remote_backup_strategy: nil)
         @config_commands = command_list(config_commands, :config_commands, allow_nil: true)
         @save_commands = command_list(save_commands, :save_commands)
         @login_prompt = pattern(login_prompt, :login_prompt, allow_nil: true)
@@ -64,6 +64,7 @@ module Net
         @privilege_command = optional_text(privilege_command, :privilege_command)
         @command_timeout = duration(command_timeout, :command_timeout)
         @terminal_size = validate_terminal_size!(terminal_size)
+        @remote_backup_strategy = strategy_class(remote_backup_strategy, :remote_backup_strategy, %i[script completed?])
         @running_config_strategy = strategy_class(running_config_strategy, :running_config_strategy,
                                                   %i[clean result_step prompt_text validate_response!])
         @tftp_strategy = strategy_class(tftp_strategy, :tftp_strategy,
@@ -105,6 +106,7 @@ module Net
           terminal_size: terminal_size,
           tftp_strategy: tftp_strategy,
           topology_strategy: topology_strategy,
+          remote_backup_strategy: remote_backup_strategy,
           running_config_strategy: running_config_strategy
         }
       end

data/lib/net/connector/device/remote_backup/receipt.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "target"
+require_relative "../../engine/errors"
+
+module Net
+  module Connector
+    class RemoteBackup
+      # 不保存认证秘密；此回执只说明设备报告写出，未读取远端文件。
+      Receipt = Data.define(:server, :path, :protocol, :username, :completed_at, :configuration_kind, :verification) do
+        def initialize(server:, path:, protocol:, username:, completed_at:, configuration_kind: :running, verification: :device_reported)
+          Target.new(host: server, path: path, protocol: protocol, username: username)
+          unless completed_at.is_a?(Time) && configuration_kind == :running && verification == :device_reported
+            raise ArgumentError, "invalid remote backup receipt"
+          end
+          super(server: server.dup.freeze, path: path.dup.freeze, protocol: protocol, username: username.dup.freeze,
+                completed_at: completed_at.dup.freeze, configuration_kind: configuration_kind, verification: verification)
+        end
+      end
+
+      # 完成后出现收尾错误时保留上传事实，避免调用方盲目重传。
+      class CompletionError < Error
+        attr_reader :receipt, :underlying_type
+
+        def initialize(receipt:, host:, underlying:)
+          raise ArgumentError, "remote backup receipt required" unless receipt.instance_of?(Receipt)
+
+          @receipt = receipt
+          @underlying_type = Error::Metadata.type(underlying.class.name)
+          super("device reported remote backup completion but finalization failed",
+                code: :transfer_finalize_failed, host: host, phase: :remote_backup)
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/device/remote_backup/target.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Net
+  module Connector
+    class RemoteBackup
+      # 目标必须可直接作为一个 CLI 单词使用，不接受 URL 内密码或命令片段。
+      Target = Data.define(:host, :path, :username, :protocol) do
+        def initialize(host:, path:, username:, protocol:)
+          unless %i[ftp scp].include?(protocol)
+            raise ArgumentError, "remote backup protocol must be ftp or scp"
+          end
+          unless username.is_a?(String) && username.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
+            raise ArgumentError, "remote backup username must be a safe account name"
+          end
+          unless host.is_a?(String) && host.bytesize <= 253 && host.match?(/\A[A-Za-z0-9][A-Za-z0-9.-]*\z/) && !host.include?("..")
+            raise ArgumentError, "remote backup host must be an IPv4 address or DNS name"
+          end
+          unless path.is_a?(String) && path.bytesize <= 220 &&
+                 path.match?(/\A[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*\z/) &&
+                 path.split("/").none? { |part| %w[. ..].include?(part) }
+            raise ArgumentError, "remote backup path must be a relative filename without traversal"
+          end
+          super(host: host.dup.freeze, path: path.dup.freeze, username: username.dup.freeze, protocol: protocol)
+        end
+
+        def url
+          "#{protocol}://#{username}@#{host}/#{path}"
+        end
+      end
+      private_constant :Target
+    end
+  end
+end

data/lib/net/connector/device/remote_backup.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../engine/script"
+require_relative "remote_backup/receipt"
+
+module Net
+  module Connector
+    # 设备原生 FTP/SCP 导出；与采集到本机的 LocalBackup 分别保留完成证据。
+    class RemoteBackup
+      module Capability
+        def remote_backup(host:, path:, username:, protocol: :scp, password: nil)
+          RemoteBackup.new(self).call(host: host, path: path, username: username, protocol: protocol, password: password)
+        end
+      end
+
+      def initialize(device) = @device = device
+
+      def call(host:, path:, username:, protocol:, password: nil)
+        receipt = nil
+        implementation = @device.profile.remote_backup_strategy
+        unless implementation
+          raise UnsupportedOperation.new("native FTP/SCP backup is not supported for this vendor",
+                                         host: @device.host, phase: :remote_backup)
+        end
+        target = Target.new(host: host, path: path, username: username, protocol: protocol)
+        if !password.nil? && (!password.is_a?(String) || password.match?(/[\r\n\x00]/))
+          raise ArgumentError, "remote backup password must be a single-line String"
+        end
+        password = password&.dup&.freeze
+        strategy = implementation.new(@device)
+        @device.with_operation(:remote_backup) do
+          result = @device.execute_operation(strategy.script(target, password: password), name: :remote_backup, privilege: false)
+          unless strategy.completed?(target, result)
+            result.value!
+            raise DeviceError.new("device did not confirm remote backup completion", code: :transfer_unconfirmed,
+                                  host: @device.host, phase: :remote_backup)
+          end
+          receipt = Receipt.new(server: target.host, path: target.path, protocol: target.protocol, username: target.username,
+                      completed_at: Time.now.utc)
+          result.value! if result.failure?
+          receipt
+        end
+      rescue StandardError => error
+        raise unless receipt
+        raise if error.instance_of?(CompletionError)
+
+        raise CompletionError.new(receipt: receipt, host: @device.host, underlying: error), cause: nil
+      end
+    end
+  end
+end