net-connector 0.4.1 → 0.4.2

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

@@ -1,41 +1,95 @@
 # frozen_string_literal: true
 
 require "json"
-require "uri"
 
 module Net
   module Connector
     module Netdisco
-      # 使用时从环境中读取配置，并提供明确的默认值。
+      # 活的凭据来源与不可变的批次策略分开保存；只有明确列出的非敏感字段进入快照。
       class Settings
         DEFAULT_BACKUP_DIRECTORY = "backups"
         DEFAULT_CONCURRENCY = 4
         MAX_CONCURRENCY = 50
-        DEFAULT_PAGE_SIZE = 500
+        DEFAULT_PAGE_SIZE = Client::DEFAULTS.fetch(:page_size)
+        UNSET = Object.new.freeze
+        private_constant :UNSET
 
-        # 加载 YAML 配置，并使环境变量覆盖文件配置。
         def self.from_file(path, env: ENV)
-          new(env: ConfigFile.load(path).merge(env.to_h))
+          new(env: env, defaults: ConfigFile.load(path))
         end
 
-        # 保存当前批次读取配置所用的环境映射。
-        def initialize(env: ENV)
-          @env = env
+        def initialize(env: ENV, defaults: {}, overrides: {}, policy: nil, fixed: false)
+          @env, @defaults, @overrides = env, defaults, overrides
+          @policy, @fixed = policy, fixed
         end
 
-        # 使用 Netdisco 地址和认证信息创建客户端。
-        def client
-          options = { url: required("NETDISCO_URL"), page_size: integer("NETDISCO_PAGE_SIZE", DEFAULT_PAGE_SIZE) }
-          if present?(@env["NETDISCO_API_KEY"])
-            options[:api_key] = @env["NETDISCO_API_KEY"]
-          else
-            options[:username] = required("NETDISCO_USERNAME")
-            options[:password] = required("NETDISCO_PASSWORD")
+        # 快照自身不保留 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
+          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)
+          end
+          self.class.new(env: values.freeze, fixed: true).validate!(mode: mode).freeze
+        end
+
+        # CLI 的一次预览/执行使用同一策略；凭据仍指向原环境映射，允许逐设备轮换。
+        def for_run(mode: :backup)
+          self.class.new(env: @env, defaults: @defaults, overrides: @overrides, policy: snapshot(mode: mode))
+        end
+
+        def validate!(mode:)
+          unless %i[backup tftp inventory show_config export].include?(mode)
+            raise ArgumentError, "unknown settings validation mode"
+          end
+          backup_directory
+          return self if mode == :export
+
+          client_options
+          rules
+          concurrency
+          limit_per_vendor
+          log_directory
+          connection_options
+          Net::Connector.vendors.each { |vendor| connection_options(vendor) }
+          tftp_source_files.each_value { |source| TftpTarget.validate_source_file!(source) }
+          tftp_vrfs
+          TftpTarget.new(host: tftp_server, path: "preflight.cfg") if tftp_server
+          self
+        end
+
+        def client(policy: snapshot(mode: :inventory))
+          options = policy.client_options
+          raise ArgumentError, "NETDISCO_URL is required" unless options.fetch(:url)
+
+          authentication = if (token = secret_value("NETDISCO_API_KEY"))
+                             { api_key: token }
+                           else
+                             { username: required_secret("NETDISCO_USERNAME"), password: required_secret("NETDISCO_PASSWORD") }
+                           end
+          Client.new(**options, **authentication)
+        end
+
+        # 原生客户端和 --show-config 共享同一预算、地址与 HTTP 策略校验。
+        def client_options
+          options = Client::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
-          Client.new(**options)
+          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 rules
           Rules.new(include_hosts: list("NET_CONNECTOR_INCLUDE_HOSTS"),
                     exclude_hosts: list("NET_CONNECTOR_EXCLUDE_HOSTS"),
@@ -45,15 +99,13 @@ module Net
                     mappings: json("NET_CONNECTOR_DEVICE_RULES", []))
         end
 
-        # 读取并展开本地备份目录。
         def backup_directory
