net-connector 0.7.3 → 0.9.0

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

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 require "optparse"
+require_relative "../settings"
+require_relative "../planner"
+require_relative "../config_file"
 
 module Net
   module Connector
@@ -8,6 +11,7 @@ module Net
       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)
@@ -19,7 +23,7 @@ module Net
               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)
+            read_password(values, :ask_netdisco_password, "ND_PASSWORD", "Netdisco 密码", input: input, output: error)
 
             values
           rescue OptionParser::ParseError
@@ -33,6 +37,7 @@ module Net
               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("--no-progress", "关闭进度显示") { values[:no_progress] = true }
               opts.on("--verbose", "显示逐条登录和命令事件") { values[:verbose] = true }
               opts.on("--json", "在 STDOUT 输出计划和结果 JSON") { values[:json] = true }
               opts.on("--stdin-credentials", "从标准输入读取凭据并等待 RUN") { values[:stdin_credentials] = true }
@@ -40,6 +45,7 @@ module Net
             end
           end
 
+          # 正式 CLI 与批次示例共用并发、抽样、核验和成功策略选项。
           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)
@@ -57,14 +63,17 @@ module Net
             end
           end
 
+          # 公开 CLI 参数进入 overrides，凭据留在 environment；内部键不会重新开放已移除环境设置。
           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",
+            keys = ConfigFile::FIELDS.values.flat_map { |fields| fields.values.map(&:first) }
+            overrides = options.fetch(:environment).slice(*keys)
+            environment = environment.reject { |key, _| overrides.key?(key) && !Settings::ENVIRONMENT_KEYS.include?(key) }
+            { source: "ND_SOURCE", query: "ND_QUERY", query_params: "ND_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)
@@ -73,14 +82,15 @@ module Net
             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 密码"],
+              "--netdisco-url URL" => ["ND_URL", "Netdisco 地址"],
+              "--netdisco-username USER" => ["ND_USERNAME", "Netdisco 用户名"],
+              "--netdisco-password PASSWORD" => ["ND_PASSWORD", "Netdisco 密码"],
               "--directory DIR" => ["NC_BACKUP_DIRECTORY", "备份目录，相对项目根目录"],
               "--config FILE" => ["NC_CONFIG", "YAML 配置，相对项目根目录"]
             }.each do |flag, (key, description)|
@@ -98,6 +108,7 @@ module Net
             end
           end
 
+          # 复制原环境并合并显式凭据，清除被通用凭据覆盖的厂商值及旧 API key。
           def self.environment(options, env: ENV)
             result = env.to_h.dup
             overrides = options.fetch(:environment)
@@ -111,12 +122,13 @@ module Net
                   (suffix != "PASSWORD" || !name.end_with?("_ENABLE_PASSWORD"))
               end
             end
-            if overrides.key?("NETDISCO_USERNAME") || overrides.key?("NETDISCO_PASSWORD")
-              result.delete("NETDISCO_API_KEY")
+            if overrides.key?("ND_USERNAME") || overrides.key?("ND_PASSWORD")
+              result.delete("ND_API_KEY")
             end
             result.merge(overrides)
           end
 
+          # 隐藏输入只用于交互终端；与显式密码互斥，不输出或记录密码内容。
           def self.read_password(values, flag, key, label, input:, output:)
             return unless values[flag]
 

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

@@ -3,6 +3,9 @@
 require "json"
 require "ipaddr"
 require "optparse"
+require_relative "../version"
+require_relative "fleet"
+require_relative "cli/options"
 
 module Net
   module Connector
@@ -36,7 +39,7 @@ module Net
             return 0
           end
           if options[:tftp] && !options[:plan] && !settings.tftp_server
-            raise ArgumentError, "TFTP_HOST is required"
+            raise ArgumentError, "YAML tftp.server is required"
           end
 
           fleet = @fleet_factory.call(settings)
@@ -46,29 +49,29 @@ module Net
             return 0
           end
 
-          batch = backup(fleet, plan, settings, options)
-          summary = batch.summary
+          report = backup(fleet, plan, settings, options)
+          summary = report.summary
           @output.puts JSON.pretty_generate(summary)
-          batch.policy_success? ? 0 : 1
+          report.policy_success? ? 0 : 1
         rescue Storage::PrivateFile::WriteError => exception
           message = Storage::PrivateFile.receipt_error?(exception) ? exception.message : exception.class.name
-          @error.puts "net-connector-backup: #{message}"
+          @error.puts "net-backup: #{message}"
           2
         rescue OptionParser::ParseError
