zabbix_manager 5.1.5 → 5.1.6

data/lib/zabbix_manager/classes/hosts.rb

@@ -2,122 +2,232 @@
 
 class ZabbixManager
   class Hosts < Basic
-    # 与 Zabbix API 交互的主机方法名称
+    # 返回主机对应的 Zabbix API 模块名。
     def method_name
       "host"
     end
 
-    # 用于通过 Zabbix API 标识特定主机对象的 id 字段名称
+    # 使用技术主机名作为通用 CRUD 标识。
     def identify
       "host"
     end
 
-    # 在通过 Zabbix API 创建主机对象时使用的默认选项
+    # 返回创建主机时的克制默认值。
     def default_options
       {
-        host:           nil,
-        interfaces:     {
-          main:    1,
-          useip:   1,
-          type:    2,
-          ip:      nil,
-          dns:     "",
-          port:    161,
-          details: {
-            version:   2,
-            community: "public"
-          }
-        },
-        status:         0,
-        available:      1,
-        groups:         [],
-        proxy_hostid:   nil,
+        status: 0,
         inventory_mode: 1
       }
     end
 
-    # 通过 Zabbix API 从指定的 key 值获取主机对象数据
+    # 按主机 ID 查询完整主机及接口、群组和模板。
     def dump_by_id(data)
