net-connector 0.6.0 → 0.7.0

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

@@ -10,6 +10,8 @@ module Net
         DEFAULT_BACKUP_DIRECTORY = "backups"
         DEFAULT_CONCURRENCY = 4
         MAX_CONCURRENCY = 50
+        ENVIRONMENT_KEYS = %w[NETDISCO_URL NC_BACKUP_DIRECTORY NC_CONCURRENCY NC_SAMPLE_PER_VENDOR
+                              NC_PROTOCOL NC_KNOWN_HOSTS NC_HOST_KEY_POLICY NC_LOG_DIRECTORY NC_LOG_LEVEL TFTP_HOST].freeze
         DEFAULT_PAGE_SIZE = Client::DEFAULTS.fetch(:page_size)
         UNSET = Object.new.freeze
         private_constant :UNSET
@@ -18,17 +20,29 @@ module Net
           new(env: env, defaults: ConfigFile.load(path))
         end
 
+        def self.from_env(env: ENV)
+          path = env["NC_CONFIG"]
+          path && !path.empty? ? from_file(path, env: env) : new(env: env)
+        end
+
         def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false)
           @env, @defaults, @overrides = env, defaults, overrides
           @policy, @fixed = policy, fixed
         end
 
+        # 调用入口补充运行目录等非敏感覆盖，凭据仍从同一来源读取。
+        def with_overrides(values)
+          self.class.new(env: @env, defaults: @defaults, overrides: @overrides.merge(values))
+        end
+
         # 快照自身不保留 ENV、凭据 resolver 或原 Settings 的引用，不能携带秘密进入摘要。
         def snapshot(mode: :backup)
           return @policy.validate!(mode: mode) if @policy
           return validate!(mode: mode) if @fixed
 
-          keys = mode == :export ? ["NET_CONNECTOR_BACKUP_DIRECTORY"] : non_secret_keys
+          validate_environment! unless mode == :export
+
+          keys = mode == :export ? ["NC_BACKUP_DIRECTORY"] : non_secret_keys
           values = keys.each_with_object({}) do |key, result|
             item = raw(key, UNSET)
             result[key.freeze] = item.is_a?(String) ? item.dup.freeze : item unless item.equal?(UNSET)
@@ -61,18 +75,25 @@ module Net
           self
         end
 
-        def client(policy: snapshot(mode: :inventory))
+        def client(policy: snapshot(mode: :inventory), credentials: nil)
+          if credentials && (!credentials.is_a?(Hash) || credentials.keys.sort != %i[password username] ||
+            !credentials.values.all? { |value| present?(value) })
+            raise ArgumentError, "inventory credentials require nonempty username and password"
+          end
           options = policy.client_options
           if policy.inventory_source == :postgres
             connection = DatabaseClient::CONNECTION_ENV.each_with_object({}) do |(key, name), values|
               item = secret_value(name)
               values[key] = item if item
             end
+            connection.merge!(user: credentials[:username], password: credentials[:password]) if credentials
             return DatabaseClient.new(connection_options: connection, **options)
           end
           raise ArgumentError, "NETDISCO_URL is required" unless options.fetch(:url)
 
-          authentication = if (token = secret_value("NETDISCO_API_KEY"))
+          authentication = if credentials
+                             credentials
+                           elsif (token = secret_value("NETDISCO_API_KEY"))
                              { api_key: token }
                            else
                              { username: required_secret("NETDISCO_USERNAME"), password: required_secret("NETDISCO_PASSWORD") }
@@ -90,54 +111,36 @@ module Net
         # 原生客户端和 --show-config 共享预算校验；只验证所选来源的查询设置。
         def client_options
           defaults = inventory_source == :postgres ? DatabaseClient::DEFAULTS : Client::DEFAULTS