-          @error.puts "net-connector-backup: 参数无效；使用 --help 查看参数"
+          @error.puts "net-backup: 参数无效；使用 --help 查看参数"
           2
         rescue ArgumentError, KeyError, Errno::ENOENT,
           Psych::Exception, JSON::ParserError, Client::Error => exception
-          @error.puts "net-connector-backup: #{exception.message}"
+          @error.puts "net-backup: #{exception.message}"
           2
         rescue StandardError => exception
-          @error.puts "net-connector-backup 失败（#{exception.class}）"
+          @error.puts "net-backup 失败（#{exception.class}）"
           2
         end
 
         private
 
-        # 文件、环境变量、命令行按优先级覆盖，凭据仍只来自环境变量。
+        # 公开 CLI 参数覆盖 YAML 与 ND_URL；设备凭据按环境或显式 CLI 参数解析。
         def settings_for(options)
           Options.settings(options, env: @env)
         end
@@ -102,7 +105,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, verification_root: options[:tftp_root] || @env["TFTP_ROOT"], **reporting)
+                                  source_files: settings.tftp_source_files, verification_root: options[:tftp_root] || settings.tftp_root, **reporting)
           else
             fleet.backup_all(plan: plan, directory: settings.backup_directory,
                              concurrency: settings.concurrency, **reporting)
@@ -113,7 +116,7 @@ module Net
         def parse_options
           options = { environment: {} }
           parser = OptionParser.new do |args|
-            args.banner = "用法：net-connector-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
+            args.banner = "用法：net-backup [--config FILE] [--plan | --show-config | --export IP] [--tftp]"
             Options.add_settings(args, options)
             Options.add_execution(args, options)
             args.on("--source SOURCE", %w[http postgres], "清单来源：http（默认）或 postgres") { |value| options[:source] = value }

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

@@ -6,20 +6,24 @@ require "yaml"
 module Net
   module Connector
     module Netdisco
