net-connector 0.6.0 → 0.7.1

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

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Net
+  module Connector
+    module Netdisco
+      class CLI
+        # 可注入参数与输入输出的备份选项，不退出宿主进程。
+        class Options
+          def self.parse(argv: ARGV, input: $stdin, output: $stdout, error: $stderr, program: $PROGRAM_NAME)
+            values = { environment: {}, json: false, verbose: false, stdin_credentials: false }
+            parser = parser_for(values, output: output, program: program)
+            remaining = parser.parse!(argv.dup)
+            return values if values[:help]
+            raise OptionParser::InvalidArgument unless remaining.empty?
+            credentials = values[:environment].keys.any? { |key| key.match?(/USERNAME|PASSWORD/) }
+            if values[:stdin_credentials] && (credentials || values[:ask_password] || values[:ask_netdisco_password])
+              raise ArgumentError, "--stdin-credentials 不能与命令行凭据或密码提示同时使用"
+            end
+            read_password(values, :ask_password, "NC_DEVICE_PASSWORD", "设备密码", input: input, output: error)
+            read_password(values, :ask_netdisco_password, "NETDISCO_PASSWORD", "Netdisco 密码", input: input, output: error)
+
+            values
+          rescue OptionParser::ParseError
+            raise ArgumentError, "参数无效：并发数须为 1 至 50，抽样须为 1 至 5；使用 --help 查看参数", cause: nil
+          end
+
+          def self.parser_for(values, output:, program:)
+            OptionParser.new do |opts|
+              opts.banner = "用法：ruby #{File.basename(program)} [选项]（默认全量）"
+              add_settings(opts, values)
+              add_execution(opts, values)
+              opts.on("--ask-password", "隐藏输入设备密码") { values[:ask_password] = true }
+              opts.on("--ask-netdisco-password", "隐藏输入 Netdisco 密码") { values[:ask_netdisco_password] = true }
+              opts.on("--verbose", "显示逐条登录和命令事件") { values[:verbose] = true }
+              opts.on("--json", "在 STDOUT 输出计划和结果 JSON") { values[:json] = true }
+              opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
+              opts.on("-h", "--help", "显示帮助") { output.puts opts; values[:help] = true }
+            end
+          end
+
+          def self.add_execution(opts, values)
+            opts.on("-c", "--concurrency N", Integer, "并发设备数，1 至 50") do |count|
+              raise OptionParser::InvalidArgument unless (1..Settings::MAX_CONCURRENCY).cover?(count)
+
+              values[:environment]["NC_CONCURRENCY"] = count.to_s
+            end
+            opts.on("--sample N", "--limit-per-vendor N", Integer, "每厂商抽样 1 至 5 台") do |count|
+              Planner.validate_limit!(count)
+              values[:limit] = count
+            end
+            opts.on("--tftp-root DIR", "本机 TFTP 服务器文件目录") { |path| values[:tftp_root] = path }
+            opts.on("--all", "选择全部就绪设备") { values[:all] = true }
+            opts.on("--success-policy POLICY", %w[strict selected verified], "成功判定：strict / selected / verified（TFTP 文件核验）") do |policy|
+              values[:success_policy] = policy.to_sym
+            end
+          end
+
+          def self.settings(options, env: ENV)
+            raise ArgumentError, "--all 不能与抽样同时使用" if options[:all] && options[:limit]
+
+            environment = environment(options, env: env)
+            path = environment["NC_CONFIG"]
+            defaults = path && !path.empty? ? ConfigFile.load(path) : {}
+            overrides = {}
+            { source: "NETDISCO_SOURCE", query: "NETDISCO_QUERY", query_params: "NETDISCO_QUERY_PARAMS",
+              max_script_output_bytes: "NC_MAX_SCRIPT_OUTPUT_BYTES", host: "NC_INCLUDE_HOSTS",
+              limit: "NC_SAMPLE_PER_VENDOR" }.each do |option, key|
+              overrides[key] = options[option].to_s if options.key?(option)
+            end
+            overrides["NC_SAMPLE_PER_VENDOR"] = nil if options[:all]
+            Settings.new(env: environment, defaults: defaults, overrides: overrides)
+          end
+
+          def self.add_settings(opts, values)
+            {
+              "--username USER" => ["NC_DEVICE_USERNAME", "设备登录用户名"],
+              "--password PASSWORD" => ["NC_DEVICE_PASSWORD", "设备登录密码（可改用 --ask-password）"],
+              "--enable-password PASSWORD" => ["NC_ENABLE_PASSWORD", "设备提权密码"],
+              "--netdisco-url URL" => ["NETDISCO_URL", "Netdisco 地址"],
+              "--netdisco-username USER" => ["NETDISCO_USERNAME", "Netdisco 用户名"],
+              "--netdisco-password PASSWORD" => ["NETDISCO_PASSWORD", "Netdisco 密码"],
+              "--directory DIR" => ["NC_BACKUP_DIRECTORY", "备份目录，相对项目根目录"],
+              "--config FILE" => ["NC_CONFIG", "YAML 配置，相对项目根目录"]
+            }.each do |flag, (key, description)|
+              opts.on(flag, description) do |value|
+                raise OptionParser::InvalidArgument if value.empty?
+
+                values[:environment][key] = value
+              end
+            end
+            opts.on("--host-key-policy POLICY", %w[strict accept_new replace], "主机密钥策略：strict / accept_new / replace（变化时自动替换）") do |policy|
+              values[:environment]["NC_HOST_KEY_POLICY"] = policy
+            end
+            opts.on("--known-hosts FILE", "持久保存主机密钥的文件") do |path|
+              values[:environment]["NC_KNOWN_HOSTS"] = path
+            end
+          end
+
+          def self.environment(options, env: ENV)
+            result = env.to_h.dup
+            overrides = options.fetch(:environment)
+            # 显式设备参数覆盖对应厂商默认值；未指定的字段继续按原凭据规则解析。
+            { "NC_DEVICE_USERNAME" => "USERNAME", "NC_DEVICE_PASSWORD" => "PASSWORD",
+              "NC_ENABLE_PASSWORD" => "ENABLE_PASSWORD" }.each do |key, suffix|
+              next unless overrides.key?(key)
+
+              result.delete_if do |name, _|
+                name.start_with?("NC_") && name.end_with?("_#{suffix}") &&
+                  (suffix != "PASSWORD" || !name.end_with?("_ENABLE_PASSWORD"))
+              end
+            end
+            if overrides.key?("NETDISCO_USERNAME") || overrides.key?("NETDISCO_PASSWORD")
+              result.delete("NETDISCO_API_KEY")
+            end
+            result.merge(overrides)
+          end
+
+          def self.read_password(values, flag, key, label, input:, output:)
+            return unless values[flag]
+
+            raise ArgumentError, "密码提示与显式密码不能同时使用" if values[:environment].key?(key)
+            raise ArgumentError, "密码提示需要交互终端；自动化任务可使用环境变量或 --stdin-credentials" unless input.tty?
+            require "io/console"
+            output.print "#{label}："
+            output.flush
+            password = input.noecho(&:gets)&.chomp
+            output.puts
+            raise ArgumentError, "密码不能为空" if password.nil? || password.empty?
+
+            values[:environment][key] = password
+          end
+          private_class_method :read_password, :parser_for
+        end
+      end
+    end
+  end
+end

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