net-connector 0.6.0 → 0.7.0

data/lib/net/connector/netdisco/cli.rb

@@ -54,7 +54,10 @@ module Net
           message = Storage::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
           @error.puts "net-connector-backup: #{message}"
           2
-        rescue OptionParser::ParseError, ArgumentError, KeyError, Errno::ENOENT,
+        rescue OptionParser::ParseError
+          @error.puts "net-connector-backup: 参数无效；使用 --help 查看参数"
+          2
+        rescue ArgumentError, KeyError, Errno::ENOENT,
           Psych::Exception, JSON::ParserError, Client::Error => exception
           @error.puts "net-connector-backup: #{exception.message}"
           2
@@ -67,18 +70,7 @@ module Net
 
         # 文件、环境变量、命令行按优先级覆盖，凭据仍只来自环境变量。
         def settings_for(options)
-          defaults = options[:config] ? ConfigFile.load(options[:config]) : {}
-          values = {}
-          values["NETDISCO_SOURCE"] = options[:source] if options[:source]
-          values["NETDISCO_QUERY"] = options[:query] if options[:query]
-          values["NETDISCO_QUERY_PARAMS"] = options[:query_params] if options[:query_params]
-          values["NET_CONNECTOR_BACKUP_DIRECTORY"] = options[:directory] if options[:directory]
-          values["NET_CONNECTOR_CONCURRENCY"] = options[:concurrency].to_s if options[:concurrency]
-          values["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES"] = options[:max_script_output_bytes].to_s if options[:max_script_output_bytes]
-          values["NET_CONNECTOR_INCLUDE_HOSTS"] = options[:host] if options[:host]
-          values["NET_CONNECTOR_SAMPLE_PER_VENDOR"] = options[:limit].to_s if options[:limit]
-          values["NET_CONNECTOR_SAMPLE_PER_VENDOR"] = nil if options[:all]
-          Settings.new(env: @env, defaults: defaults, overrides: values)
+          Options.settings(options, env: @env)
         end
 
         # 导出已有配置不创建清单或设备连接。
@@ -110,7 +102,7 @@ module Net
             fleet.tftp_backup_all(plan: plan, server: settings.tftp_server,
                                   concurrency: settings.concurrency,
                                   vrfs: settings.tftp_vrfs,
-                                  source_files: settings.tftp_source_files, **reporting)
+                                  source_files: settings.tftp_source_files, verification_root: options[:tftp_root] || @env["TFTP_ROOT"], **reporting)
           else
             fleet.backup_all(plan: plan, directory: settings.backup_directory,
                              concurrency: settings.concurrency, **reporting)
@@ -119,10 +111,11 @@ module Net
 
         # 解析命令行参数并处理帮助及版本信息。
         def parse_options
-          options = { config: @env["NET_CONNECTOR_CONFIG"] }
+          options = { environment: {} }
           parser = OptionParser.new do |args|
             args.banner = "用法：net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
-            args.on("--config FILE", "读取不含凭据的 YAML 设置") { |value| options[:config] = value }
+            Options.add_settings(args, options)
+            Options.add_execution(args, options)
             args.on("--source SOURCE", %w[http postgres], "清单来源：http（默认）或 postgres") { |value| options[:source] = value }
             args.on("--query SQL", "PostgreSQL 清单查询，使用 $1、$2 绑定参数") { |value| options[:query] = value }
             args.on("--query-params JSON", "查询参数的 JSON 数组") { |value| options[:query_params] = value }
@@ -131,15 +124,8 @@ module Net
             args.on("--tftp", "由设备发起 TFTP 备份") { options[:tftp] = true }
             args.on("--export IP", "导出已保存的本地配置") { |value| options[:export] = value }
             args.on("--output FILE", "将导出配置写入私有文件") { |value| options[:output] = value }
-            args.on("--directory PATH", "备份和报告目录") { |value| options[:directory] = value }
             args.on("--host IP", "按管理地址选择一台设备") { |value| options[:host] = value }