-      # 命令行使用的无凭据 YAML 配置，环境变量优先。
+      # 无凭据 YAML 配置；仅 ND_URL 允许从进程环境覆盖，其他策略由 CLI 覆盖。
       class ConfigFile
         FIELDS = {
-          "netdisco" => { "source" => ["NETDISCO_SOURCE", :string],
-                          "query" => ["NETDISCO_QUERY", :string],
-                          "query_params" => ["NETDISCO_QUERY_PARAMS", :json_array],
-                          "url" => ["NETDISCO_URL", :string],
-                          "page_size" => ["NETDISCO_PAGE_SIZE", :integer],
-                          "max_pages" => ["NETDISCO_MAX_PAGES", :integer],
-                          "max_response_bytes" => ["NETDISCO_MAX_RESPONSE_BYTES", :integer],
-                          "max_inventory_bytes" => ["NETDISCO_MAX_INVENTORY_BYTES", :integer],
-                          "max_devices" => ["NETDISCO_MAX_DEVICES", :integer],
-                          "inventory_timeout" => ["NETDISCO_INVENTORY_TIMEOUT", :number],
-                          "allow_insecure_http" => ["NETDISCO_ALLOW_INSECURE_HTTP", :boolean] },
+          "netdisco" => { "source" => ["ND_SOURCE", :string],
+                          "query" => ["ND_QUERY", :string],
+                          "query_params" => ["ND_QUERY_PARAMS", :json_array],
+                          "url" => ["ND_URL", :string],
+                          "page_size" => ["ND_PAGE_SIZE", :integer],
+                          "max_pages" => ["ND_MAX_PAGES", :integer],
+                          "max_response_bytes" => ["ND_MAX_RESPONSE_BYTES", :integer],
+                          "max_inventory_bytes" => ["ND_MAX_INVENTORY_BYTES", :integer],
+                          "max_devices" => ["ND_MAX_DEVICES", :integer],
+                          "inventory_timeout" => ["ND_INVENTORY_TIMEOUT", :number],
+                          "allow_insecure_http" => ["ND_ALLOW_INSECURE_HTTP", :boolean],
+                          "db_port" => ["ND_DB_PORT", :integer],
+                          "db_sslmode" => ["ND_DB_SSLMODE", :string],
+                          "db_sslrootcert" => ["ND_DB_SSLROOTCERT", :string],
+                          "db_connect_timeout" => ["ND_DB_CONNECT_TIMEOUT", :integer] },
           "backup" => { "directory" => ["NC_BACKUP_DIRECTORY", :string],
                         "concurrency" => ["NC_CONCURRENCY", :integer],
                         "limit_per_vendor" => ["NC_SAMPLE_PER_VENDOR", :integer] },
@@ -36,14 +40,15 @@ module Net
                      "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],
+          "tftp" => { "server" => ["NC_TFTP_HOST", :string],
+                      "verification_root" => ["NC_TFTP_ROOT", :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 配置并映射到环境变量格式。
+        # 安全读取 YAML 配置并编码为 Settings 的内部键值。
         def self.load(path)
           raise ArgumentError, "config path must be a nonempty String" unless path.is_a?(String) && !path.empty?
 

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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require_relative "client"
 
 # 清单连接与设备凭据来源；业务入口负责规划和执行备份。
 module Net

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

@@ -8,15 +8,44 @@ module Net
     module Netdisco
       # SQL 负责业务选择和列别名；适配器只管理只读查询、清单预算与连接生命周期。
       class DatabaseClient
+        # 只有数据库身份从环境读取；非敏感连接策略的内部选项与诊断名称另行映射。
         CONNECTION_ENV = {
-          host: "NETDISCO_DB_HOST", port: "NETDISCO_DB_PORT", dbname: "NETDISCO_DB_NAME",
-          user: "NETDISCO_DB_USER", password: "NETDISCO_DB_PASS",
-          sslmode: "NETDISCO_DB_SSLMODE", sslrootcert: "NETDISCO_DB_SSLROOTCERT",
-          connect_timeout: "NETDISCO_DB_CONNECT_TIMEOUT"
+          host: "ND_DB_HOST", dbname: "ND_DB_NAME", user: "ND_DB_USER", password: "ND_DB_PASS"
         }.freeze
+        CONNECTION_OPTIONS = CONNECTION_ENV.merge(
+          port: "netdisco.db_port", sslmode: "netdisco.db_sslmode", sslrootcert: "netdisco.db_sslrootcert",
+          connect_timeout: "netdisco.db_connect_timeout"
+        ).freeze
         REQUIRED_CONNECTION_KEYS = %i[host dbname user password].freeze
+        POLICY_KEYS = (CONNECTION_OPTIONS.keys - REQUIRED_CONNECTION_KEYS).freeze
+        private_constant :POLICY_KEYS
         DEFAULTS = Client::DEFAULTS.except(:allow_insecure_http).freeze
 
+        # 预检与实际连接共用公开策略校验；不读取身份凭据，也不访问文件或数据库。
+        def self.connection_policy(**options)
+          raise ArgumentError, "unknown PostgreSQL connection policy" unless (options.keys - POLICY_KEYS).empty?
+
+          options.each do |key, value|
+            valid = value.is_a?(String) && !value.empty? && !value.include?("\0")
+            valid ||= %i[port connect_timeout].include?(key) && value.is_a?(Integer)
+            raise ArgumentError, "#{CONNECTION_OPTIONS.fetch(key)} is invalid" unless valid
+          end
+          %i[port connect_timeout].each do |key|
+            next unless options.key?(key)
+
+            value = options.fetch(key).to_s
+            maximum = key == :port ? 65_535 : 2_147_483_647
+            unless value.match?(/\A\d+\z/) && value.to_i.between?(1, maximum)
+              raise ArgumentError, "#{CONNECTION_OPTIONS.fetch(key)} must be a positive integer within range"
+            end
+          end
+          if options[:sslmode] && !%w[disable allow prefer require verify-ca verify-full].include?(options[:sslmode])
+            raise ArgumentError, "netdisco.db_sslmode is invalid"
+          end
+          options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+        end
+
+        # 纯校验 SQL、绑定参数和清单预算，不连接数据库或打印查询内容。
         def self.options(query:, query_params: [], **values)
           unless query.is_a?(String) && !query.strip.empty? && !query.include?("\0")
             raise ArgumentError, "query must be a nonempty SQL string without NUL"
@@ -35,6 +64,7 @@ module Net
           ).freeze
         end
 
+        # 复制并校验查询与连接选项；真正连接由 devices 的资源作用域管理。
         def initialize(connection_options:, **options)
           @options = self.class.options(**options)
           @connection_options = validate_connection_options!(connection_options)
@@ -48,8 +78,10 @@ module Net
           connected = false
           begin
             Timeout.timeout(budget.remaining, Client::InventoryTimeout) do
-              # 从握手开始持有连接；PG.connect 尚未返回时被超时中断，调用方无法负责关闭它。
-              connection = PG::Connection.connect_start(@connection_options)
+              # 先取得连接句柄再交付超时，确保异常到达时 ensure 能显式关闭连接。
+              Thread.handle_interrupt(Client::InventoryTimeout => :never) do
+                connection = PG::Connection.connect_start(@connection_options)
+              end
               # PostgreSQL NOTICE 可能包含 SQL 或数据，不交给 libpq 默认的 stderr 输出器。
               connection.set_notice_processor { |_notice| nil }
               wait_for_connection(connection, budget)
@@ -103,36 +135,22 @@ module Net
           end
         end
 
+        # 数据库名不得嵌入 URI/conninfo；合法选项仍受清单总期限及只读查询边界约束。
         def validate_connection_options!(options)
-          unless options.is_a?(Hash) && (options.keys - CONNECTION_ENV.keys).empty?
+          unless options.is_a?(Hash) && (options.keys - CONNECTION_OPTIONS.keys).empty?
             raise ArgumentError, "connection_options must contain supported PostgreSQL connection keys"
           end
           REQUIRED_CONNECTION_KEYS.each do |key|
             value = options[key]
             unless value.is_a?(String) && !value.strip.empty?
-              raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} is required"
-            end
-          end
-          options.each do |key, value|
-            valid = value.is_a?(String) && !value.empty? && !value.include?("\0")
-            valid ||= %i[port connect_timeout].include?(key) && value.is_a?(Integer)
-            raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} is invalid" unless valid
-          end
-          %i[port connect_timeout].each do |key|
-            next unless options.key?(key)
-
-            value = options.fetch(key).to_s
-            maximum = key == :port ? 65_535 : 2_147_483_647
-            unless value.match?(/\A\d+\z/) && value.to_i.between?(1, maximum)
-              raise ArgumentError, "#{CONNECTION_ENV.fetch(key)} must be a positive integer within range"
+              raise ArgumentError, "#{CONNECTION_OPTIONS.fetch(key)} is required"
             end
