net-connector 0.5.0 → 0.7.0

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,21 +70,13 @@ module Net
 
         # 文件、环境变量、命令行按优先级覆盖，凭据仍只来自环境变量。
         def settings_for(options)
-          defaults = options[:config] ? ConfigFile.load(options[:config]) : {}
-          values = {}
-          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
 
         # 导出已有配置不创建清单或设备连接。
         def export_config(settings, options)
           path = Storage::SavedConfig.new(directory: settings.backup_directory)
-                                        .export(host: options[:export], output: options[:output], io: @output)
+                                     .export(host: options[:export], output: options[:output], io: @output)
           @output.puts JSON.generate(host: options[:export], output: path) if path
         end
 
@@ -107,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)
@@ -116,24 +111,21 @@ 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 }
             args.on("--show-config", "显示生效的非敏感设置") { options[:show_config] = true }
             args.on("--plan", "预览设备清单，不连接设备") { options[:plan] = true }
             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
@@ -151,15 +143,19 @@ 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]
           raise ArgumentError, "--all 不能与 --limit-per-vendor 同时使用" if options[:all] && options[:limit]
-          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[:source] || options[:query] || options[:query_params])
+            raise ArgumentError, "--export 不能与清单查询选项同时使用"
+          end
+          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

@@ -96,7 +96,7 @@ module Net
           @options.fetch(:max_pages).times do |index|
             uri = endpoint("api/v1/search/device")
             uri.query = URI.encode_www_form(fields: FIELDS.join(","), limit: @options.fetch(:page_size),
-                                           offset: index * @options.fetch(:page_size))
+                                            offset: index * @options.fetch(:page_size))
             page = request_json(uri, authorized_get(uri, token), budget, allow_empty: true, query_fallback: true)
             validate_rows!(page, budget)
             return rows.uniq if page.empty?
@@ -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,12 +268,13 @@ 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)
+
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end

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