-            args.on("--concurrency N", Integer, "最大并发设备数") { |value| options[:concurrency] = value }
             args.on("--max-script-output-bytes N", Integer, "每个脚本的累计响应字节上限") { |value| options[:max_script_output_bytes] = value }
-            args.on("--limit-per-vendor N", Integer, "每厂商选择 N 台设备（1 至 5）") do |value|
-              options[:limit] = value
-            end
-            args.on("--all", "选择全部就绪设备") { options[:all] = true }
-            args.on("--success-policy POLICY", %w[strict selected], "成功判定：strict（默认）或 selected") { |value| options[:success_policy] = value.to_sym }
             args.on("-v", "--version", "显示版本") do
               @output.puts Net::Connector::VERSION
               options[:done] = true
@@ -157,9 +143,10 @@ module Net
 
         # 拒绝互斥或缺少依赖的命令行选项。
         def validate_options!(options)
+          raise ArgumentError, "verified policy requires --tftp" if options[:success_policy] == :verified && !options[:tftp]
           Report.validate_policy!(options.fetch(:success_policy, :strict))
           Planner.validate_limit!(options[:limit])
-          Worker.new(concurrency: options[:concurrency]) if options[:concurrency]
+          raise ArgumentError, "--tftp-root requires --tftp" if options[:tftp_root] && !options[:tftp]
           modes = [:show_config, :plan, :export].count { |key| options[key] }
           raise ArgumentError, "--show-config、--plan 和 --export 只能选择一项" if modes > 1
           raise ArgumentError, "--output 需要同时指定 --export" if options[:output] && !options[:export]
@@ -167,8 +154,8 @@ module Net
           if options[:export] && (options[:source] || options[:query] || options[:query_params])
             raise ArgumentError, "--export 不能与清单查询选项同时使用"
           end
-          if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:concurrency] || options[:host] ||
-            options[:success_policy] || options[:max_script_output_bytes])
+          if options[:export] && (options[:tftp] || options[:all] || options[:limit] || options[:environment].key?("NC_CONCURRENCY") || options[:host] ||
+            options[:success_policy] || options[:tftp_root] || options[:max_script_output_bytes])
             raise ArgumentError, "--export 不能与备份选项同时使用"
           end
         end

data/lib/net/connector/netdisco/client.rb

@@ -258,9 +258,9 @@ module Net
             row.is_a?(Hash) && present?(row["ip"]) &&
               FIELDS.drop(1).all? { |field| row[field].nil? || row[field].is_a?(String) }
           end
-          unless valid
-            raise Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
-          end
+          return if valid
+
+          raise Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
         end
 
         def validate_credentials!(username, password, api_key)
@@ -268,9 +268,9 @@ module Net
                  (present?(api_key) && username.nil? && password.nil?)
             raise ArgumentError, "provide either username and password or api_key"
           end
-          if [username, password, api_key].compact.any? { |value| value.match?(/[\r\n\x00]/) }
-            raise ArgumentError, "credentials must be single-line strings"
-          end
+          return unless [username, password, api_key].compact.any? { |value| value.match?(/[\r\n\x00]/) }
+
+          raise ArgumentError, "credentials must be single-line strings"
         end
 
         def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)

data/lib/net/connector/netdisco/config_file.rb

@@ -20,26 +20,27 @@ module Net
                           "max_devices" => ["NETDISCO_MAX_DEVICES", :integer],
                           "inventory_timeout" => ["NETDISCO_INVENTORY_TIMEOUT", :number],
                           "allow_insecure_http" => ["NETDISCO_ALLOW_INSECURE_HTTP", :boolean] },