-          path = @env.fetch("NET_CONNECTOR_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
+          path = raw("NET_CONNECTOR_BACKUP_DIRECTORY", DEFAULT_BACKUP_DIRECTORY)
           raise ArgumentError, "NET_CONNECTOR_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
@@ -61,121 +113,178 @@ module Net
           count
         end
 
-        # 确定厂商采样数量：本地默认全量，TFTP 默认每厂商五台。
         def limit_per_vendor(tftp: false)
-          return integer("NET_CONNECTOR_SAMPLE_PER_VENDOR", 5) if @env.key?("NET_CONNECTOR_SAMPLE_PER_VENDOR")
-
-          5 if tftp
+          count = if configured?("NET_CONNECTOR_SAMPLE_PER_VENDOR")
+                    integer("NET_CONNECTOR_SAMPLE_PER_VENDOR", 5) unless raw("NET_CONNECTOR_SAMPLE_PER_VENDOR").nil?
+                  elsif tftp
+                    5
+                  end
+          Planner.validate_limit!(count)
+          count
         end
 
-        # 读取厂商的 TFTP 源文件配置，并提供华为启动配置默认路径。
         def tftp_source_files
-          files = { huawei: @env.fetch("NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
+          files = { huawei: raw("NET_CONNECTOR_HUAWEI_TFTP_SOURCE_FILE", "flash:/startup.cfg") }
           %i[h3c h3c_wireless].each do |vendor|
             key = "NET_CONNECTOR_#{vendor.to_s.upcase}_TFTP_SOURCE_FILE"
-            files[vendor] = @env.fetch(key) if @env.key?(key)
+            files[vendor] = raw(key) if configured?(key)
           end
           files
         end
 
-        # 读取各厂商 TFTP 出口 VRF 的名称映射。
         def tftp_vrfs
-          raw = json("NET_CONNECTOR_TFTP_VRFS", {})
-          raise ArgumentError, "NET_CONNECTOR_TFTP_VRFS must be a JSON object" unless raw.is_a?(Hash)
+          mapping = json("NET_CONNECTOR_TFTP_VRFS", {})
+          raise ArgumentError, "NET_CONNECTOR_TFTP_VRFS must be a JSON object" unless mapping.is_a?(Hash)
+
+          self.class.validate_vrfs!(mapping.transform_keys(&:to_sym))
+        end
+
+        def self.validate_vrfs!(vrfs)
+          unless vrfs.is_a?(Hash) && vrfs.all? { |vendor, name|
+            %i[cisco_nxos hillstone].include?(vendor) && name.is_a?(String) &&
+              name.match?(/\A[A-Za-z0-9_][A-Za-z0-9_.-]*\z/)
+          }
+            raise ArgumentError, "vrfs must map supported vendor names to safe VRF names"
+          end
+          vrfs
+        end
 
-          raw.transform_keys(&:to_sym)
+        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")
+          )
+          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 credentials_for(device)
+        # 兼容原入口；Fleet 传入本批策略，独立调用则读取当前策略和当前秘密。
+        def credentials_for(device, policy: snapshot(mode: :backup))
+          credentials = device_credentials_for(device)
+          policy.connection_options(device.vendor).merge(credentials) if credentials
+        end
+
+        def device_credentials_for(device)
           prefix = "NET_CONNECTOR_#{device.vendor.to_s.upcase}_"
-          username = value(prefix + "USERNAME") || value("NET_CONNECTOR_DEVICE_USERNAME")
+          username = secret_value(prefix + "USERNAME") || secret_value("NET_CONNECTOR_DEVICE_USERNAME")
           return nil unless username
 
-          {
-            username: username,
-            password: value(prefix + "PASSWORD") || value("NET_CONNECTOR_DEVICE_PASSWORD"),
-            enable_password: value(prefix + "ENABLE_PASSWORD") || value("NET_CONNECTOR_ENABLE_PASSWORD"),
-            protocol: (value(prefix + "PROTOCOL") || value("NET_CONNECTOR_PROTOCOL") || "ssh").to_sym,
-            log_level: (value("NET_CONNECTOR_LOG_LEVEL") || "info").to_sym,
-            known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
-            host_key_policy: (value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict").to_sym
-          }
+          { 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") }
         end
 
-        # 读取并展开设备日志目录。
         def log_directory
           path = value("NET_CONNECTOR_LOG_DIRECTORY")
           File.expand_path(path) if path
         end
 
-        # 仅展示非敏感配置，不输出设备凭据或 API 密钥。
-        # 生成不包含凭据的可展示配置。
         def public_config
-          rules
-          url = value("NETDISCO_URL")
-          if url
-            uri = URI.parse(url)
-            unless uri.is_a?(URI::HTTP) && uri.host && !uri.userinfo && !uri.query && !uri.fragment
-              raise ArgumentError, "NETDISCO_URL must be a base URL without credentials or query"
-            end
-          end
+          snapshot(mode: :show_config).send(:config_hash)
+        end
+
+        def inspect = "#<#{self.class}>"
+
+        private
+
+        def config_hash
           {
-            netdisco: { url: url, page_size: integer("NETDISCO_PAGE_SIZE", DEFAULT_PAGE_SIZE) },
-            backup: { directory: backup_directory, concurrency: concurrency,
-                      limit_per_vendor: limit_per_vendor },
+            netdisco: client_options,
+            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", []) },
-            ssh: { protocol: value("NET_CONNECTOR_PROTOCOL") || "ssh",
-                   known_hosts: value("NET_CONNECTOR_KNOWN_HOSTS"),
-                   host_key_policy: value("NET_CONNECTOR_HOST_KEY_POLICY") || "strict",
-                   log_directory: log_directory,
-                   log_level: value("NET_CONNECTOR_LOG_LEVEL") || "info" },
-            tftp: { server: value("TFTP_HOST"), vrfs: tftp_vrfs.transform_keys(&:to_s) }
+            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
+            ),
+            tftp: { server: tftp_server, vrfs: tftp_vrfs.transform_keys(&:to_s), source_files: tftp_source_files }
           }
-        rescue URI::InvalidURIError
-          raise ArgumentError, "NETDISCO_URL is invalid"
         end
 
-        private
+        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 @overrides.fetch(key) if @overrides.key?(key)
+          return @env.fetch(key) if @env.key?(key)
+
+          @defaults.fetch(key, default)
+        end
+
+        def configured?(key) = !raw(key, UNSET).equal?(UNSET)
 
-        # 解析指定环境变量中的 JSON 配置。
         def json(key, default)
-          raw = value(key)
-          raw ? JSON.parse(raw) : default
+          text = value(key)
+          text ? JSON.parse(text) : default
         rescue JSON::ParserError
-          raise ArgumentError, "#{key} must be valid JSON"
+          raise ArgumentError, "#{key} must be valid JSON", cause: nil
         end
 
-        # 解析逗号分隔的环境变量列表。
-        def list(key) = @env.fetch(key, "").split(",").map(&:strip).reject(&:empty?)
+        def list(key) = (value(key) || "").split(",").map(&:strip).reject(&:empty?)
 
-        # 读取正整数配置并统一错误信息。
         def integer(key, default)
-          raw = @env.fetch(key, default)
-          value = Integer(raw.to_s, 10)
-          raise ArgumentError, "#{key} must be a positive integer" unless value.positive?
+          result = Integer(raw(key, default).to_s, 10)
+          raise ArgumentError unless result.positive?
 
-          value
+          result
         rescue ArgumentError, TypeError
-          raise ArgumentError, "#{key} must be a positive integer"
+          raise ArgumentError, "#{key} must be a positive integer", cause: nil
+        end
+
+        def optional_integer(key)
+          integer(key, nil) unless raw(key).nil?
+        end
+
+        def number(key, default)
+          input = raw(key, default)
+          result = input.is_a?(String) ? Float(input) : input
+          unless result.is_a?(Numeric) && result.real? && result.finite? && result.positive? && result.to_f.finite?
+            raise ArgumentError
+          end
+          result
+        rescue ArgumentError, TypeError
+          raise ArgumentError, "#{key} must be a positive finite number", cause: nil
+        end
+
+        def boolean(key, default)
+          result = raw(key, default)
+          return true if result == true || result == "true"
+          return false if result == false || result == "false"
+
+          raise ArgumentError, "#{key} must be true or false"
         end
 
-        # 读取非空字符串配置。
         def value(key)
-          result = @env[key]
+          result = raw(key)
+          raise ArgumentError, "#{key} must be a String" unless result.nil? || result.is_a?(String)
+
           result if present?(result)
         end
 
-        # 读取必填环境变量。
-        def required(key) = value(key) || (raise ArgumentError, "#{key} is required")
+        def secret_value(key)
+          result = @env[key]
+          raise ArgumentError, "#{key} must be a String" unless result.nil? || result.is_a?(String)
+
+          result.dup.freeze if present?(result)
+        end
 
-        # 判断环境变量是否为非空字符串。
+        def required_secret(key) = secret_value(key) || (raise ArgumentError, "#{key} is required")
         def present?(value) = value.is_a?(String) && !value.strip.empty?
       end
     end

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

@@ -31,25 +31,10 @@ module Net
                 Thread.current.report_on_exception = false
                 while (task = queue.pop)
                   index, device = task
-                  started_at = Time.now.utc
-                  begin
-                    on_start&.call(device)
-                  rescue StandardError => error
-                    callback_errors << { host: device.host, error_type: error.class.name }.freeze
-                  end
-                  result = begin
-                             yield device
-                           rescue StandardError => error
-                             on_error.call(device, error)
-                           end
-                  result = result.with(started_at: started_at, finished_at: Time.now.utc)
+                  result = run_task(device, on_error, on_start, callback_errors) { yield device }
                   outcomes[index] = result
                   Array(on_result).each do |callback|
-                    begin
-                      callback.call(result)
-                    rescue StandardError => error
-                      callback_errors << { host: device.host, error_type: error.class.name }.freeze
-                    end
+                    notify(callback, result, host: device.host, errors: callback_errors)
                   end
                 end
               ensure
@@ -76,6 +61,30 @@ module Net
           end
           Array.new(callback_errors.size) { callback_errors.pop }.freeze
         end
+
+        private
+
+        # 普通设备故障转换为结果，中断仍交给批次统一停止其余线程。
+        def run_task(device, on_error, on_start, callback_errors)
+          started_at = Time.now.utc
+          started = monotonic
+          notify(on_start, device, host: device.host, errors: callback_errors) unless on_start.nil?
+          result = begin
+                     yield
+                   rescue StandardError => error
+                     on_error.call(device, error)
+                   end
+          result.with(started_at: started_at, finished_at: Time.now.utc, duration_ms: ((monotonic - started) * 1000).round)
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        # 回调故障不覆盖设备结果，也不把异常消息中的凭据写入报告。
+        def notify(callback, value, host:, errors:)
+          callback.call(value)
+        rescue StandardError => error
+          errors << { host: host, error_type: error.class.name }.freeze
+        end
       end
     end
   end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../engine/errors"
+
+module Net
+  module Connector
+    class BackupBusy < Error; end
+
+    module Operations
+      # 路径锁在设备采集之前取得；锁文件长期保留，避免等待者落在已经删除的 inode 上。
+      class BackupLock
+        STORAGE_KEY = :net_connector_backup_delegation
+        private_constant :STORAGE_KEY
+
+        attr_reader :path
+
+        def self.lock_path(path)
+          destination = File.expand_path(path)
+          directory = File.realpath(File.dirname(destination))
+          # 锁名先折叠 Unicode 与大小写，避免大小写不敏感文件系统上的别名绕过互斥。
+          # 在区分大小写的文件系统上可能保守地合并两个锁，但不会改写目标文件名。
+          filename = File.basename(destination).b.force_encoding(Encoding::UTF_8)
+          filename = filename.valid_encoding? ? filename.unicode_normalize(:nfc).downcase(:fold).unicode_normalize(:nfc) : filename.b.downcase
+          File.join(directory, ".net-connector-#{Digest::SHA256.hexdigest(filename)}.lock")
+        end
+
+        def self.synchronize(path, **options, &block) = new(path, **options).synchronize(&block)
+
+        def initialize(path, timeout: 0, host: nil)
+          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+          unless timeout.is_a?(Numeric) && timeout.real? && timeout.finite? && timeout >= 0 && timeout.to_f.finite?
+            raise ArgumentError, "lock_timeout must be a nonnegative finite number"
+          end
+
+          @path = File.expand_path(path).freeze
+          @lock_path = self.class.lock_path(@path).freeze
+          @timeout, @host = timeout.to_f, host
+        end
+
+        def synchronize
+          # Fleet 只向下层备份借用一次；消费后清除，采集回调中的递归备份仍须竞争锁。
+          # Thread#[] 是 Fiber 局部存储；fork 后不能消费父进程的借用记录。
+          if Thread.current[STORAGE_KEY] == [@lock_path, Process.pid]
+            Thread.current[STORAGE_KEY] = nil
+            return yield self
+          end
+
+          file = nil
+          begin
+            file = open_lock
+            verify_lock!(file)
+            acquire(file)
+            verify_lock!(file)
+            @owner = [Process.pid, Fiber.current]
+            yield self
+          ensure
+            @owner = nil
+            file&.close
+          end
+        end
+
+        # 仅持有实际 flock 的同一 Fiber 可授权一次内层采集，避免把路径锁变成任意可重入锁。
+        def delegate
+          raise ThreadError, "backup path delegation requires lock ownership" unless @owner == [Process.pid, Fiber.current]
+
+          previous = Thread.current[STORAGE_KEY]
+          begin
+            Thread.current[STORAGE_KEY] = [@lock_path, Process.pid]
+            yield
+          ensure
+            Thread.current[STORAGE_KEY] = previous
+          end
+        end
+
+        private
+
+        def open_lock
+          File.open(@lock_path, File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600)
+        rescue Errno::ELOOP, Errno::EISDIR, Errno::ENXIO
+          raise ArgumentError, "backup lock must be a private regular file", cause: nil
+        end
+
+        def verify_lock!(file)
+          stat = file.stat
+          unless stat.file? && stat.uid == Process.euid && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600
+            raise ArgumentError, "backup lock must be an owned regular file with mode 0600 and one link"
+          end
+          current = File.lstat(@lock_path)
+          unless current.file? && current.dev == stat.dev && current.ino == stat.ino
+            raise ArgumentError, "backup lock path changed while acquiring ownership"
+          end
+        rescue Errno::ENOENT
+          raise ArgumentError, "backup lock path changed while acquiring ownership", cause: nil
+        end
+
+        def acquire(file)
+          deadline = monotonic + @timeout
+          loop do
+            acquired = file.flock(File::LOCK_EX | File::LOCK_NB)
+            return if acquired && (@timeout.zero? || monotonic < deadline)
+
+            remaining = deadline - monotonic
+            if remaining <= 0
+              raise BackupBusy.new("backup path already belongs to another operation", host: @host, phase: :backup), cause: nil
+            end
+            wait([remaining, 0.05].min)
+          end
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        def wait(seconds) = sleep(seconds)
+      end
+    end
+  end
+end

data/lib/net/connector/operations/local_backup.rb

@@ -2,6 +2,8 @@
 
 require "digest"
 require_relative "private_file"
+require_relative "backup_lock"
+require_relative "safe_file"
 
 module Net
   module Connector
@@ -15,19 +17,47 @@ module Net
       def changed? = [:created, :changed].include?(change)
     end
 
+    # 只携带库自身的提交回执和配置元数据，不携带正文或原始文件系统异常。
+    class BackupPersistenceError < Error
+      attr_reader :backup, :receipt, :underlying_type
+
+      def initialize(backup:, write_error:, host: nil)
+        unless backup.instance_of?(Backup) && Operations::PrivateFile.receipt_error?(write_error) &&
+               write_error.receipt.committed? && write_error.receipt.path == backup.path
+          raise ArgumentError, "backup persistence error requires a matching committed backup receipt"
+        end
+
+        @backup, @receipt = backup, write_error.receipt
+        @underlying_type = write_error.underlying_type
+        code = if write_error.instance_of?(Operations::PrivateFile::DirectorySyncUnsupported)
+                 :backup_durability_unsupported
+               elsif receipt.durable?
+                 :backup_finalize_failed
+               else
+                 :backup_persistence_unconfirmed
+               end
+        super(write_error.message, code: code, host: host, phase: :backup)
+      end
+    end
+
     module Operations
       class LocalBackup
         # 保存执行配置采集的设备对象。
         def initialize(device) = @device = device
 
         # 采集配置、识别变更并原子写入私有文件。
-        def call(path:)
-          raise ArgumentError, "path must be a nonempty String" unless path.is_a?(String) && !path.empty?
+        def call(path:, lock_timeout: 0)
+          host = @device.host if @device.respond_to?(:host)
+          BackupLock.synchronize(path, timeout: lock_timeout, host: host) { |lock| collect_and_write(lock.path) }
+        end
+
+        private
 
+        def collect_and_write(destination)
           contents = @device.running_config.value!
-          destination = File.expand_path(path)
           digest = Digest::SHA256.hexdigest(contents)
-          previous_digest = Digest::SHA256.file(destination).hexdigest if File.file?(destination) && !File.symlink?(destination)
+          previous = SafeFile.fingerprint(destination, missing: true, replace_symlink: true)
+          previous_digest = previous&.sha256
           change = if previous_digest.nil?
                      :created
                    elsif previous_digest == digest
@@ -36,12 +66,22 @@ module Net
                      :changed
                    end
 
-          if change != :unchanged || (File.stat(destination).mode & 0o777) != 0o600
-            PrivateFile.write(destination, contents)
+          backup = Backup.new(path: destination, bytes: contents.bytesize,
+                              sha256: digest, collected_at: Time.now.utc, change: change,
+                              previous_sha256: previous_digest)
+          if change != :unchanged || previous.mode != 0o600 || !SafeFile.same_entry?(destination, previous)
+            write_backup(backup, contents)
           end
-          Backup.new(path: destination, bytes: contents.bytesize,
-                     sha256: digest, collected_at: Time.now.utc, change: change,
-                     previous_sha256: previous_digest)
+          backup
+        end
+
+        def write_backup(backup, contents)
+          PrivateFile.write_receipt(backup.path, contents)
+        rescue PrivateFile::WriteError => error
+          raise unless PrivateFile.receipt_error?(error) && error.receipt.committed?
+
+          host = @device.host if @device.respond_to?(:host)
+          raise BackupPersistenceError.new(backup: backup, write_error: error, host: host), cause: nil
         end
       end
     end