@@ -9,7 +9,10 @@ module Net
       # 命令行使用的无凭据 YAML 配置，环境变量优先。
       class ConfigFile
         FIELDS = {
-          "netdisco" => { "url" => ["NETDISCO_URL", :string],
+          "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],
@@ -17,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 配置并映射到环境变量格式。
@@ -94,8 +98,8 @@ module Net
             end
 
             value.join(",")
-          when :json
-            expected = name == "device_rules" ? Array : Hash
+          when :json, :json_array
+            expected = type == :json_array || name == "device_rules" ? Array : Hash
             raise ArgumentError, "#{section}.#{name} must be a #{expected}" unless value.is_a?(expected)
 
             JSON.generate(value)

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "timeout"
+require_relative "client"
+
+module Net
+  module Connector
+    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"
+        }.freeze
+        REQUIRED_CONNECTION_KEYS = %i[host dbname user password].freeze
+        DEFAULTS = Client::DEFAULTS.except(:allow_insecure_http).freeze
+
+        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"
+          end
+          unless query_params.is_a?(Array) && query_params.all? { |value|
+            value.nil? || value == true || value == false || value.is_a?(Integer) ||
+              (value.is_a?(Float) && value.finite?) || (value.is_a?(String) && !value.include?("\0"))
+          }
+            raise ArgumentError, "query_params must be an array of JSON scalar values without NUL"
+          end
+          raise ArgumentError, "unknown database inventory options" unless (values.keys - DEFAULTS.keys).empty?
+
+          Client.options(**values).slice(*DEFAULTS.keys).merge(
+            query: query.dup.freeze,
+            query_params: query_params.map { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          ).freeze
+        end
+
+        def initialize(connection_options:, **options)
+          @options = self.class.options(**options)
+          @connection_options = validate_connection_options!(connection_options)
+        end
+
+        # 每次查询独占连接和游标；只有全部结果验证成功后才把清单交给 Fleet。
+        def devices
+          require "pg"
+          budget = InventoryBudget.new(@options, clock: method(:monotonic))
+          connection = nil
+          connected = false
+          begin
+            Timeout.timeout(budget.remaining, Client::InventoryTimeout) do
+              # 从握手开始持有连接；PG.connect 尚未返回时被超时中断，调用方无法负责关闭它。
+              connection = PG::Connection.connect_start(@connection_options)
+              # PostgreSQL NOTICE 可能包含 SQL 或数据，不交给 libpq 默认的 stderr 输出器。
+              connection.set_notice_processor { |_notice| nil }
+              wait_for_connection(connection, budget)
+              connected = true
+              # 使用 pg 可中断的 Ruby 等待接口；底层 socket 仍以非阻塞方式工作。
+              connection.setnonblocking(false)
+              connection.set_client_encoding("UTF8")
+              connection.exec("BEGIN READ ONLY").clear
+              set_statement_timeout(connection, budget)
+              # 即使没有参数也走扩展查询协议，由 PostgreSQL 拒绝多语句和非查询命令。
+              connection.exec_params("DECLARE net_connector_inventory NO SCROLL CURSOR FOR\n#{@options.fetch(:query)}",
+                                     @options.fetch(:query_params)).clear
+              rows = inventory(connection, budget)
+              connection.exec("ROLLBACK").clear
+              budget.remaining
+              rows
+            end
+          rescue Client::Error => error
+            raise error, cause: nil
+          rescue PG::QueryCanceled
+            raise Client::InventoryTimeout, cause: nil
+          rescue PG::Error, IOError, SystemCallError
+            code = connected ? :query_failed : :connection_failed
+            raise Client::Error.new("Netdisco database #{code.to_s.tr("_", " ")}", code: code), cause: nil
+          ensure
+            connection&.finish
+          end
+        end
+
+        def inspect = "#<#{self.class}>"
+
+        private
+
+        def wait_for_connection(connection, budget)
+          deadline = monotonic + @connection_options.fetch(:connect_timeout, budget.remaining).to_f
+          loop do
+            status = connection.connect_poll
+            return if status == PG::PGRES_POLLING_OK
+            raise PG::ConnectionBad unless [PG::PGRES_POLLING_READING, PG::PGRES_POLLING_WRITING].include?(status)
+
+            remaining = [budget.remaining, deadline - monotonic].min
+            raise PG::ConnectionBad if remaining <= 0
+
+            socket = connection.socket_io
+            readers = status == PG::PGRES_POLLING_READING ? [socket] : nil
+            writers = status == PG::PGRES_POLLING_WRITING ? [socket] : nil
+            next if IO.select(readers, writers, [socket], remaining)
+
+            budget.remaining
+            raise PG::ConnectionBad
+          end
+        end
+
+        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
+          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"
+            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
+          # 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"
+          end
+          options.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+        end
+
+        def set_statement_timeout(connection, budget)
+          milliseconds = [(budget.remaining * 1000).ceil, 2_147_483_647].min
+          connection.exec_params("SELECT set_config('statement_timeout', $1, true)", [milliseconds.to_s]).clear
+        end
+
+        def inventory(connection, budget)
+          rows = []
+          @options.fetch(:max_pages).times do
+            set_statement_timeout(connection, budget)
+            count = fetch_page(connection, rows, budget)
+            return rows if count < @options.fetch(:page_size)
+          end
+          raise Client::Error.new("Netdisco inventory exceeded max_pages", code: :max_pages), cause: nil
+        end
+
+        # 单行模式避免 libpq 先缓存整页；Ruby 只积累已经通过预算检查的白名单字段。
+        def fetch_page(connection, rows, budget)
+          connection.send_query_params("FETCH FORWARD #{@options.fetch(:page_size)} FROM net_connector_inventory", [])
+          connection.set_single_row_mode
+          count = 0
+          response_bytes = 0
+          while (result = connection.get_result)
+            begin
+              result.check
+              response_bytes = append_rows(result, rows, budget, response_bytes)
+              count += result.ntuples
+            ensure
+              result.clear
+            end
+          end
+          count
+        end
+
+        def append_rows(result, rows, budget, response_bytes)
+          fields = result.fields
+          unless fields.include?("ip") && fields.uniq == fields
+            raise Client::Error.new("Netdisco database query must return unique column names including ip",
+                                    code: :invalid_inventory), cause: nil
+          end
+          budget.consume_devices(result.ntuples)
+          result.each do |row|
+            # 未选用的列也占传输预算，但不会进入清单、计划或报告。
+            size = row.sum { |key, value| key.bytesize + (value&.bytesize || 0) }
+            budget.consume_bytes(size, response_bytes: response_bytes)
+            response_bytes += size
+            unless row["ip"].is_a?(String) && !row["ip"].strip.empty?
+              raise Client::Error.new("Netdisco returned an invalid device inventory", code: :invalid_inventory), cause: nil
+            end
+            rows << row.slice(*Client::FIELDS)
+          end
+          response_bytes
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+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