-          "backup" => { "directory" => ["NET_CONNECTOR_BACKUP_DIRECTORY", :string],
-                        "concurrency" => ["NET_CONNECTOR_CONCURRENCY", :integer],
-                        "limit_per_vendor" => ["NET_CONNECTOR_SAMPLE_PER_VENDOR", :integer] },
-          "inventory" => { "include_hosts" => ["NET_CONNECTOR_INCLUDE_HOSTS", :list],
-                           "exclude_hosts" => ["NET_CONNECTOR_EXCLUDE_HOSTS", :list],
-                           "include_vendors" => ["NET_CONNECTOR_INCLUDE_VENDORS", :list],
-                           "vendor_overrides" => ["NET_CONNECTOR_VENDOR_OVERRIDES", :json],
-                           "host_overrides" => ["NET_CONNECTOR_HOST_OVERRIDES", :json],
-                           "device_rules" => ["NET_CONNECTOR_DEVICE_RULES", :json] },
-          "ssh" => { "protocol" => ["NET_CONNECTOR_PROTOCOL", :string],
-                     "max_script_output_bytes" => ["NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES", :optional_integer],
-                     "known_hosts" => ["NET_CONNECTOR_KNOWN_HOSTS", :string],
-                     "host_key_policy" => ["NET_CONNECTOR_HOST_KEY_POLICY", :string],
-                     "log_directory" => ["NET_CONNECTOR_LOG_DIRECTORY", :string],
-                     "log_level" => ["NET_CONNECTOR_LOG_LEVEL", :string] },
+          "backup" => { "directory" => ["NC_BACKUP_DIRECTORY", :string],
+                        "concurrency" => ["NC_CONCURRENCY", :integer],
+                        "limit_per_vendor" => ["NC_SAMPLE_PER_VENDOR", :integer] },
+          "inventory" => { "include_hosts" => ["NC_INCLUDE_HOSTS", :list],
+                           "exclude_hosts" => ["NC_EXCLUDE_HOSTS", :list],
+                           "include_vendors" => ["NC_INCLUDE_VENDORS", :list],
+                           "vendor_overrides" => ["NC_VENDOR_OVERRIDES", :json],
+                           "host_overrides" => ["NC_HOST_OVERRIDES", :json],
+                           "device_rules" => ["NC_DEVICE_RULES", :json] },
+          "ssh" => { "protocol" => ["NC_PROTOCOL", :string],
+                     "vendor_protocols" => ["NC_VENDOR_PROTOCOLS", :json],
+                     "max_script_output_bytes" => ["NC_MAX_SCRIPT_OUTPUT_BYTES", :optional_integer],
+                     "known_hosts" => ["NC_KNOWN_HOSTS", :string],
+                     "host_key_policy" => ["NC_HOST_KEY_POLICY", :string],
+                     "log_directory" => ["NC_LOG_DIRECTORY", :string],
+                     "log_level" => ["NC_LOG_LEVEL", :string] },
           "tftp" => { "server" => ["TFTP_HOST", :string],
-                      "vrfs" => ["NET_CONNECTOR_TFTP_VRFS", :json],
-                      "h3c_source_file" => ["NET_CONNECTOR_H3C_TFTP_SOURCE_FILE", :string],
-                      "h3c_wireless_source_file" => ["NET_CONNECTOR_H3C_WIRELESS_TFTP_SOURCE_FILE", :string],
-                      "huawei_source_file" => ["NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", :string] }
+                      "vrfs" => ["NC_TFTP_VRFS", :json],
+                      "h3c_source_file" => ["NC_H3C_TFTP_SOURCE_FILE", :string],
+                      "h3c_wireless_source_file" => ["NC_H3C_WIRELESS_TFTP_SOURCE_FILE", :string],
+                      "huawei_source_file" => ["NC_HUAWEI_TFTP_SOURCE_FILE", :string] }
         }.freeze
 
         # 安全读取 YAML 配置并映射到环境变量格式。