-      log "[DEBUG] 调用 dump_by_id 方法，参数: #{data.inspect}"
-
-      get_raw({
-                filter:      {
-                  key.to_sym => data[key.to_sym]
-                },
-                output:      "extend",
-                selectHosts: "shorten"
-              }
+      log "[DEBUG] Call dump_by_id with parameters: #{data.inspect}"
+      @client.api_request(
+        method: "host.get",
+        params: {
+          filter: { key.to_sym => data[key.to_sym] },
+          output: "extend",
+          selectGroups: "extend",
+          selectInterfaces: "extend",
+          selectParentTemplates: ["templateid", "host", "name"]
+        }
       )
     end
 
-    # 通过 Zabbix API 根据名称获取 Zabbix 对象的 ID
-    def get_ids_by_name(data)
-      log "[DEBUG] 调用 #{method_name}.get_ids_by_name 方法，参数: #{data.inspect}"
-
-      result = get_raw({
-                         filter: { name: [data].flatten },
-                         output: [key]
-                       }
+    # 从指定主机批量解除模板关联。
+    def unlink_templates(data)
+      result = @client.api_request(
+        method: "host.massRemove",
+        params: {
+          hostids: data[:hosts_id],
+          templateids: data[:templates_id]
+        }
       )
-      result.empty? ? nil : result.map { |i| { key.to_sym => i[key] } }
+      !result.empty?
     end
 
-    # 使用 Zabbix API 创建或更新 Zabbix 对象
-    def create_or_update(data)
-      # 输出调试日志，显示方法调用和参数信息
-      log "[DEBUG] 调用 #{method_name}.create_or_update 方法，参数: #{data.inspect}"
+    # 使用显式群组和接口创建主机，不注入隐藏凭据。
+    def create(data)
+      attributes = default_options.merge(data.deep_symbolize_keys)
+      validate_create_attributes!(attributes)
+      result = @client.api_request(method: "host.create", params: attributes)
+      first_id(result, "hostids")
+    end
 
-      # 获取 Zabbix 对象的 ID
-      hostid = get_id(identify.to_sym => data[identify.to_sym])
-      # 如果不存在对应的对象ID，则创建新对象
-      return create(data) unless hostid
+    # 规范化并校验设备定义，不执行远端查询或写入。
+    # 已存在设备允许只更新部分字段，新设备的群组和接口由 create 再次严格校验。
+    # @return [Hash]
+    def validate(data)
+      attributes = data.deep_symbolize_keys
+      raise Invalid, "host is required" if attributes[:host].blank?
 
-      # 获取对象的接口 ID
-      interface_id = get_interfaceid(hostid)
-      # 如果接口 ID 不存在，抛出异常
-      raise ZbxError, "#{data.inspect} get_interfaceid 查无记录" unless interface_id
+      hostinterfaces.validate(attributes[:interfaces]) if attributes.key?(:interfaces)
+      attributes
+    end
 
-      # 复制数据以避免修改原始数据
-      dump_data = data.dup
+    # 幂等同步主机元数据和显式接口，调用方保持业务字段权威。
+    def reconcile(data)
+      attributes = validate(data)
+      host = attributes.fetch(:host)
+
+      hostid = get_id(host: host)
+      unless hostid
+        outcome, hostid = @client.with_upsert_lock("host-create:#{host}") do
+          current_id = get_id(host: host)
+          current_id ? [:existing, current_id] : [:created, create(attributes)]
+        end
+        return hostid.to_i if outcome == :created
+      end
+
+      update_existing(hostid, attributes)
+    end
 
-      # 从数据中提取并删除 interfaces，并合并接口 ID
-      interfaces = dump_data.delete(:interfaces)&.merge(interfaceid: interface_id)
+    # 更新主机元数据，并把接口同步委托给带主机锁的接口模块。
+    # @return [Integer]
+    # @api private
+    private def update_existing(hostid, attributes)
+      attributes = attributes.dup
+
+      interfaces = Array.wrap(attributes.delete(:interfaces))
+      hostinterfaces.validate(interfaces)
+      update_attributes = attributes.merge(hostid: hostid)
+      @client.api_request(method: "host.update", params: update_attributes)
+      hostinterfaces.reconcile_for_host(hostid: hostid, interfaces: interfaces) if interfaces.any?
+      hostid.to_i
+    end
 
-      # 构建参数，包括 interfaces 和 Zabbix 对象的键值对
-      params = dump_data.merge(interfaces: interfaces).merge(key.to_sym => hostid.to_s)
+    # 查询指定主机的全部接口。
+    def interfaces_for(hostid)
+      hostinterfaces.for_host(hostid)
+    end
 
-      # 更新对象
-      update(params)
+    # 返回主机的第一个接口 ID；高频业务应优先使用 hostinterfaces。
+    def get_interface_id(hostid)
+      interfaces_for(hostid).first&.fetch("interfaceid", nil)
     end
 
-    # 从 API 中基于提供的 hostid 获取 Zabbix interface 的 id
-    def get_interfaceid(hostid)
-      log "[DEBUG] 调用 #{method_name}.get_interfaceid 方法，参数: #{hostid.inspect}"
+    # 按技术主机名查询主机 ID。
+    def get_host_id(name)
+      find_host_id(host: name)
+    end
 
-      result = @client.api_request(
-        method: "hostinterface.get",
-        params: { output: "interfaceid", hostids: hostid }
-      )
+    # 按可见名称查询主机 ID。
+    def get_hostid_by_name(name)
+      find_host_id(name: name)
+    end
+
+    # 用技术名、可见名或接口 IP/DNS 解析唯一主机。
+    def find_by_candidates(candidates)
+      matches = Array(candidates).filter_map { |candidate| candidate.to_s.strip.presence }.uniq.flat_map do |candidate|
+        hosts = [find_host_by_filter(host: candidate), find_host_by_filter(name: candidate)].compact
+        interface = find_interface_by_endpoint(candidate)
+        hosts << find_host_by_filter(hostid: interface["hostid"]) if interface
+        hosts
+      end
+      matches.uniq! { |host| host.fetch("hostid") }
+      if matches.length > 1
+        raise Conflict, "host candidates resolve to multiple hosts; provide an explicit host object"
+      end
+
+      matches.first
+    end
 
-      # 使用 dig 方法获取深层嵌套的值
-      interface_id = result&.dig(0, "interfaceid")&.to_i
+    # 按主机 ID 查询唯一主机，并返回表达式需要的技术名称。
+    # @return [Hash, nil]
+    def find_by_id(hostid)
+      find_host_by_filter(hostid: hostid)
+    end
 
-      # 如果获取接口 ID 失败，提供更具体的错误信息
-      raise ZbxError, "无法获取 #{hostid} 的接口 ID" if interface_id.nil?
+    # 批量启用或停用主机。
+    # @return [Array<Integer>]
+    def set_status(hostids, enabled:)
+      ids = Array(hostids).filter_map { |value| value.to_s.strip.presence }.uniq
+      raise Invalid, "hostids are required" if ids.empty?
 
-      interface_id
+      params = ids.map { |hostid| { hostid: hostid, status: enabled ? 0 : 1 } }
+      result = @client.api_request(method: "host.update", params: params)
+      Array(result.fetch("hostids")).map(&:to_i)
     end
 
-    # 在 Hosts 中使用 Zabbix API 取消关联/移除模板
-    def unlink_templates(data)
-      result = @client.api_request(
-        method: "host.massRemove",
-        params: {
-          hostids:   data[:hosts_id],
-          templates: data[:templates_id]
-        }
-      )
-      result.empty? ? false : true
+    # 把可见名称对应的主机更新为稳定技术标识。
+    def update_host_to_serial(data)
+      attributes = data.deep_symbolize_keys
+      hostid = get_hostid_by_name(attributes[:name])
+      return nil unless hostid
+
+      attributes.delete(:templates)
+      @client.api_request(method: "host.update", params: attributes.merge(hostid: hostid))
+      hostid.to_i
     end
+
+    private
+
+      # 校验创建主机所需的技术名、群组和接口。
+      def validate_create_attributes!(attributes)
+        raise Invalid, "host is required" if attributes[:host].blank?
+        raise Invalid, "groups are required when creating a host" if Array.wrap(attributes[:groups]).empty?
+        raise Invalid, "interfaces are required when creating a host" if Array.wrap(attributes[:interfaces]).empty?
+
+        attributes[:interfaces] = hostinterfaces.validate_for_create(attributes[:interfaces])
+      end
+
+      # 使用精确过滤查询唯一主机。
+      def find_host_by_filter(filter)
+        result = @client.api_request(
+          method: "host.get",
+          params: {
+            output: %w[hostid host name status],
+            filter: filter,
+            selectInterfaces: %w[interfaceid ip dns]
+          }
+        )
+        raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
+
+        result.first
+      end
+
+      # 按 IP 和 DNS 端点查询唯一主机接口。
+      def find_interface_by_endpoint(candidate)
+        matches = []
+        %i[ip dns].each do |field|
+          result = @client.api_request(
+            method: "hostinterface.get",
+            params: { filter: { field => candidate }, output: ["hostid"] }
+          )
+          matches.concat(result)
+        end
+        matches.uniq! { |interface| interface.fetch("hostid") }
+        raise Conflict, "interface endpoint #{candidate} belongs to multiple hosts" if matches.length > 1
+
+        matches.first
+      end
+
+      # 只查询唯一主机 ID。
+      def find_host_id(filter)
+        result = @client.api_request(
+          method: "host.get",
+          params: {
+            output: ["hostid"],
+            filter: filter
+          }
+        )
+        raise Conflict, "host lookup is ambiguous for #{filter.inspect}" if result.length > 1
+
+        result.first&.fetch("hostid", nil)
+      end
+
+      # 从 Zabbix 创建响应中提取首个整数 ID。
+      def first_id(result, key_name)
+        value = result.fetch(key_name).first
+        value && value.to_i
+      end
+
+      # 延迟构建接口模块并复用当前客户端。
+      # @return [HostInterfaces]
+      # @api private
+      def hostinterfaces
+        @hostinterfaces ||= HostInterfaces.new(@client)
+      end
   end
 end

data/lib/zabbix_manager/classes/httptests.rb

@@ -2,39 +2,37 @@
 
 class ZabbixManager
   class HttpTests < Basic
-    # 用于通过 Zabbix API 与 HttpTests 交互的方法名称
+    # 返回 Web 场景对象对应的 Zabbix API 方法前缀。
+    #
+    # @return [String]
     def method_name
       "httptest"
     end
 
-    # 用于通过 Zabbix API 标识特定 HttpTest 对象的 id 字段名称
+    # 返回 Web 场景用于业务识别的字段名。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 通过 Zabbix API 创建 HttpTest 对象时使用的默认选项
+    # 返回创建 Web 场景时使用的默认步骤列表。
+    #
+    # @return [Hash] Web 场景默认属性
     def default_options
       {
-        hostid: nil,
-        name:   nil,
-        steps:  []
+        steps: []
       }
     end
 
-    # 通过 Zabbix API 获取或创建 HttpTest 对象
-    def get_or_create(data)
-      log "[DEBUG] 使用参数调用 get_or_create: #{data.inspect}"
-
-      unless (id = get_id(name: data[:name], hostid: data[:hostid]))
-        id = create(data)
-      end
-      id
-    end
-
-    # 通过 Zabbix API 创建或更新 HttpTest 对象
-    def create_or_update(data)
-      httptestid = get_id(name: data[:name], hostid: data[:hostid])
-      httptestid ? update(data.merge(httptestid: httptestid)) : create(data)
+    # 生成由 Web 场景名称和所属主机构成的稳定查询条件。
+    #
+    # @param data [Hash] 包含 name 和 hostid 的 Web 场景属性
+    # @raise [KeyError] 缺少 name 或 hostid 时抛出
+    # @return [Hash] Web 场景唯一查询条件
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
     end
   end
 end

data/lib/zabbix_manager/classes/items.rb

@@ -2,94 +2,224 @@
 
 class ZabbixManager
   class Items < Basic
-    # 用于通过 Zabbix API 与 Items 交互的方法名称
+    DEFAULT_OPTIONS = {
+      delay: "1m",
+      history: "1h",
+      status: 0,
+      value_type: 3
+    }.freeze
+    ITEM_TYPES = [0, 2, 3, 5, 7, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22].freeze
+    REQUIRED_INTERFACE_TYPES = [0, 12, 16, 17, 20].freeze
+    REQUIRED_PARAMS_TYPES = [11, 13, 14, 15, 21, 22].freeze
+
+    # 返回监控项对应的 Zabbix API 模块名。
+    #
+    # @return [String]
     def method_name
       "item"
     end
 
-    # 用于通过 Zabbix API 标识特定 Item 对象的 id 字段名称
+    # 使用名称作为通用 CRUD 的业务标识。
+    #
+    # @return [String]
     def identify
       "name"
     end
 
-    # 通过 Zabbix API 创建 Item 对象时使用的默认选项
+    # 返回创建监控项时的克制默认值。
+    #
+    # @return [Hash]
     def default_options
-      {
-        name:                  nil,
-        key_:                  nil,
-        hostid:                nil,
-        delay:                 60,
-        history:               3600,
-        status:                0,
-        type:                  7,
-        snmp_community:        "",
-        snmp_oid:              "",
-        value_type:            3,
-        data_type:             0,
-        trapper_hosts:         "localhost",
-        snmp_port:             161,
-        units:                 "",
-        multiplier:            0,
-        delta:                 0,
-        snmpv3_securityname:   "",
-        snmpv3_securitylevel:  0,
-        snmpv3_authpassphrase: "",
-        snmpv3_privpassphrase: "",
-        formula:               0,
-        trends:                86_400,
-        logtimefmt:            "",
-        valuemapid:            0,
-        delay_flex:            "",
-        authtype:              0,
-        username:              "",
-        password:              "",
-        publickey:             "",
-        privatekey:            "",
-        params:                "",
-        ipmi_sensor:           ""
-      }
+      DEFAULT_OPTIONS.dup
+    end
+
+    # 使用主机和名称组成通用 CRUD 的查询边界。
+    #
+    # @param data [Hash] Needs to include name and hostid to properly identify Items via Zabbix API
+    # @raise [ApiError] Error returned when there is a problem with the Zabbix API call.
+    # @raise [TransportError] Error raised when HTTP status from Zabbix Server response is not a 200 OK.
+    # @return [Integer] Zabbix object id
+    def identity_filter(data)
+      attributes = data.deep_symbolize_keys
+      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+    end
+
+    # 查询主机监控项，可按稳定 key 集合过滤并选择关联对象。
+    # @return [Array<Hash>]
+    def for_host(hostid, keys: nil, output: "extend", select_preprocessing: nil, select_tags: nil)
+      raise Invalid, "hostid is required" if hostid.blank?
+
+      params = { hostids: hostid, output: output }
+      params[:filter] = { key_: keys } if keys.present?
+      params[:selectPreprocessing] = select_preprocessing if select_preprocessing
+      params[:selectTags] = select_tags if select_tags
+      @client.api_request(method: "item.get", params: params)
+    end
+
+    # 按主机和稳定 key 查询唯一监控项。
+    # @return [Hash, nil]
+    def find_by_key(hostid:, key:)
+      result = for_host(hostid, keys: key, output: ["itemid", "key_", "name"])
+      raise Conflict, "multiple items use key #{key} on host #{hostid}" if result.length > 1
+
+      result.first
     end
 
-    # 通过 Zabbix API 获取或创建 Item 对象
-    def get_or_create(data)
-      log "[DEBUG] 调用 #{method_name}.get_or_create 方法，参数: #{data.inspect}"
+    # 按 hostid + key_ 幂等创建或更新监控项。
+    # @return [Integer]
+    def upsert_by_key(data)
+      attributes = validate_item!(data)
 
-      if (id = get_id(name: data[:name], hostid: data[:hostid]))
-        id
+      current = find_by_key(hostid: attributes[:hostid], key: attributes[:key_])
+      if current
+        itemid = current.fetch("itemid")
+        @client.api_request(
+          method: "item.update",
+          params: attributes.except(:hostid).merge(itemid: itemid)
+        )
+        itemid.to_i
       else
-        create(data)
+        create_attributes = default_options.merge(attributes)
+        validate_create_item!(create_attributes)
+        result = @client.api_request(method: "item.create", params: create_attributes)
+        result.fetch("itemids").first.to_i
       end
     end
 
-    # 通过 Zabbix API 创建或更新 Item 对象
-    def create_or_update(data)
-      itemid = get_id(name: data[:name], hostid: data[:hostid])
-      itemid ? update(data.merge(itemid: itemid)) : create(data)
+    # 先校验整批数据，再按稳定 key 逐项幂等写入。
+    # @return [Array<Integer>]
+    def upsert_many(collection)
+      items = Array(collection).map { |data| validate_item!(data) }
+      identities = items.map { |item| [item[:hostid].to_s, item[:key_].to_s] }
+      duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
+      raise Invalid, "duplicate hostid + key_ identity #{duplicate.join(":")}" if duplicate
+
+      items.map { |item| upsert_by_key(item) }
     end
 
-    # 通过 Zabbix API 获取特定主机和接口下的监控项
-    def get_interface_items(hostid, name)
-      # 记录调试信息，标识方法调用以及传递的参数
-      log "[DEBUG] 调用 #{method_name}.get_interface_items，参数：hostid #{hostid.inspect}，name #{name.inspect}"
+    # 批量启用或停用监控项。
+    # @return [Array<Integer>]
+    def set_status(hostid:, itemids:, enabled:)
+      ids = normalized_ids(itemids, "itemids")
+      verify_host_ownership!(hostid, ids)
+      result = @client.api_request(
+        method: "item.update",
+        params: ids.map { |itemid| { itemid: itemid, status: enabled ? 0 : 1 } }
+      )
+      Array(result.fetch("itemids")).map(&:to_i)
+    end
 
-      # 自动剔除收尾空白字符，规范化接口名
-      _name = name&.gsub(%r{[^/0-9]}, "")&.strip
-      iface = "#{_name}("
+    # 批量删除明确指定的监控项。
+    # @return [Array<Integer>]
+    def delete_many(hostid:, itemids:)
+      ids = normalized_ids(itemids, "itemids")
+      verify_host_ownership!(hostid, ids)
+      result = @client.api_request(method: "item.delete", params: ids)
+      Array(result.fetch("itemids")).map(&:to_i)
+    end
 
-      # 使用 Zabbix API 进行模糊查询，获取特定主机和接口下的监控项
-      result = get_raw(
-        {
-          output:  "extend",
+    # 返回主机中可能表示接口流量的已启用监控项。
+    # 方向和接口精确匹配由 Monitoring 业务层负责。
+    # @return [Array<Hash>]
+    def monitored_traffic_candidates(hostid)
+      @client.api_request(
+        method: "item.get",
+        params: {
           hostids: [hostid],
-          search:  { name: iface }
+          monitored: true,
+          output: %w[itemid hostid name key_ snmp_oid value_type status units],
+          selectPreprocessing: "extend",
+          sortfield: "name",
+          sortorder: "ASC"
         }
       )
+    end
 
-      # 过滤结果，只保留符合正则表达式的项
-      filtered_result = result.select { |item| item["snmp_oid"].match?(/(1.3.6.1.2.1.31.1.1.1.(6|10|15)|1.3.6.1.2.1.2.2.1.8)./) }
+    # 按主机接口幂等创建或更新 DNS 解析监控项，并返回监控项 ID。
+    # DNS 名称会进入 item key，因此拒绝可能改变 key 参数结构的分隔符。
+    # @return [Integer]
+    def upsert_dns_item(hostid:, interfaceid:, dns_name:)
+      name = dns_name.to_s.strip
+      raise Invalid, "dns_name is required" if name.blank?
+      raise Invalid, "dns_name contains unsupported item key delimiters" if name.match?(/[\[\],]/)
 
-      # 如果结果为空，则返回 nil；否则，返回排序后的结果
-      filtered_result.empty? ? nil : filtered_result.sort_by { |item| item["key_"] }
+      itemid = upsert_by_key(
+        hostid: hostid,
+        interfaceid: interfaceid,
+        name: "【DNS域名解析监控】#{name}",
+        key_: "net.dns.record[,#{name},A,2,2]",
+        type: 0,
+        value_type: 1,
+        delay: "1m",
+        history: "90d",
+        timeout: "3s"
+      )
+      log "Ensured DNS monitoring item for #{name}"
+      itemid
+    rescue StandardError => e
+      log "Failed to ensure DNS monitoring item: #{e.class}"
+      raise
     end
+
+    private
+
+      # 规范化并校验幂等写入所需字段。
+      # @return [Hash]
+      # @api private
+      def validate_item!(data)
+        attributes = data.deep_symbolize_keys
+        raise Invalid, "hostid is required" if attributes[:hostid].blank?
+        raise Invalid, "key_ is required" if attributes[:key_].blank?
+        raise Invalid, "name is required" if attributes[:name].blank?
+
+        attributes
+      end
+
+      # 校验 item.create 的通用必填字段和 SNMP 条件字段。
+      def validate_create_item!(attributes)
+        raise Invalid, "type is required when creating an item" if attributes[:type].blank?
+        raise Invalid, "value_type is required when creating an item" if attributes[:value_type].blank?
+
+        type = Integer(attributes[:type])
+        raise Invalid, "unsupported item type #{type}" unless ITEM_TYPES.include?(type)
+
+        if REQUIRED_INTERFACE_TYPES.include?(type) && attributes[:interfaceid].blank?
+          raise Invalid, "interfaceid is required for item type #{type}"
+        end
+        if REQUIRED_PARAMS_TYPES.include?(type) && attributes[:params].blank?
+          raise Invalid, "params is required for item type #{type}"
+        end
+
+        raise Invalid,
+              "master_itemid is required for a dependent item" if type == 18 && attributes[:master_itemid].blank?
+        raise Invalid, "url is required for an HTTP item" if type == 19 && attributes[:url].blank?
+        return unless type == 20
+
+        raise Invalid, "snmp_oid is required for an SNMP item" if attributes[:snmp_oid].blank?
+      rescue ArgumentError, TypeError
+        raise Invalid, "type must be a supported integer"
+      end
+
+      # 回查监控项归属，阻止共享高权限令牌跨主机修改。
+      def verify_host_ownership!(hostid, ids)
+        raise Invalid, "hostid is required" if hostid.blank?
+
+        result = @client.api_request(
+          method: "item.get", params: { hostids: hostid, itemids: ids, output: ["itemid"] }
+        )
+        owned_ids = result.map { |item| item.fetch("itemid").to_s }
+        foreign_ids = ids - owned_ids
+        raise Conflict, "items do not belong to host #{hostid}: #{foreign_ids.join(", ")}" if foreign_ids.any?
+      end
+
+      # 统一批量 ID 并拒绝空集合。
+      # @return [Array<String>]
+      # @api private
+      def normalized_ids(values, name)
+        ids = Array(values).filter_map { |value| value.to_s.strip.presence }.uniq
+        raise Invalid, "#{name} are required" if ids.empty?
+
+        ids
+      end
   end
 end