-          options = defaults.to_h do |name, default|
-            key = "NETDISCO_#{name.to_s.upcase}"
-            parsed = case name
-                     when :inventory_timeout then number(key, default)
-                     when :allow_insecure_http then boolean(key, default)
-                     else integer(key, default)
-                     end
-            [name, parsed]
-          end
-          if inventory_source == :postgres
-            query = value("NETDISCO_QUERY") || (raise ArgumentError, "NETDISCO_QUERY is required for postgres")
-            return DatabaseClient.options(query: query, query_params: json("NETDISCO_QUERY_PARAMS", []), **options)
-          end
-          if value("NETDISCO_QUERY") || value("NETDISCO_QUERY_PARAMS")
-            raise ArgumentError, "SQL query settings require NETDISCO_SOURCE=postgres"
-          end
-          options = Client.options(**options)
-          url = value("NETDISCO_URL")
-          Client.validate_url!(url, allow_insecure_http: options.fetch(:allow_insecure_http)) if url
-          options.merge(url: url).freeze
+          options = client_budget_options(defaults)
+          inventory_source == :postgres ? postgres_options(options) : http_options(options)
         end
 
         def rules
-          Rules.new(include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
-                    exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
-                    include_vendors: list("NET_CONNECTOR_INCLUDE_VENDORS"),
-                    vendor_overrides: json("NET_CONNECTOR_VENDOR_OVERRIDES", {}),
-                    host_overrides: json("NET_CONNECTOR_HOST_OVERRIDES", {}),
-                    mappings: json("NET_CONNECTOR_DEVICE_RULES", []))
+          Rules.new(include_hosts: list("NC_INCLUDE_HOSTS"),
+                    exclude_hosts: list("NC_EXCLUDE_HOSTS"),
+                    include_vendors: list("NC_INCLUDE_VENDORS"),
+                    vendor_overrides: json("NC_VENDOR_OVERRIDES", {}),
+                    host_overrides: json("NC_HOST_OVERRIDES", {}),
+                    mappings: json("NC_DEVICE_RULES", []))
         end
 
         def backup_directory