data/lib/net/connector/netdisco/connection.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "client"
+
+# 清单连接与设备凭据来源；业务入口负责规划和执行备份。
+module Net
+  module Connector
+    module Netdisco
+      # 将调用方提供的输入解析为清单客户端和设备凭据 resolver。
+      class Connection
+        def self.build(settings, stdin_credentials: false, input: $stdin)
+          unless stdin_credentials
+            return [settings.client, settings.method(:device_credentials_for)]
+          end
+
+          begin
+            values = JSON.parse(input.gets || "")
+          rescue JSON::ParserError
+            raise ArgumentError, "凭据 JSON 无效", cause: nil
+          end
+          keys = %w[netdisco_username netdisco_password device_username device_password]
+          raise ArgumentError, "需要四个非空凭据字符串" unless values.is_a?(Hash) && keys.all? { |key| values[key].is_a?(String) && !values[key].strip.empty? }
+
+          client = settings.client(credentials: {
+            username: values.fetch("netdisco_username"), password: values.fetch("netdisco_password")
+          })
+          credentials = lambda do |device|
+            inherited = device ? settings.device_credentials_for(device) : nil
+            (inherited || {}).merge(username: values.fetch("device_username"),
+                                   password: values.fetch("device_password"))
+          end
+          [client, credentials]
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/netdisco/database_client.rb

@@ -37,7 +37,7 @@ module Net
 
         def initialize(connection_options:, **options)
           @options = self.class.options(**options)
-          @connection_options = validate_connection_options(connection_options)
+          @connection_options = validate_connection_options!(connection_options)
         end
 
         # 每次查询独占连接和游标；只有全部结果验证成功后才把清单交给 Fleet。
@@ -103,7 +103,7 @@ module Net
           end
         end
 
-        def validate_connection_options(options)
+        def validate_connection_options!(options)
           unless options.is_a?(Hash) && (options.keys - CONNECTION_ENV.keys).empty?
             raise ArgumentError, "connection_options must contain supported PostgreSQL connection keys"
           end

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

@@ -44,7 +44,17 @@ module Net
         def ready? = issue.nil?
 
         # 生成不随名称或厂商信息改变的本地文本文件名。
-        def backup_filename = Storage::SavedConfig.filename(host)
+        def backup_filename(style: :ip)
+          address = Storage::SavedConfig.filename(host)
+          return address if style == :ip
+          raise ArgumentError, "filename style must be ip or hostname_ip" unless style == :hostname_ip
+
+          label = name.to_s.encode("UTF-8", invalid: :replace, undef: :replace, replace: "-")
+                      .gsub(/[^\p{L}\p{N}._-]+/, "-").byteslice(0, 160).scrub("")
+                      .gsub(/\A[._-]+|[._-]+\z/, "")
+          label = "unnamed" if label.empty?
+          "#{label}-#{address}"
+        end
 
         # 生成设备 CLI 可用的 ASCII 远端文件名。
         def tftp_filename

data/lib/net/connector/netdisco/fleet.rb

@@ -13,7 +13,7 @@ module Net
 
         # 组装清单客户端、规则、凭据与结果存储。
         def initialize(client: nil, settings: Settings.new, rules: nil, credentials: nil, connector_factory: nil,
-                       result_store: ResultStore::Text.new)
+                       result_store: ResultStore::Json.new)
           @settings = settings
           @client = client
           @rules = rules
@@ -35,46 +35,53 @@ module Net
         end
 
         # 规划 TFTP 配置备份的设备集合。
-        def plan_tftp_backup(limit_per_vendor: 5)
-          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp))
+        def plan_tftp_backup(limit_per_vendor: 5, allow_fixed_name_reuse: false)
+          build_plan(:tftp, limit_per_vendor, @settings.snapshot(mode: :tftp),
+                     allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 先拉取完整清单，再并发采集并保存设备配置。
         def backup_all(directory: DEFAULT_SETTING, concurrency: DEFAULT_SETTING,
                        limit_per_vendor: nil, plan: nil, on_start: nil, on_result: nil, on_change: nil,
-                       success_policy: :strict)
-          reporting = Report.validate_policy!(success_policy)
-          policy = @settings.snapshot(mode: :backup)
-          directory = policy.backup_directory if directory.equal?(DEFAULT_SETTING)
-          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
+                       success_policy: :strict, filename_style: :ip)
+          raise ArgumentError, "filename style must be ip or hostname_ip" unless %i[ip hostname_ip].include?(filename_style)
+
+          Report.validate_policy!(success_policy)
+          raise ArgumentError, "verified policy requires TFTP mode" if success_policy == :verified
+          settings_snapshot = @settings.snapshot(mode: :backup)
+          directory = settings_snapshot.backup_directory if directory.equal?(DEFAULT_SETTING)
+          concurrency = settings_snapshot.concurrency if concurrency.equal?(DEFAULT_SETTING)
           raise ArgumentError, "directory must be a nonempty String" unless directory.is_a?(String) && !directory.empty?