+            raise ArgumentError, "#{CONNECTION_OPTIONS.fetch(key)} is invalid" if value.include?("\0")
           end
-          if options[:sslmode] && !%w[disable allow prefer require verify-ca verify-full].include?(options[:sslmode])
-            raise ArgumentError, "NETDISCO_DB_SSLMODE is invalid"
-          end
+          self.class.connection_policy(**options.slice(*POLICY_KEYS))
           # libpq 会把 dbname 中的 URI/conninfo 再解释为连接参数，不能借此绕过凭据来源。
           if options.fetch(:dbname).match?(/=|\Apostgres(?:ql)?:\/\//)
-            raise ArgumentError, "NETDISCO_DB_NAME must be a database name, not a connection string"
+            raise ArgumentError, "ND_DB_NAME must be a database name, not a connection string"
           end
           options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
         end

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

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
 require "ipaddr"
+require_relative "../../connector"
 require_relative "../storage/saved_config"
+require_relative "client"
 
 module Net
   module Connector
@@ -15,6 +17,9 @@ module Net
           super(*frozen_values, **frozen_attributes)
         end
 
+        # Ruby 3.2 的 Data#with 不调用初始化；更新也须复制并冻结外部字符串。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         # 将 Netdisco 清单记录转换为可规划的设备对象。
         def self.from_row(row, rules:)
           valid = row.is_a?(Hash) && row["ip"].is_a?(String) && !row["ip"].empty? &&

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

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 require_relative "../engine/error_metadata"
+require_relative "../engine/errors"
+require_relative "../device/local_backup"
+require_relative "../device/tftp/receipt"
+require_relative "../storage/private_file"
 
 module Net
   module Connector
@@ -26,6 +30,9 @@ module Net
                 verification: verification == :device_reported ? verification : nil)
         end
 
+        # 更新也经过初始化白名单；Ruby 3.2 的原生 Data#with 会跳过这一边界。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         # 读取已知错误的白名单属性后立即丢弃异常引用，不把回调对象保留进批次。
         def self.from(error, backup: nil, phase: nil)
           return unless error
@@ -40,6 +47,7 @@ module Net
           new(error_type: "StandardError", phase: phase)
         end
 