-          path = raw("NET_CONNECTOR_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
-          raise ArgumentError, "NET_CONNECTOR_BACKUP_DIRECTORY must be nonempty" unless present?(path)
+          path = raw("NC_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
+          raise ArgumentError, "NC_BACKUP_DIRECTORY must be nonempty" unless present?(path)
 
           File.expand_path(path)
         end
 
         def concurrency
-          count = integer("NET_CONNECTOR_CONCURRENCY", DEFAULT_CONCURRENCY)
-          raise ArgumentError, "NET_CONNECTOR_CONCURRENCY must be at most #{MAX_CONCURRENCY}" if count > MAX_CONCURRENCY
+          count = integer("NC_CONCURRENCY", DEFAULT_CONCURRENCY)
+          raise ArgumentError, "NC_CONCURRENCY must be at most #{MAX_CONCURRENCY}" if count > MAX_CONCURRENCY
 
           count
         end
 
         def limit_per_vendor(tftp: false)
-          count = if configured?("NET_CONNECTOR_SAMPLE_PER_VENDOR")
-                    integer("NET_CONNECTOR_SAMPLE_PER_VENDOR", 5) unless raw("NET_CONNECTOR_SAMPLE_PER_VENDOR").nil?
+          count = if configured?("NC_SAMPLE_PER_VENDOR")
+                    integer("NC_SAMPLE_PER_VENDOR", 5) unless raw("NC_SAMPLE_PER_VENDOR").nil?
                   elsif tftp
                     5
                   end
@@ -146,17 +149,17 @@ module Net
         end
 
         def tftp_source_files
-          files = { huawei: raw("NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
+          files = { huawei: raw("NC_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
           %i[h3c h3c_wireless].each do |vendor|
-            key = "NET_CONNECTOR_#{vendor.to_s.upcase}_TFTP_SOURCE_FILE"
+            key = "NC_#{vendor.to_s.upcase}_TFTP_SOURCE_FILE"
             files[vendor] = raw(key) if configured?(key)
           end
           files
         end
 
         def tftp_vrfs
-          mapping = json("NET_CONNECTOR_TFTP_VRFS", {})
-          raise ArgumentError, "NET_CONNECTOR_TFTP_VRFS must be a JSON object" unless mapping.is_a?(Hash)
+          mapping = json("NC_TFTP_VRFS", {})
+          raise ArgumentError, "NC_TFTP_VRFS must be a JSON object" unless mapping.is_a?(Hash)
 
           self.class.validate_vrfs!(mapping.transform_keys(&:to_sym))
         end
@@ -174,75 +177,122 @@ module Net
         def tftp_server = value("TFTP_HOST")
 
         def connection_options(vendor = nil)
-          prefix = "NET_CONNECTOR_#{vendor.to_s.upcase}_"
           configuration = Configuration.new(
-            protocol: (vendor && value(prefix + "PROTOCOL")) || value("NET_CONNECTOR_PROTOCOL") || "ssh",
-            log_level: value("NET_CONNECTOR_LOG_LEVEL") || "info", known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
-            host_key_policy: value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict",
-            max_script_output_bytes: optional_integer("NET_CONNECTOR_MAX_SCRIPT_OUTPUT_BYTES")
+            protocol: vendor_protocols[vendor.to_s] || value("NC_PROTOCOL") || "ssh",
+            log_level: value("NC_LOG_LEVEL") || "info", known_hosts: value("NC_KNOWN_HOSTS"),
+            host_key_policy: value("NC_HOST_KEY_POLICY") || "strict",
+            max_script_output_bytes: optional_integer("NC_MAX_SCRIPT_OUTPUT_BYTES")
           )
           options = %i[protocol log_level known_hosts host_key_policy].to_h { |key| [key, configuration.public_send(key)] }
           options[:max_script_output_bytes] = configuration.max_script_output_bytes if configuration.max_script_output_bytes
           options.freeze
         end
 
+        def vendor_protocols
+          values = json("NC_VENDOR_PROTOCOLS", {})
+          unless values.is_a?(Hash) && values.all? { |vendor, protocol| Net::Connector.vendors.map(&:to_s).include?(vendor) && %w[ssh telnet].include?(protocol) }
+            raise ArgumentError, "ssh.vendor_protocols must map supported vendors to ssh or telnet"
+          end
+          values
+        end
+
         def device_credentials_for(device)
-          prefix = "NET_CONNECTOR_#{device.vendor.to_s.upcase}_"
-          username = secret_value(prefix + "USERNAME") || secret_value("NET_CONNECTOR_DEVICE_USERNAME")
+          prefix = "NC_#{device.vendor.to_s.upcase}_"
+          username = secret_value(prefix + "USERNAME") || secret_value("NC_DEVICE_USERNAME")
           return nil unless username
 
           { username: username,
-            password: secret_value(prefix + "PASSWORD") || secret_value("NET_CONNECTOR_DEVICE_PASSWORD"),
-            enable_password: secret_value(prefix + "ENABLE_PASSWORD") || secret_value("NET_CONNECTOR_ENABLE_PASSWORD") }
+            password: secret_value(prefix + "PASSWORD") || secret_value("NC_DEVICE_PASSWORD"),
+            enable_password: secret_value(prefix + "ENABLE_PASSWORD") || secret_value("NC_ENABLE_PASSWORD") }
         end
 
         def log_directory
-          path = value("NET_CONNECTOR_LOG_DIRECTORY")
+          path = value("NC_LOG_DIRECTORY")
           File.expand_path(path) if path
         end
 
         def public_config
-          snapshot(mode: :show_config).send(:config_hash)
+          snapshot(mode: :show_config).config_hash
         end
 
         def inspect = "#<#{self.class}>"
 
-        private
+        protected
 
         def config_hash
           {
             netdisco: client_options.merge(source: inventory_source),
             backup: { directory: backup_directory, concurrency: concurrency, limit_per_vendor: limit_per_vendor },
-            inventory: { include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
-                         exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
-                         include_vendors: list("NET_CONNECTOR_INCLUDE_VENDORS"),
-                         vendor_overrides: json("NET_CONNECTOR_VENDOR_OVERRIDES", {}),
-                         host_overrides: json("NET_CONNECTOR_HOST_OVERRIDES", {}),
-                         device_rules: json("NET_CONNECTOR_DEVICE_RULES", []) },
+            inventory: { include_hosts: list("NC_INCLUDE_HOSTS"),
+                         exclude_hosts: list("NC_EXCLUDE_HOSTS"),
+                         include_vendors: list("NC_INCLUDE_VENDORS"),
+                         vendor_overrides: json("NC_VENDOR_OVERRIDES", {}),
+                         host_overrides: json("NC_HOST_OVERRIDES", {}),
+                         device_rules: json("NC_DEVICE_RULES", []) },
             ssh: connection_options.transform_values { |item| item.is_a?(Symbol) ? item.to_s : item }.merge(
               log_directory: log_directory,
-              vendor_protocols: Net::Connector.vendors.filter_map do |vendor|
-                protocol = value("NET_CONNECTOR_#{vendor.to_s.upcase}_PROTOCOL")
-                [vendor, protocol] if protocol
-              end.to_h
+              vendor_protocols: vendor_protocols
             ),
             tftp: { server: tftp_server, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
           }
         end
 
-        def non_secret_keys
-          keys = ConfigFile::FIELDS.values.flat_map { |section| section.values.map(&:first) }
-          keys + Net::Connector.vendors.map { |vendor| "NET_CONNECTOR_#{vendor.to_s.upcase}_PROTOCOL" }
-        end
-
         def raw(key, default = nil)
-          return @policy.send(:raw, key, default) if @policy
+          return @policy.raw(key, default) if @policy
           return @overrides.fetch(key) if @overrides.key?(key)
-          return @env.fetch(key) if @env.key?(key)
+          if @env.key?(key)
+            unless @fixed || ENVIRONMENT_KEYS.include?(key)
+              raise ArgumentError, "#{key} is no longer an environment setting; use YAML via NC_CONFIG or CLI options"
+            end
+            return @env.fetch(key)
+          end
 
           @defaults.fetch(key, default)
         end
 
+        private
+
+        def client_budget_options(defaults)
+          defaults.to_h do |name, default|
+            key = "NETDISCO_#{name.to_s.upcase}"
+            parsed = case name
+                     when :inventory_timeout then number(key, default)
+                     when :allow_insecure_http then boolean(key, default)
+                     else integer(key, default)
+                     end
+            [name, parsed]
+          end
+        end
+
+        def postgres_options(options)
+          query = value("NETDISCO_QUERY") || (raise ArgumentError, "NETDISCO_QUERY is required for postgres")
+          DatabaseClient.options(query: query, query_params: json("NETDISCO_QUERY_PARAMS", []), **options)
+        end
+
+        def http_options(options)
+          if value("NETDISCO_QUERY") || value("NETDISCO_QUERY_PARAMS")
+            raise ArgumentError, "SQL query settings require NETDISCO_SOURCE=postgres"
+          end
+          options = Client.options(**options)
+          url = value("NETDISCO_URL")
+          Client.validate_url!(url, allow_insecure_http: options.fetch(:allow_insecure_http)) if url
+          options.merge(url: url).freeze
+        end
+
+        def non_secret_keys
+          ConfigFile::FIELDS.values.flat_map { |section| section.values.map(&:first) }
+        end
+
+        def validate_environment!
+          legacy = @env.keys.find { |key| key.start_with?("NET_CONNECTOR_") }
+          raise ArgumentError, "#{legacy} has been renamed to #{legacy.sub("NET_CONNECTOR_", "NC_")}" if legacy
+
+          removed = non_secret_keys - ENVIRONMENT_KEYS
+          removed += Net::Connector.vendors.map { |vendor| "NC_#{vendor.to_s.upcase}_PROTOCOL" }
+          key = removed.find { |name| @env.key?(name) }
+          raise ArgumentError, "#{key} is no longer an environment setting; use YAML via NC_CONFIG or CLI options" if key
+        end
+
         def configured?(key) = !raw(key, UNSET).equal?(UNSET)
 
         def json(key, default)

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

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../storage/backup_lock"
+require_relative "../storage/private_file"
+require_relative "../storage/safe_file"
+require_relative "tftp_verification"
+
+module Net
+  module Connector
+    module Netdisco
+      # 设备先上传到服务器根目录，核验后按批次归档；固定文件名不会覆盖历史文件。
+      class TftpArchive
+        BATCH_DIRECTORY_NAME = /\A\d{4}-\d{2}-\d{2}_\d{2}-\d{2}-\d{2}(?:_\d{2})?\z/
+        private_constant :BATCH_DIRECTORY_NAME
+
+        class Unavailable < Net::Connector::Error
+          def initialize(host: nil)
+            super("a local TFTP root is required to retain a fixed-name upload", code: :tftp_history_unavailable,
+                  host: host, phase: :tftp_backup)
+          end
+        end
+
+        class ArchiveFailed < Net::Connector::Error
+          def initialize(host: nil)
+            super("the uploaded file could not be retained in the batch", code: :tftp_archive_failed,
+                  host: host, phase: :tftp_backup)
+          end
+        end
+
+        def initialize(directory:, root: nil)
+          @report_directory = File.expand_path(directory)
+          @server_root = root && File.realpath(root)
+          @server_archive_directory = create_server_archive_directory if @server_root
+          @remote_suffix = reserve_remote_suffix unless @server_root
+          @verifier = TftpVerification.new(root: @server_root)
+        end
+
+        def upload_filename(device)
+          name = device.tftp_filename
+          return name if @server_root || device.vendor == :palo_alto
+
+          extension = File.extname(name)
+          stem = File.basename(name, extension)
+          suffix = "-#{@remote_suffix}#{extension}"
+          TftpTarget.validate_path!("#{stem.byteslice(0, TftpTarget::MAX_PATH_BYTES - suffix.bytesize)}#{suffix}")
+        end
+
+        def upload_and_archive(device, started_at:)
+          raise Unavailable.new(host: device.host) if device.vendor == :palo_alto && !@server_root
+
+          remote_filename = upload_filename(device)
+          return yield remote_filename unless @server_root
+
+          # The lock spans the upload and copy, including a fixed-name PAN-OS upload.
+          Storage::BackupLock.synchronize(File.join(@server_root, remote_filename), host: device.host, timeout: 240) do
+            archive_existing_file(device, remote_filename)
+            outcome = yield remote_filename
+            receipt = outcome.backup
+            return outcome unless receipt.is_a?(TftpReceipt) && receipt.path
+
+            verified = @verifier.verify_outcome(outcome.with(started_at: started_at))
+            return outcome.success? ? archive_failure(outcome) : outcome unless verified.backup.verification == :server_verified
+
+            archive_uploaded_file(verified)
+          end
+        end
+
+        alias path_for upload_filename
+        alias capture upload_and_archive
+
+        private
+
+        # 首次采用固定远端名时，先保留服务器上原有文件，再允许设备覆盖。
+        def archive_existing_file(device, remote_filename)
+          existing_path = File.join(@server_root, remote_filename)
+          bytes = Storage::SafeFile.open(existing_path, missing: true) { |file, _stat| file.read }
+          return unless bytes
+
+          previous_directory = File.join(@server_archive_directory, "previous")
+          FileUtils.mkdir_p(previous_directory, mode: 0o700)
+          archive_path = File.join(previous_directory, archive_filename(device, File.extname(remote_filename)))
+          Storage::PrivateFile.write(archive_path, bytes)
+        rescue StandardError
+          raise ArchiveFailed.new(host: device.host), cause: nil
+        end
+
+        def create_server_archive_directory
+          parent = File.join(@server_root, "archive")
+          raise ArgumentError, "TFTP archive directory must not be a symlink" if File.symlink?(parent)
+
+          FileUtils.mkdir_p(parent, mode: 0o700)
+          raise ArgumentError, "TFTP archive directory escaped its root" unless File.realpath(parent) == parent
+
+          base = batch_name
+          number = 0
+          loop do
+            candidate = number.zero? ? base : "#{base}_#{format("%02d", number)}"
+            path = File.join(parent, candidate)
+            begin
+              Dir.mkdir(path, 0o700)
+              return path
+            rescue Errno::EEXIST
+              number += 1
+            end
+          end
+        end
+
+        # 同一目录重跑时用原子预留的序号区分运行，不依赖随机数或进程 ID。
+        def reserve_remote_suffix
+          base = batch_name
+          number = 0
+          loop do
+            candidate = number.zero? ? base : "#{base}_#{format("%02d", number)}"
+            marker = File.join(@report_directory, ".tftp-run-#{candidate}")
+            begin
+              File.open(marker, File::WRONLY | File::CREAT | File::EXCL, 0o600) { |file| file.write("\n") }
+              return candidate
+            rescue Errno::EEXIST
+              number += 1
+            end
+          end
+        end
+
+        def batch_name
+          name = File.basename(@report_directory)
+          name.match?(BATCH_DIRECTORY_NAME) ? name : Time.now.getlocal("+08:00").strftime("%Y-%m-%d_%H-%M-%S")
+        end
+
+        def archive_uploaded_file(outcome)
+          receipt = outcome.backup
+          saved_batch_path = nil
+          batch_directory = File.join(@report_directory, "tftp")
+          FileUtils.mkdir_p(batch_directory, mode: 0o700)
+          extension = File.extname(receipt.path)
+          filename = archive_filename(outcome.device, extension)
+          batch_archive_path = File.join(batch_directory, filename)
+          server_archive_path = File.join(@server_archive_directory, filename)
+          uploaded_path = receipt.local_path
+          bytes = Storage::SafeFile.open(uploaded_path) do |file, stat|
+            raise ArchiveFailed.new(host: outcome.device.host) unless stat.size == receipt.server_bytes
+
+            file.read
+          end
+          raise ArchiveFailed.new(host: outcome.device.host) unless Digest::SHA256.hexdigest(bytes) == receipt.server_sha256
+
+          Storage::PrivateFile.write(batch_archive_path, bytes)
+          saved_batch_path = batch_archive_path
+          Storage::PrivateFile.write(server_archive_path, bytes)
+          if outcome.success?
+            uploaded_fingerprint = Storage::SafeFile.fingerprint(uploaded_path)
+            raise ArchiveFailed.new(host: outcome.device.host) unless uploaded_fingerprint.sha256 == receipt.server_sha256
+            raise ArchiveFailed.new(host: outcome.device.host) unless Storage::SafeFile.same_entry?(uploaded_path, uploaded_fingerprint)
+
+            File.unlink(uploaded_path)
+          end
+          outcome.with(backup: receipt.with(local_path: batch_archive_path, archive_path: server_archive_path))
+        rescue StandardError
+          retained = outcome.with(backup: receipt.with(local_path: saved_batch_path))
+          outcome.success? ? archive_failure(retained) : retained
+        end
+
+        def archive_failure(outcome)
+          error = ArchiveFailed.new(host: outcome.device.host)
+          outcome.with(status: :reported_with_error, error_code: error.code, error_type: error.class.name,
+                       diagnostic: Diagnostic.from(error, backup: outcome.backup))
+        end
+
+        def archive_filename(device, extension)
+          "#{device.backup_filename(style: :hostname_ip).delete_suffix(".txt")}#{extension}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "tftp_archive"
+
+module Net
+  module Connector
+    module Netdisco
+      # Compatibility with the first batch archive entry point.
+      class TftpHistory < TftpArchive
+        def initialize(server:, **options) # rubocop:disable Lint/UnusedMethodArgument -- Accept the former constructor keyword.
+          super(**options)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../storage/safe_file"
+
+module Net
+  module Connector
+    module Netdisco
+      # 只核验本次设备回执指向的本地服务器文件；远端可读不等于本次上传证据。
+      class TftpVerification
+        def initialize(root: nil)
+          @root = root && File.realpath(root)
+        end
+
+        def call(report)
+          return report unless @root
+
+          outcomes = report.outcomes.map do |outcome|
+            receipt = outcome.backup
+            next outcome unless receipt.is_a?(TftpReceipt) && receipt.path && outcome.started_at
+
+            verify(outcome, receipt)
+          end
+          report.with(outcomes: outcomes.freeze)
+        end
+
+        def verify_outcome(outcome)
+          return outcome unless @root && outcome.started_at && outcome.backup.is_a?(TftpReceipt) && outcome.backup.path
+
+          verify(outcome, outcome.backup)
+        end
+
+        private
+
+        def verify(outcome, receipt)
+          path = File.join(@root, receipt.path)
+          parent = File.realpath(File.dirname(path))
+          return outcome unless parent == @root || parent.start_with?(@root + File::SEPARATOR)
+
+          size = nil
+          fingerprint = Storage::SafeFile.open(path, missing: true) do |file, stat|
+            next unless stat.size.positive? && stat.mtime >= outcome.started_at
+
+            size = stat.size
+            value = Storage::SafeFile.fingerprint_io(path, file, stat)
+            after = file.stat
+            value if [stat.size, stat.mtime, stat.ctime] == [after.size, after.mtime, after.ctime]
+          end
+          return outcome unless fingerprint && Storage::SafeFile.same_entry?(path, fingerprint)
+
+          outcome.with(backup: receipt.with(verification: :server_verified, server_sha256: fingerprint.sha256, server_bytes: size, local_path: path))
+        rescue IOError, SystemCallError, ArgumentError
+          # 核验失败不抹去设备上传回执；要求服务器证据的策略仍判为未完成。
+          outcome
+        end
+      end
+    end
+  end
+end

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

@@ -5,13 +5,18 @@ module Net
     module Netdisco
       # 以固定并发上限执行相互隔离的设备任务。
       class Worker
-        # 校验并保存最大设备并发数。
-        def initialize(concurrency:)
+        # 内部预检与实际执行共用规则，不为校验创建工作线程池对象。
+        def self.validate_concurrency!(concurrency)
           unless concurrency.is_a?(Integer) && (1..Settings::MAX_CONCURRENCY).cover?(concurrency)
             raise ArgumentError, "concurrency must be an Integer in 1..#{Settings::MAX_CONCURRENCY}"
           end
 
-          @concurrency = concurrency
+          concurrency
+        end
+
+        # 校验并保存最大设备并发数。
+        def initialize(concurrency:)
+          @concurrency = Worker.validate_concurrency!(concurrency)
         end
 
         # 按清单顺序收集结果，并隔离设备及回调异常。

data/lib/net/connector/netdisco.rb

@@ -12,4 +12,14 @@ require_relative "netdisco/result_store"
 require_relative "netdisco/batch"
 require_relative "netdisco/planner"
 require_relative "netdisco/fleet"
+require_relative "netdisco/progress"
 require_relative "netdisco/cli"
+require_relative "storage/batch_directory"
+require_relative "netdisco/report/text"
+require_relative "netdisco/connection"
+require_relative "netdisco/cli/options"
+require_relative "netdisco/report/files"
+require_relative "netdisco/tftp_verification"
+require_relative "netdisco/tftp_archive"
+require_relative "netdisco/tftp_history"
+require_relative "netdisco/backup_run"

data/lib/net/connector/storage/backup_lock.rb

@@ -25,7 +25,7 @@ module Net
           File.join(directory, ".net-connector-#{Digest::SHA256.hexdigest(filename)}.lock")
         end
 
-        def self.synchronize(path, **options, &block) = new(path, **options).synchronize(&block)
+        def self.synchronize(path, **options, &) = new(path, **options).synchronize(&)
 
         def initialize(path, timeout: 0, host: nil)
           raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?

data/lib/net/connector/storage/batch_directory.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Net
+  module Connector
+    module Storage
+      # 使用本地业务时区命名，原子创建互不覆盖的批次目录。
+      class BatchDirectory
+        # 固定 UTC+8，不依赖运行主机时区；mkdir 原子防止并发任务覆盖。
+        def self.create(root, time: Time.now)
+          FileUtils.mkdir_p(root, mode: 0o700)
+          stamp = time.getlocal("+08:00").strftime("%Y-%m-%d_%H-%M-%S")
+          suffix = 0
+          loop do
+            name = suffix.zero? ? stamp : "#{stamp}_#{format("%02d", suffix)}"
+            path = File.join(root, name)
+            begin
+              Dir.mkdir(path, 0o700)
+              return path
+            rescue Errno::EEXIST
+              suffix += 1
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/net/connector/storage.rb

@@ -4,6 +4,7 @@ module Net
   module Connector
     # 文件存储不依赖设备连接；备份、离线导出和批量报告共享这些原语。
     module Storage
+      autoload :BatchDirectory, File.expand_path("storage/batch_directory", __dir__)
       autoload :BackupLock, File.expand_path("storage/backup_lock", __dir__)
       autoload :PrivateFile, File.expand_path("storage/private_file", __dir__)
       autoload :SafeFile, File.expand_path("storage/safe_file", __dir__)

data/lib/net/connector/vendor/h3c.rb

@@ -38,7 +38,8 @@ module Net
             )
           end
 
-          command_timeout 10
+          # 核心交换机配置采集实测超过 10 秒，保留有界的整条命令预算。
+          command_timeout 60
 
           interactions do
             confirm %r{Are\s+you\s+sure\?\s*\[Y/N\]}i, response: "y\n"