-          Worker.new(concurrency: concurrency)
+          Worker.validate_concurrency!(concurrency)
           Planner.validate_limit!(limit_per_vendor)
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
           validate_callback!(on_change, :on_change)
 
-          plan ||= build_plan(:backup, limit_per_vendor, policy)
+          plan ||= build_plan(:backup, limit_per_vendor, settings_snapshot)
           validate_plan!(plan, :backup)
           callbacks = [on_result]
-          callbacks << ->(item) { on_change.call(item) if item.backup.is_a?(Backup) && item.backup.changed? } if on_change
+          callbacks << ->(outcome) { on_change.call(outcome) if outcome.backup.is_a?(Backup) && outcome.backup.changed? } if on_change
           target_directory = File.expand_path(directory)
           run_batch(:backup, plan, concurrency: concurrency, report_directory: directory,
-                    output_directory: target_directory, policy: policy, reporting: reporting,
+                    output_directory: target_directory, settings_snapshot: settings_snapshot, success_policy: success_policy,
                     on_start: on_start, on_result: callbacks.compact) do |device, log_directory|
-            backup_one(device, target_directory, log_directory, policy)
+            backup_device(device, target_directory, log_directory, settings_snapshot, filename_style: filename_style)
           end
         end
 
         # 让设备主动导出配置，在执行前检查同批目标文件名冲突。
         def tftp_backup_all(server:, source_files: {}, concurrency: DEFAULT_SETTING,
                             limit_per_vendor: 5, vrfs: {}, on_start: nil, on_result: nil, plan: nil,
-                            report_directory: DEFAULT_SETTING, success_policy: :strict)
-          reporting = Report.validate_policy!(success_policy)
-          policy = @settings.snapshot(mode: :tftp)
-          concurrency = policy.concurrency if concurrency.equal?(DEFAULT_SETTING)
-          report_directory = policy.backup_directory if report_directory.equal?(DEFAULT_SETTING)
-          Worker.new(concurrency: concurrency)
+                            report_directory: DEFAULT_SETTING, success_policy: :strict, verification_root: nil,
+                            preserve_history: false)
+          Report.validate_policy!(success_policy)
+          raise ArgumentError, "verified policy requires a local TFTP directory" if success_policy == :verified && !verification_root
+          verification = TftpVerification.new(root: verification_root)
+          settings_snapshot = @settings.snapshot(mode: :tftp)
+          concurrency = settings_snapshot.concurrency if concurrency.equal?(DEFAULT_SETTING)
+          report_directory = settings_snapshot.backup_directory if report_directory.equal?(DEFAULT_SETTING)
+          Worker.validate_concurrency!(concurrency)
           server = TftpTarget.new(host: server, path: "preflight.cfg").host
           raise ArgumentError, "source_files must be a Hash" unless source_files.is_a?(Hash)
           source_files.each_value { |source_file| TftpTarget.validate_source_file!(source_file) }
@@ -84,40 +91,53 @@ module Net
           validate_callback!(on_result, :on_result)
           validate_callback!(on_start, :on_start)
 
-          plan ||= build_plan(:tftp, limit_per_vendor, policy)
+          plan ||= build_plan(:tftp, limit_per_vendor, settings_snapshot,
+                              allow_fixed_name_reuse: preserve_history && !verification_root.nil?)
           validate_plan!(plan, :tftp)