+        # 只有本库错误与匹配的业务回执才能证明提交状态，不能采信任意对象自报成功。
         def self.completion_fields(error, backup, phase)
           if error.instance_of?(BackupPersistenceError) && backup.instance_of?(Backup) && error.backup.equal?(backup)
             { artifact_state: error.receipt.state, artifact_phase: error.receipt.phase,

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

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "digest"
+require_relative "../storage"
+require_relative "client"
+require_relative "settings"
+require_relative "device"
+require_relative "worker"
+require_relative "result_store"
+require_relative "planner"
+require_relative "report"
+require_relative "tftp_verification"
+require_relative "tftp_archive"
 
 module Net
   module Connector
@@ -120,8 +129,8 @@ module Net
 
           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
+          host_counts = devices.each_with_object(Hash.new(0)) { |device, counts| counts[device.host] += 1 if device.host }
+          devices.map { |device| host_counts[device.host] > 1 ? device.with(issue: :duplicate_host) : device }.freeze
         end
 
         def build_plan(mode, limit, settings_snapshot, allow_fixed_name_reuse: false)

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

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "ipaddr"
+require_relative "device"
+require_relative "batch"
+
 module Net
   module Connector
     module Netdisco
@@ -21,6 +25,9 @@ module Net
         # 按清单顺序返回选中的设备。
         def selected = ready.map(&:last)
 
+        # 更新与新建共用容器复制边界，不能因 Ruby 版本差异共享可变任务槽位。
+        def with(**attributes) = attributes.empty? ? self : self.class.new(**to_h.merge(attributes))
+
         # 在任何设备 I/O 前校验完整快照，外部构造或修改的计划也必须遵守相同约束。
         def validate!
           raise ArgumentError, "plan mode must be backup or tftp" unless %i[backup tftp].include?(mode)
@@ -68,10 +75,16 @@ module Net
 
         # 外部快照也遵守清单入口的地址唯一性；采样不能把重复设备重新变为可执行。
         def validate_duplicate_hosts!
-          groups = inventory.group_by { |device| device.host && IPAddr.new(device.host).to_s }
-          return unless groups.any? { |host, devices| host && devices.size > 1 && devices.any? { |device| device.issue != :duplicate_host } }
+          issues_by_host = {}
+          inventory.each do |device|
+            next unless device.host
 
-          raise ArgumentError, "plan duplicate hosts must be marked as duplicate_host"
+            host = IPAddr.new(device.host).to_s
+            if issues_by_host.key?(host) && (issues_by_host[host] != :duplicate_host || device.issue != :duplicate_host)
+              raise ArgumentError, "plan duplicate hosts must be marked as duplicate_host"
+            end
+            issues_by_host[host] = device.issue
+          end
         end
 
         # 跳过结果不携带执行产物；文件冲突必须有本批次实际执行的目标作为依据。

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "plan"
+require_relative "batch"
 
 module Net
   module Connector
@@ -20,7 +21,7 @@ module Net
           end
           selected_tasks = if limit_per_vendor
                              ready_tasks.group_by { |_index, device| device.vendor }.values.flat_map do |tasks|
-                               tasks.sort_by { |_index, device| device.host }.first(limit_per_vendor)
+                               tasks.min_by(limit_per_vendor) { |_index, device| device.host }
                              end
                            else
                              ready_tasks

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

@@ -1,12 +1,17 @@
 # frozen_string_literal: true
 
 require "io/console"
+require_relative "../engine/error_metadata"
+require_relative "../engine/log/event"
 
 module Net
   module Connector
     module Netdisco
       # 共享一个实例接收并发会话事件和任务回调；人类进度不混入 JSON 输出。
       class Progress
+        attr_reader :output_error
+
+        # 调用方保留输出 IO 所有权；同一个互斥锁保护心跳、事件和任务计数。
         def initialize(io: $stderr, enabled: true, verbose: false)
           @io, @enabled, @verbose = io, enabled, verbose
           @tty = io.respond_to?(:tty?) && io.tty?
@@ -23,6 +28,7 @@ module Net
           write(nil, "正在读取 Netdisco 设备清单")
         end
 
+        # 以实际选中设备初始化进度，清单中被跳过的条目不计入执行任务总数。
         def plan(plan, concurrency:, limit_per_vendor: nil)
           @mutex.synchronize do
             @total = plan.ready.size
@@ -33,6 +39,7 @@ module Net
           end
         end
 
+        # 任务开始时记录单调时钟与登录阶段，不把开始通知当作连接成功。
         def start(device)
           @mutex.synchronize do
             @active += 1
@@ -71,6 +78,7 @@ module Net
           write(fields[:host], message) if message
         end
 
+        # 只消费最终任务结果，分别展示已保存、设备报告上传和服务器核验状态。
         def result(outcome)
           @mutex.synchronize do
             @completed += 1
@@ -100,6 +108,7 @@ module Net
           end
         end
 
+        # 使用报告的成功策略与受控失败分类，进度百分比不代替业务成功判定。
         def finish(report)
           return unless @enabled
 
@@ -144,12 +153,13 @@ module Net
           end
         end
 
+        # 心跳仅在持锁后刷新显示，不改变设备任务或完成计数。
         def tick
           @mutex.synchronize { refresh(force: true) }
         end
 
-        def location(path)
-          write(nil, "报告：#{path}")
+        def location(path, label: "报告")
+          write(nil, "#{label}：#{path}")
         end
 
         private
@@ -178,6 +188,7 @@ module Net
           format("%02d:%02d:%02d", total / 3600, total / 60 % 60, total % 60)
         end
 
+        # 吞吐与预计剩余时间使用单调时钟；异构设备的估算不能视为任务期限。
         def timing_line
           elapsed = [monotonic - (@run_started || @started_at), 0].max
           rate = elapsed.positive? ? @completed / elapsed : 0
@@ -196,6 +207,7 @@ module Net
           line
         end
 
+        # TTY 原地刷新最多每秒五次；详细事件和重定向输出采用独立显示路径。
         def refresh(force: false)
           return unless @enabled && @tty && !@verbose
 
@@ -209,9 +221,7 @@ module Net
 
           clear_refresh
           @last_status = lines
-          @io.write(lines.join("\n"))
-          @io.flush
-          @refreshing = true
+          @refreshing = write_output(lines.join("\n"))
         end
 
         # 留一列避免终端自动换行，窄窗口也不会留下旧进度行。
@@ -228,10 +238,11 @@ module Net
           line
         end
 
+        # 擦除前一次实际显示的行数，避免短文本或窄终端留下旧状态。
         def clear_refresh
           return unless @refreshing
 
-          @io.write("\r\e[2K" + ("\e[1A\r\e[2K" * (@last_status.length - 1)))
+          write_output("\r\e[2K" + ("\e[1A\r\e[2K" * (@last_status.length - 1)))
           @refreshing = false
         end
 
@@ -246,8 +257,21 @@ module Net
           clear_refresh
           line = "[#{Time.now.strftime("%H:%M:%S")}] [#{@completed}/#{@total}#{percent} 执行中 #{@active}] [#{host || "批次"}] #{message}"
           line = "[#{Time.now.strftime("%H:%M:%S")}] #{host ? "#{host}  " : ""}#{message}" unless @verbose
-          @io.write(line.gsub(/[[:cntrl:]]/, " ") + "\n")
+          write_output(line.gsub(/[[:cntrl:]]/, " ") + "\n")
+        end
+
+        # 显示失败只停用进度输出；批次仍保存回执和事件，并记录一次受控回调诊断。
+        # 所有调用均持有 @mutex，心跳与设备线程不会重复访问已失败的输出。
+        def write_output(text)
+          return false unless @enabled
+
+          @io.write(text)
           @io.flush
+          true
+        rescue IOError, SystemCallError => error
+          @output_error = { host: nil, error_type: ErrorMetadata.type(error.class.name) }.freeze
+          @enabled = false
+          false
         end
       end
     end

data/lib/net/connector/netdisco/report/files.rb

@@ -9,6 +9,7 @@ module Net
       class Report
         # 示例与批次入口共享唯一摘要结构；保存结果先于终端成功提示。
         class Files
+          # 文本和 JSON 分别提交；失败时尝试保存诊断，并保留已提交的 JSON 位置。
           def self.write(report, directory:, plan:, concurrency:)
             destination = File.join(directory, "summary.json")
             finalized = report.with(report_location: destination)
@@ -16,8 +17,9 @@ module Net
             Storage::PrivateFile.write(destination, JSON.pretty_generate(finalized.summary))
             finalized
           rescue StandardError => error
-            location = committed_location(error, destination)
-            failed = report.with_report_error(error, location: location)
+            location = committed_location(error, destination) || report.report_location
+            # 更新已有诊断时仍保留首次报告故障，以及之前已提交的报告位置。
+            failed = report.report_error ? report.with(report_location: location) : report.with_report_error(error, location: location)
             begin
               saved = failed.with(report_location: destination)
               Storage::PrivateFile.write(destination, JSON.pretty_generate(saved.summary))