+          if plan.allow_fixed_name_reuse && (!preserve_history || !verification_root)
+            raise ArgumentError, "fixed-name TFTP uploads require local history archival"
+          end
+          archive = TftpArchive.new(directory: report_directory, root: verification_root) if preserve_history
           run_batch(:tftp, plan, concurrency: concurrency, report_directory: report_directory,
-                    policy: policy, reporting: reporting, on_start: on_start, on_result: on_result) do |device, log_directory|
-            tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
+                    settings_snapshot: settings_snapshot, success_policy: success_policy, on_start: on_start, on_result: on_result,
+                    verification: preserve_history ? nil : verification) do |device, log_directory|
+            if archive
+              archive.upload_and_archive(device, started_at: Time.now.utc) do |remote_filename|
+                tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot, path: remote_filename)
+              end
+            else
+              tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot)
+            end
           end
         end
 
         private
 
         # 策略在清单请求之前固定；注入的清单客户端仍由调用方负责其自身生命周期。
-        def inventory(policy)
-          rows = (@client || @settings.client(policy: policy)).devices
+        def inventory(settings_snapshot)
+          rows = (@client || @settings.client(policy: settings_snapshot)).devices
           raise Client::Error, "Netdisco returned an invalid device inventory" unless rows.is_a?(Array)
 
-          rules = @rules || policy.rules
+          rules = @rules || settings_snapshot.rules
           devices = rows.map { |row| Device.from_row(row, rules: rules) }
           duplicates = devices.group_by(&:host).reject { |host, entries| host.nil? || entries.size == 1 }
           devices.map { |device| duplicates.key?(device.host) ? device.with(issue: :duplicate_host) : device }.freeze
         end
 
-        def build_plan(mode, limit, policy)
+        def build_plan(mode, limit, settings_snapshot, allow_fixed_name_reuse: false)
           Planner.validate_limit!(limit)
-          Planner.new(inventory(policy)).call(mode: mode, limit_per_vendor: limit)
+          Planner.new(inventory(settings_snapshot)).call(mode: mode, limit_per_vendor: limit,
+                                               allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 统一组织设备任务、日志目录与报告；Worker 保证单台设备失败不影响其他设备。
-        def run_batch(mode, plan, concurrency:, report_directory:, policy:, reporting:, on_start:, on_result:, output_directory: nil)
+        def run_batch(mode, plan, concurrency:, report_directory:, settings_snapshot:, success_policy:, on_start:, on_result:, output_directory: nil, verification: nil)
           worker = Worker.new(concurrency: concurrency)
           started_at = Time.now.utc
           started = monotonic
           outcomes = plan.outcomes.dup
           FileUtils.mkdir_p(output_directory, mode: 0o700) if output_directory && !plan.ready.empty?
-          log_directory = policy.log_directory
+          log_directory = settings_snapshot.log_directory
           FileUtils.mkdir_p(log_directory, mode: 0o700) if log_directory && !plan.ready.empty?
           callback_errors = worker.run(plan.ready, outcomes: outcomes, on_start: on_start, on_result: on_result,
                                        on_error: ->(device, error) { build_outcome(device, :failed, error: error) }) do |device|
@@ -126,8 +146,9 @@ module Net
           batch = Batch.new(mode: mode, outcomes: outcomes.freeze, started_at: started_at,
                             finished_at: Time.now.utc, callback_errors: callback_errors,
                             report_location: nil, report_error: nil)
-          batch = Report.new(batch, policy: reporting, duration_ms: ((monotonic - started) * 1000).round)
-          save_report(batch, directory: report_directory)
+          report = Report.new(batch, policy: success_policy, duration_ms: ((monotonic - started) * 1000).round, log_directory: log_directory)
+          report = verification.call(report) if verification
+          save_report(report, directory: report_directory)
         end
 
         def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -138,16 +159,16 @@ module Net
         end
 
         # 保存批量报告，记录写入失败而不覆盖设备结果。
-        def save_report(batch, directory:)
-          return batch unless @result_store
+        def save_report(report, directory:)
+          return report unless @result_store
 
-          batch.with(report_location: @result_store.write(batch, directory: directory))
+          report.with(report_location: @result_store.write(report, directory: directory))
         rescue Storage::PrivateFile::WriteError => error
           # 报告也可能已经原子替换；保留已知位置，不将持久性失败误写成完全没有产物。
           location = error.receipt.path if Storage::PrivateFile.receipt_error?(error) && error.receipt.committed?
-          batch.with_report_error(error, location: location)
+          report.with_report_error(error, location: location)
         rescue StandardError => error
-          batch.with_report_error(error)
+          report.with_report_error(error)
         end
 
         # 确认传入计划属于当前备份模式。
@@ -165,30 +186,30 @@ module Net
         end
 
         # 执行单台设备的 TFTP 导出。
-        def tftp_backup_one(device, server, source_files, log_directory, vrfs, policy)
-          run_one(device, log_directory, policy, success_status: :reported_uploaded,
-                  close_error_status: :reported_with_error, backup_class: TftpReceipt) do |connector|
+        def tftp_backup_device(device, server, source_files, log_directory, vrfs, settings_snapshot, path: device.tftp_filename)
+          run_device(device, log_directory, settings_snapshot, success_status: :reported_uploaded,
+                     partial_status: :reported_with_error, backup_class: TftpReceipt) do |connector|
             source_file = source_files.fetch(device.vendor, nil)
-            transfer_settings = { host: server, path: device.tftp_filename, source_file: source_file }
+            transfer_settings = { host: server, path: path, source_file: source_file }
             transfer_settings[:vrf] = vrfs.fetch(device.vendor) if vrfs.key?(device.vendor)
             connector.tftp_backup(**transfer_settings)
           end
         end
 
         # 执行单台设备的本地配置采集。
-        def backup_one(device, directory, log_directory, policy)
-          destination = File.join(directory, device.backup_filename)
+        def backup_device(device, directory, log_directory, settings_snapshot, filename_style: :ip)
+          destination = File.join(directory, device.backup_filename(style: filename_style))
           Storage::BackupLock.synchronize(destination, host: device.host) do |path_lock|
             Storage::SafeFile.open(destination, missing: true) { |_file, _stat| nil }
-            run_one(device, log_directory, policy, success_status: :backed_up,
-                    close_error_status: :saved_with_error, backup_class: Backup) do |connector|
+            run_device(device, log_directory, settings_snapshot, success_status: :backed_up,
+                       partial_status: :saved_with_error, backup_class: Backup) do |connector|
               path_lock.with_delegated_lock { connector.backup(path: destination) }
             end
           end
         end
 
         # 隔离单台设备的凭据、连接、操作和关闭异常。
-        def run_one(device, log_directory, policy, success_status:, close_error_status:, backup_class:)
+        def run_device(device, log_directory, settings_snapshot, success_status:, partial_status:, backup_class:)
           connection_settings = @credentials ? @credentials.call(device) : @settings.device_credentials_for(device)
           return build_outcome(device, :missing_credentials) if connection_settings.nil?
           unless connection_settings.is_a?(Hash) && connection_settings.keys.all?(Symbol) &&
@@ -197,7 +218,7 @@ module Net
             raise ArgumentError, "credential resolver must return settings with username and without host"
           end
 
-          connection_settings = policy.connection_options(device.vendor).merge(connection_settings)
+          connection_settings = settings_snapshot.connection_options(device.vendor).merge(connection_settings)
           log_name = device.host.tr(":", "_")
           if log_directory
             connection_settings = connection_settings.merge(log_file: File.join(log_directory, "#{log_name}.log"))
@@ -206,7 +227,7 @@ module Net
           backup, failure = perform_one(connector, backup_class) { yield connector }
           return build_outcome(device, success_status, backup: backup) unless failure
 
-          build_outcome(device, backup ? close_error_status : :failed, backup: backup, error: failure)
+          build_outcome(device, backup ? partial_status : :failed, backup: backup, error: failure)
         rescue StandardError => error
           build_outcome(device, :failed, error: error)
         end

data/lib/net/connector/netdisco/inventory_budget.rb

@@ -23,21 +23,21 @@ module Net
         # 在追加正文前计数；不能靠 Content-Length 或 JSON 解析后的大小限制内存。
         def consume_bytes(size, response_bytes:)
           remaining
-          check_limit!(:max_response_bytes, response_bytes + size)
-          check_limit!(:max_inventory_bytes, @bytes + size)
+          validate_limit!(:max_response_bytes, response_bytes + size)
+          validate_limit!(:max_inventory_bytes, @bytes + size)
           @bytes += size
         end
 
         # 去重前的记录同样占用清单内存；兼容查询也使用这个累计计数。
         def consume_devices(size)
           remaining
-          check_limit!(:max_devices, @devices + size)
+          validate_limit!(:max_devices, @devices + size)
           @devices += size
         end
 
         private
 
-        def check_limit!(name, value)
+        def validate_limit!(name, value)
           return if value <= @options.fetch(name)
 
           raise Client::Error.new("Netdisco inventory exceeded #{name}", code: name), cause: nil

data/lib/net/connector/netdisco/plan.rb

@@ -4,15 +4,18 @@ module Net
   module Connector
     module Netdisco
       # 固定一份清单上的选择结果与跳过原因，供预览和执行复用。
-      Plan = Data.define(:mode, :inventory, :ready, :outcomes) do
+      Plan = Data.define(:mode, :inventory, :ready, :outcomes, :allow_fixed_name_reuse) do
         # Data 只冻结对象自身；这里复制并冻结可能由调用方修改的计划容器。
-        def initialize(mode:, inventory:, ready:, outcomes:)
+        def initialize(mode:, inventory:, ready:, outcomes:, allow_fixed_name_reuse: false)
           unless inventory.is_a?(Array) && ready.is_a?(Array) && outcomes.is_a?(Array)
             raise ArgumentError, "plan inventory, ready tasks, and outcomes must be Arrays"
           end
 
           tasks = ready.map { |task| task.is_a?(Array) ? task.dup.freeze : task }.freeze
-          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze)
+          raise ArgumentError, "allow_fixed_name_reuse must be boolean" unless [true, false].include?(allow_fixed_name_reuse)
+
+          super(mode: mode, inventory: inventory.dup.freeze, ready: tasks, outcomes: outcomes.dup.freeze,
+                allow_fixed_name_reuse: allow_fixed_name_reuse)
         end
 
         # 按清单顺序返回选中的设备。
@@ -26,7 +29,7 @@ module Net
           end
 
           selected_indices = {}
-          filenames = {}
+          selected_filenames = {}
           previous_index = -1
           ready.each do |task|
             unless task.is_a?(Array) && task.size == 2 && task.first.is_a?(Integer)
@@ -39,9 +42,11 @@ module Net
             end
             if mode == :tftp
               filename = device.tftp_filename
-              raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename" if filenames.key?(filename)
+              if selected_filenames.key?(filename) && !(allow_fixed_name_reuse && device.vendor == :palo_alto)
+                raise ArgumentError, "plan cannot upload multiple devices to one TFTP filename"
+              end
 
-              filenames[filename] = true
+              selected_filenames[filename] = true
             end
             selected_indices[index] = true
             previous_index = index
@@ -51,7 +56,7 @@ module Net
             result = outcomes[index]
             next if selected_indices[index] && result.nil?
 
-            unless !selected_indices[index] && valid_skipped_outcome?(result, device, filenames)
+            unless !selected_indices[index] && valid_skipped_outcome?(result, device, selected_filenames)
               raise ArgumentError, "plan outcome does not match its inventory slot"
             end
           end
@@ -61,7 +66,7 @@ module Net
         private
 
         # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。
-        def valid_skipped_outcome?(result, device, filenames)
+        def valid_skipped_outcome?(result, device, selected_filenames)
           return false unless result.is_a?(Outcome) && result.device.equal?(device) && result.backup.nil? &&
                               result.error_code.nil? && result.error_type.nil? &&
                               result.started_at.nil? && result.finished_at.nil?
@@ -69,7 +74,7 @@ module Net
           return result.status == device.issue unless device.ready?
 
           result.status == :sample_limit ||
-            (mode == :tftp && result.status == :remote_filename_collision && filenames.key?(device.tftp_filename))
+            (mode == :tftp && result.status == :remote_filename_collision && selected_filenames.key?(device.tftp_filename))
         end
       end
     end