zabbix_manager 6.0.1 → 6.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad8094e06c6d99c1ff334dd2cf9d86c40bb9f45467d811e53be92d1ffcf05bb3
-  data.tar.gz: 90375dfe1473875e17e2b8e82b3f947818076239b1ceb3d2f868001b600f4c12
+  metadata.gz: 7bdb7262133718703b6cdd1a245914b33a3efa6d989b6a22877576ad18c83302
+  data.tar.gz: c5786d77070a1d5da5d34afc488feb21c0b7d1a2f7d91cdb808bdcb1c78469ef
 SHA512:
-  metadata.gz: 629f1278b1f79497c95de696db6c46169b75995c34e69993508c12672227b2ebf3f8264a9ba228e001c83a68f2c352f3aa80a771ff729effd95b7d50e6ca0e2f
-  data.tar.gz: d0d7377ba225db508bcc46bf177a65518dcdade2beb6190b92ed2d5bb1b17367748f2f2f3a005daf46af329437c8ec4d80f3e452f626bda440bd96b60a442945
+  metadata.gz: abb93fb5caaabef8b9e5ddc44c9c8d7aeddfa872490c7aedfb952d985395e57ef985d1486c1ae351786a14844c7b4c01cc783fcd98b9ab889aea7ab3ff96a5b6
+  data.tar.gz: 600d3d5797909d4ce7c453536336700303a9b3bea45e7b4b8ca1538b5125c5a6df08db176de233c8dc457efb60357fc83d10c32af2a9c604aed74db758025ccf

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## 6.0.3 (2026-10-11)
+
+* Enable HTTPS certificate verification by default; use `ca_file:` for private certificate authorities.
+* Freeze the negotiated API version and parse its major component once so authentication cannot drift between requests.
+* Canonicalize resource IDs before queries, writes, receipt checks and upsert locking; deduplicate equivalent user targets.
+* Snapshot interface monitoring definitions and serialize their execution with other monitoring workflows.
+* Verify managed trigger identities and ownership before updates, including interface preflight before item writes; reject contradictory line tags during local validation.
+* Validate complete group lookup responses before creating missing groups and verify host/global macro lookup identities.
+
+## 6.0.2 (2026-10-05)
+
+* Use the repository account name for Gem author metadata.
+
 ## 6.0.1 (2026-10-05)
 
 * Discover batch item keys once per host and validate returned ownership, identities and duplicate targets before writes.

data/README.md

@@ -93,7 +93,7 @@ Logging uses `ActiveSupport::Logger` and `ActiveSupport::TaggedLogging`; structu
 
 Passwords, API tokens, SNMPv3 authentication/privacy passphrases, authorization values, cookies, and session IDs are filtered. Quoted diagnostic credentials are filtered as complete values, including escaped quotes and backslashes. Request parameters and response bodies are not logged. API exceptions expose the server error code and request ID, without remote messages or data that might echo arbitrary secrets. Malformed or mismatched JSON-RPC responses and invalid mutation ID receipts raise `ProtocolError < TransportError`: a write may already have happened, so it must not be blindly replayed.
 
-HTTPS certificate verification is disabled by default as required by this project. Set `verify_ssl: true` (and optionally `ca_file:`) to enable peer verification.
+HTTPS certificate verification is enabled by default. Use `ca_file:` for a private certificate authority. An explicit `verify_ssl: false` disables verification and emits a warning when logging is enabled.
 
 Zabbix 7 API-token requests need the `Authorization` header, so they cannot share that header with HTTP Basic authentication. The client rejects that combination instead of silently overwriting either credential.
 
@@ -123,7 +123,7 @@ zabbix.monitoring.reconcile_line(
 )
 ```
 
-The lookup accepts full and abbreviated interface names such as `Ten-GigabitEthernet1/0/49` and `Te1/0/49`. It refuses zero or multiple direction matches instead of selecting an item by response order. Trigger ownership comes from the managed identity tag; matching descriptions alone never adopt unrelated triggers.
+The lookup accepts full and abbreviated interface names such as `Ten-GigabitEthernet1/0/49` and `Te1/0/49`. It refuses zero or multiple direction matches instead of selecting an item by response order. Trigger ownership requires the requested managed identity and a unique matching `managed_by` tag. Contradictory `line_id` tags are rejected. Interface workflows check ownership before item writes, and trigger upserts check it again before updates; matching descriptions alone never adopt unrelated triggers.
 
 Use `reconcile_lines(lines)` for imports. It reuses host and item discovery results within the batch, avoiding a full `item.get` scan for every line.
 
@@ -232,7 +232,7 @@ Invalid caller input raises `ZabbixManager::Invalid`, ambiguous remote ownership
 
 `traffic.series` reads explicit item IDs; `traffic.for_interface` discovers both interface directions. Both expose missing data and query truncation, preserve numeric precision, and keep raw history separate from hourly trends. They never substitute zero or a stale last value for missing samples.
 
-Device and line definitions are copied before validation and discovery. Changes to caller-owned strings or nested fields during reconciliation do not alter the validated definition.
+Device, line and interface definitions are copied before validation and discovery. Changes to caller-owned strings or nested fields during reconciliation do not alter the validated definition.
 
 Multiword resource accessors use Ruby snake_case: `host_groups`, `host_interfaces`, `http_tests`, `media_types`, `proxy_groups`, `user_groups`, `user_macros`, `value_maps`, and `discovery_rules`.
 
@@ -248,7 +248,7 @@ The focused modules expose explicit operations:
 
 * `triggers.for_host`, `triggers.upsert_for_host`, `triggers.add_dependencies`, `triggers.replace_dependencies`, `triggers.set_status`, `triggers.delete_many`
 
-`items.upsert_many` discovers existing keys once per host before any write, then preserves input write order. Item and interface batch definitions are copied before discovery, including nested strings. Single-host helpers require a positive integer `hostid` or its decimal string representation. Identity lookup and batch helpers reject malformed query containers or required IDs with `ProtocolError`; `get_raw` preserves native response pass-through.
+`items.upsert_many` discovers existing keys once per host before any write, then preserves input write order. Item and interface batch definitions are copied before discovery, including nested strings. Single-host helpers require a positive integer `hostid` or its decimal string representation. Equivalent resource IDs are normalized before locking, queries, writes and receipt checks. Identity lookup and batch helpers reject malformed query containers or required IDs with `ProtocolError`; `get_raw` preserves native response pass-through.
 
 
 ## Supported Ruby Versions

data/lib/zabbix_manager/classes/applications.rb

@@ -15,7 +15,7 @@ class ZabbixManager
     # @return [Hash] 应用集唯一查询条件
     def identity_filter(data)
       attributes = data.deep_symbolize_keys
-      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+      { name: attributes.fetch(:name), hostid: normalized_id_attribute(attributes.fetch(:hostid), "hostid") }
     end
   end
 end

data/lib/zabbix_manager/classes/graphs.rb

@@ -76,7 +76,7 @@ class ZabbixManager
     # @return [Hash] 图形唯一查询条件
     def identity_filter(data)
       attributes = data.deep_symbolize_keys
-      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+      { name: attributes.fetch(:name), hostid: normalized_id_attribute(attributes.fetch(:hostid), "hostid") }
     end
 
     # 图形所有者由 gitems 确定，hostid 仅用于调用方的身份查询。

data/lib/zabbix_manager/classes/host_groups.rb

@@ -19,41 +19,60 @@ class ZabbixManager
 
     # 批量解析主机群组名称并返回对应的群组 ID。
     # @param data [Array<String>, String] 待查询的群组名称
+    # @raise [ProtocolError] 远端群组身份或 ID 无效
+    # @raise [Conflict] 远端群组名称不唯一
     # @return [Array<Hash>, nil] 群组 ID 列表，未命中时返回 nil
     def get_hostgroup_ids(data)
       names = normalized_names(data)
       return nil if names.empty?
 
-      groups = @client.api_request(
-        method: "hostgroup.get",
-        params: {
-          output: %w[groupid name],
-          filter: { name: names }
-        }
-      )
-
-      groups.empty? ? nil : groups.map { |group| { groupid: group.fetch("groupid") } }
+      groups = groups_by_name(names)
+      groups.empty? ? nil : groups.values.map { |id| { groupid: id } }
     end
 
     # 批量查询并创建缺失的主机群组，避免逐名称重复查询。
     # @param data [Array<String>, String] 待确保存在的群组名称
+    # @raise [ProtocolError] 远端群组身份或 ID 无效
+    # @raise [Conflict] 远端群组名称不唯一
     # @return [Array<Hash>] 群组 ID 列表
     def get_or_create_host_groups(data)
       names = normalized_names(data)
-      existing = @client.api_request(
-        method: "hostgroup.get",
-        params: { output: %w[groupid name], filter: { name: names } }
-      ).index_by { |group| group.fetch("name") }
+      return [] if names.empty?
+
+      existing = groups_by_name(names)
 
       names.map do |name|
-        group = existing[name]
-        next({ groupid: response_identifier(group["groupid"]).to_s }) if group
+        id = existing[name]
+        next({ groupid: id }) if id
 
         result = @client.api_request(method: "hostgroup.create", params: { name: name })
         { groupid: response_id(result).to_s }
       end
     end
 
+    # 全部查询结果先核对身份和 ID，损坏或重名响应不能触发部分创建。
+    private def groups_by_name(names)
+      rows = response_objects(@client.api_request(
+                                method: "hostgroup.get",
+                                params: { output: %w[groupid name], filter: { name: names } }
+                              ))
+      requested = names.to_h { |name| [name, true] }
+      ids = {}
+      rows.each_with_object({}) do |group, result|
+        name = group["name"]
+        unless name.is_a?(String) && requested.key?(name)
+          raise ProtocolError, "hostgroup.get returned a group outside the requested names"
+        end
+
+        id = response_identifier(group["groupid"]).to_s
+        raise Conflict, "multiple host groups share the same name" if result.key?(name)
+        raise ProtocolError, "hostgroup.get returned duplicate group IDs" if ids.key?(id)
+
+        ids[id] = true
+        result[name] = id
+      end
+    end
+
     # 清理、去空并去重主机群组名称。
     # @param data [Array<String>, String] 原始群组名称
     # @return [Array<String>] 规范化后的群组名称

data/lib/zabbix_manager/classes/host_interfaces.rb

@@ -24,7 +24,7 @@ class ZabbixManager
     # 查询指定主机的全部接口，可选择同时返回关联监控项。
     # @return [Array<Hash>]
     def for_host(hostid, select_items: nil)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: "extend" }
       params[:selectItems] = select_items if select_items
@@ -56,6 +56,7 @@ class ZabbixManager
     # 幂等创建或更新一个主机的接口集合。
     # @return [Array<Integer>]
     def reconcile_for_host(hostid:, interfaces:)
+      hostid = normalized_id_attribute(hostid, "hostid")
       @client.with_upsert_lock("host-interfaces:#{hostid}") do
         plan = plan_for_host(hostid: hostid, interfaces: interfaces)
         apply_plan(hostid: hostid, plan: plan)
@@ -105,6 +106,9 @@ class ZabbixManager
       raise Invalid, "interface must be a hash" unless interface.is_a?(Hash)
 
       attributes = interface.deep_symbolize_keys.deep_dup
+      if attributes.key?(:interfaceid)
+        attributes[:interfaceid] = normalized_id_attribute(attributes[:interfaceid], "interfaceid")
+      end
       if attributes.key?(:type)
         type = integer_attribute(attributes[:type], "interface type")
         raise Invalid, "interface type must be 1, 2, 3, or 4" unless [1, 2, 3, 4].include?(type)
@@ -232,7 +236,8 @@ class ZabbixManager
       endpoint_field = values[:useip].to_i == 1 ? :ip : :dns
       raise Invalid, "interface #{endpoint_field} is required" if values[endpoint_field].blank?
 
-      "endpoint:#{values[:type]}:#{values[:useip]}:#{values[endpoint_field]}:#{values[:port]}"
+      "endpoint:#{integer_attribute(values[:type], 'interface type')}:" \
+        "#{integer_attribute(values[:useip], 'interface useip')}:#{values[endpoint_field]}:#{values[:port]}"
     end
 
     # 更新已属于目标主机的接口。

data/lib/zabbix_manager/classes/hosts.rb

@@ -23,10 +23,12 @@ class ZabbixManager
 
     # 按主机 ID 查询完整主机及接口、群组和模板。
     def dump_by_id(data)
+      attributes = data.deep_symbolize_keys
+      id = normalized_id_attribute(attributes[key.to_sym], key)
       @client.api_request(
         method: "host.get",
         params: {
-          filter: { key.to_sym => data[key.to_sym] },
+          filter: { key.to_sym => id },
           output: "extend",
           selectGroups: "extend",
           selectInterfaces: "extend",
@@ -145,7 +147,7 @@ class ZabbixManager
     # 按主机 ID 查询唯一主机，并返回表达式需要的技术名称。
     # @return [Hash, nil]
     def find_by_id(hostid)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
       find_host_by_filter(hostid: hostid)
     end
 

data/lib/zabbix_manager/classes/http_tests.rb

@@ -26,7 +26,7 @@ class ZabbixManager
     # @return [Hash] Web 场景唯一查询条件
     def identity_filter(data)
       attributes = data.deep_symbolize_keys
-      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+      { name: attributes.fetch(:name), hostid: normalized_id_attribute(attributes.fetch(:hostid), "hostid") }
     end
   end
 end

data/lib/zabbix_manager/classes/items.rb

@@ -35,13 +35,13 @@ class ZabbixManager
     # @return [Hash] 名称和所属主机组成的精确过滤条件
     def identity_filter(data)
       attributes = data.deep_symbolize_keys
-      { name: attributes.fetch(:name), hostid: attributes.fetch(:hostid) }
+      { name: attributes.fetch(:name), hostid: normalized_id_attribute(attributes.fetch(:hostid), "hostid") }
     end
 
     # 查询主机监控项，可按稳定 key 集合过滤并选择关联对象。
     # @return [Array<Hash>]
     def for_host(hostid, keys: nil, output: "extend", select_preprocessing: nil, select_tags: nil)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: output }
       params[:filter] = { key_: keys } if keys.present?
@@ -68,13 +68,13 @@ class ZabbixManager
     # @return [Array<Integer>]
     def upsert_many(collection)
       items = Array(collection).map { |data| validate_item!(data) }
-      identities = items.map { |item| [positive_id_attribute(item[:hostid], "hostid").to_s, item[:key_]] }
+      identities = items.map { |item| [item[:hostid].to_s, item[:key_]] }
       duplicate = identities.tally.find { |_identity, count| count > 1 }&.first
       raise Invalid, "duplicate hostid + key_ identity #{duplicate.join(":")}" if duplicate
 
       existing = batch_items(items)
       plans = items.map do |item|
-        identity = [positive_id_attribute(item[:hostid], "hostid").to_s, item[:key_]]
+        identity = [item[:hostid].to_s, item[:key_]]
         plan_item(item, existing[identity])
       end
       if block_given?
@@ -116,7 +116,7 @@ class ZabbixManager
     # 方向和接口精确匹配由 Monitoring 业务层负责。
     # @return [Array<Hash>]
     def monitored_traffic_candidates(hostid)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
       @client.api_request(
         method: "item.get",
         params: {
@@ -155,7 +155,7 @@ class ZabbixManager
 
     # 每个主机只读取一次期望 key 集合，全部发现和校验完成后才开始写入。
     def batch_items(items)
-      groups = items.group_by { |item| positive_id_attribute(item[:hostid], "hostid").to_s }
+      groups = items.group_by { |item| item[:hostid].to_s }
       ids = {}
       groups.each_with_object({}) do |(owner, definitions), result|
         hostid = definitions.first[:hostid]
@@ -218,7 +218,7 @@ class ZabbixManager
       raise Invalid, "item must be a hash" unless data.is_a?(Hash)
 
       attributes = data.deep_symbolize_keys.deep_dup
-      positive_id_attribute(attributes[:hostid], "hostid")
+      attributes[:hostid] = normalized_id_attribute(attributes[:hostid], "hostid")
       %i[key_ name].each do |field|
         unless attributes[field].is_a?(String) && attributes[field].present?
           raise Invalid, "#{field} must be a non-empty string"
@@ -259,7 +259,7 @@ class ZabbixManager
 
     # 回查监控项归属，阻止共享高权限令牌跨主机修改。
     def verify_host_ownership!(hostid, ids)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
 
       result = @client.api_request(
         method: "item.get", params: { hostids: hostid, itemids: ids, output: ["itemid"] }

data/lib/zabbix_manager/classes/roles.rb

@@ -21,7 +21,7 @@ class ZabbixManager
       raise Invalid, "roleid is required" if attributes[:roleid].blank?
       raise Invalid, "rules is required" if attributes[:rules].blank?
 
-      normalized_ids([attributes[:roleid]])
+      attributes[:roleid] = normalized_id_attribute(attributes[:roleid], "roleid")
 
       result = @client.api_request(
         method: "role.update",

data/lib/zabbix_manager/classes/triggers.rb

@@ -26,11 +26,13 @@ class ZabbixManager
     # @raise [TransportError] HTTP 或网络请求失败，可能无法确认远端结果
     # @return [Array<Hash>] 匹配的触发器及其关联对象
     def dump_by_id(data)
+      attributes = data.deep_symbolize_keys
+      id = normalized_id_attribute(attributes[key.to_sym], key)
       @client.api_request(
         method: "trigger.get",
         params: {
           filter: {
-            key.to_sym => data[key.to_sym]
+            key.to_sym => id
           },
           output: "extend",
           selectItems: "extend",
@@ -43,7 +45,7 @@ class ZabbixManager
     # @return [Array<Hash>]
     def for_host(hostid, output: "extend", select_items: nil, select_functions: nil,
                  select_dependencies: nil, select_tags: nil, filter: nil)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
 
       params = { hostids: hostid, output: output }
       params[:selectItems] = select_items if select_items
@@ -57,7 +59,7 @@ class ZabbixManager
     # 按主机、描述和可选标签查询唯一触发器。
     # @return [Hash, nil]
     def find_for_host(hostid:, description:, tags: nil)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
       params = {
         hostids: hostid,
         filter: { description: description },
@@ -80,9 +82,13 @@ class ZabbixManager
     # 展开表达式并读取依赖，供不确定写入后的完整期望状态核对。
     # @param hostid [Integer, String] 触发器所属主机
     # @param managed_key [String] 稳定、非秘密的受管身份
+    # @param managed_by [String, nil] 指定时必须与远端唯一管理方一致
+    # @param line_id [String, nil] 指定时拒绝矛盾的远端线路标签；兼容未标记的旧线路
+    # @raise [ProtocolError] 返回标签格式无效或受管身份不匹配
+    # @raise [Conflict] 受管身份不唯一或归属另一管理方、线路
     # @return [Hash, nil]
-    def find_managed_for_host(hostid:, managed_key:)
-      positive_id_attribute(hostid, "hostid")
+    def find_managed_for_host(hostid:, managed_key:, managed_by: nil, line_id: nil)
+      hostid = normalized_id_attribute(hostid, "hostid")
       result = @client.api_request(
         method: "trigger.get",
         params: {
@@ -95,7 +101,10 @@ class ZabbixManager
         }
       )
       response_objects(result)
-      result.each { |trigger| response_identifier(trigger["triggerid"]) }
+      result.each do |trigger|
+        response_identifier(trigger["triggerid"])
+        validate_managed_identity!(trigger, managed_key: managed_key, managed_by: managed_by, line_id: line_id)
+      end
       raise Conflict, "multiple triggers use managed key #{managed_key}" if result.length > 1
 
       result.first
@@ -123,7 +132,7 @@ class ZabbixManager
     # @return [Integer]
     def upsert_for_host(data)
       attributes = data.deep_symbolize_keys.deep_dup
-      positive_id_attribute(attributes[:hostid], "hostid")
+      attributes[:hostid] = normalized_id_attribute(attributes[:hostid], "hostid")
       lock_key = "trigger:#{attributes[:hostid]}:#{attributes[:managed_key] || attributes[:description]}"
       @client.with_upsert_lock(lock_key) { perform_upsert_for_host(attributes) }
     end
@@ -197,7 +206,7 @@ class ZabbixManager
       attributes = data.deep_symbolize_keys
       hostid = attributes.delete(:hostid)
       managed_key = attributes.delete(:managed_key)&.to_s
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
       raise Invalid, "description is required" if attributes[:description].blank?
       raise Invalid, "expression is required" if attributes[:expression].blank?
 
@@ -208,7 +217,10 @@ class ZabbixManager
           tag[:tag].to_s == "zabbix_manager_id" || tag["tag"].to_s == "zabbix_manager_id"
         end
         attributes[:tags] << { tag: "zabbix_manager_id", value: managed_key }
-        current = find_managed_for_host(hostid: hostid, managed_key: managed_key)
+        current = find_managed_for_host(
+          hostid: hostid, managed_key: managed_key,
+          managed_by: desired_tag_value(attributes, "managed_by"), line_id: desired_tag_value(attributes, "line_id")
+        )
       else
         ownership_tags = Array(attributes[:tags]).select do |tag|
           tag[:tag].to_s == "managed_by" || tag["tag"].to_s == "managed_by"
@@ -250,7 +262,10 @@ class ZabbixManager
       delays = @client.options.fetch(:uncertain_write_delays, DEFAULT_UNCERTAIN_WRITE_DELAYS)
       delays.each do |delay|
         sleep(delay) if delay.positive?
-        current = find_managed_for_host(hostid: hostid, managed_key: managed_key)
+        current = find_managed_for_host(
+          hostid: hostid, managed_key: managed_key,
+          managed_by: desired_tag_value(attributes, "managed_by"), line_id: desired_tag_value(attributes, "line_id")
+        )
         if current && recovered_trigger_matches?(current, attributes)
           response_identifier(current["triggerid"])
           return current
@@ -261,6 +276,34 @@ class ZabbixManager
       nil
     end
 
+    # 原生标签过滤器不能代替本地身份和管理权校验。
+    private def validate_managed_identity!(trigger, managed_key:, managed_by:, line_id:)
+      tags = trigger["tags"]
+      unless tags.is_a?(Array) && tags.all? do |tag|
+        tag.is_a?(Hash) && tag["tag"].is_a?(String) && tag["value"].is_a?(String)
+      end
+        raise ProtocolError, "invalid trigger response: tags must contain string tag and value fields"
+      end
+
+      values = ->(name) { tags.filter_map { |tag| tag["value"] if tag["tag"] == name } }
+      unless values.call("zabbix_manager_id") == [managed_key]
+        raise ProtocolError, "trigger.get returned an unexpected managed key"
+      end
+      if managed_by && values.call("managed_by") != [managed_by]
+        raise Conflict, "trigger managed key belongs to another owner"
+      end
+
+      lines = values.call("line_id")
+      raise Conflict, "trigger managed key belongs to another line" if line_id && lines.any? && lines != [line_id]
+    end
+
+    private def desired_tag_value(attributes, name)
+      values = Array(attributes[:tags]).filter_map { |tag| tag[:value] if tag[:tag] == name }
+      raise Invalid, "#{name} must have one string value" if values.length > 1 || values.any? { |v| !v.is_a?(String) }
+
+      values.first
+    end
+
     private def recovered_trigger_matches?(current, attributes)
       desired_tags = Array(attributes[:tags]).map(&:deep_symbolize_keys)
       actual_tags = Array(current["tags"]).map(&:deep_symbolize_keys)
@@ -281,7 +324,7 @@ class ZabbixManager
 
     # 回查触发器归属，阻止共享高权限令牌跨主机修改。
     private def verify_host_ownership!(hostid, ids)
-      positive_id_attribute(hostid, "hostid")
+      hostid = normalized_id_attribute(hostid, "hostid")
 
       result = @client.api_request(
         method: "trigger.get", params: { hostids: hostid, triggerids: ids, output: ["triggerid"] }

data/lib/zabbix_manager/classes/user_macros.rb

@@ -21,26 +21,33 @@ class ZabbixManager
     # @return [Hash] 主机宏复合身份
     def identity_filter(data)
       attributes = data.deep_symbolize_keys
-      { macro: attributes.fetch(:macro), hostid: attributes.fetch(:hostid) }
+      { macro: attributes.fetch(:macro), hostid: normalized_id_attribute(attributes.fetch(:hostid), "hostid") }
     end
 
+    # @raise [ProtocolError] 远端宏名称、归属或 ID 无效
+    # @raise [Conflict] 宏身份不唯一
     # @return [Integer, nil] 唯一主机宏 ID
     def get_id(data)
       attributes = identity_filter(data)
-      unique_macro_id(get_full_data(attributes), "hostmacroid")
+      unique_macro_id(get_full_data(attributes), "hostmacroid", attributes)
     end
 
+    # @raise [ProtocolError] 远端宏名称或 ID 无效
+    # @raise [Conflict] 宏身份不唯一
     # @return [Integer, nil] 唯一全局宏 ID
     def get_id_global(data)
       attributes = data.deep_symbolize_keys
-      unique_macro_id(get_full_data_global(macro: attributes.fetch(:macro)), "globalmacroid")
+      identity = { macro: attributes.fetch(:macro) }
+      unique_macro_id(get_full_data_global(identity), "globalmacroid", identity)
     end
 
     # @return [Array<Hash>] 主机宏查询结果
     def get_full_data(data)
       attributes = data.deep_symbolize_keys
       params = { filter: attributes.except(:hostid) }
-      params[:hostids] = attributes[:hostid] if attributes.key?(:hostid)
+      if attributes.key?(:hostid)
+        params[:hostids] = normalized_id_attribute(attributes[:hostid], "hostid")
+      end
       get_raw(params)
     end
 
@@ -73,12 +80,12 @@ class ZabbixManager
 
     # @return [Integer, nil] 更新主机宏 ID
     def update(data)
-      write_macro("update", data, "hostmacroids", expected: [data.with_indifferent_access[:hostmacroid]])
+      update_macro("update", data, "hostmacroid")
     end
 
     # @return [Integer, nil] 更新全局宏 ID
     def update_global(data)
-      write_macro("updateglobal", data, "globalmacroids", expected: [data.with_indifferent_access[:globalmacroid]])
+      update_macro("updateglobal", data, "globalmacroid")
     end
 
     # @return [Integer, nil] 已存在或新建全局宏 ID
@@ -95,8 +102,25 @@ class ZabbixManager
 
     private
 
-    def unique_macro_id(result, id_field)
-      response_objects(result)
+    def update_macro(operation, data, id_field)
+      attributes = data.deep_symbolize_keys
+      id = attributes[id_field.to_sym] = normalized_id_attribute(attributes[id_field.to_sym], id_field)
+      write_macro(operation, attributes, "#{id_field}s", expected: [id])
+    end
+
+    # 名称过滤器和 hostids 只是远端查询条件，不能代替本地身份核对。
+    def unique_macro_id(result, id_field, identity)
+      response_objects(result).each do |macro|
+        response_identifier(macro[id_field], id_field)
+        unless macro["macro"].is_a?(String) && macro["macro"] == identity[:macro]
+          raise ProtocolError, "usermacro.get returned an unexpected macro identity"
+        end
+        next unless identity.key?(:hostid)
+
+        unless response_identifier(macro["hostid"], "hostid") == identity[:hostid].to_i
+          raise ProtocolError, "usermacro.get returned a macro outside the requested host"
+        end
+      end
       raise Conflict, "multiple macros match the requested identity" if result.length > 1
 
       response_identifier(result.first[id_field], id_field) if result.first

data/lib/zabbix_manager/classes/users.rb

@@ -18,11 +18,13 @@ class ZabbixManager
     # @return [Integer, nil] 首个更新用户的 ID
     def update_medias(data)
       attributes = data.deep_symbolize_keys
-      ids = normalized_ids(attributes.fetch(:userids))
+      ids = Array.wrap(attributes.fetch(:userids)).map { |id| normalized_id_attribute(id, "userid") }
+      normalized_ids(ids)
+      ids.uniq!(&:to_s)
       media_field = Gem::Version.new(@client.api_version) >= Gem::Version.new("5.4") ? :medias : :user_medias
       result = @client.api_request(
         method: "user.update",
-        params: attributes.fetch(:userids).map do |userid|
+        params: ids.map do |userid|
           { userid: userid, media_field => attributes.fetch(:media) }
         end
       )

data/lib/zabbix_manager/client.rb

@@ -16,7 +16,10 @@ class ZabbixManager
                    error: Logger::ERROR, fatal: Logger::FATAL, unknown: Logger::UNKNOWN }.freeze
     private_constant :LOG_LEVELS
 
-    attr_reader :options, :logger, :api_version
+    attr_reader :options, :logger
+
+    # @return [String] 不可变的已协商版本，认证策略在连接期间保持稳定
+    attr_reader :api_version
 
     # 校验配置后立即查询服务器版本并完成认证。
     # 初始化失败时关闭连接；成功后的客户端生命周期由调用方负责。
@@ -199,7 +202,11 @@ class ZabbixManager
     def validate_api_version!
       match = @api_version.is_a?(String) && @api_version.match(/\A(\d+)\.(\d+)\.(\d+)\z/)
       raise ProtocolError, "Invalid API version response" unless match
-      return if SUPPORTED_MAJOR_VERSIONS.cover?(match[1].to_i)
+
+      # 版本只在初始化时解析，后续请求不重复拆分字符串或改变认证策略。
+      @api_version = @api_version.dup.freeze
+      @api_major_version = match[1].to_i
+      return if SUPPORTED_MAJOR_VERSIONS.cover?(@api_major_version)
       raise ApiError, "Zabbix API version is not supported" unless @settings[:ignore_version]
 
       log(:warn, "version.unsupported", version: @api_version)
@@ -222,11 +229,11 @@ class ZabbixManager
     end
 
     def insecure_https?
-      @transport.uri.scheme == "https" && @settings[:verify_ssl] != true
+      @transport.uri.scheme == "https" && @settings[:verify_ssl] == false
     end
 
     def api_major_version
-      @api_version.to_s.split(".", 2).first.to_i
+      @api_major_version
     end
 
     def bearer_token_for(method)

data/lib/zabbix_manager/http_transport.rb

@@ -203,12 +203,12 @@ class ZabbixManager
       ]
     end
 
-    # 配置 HTTPS；证书校验默认关闭，按调用方选项开启。
+    # 配置 HTTPS；证书校验默认开启，仅在显式传入 false 时关闭。
     def configure_tls(http)
       return unless @uri.scheme == "https"
 
       http.use_ssl = true
-      http.verify_mode = @options[:verify_ssl] == true ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+      http.verify_mode = @options[:verify_ssl] == false ? OpenSSL::SSL::VERIFY_NONE : OpenSSL::SSL::VERIFY_PEER
       http.ca_file = @options[:ca_file] if @options[:ca_file]
     end
 

data/lib/zabbix_manager/monitoring/thresholds.rb

@@ -166,6 +166,10 @@ class ZabbixManager
 
           { tag: tag[:tag], value: tag.fetch(:value, "") }
         end
+        # line_id 参与资源层的归属校验，矛盾值必须在首个远端写入之前拒绝。
+        line_ids = extra.filter_map { |tag| tag[:value] if tag[:tag] == "line_id" }.uniq
+        raise Invalid, "line_id must have one string value" if line_ids.length > 1
+
         (tags + extra).uniq
       end
 

data/lib/zabbix_manager/monitoring.rb

@@ -121,12 +121,19 @@ class ZabbixManager
     end
 
     # 接口更新只增改，不自动删除远端对象；所有本地校验在首个写入之前完成。
+    # 快照调用方输入，再与设备和线路工作流共享实例互斥锁。
     # @param attributes [Hash] host、interface、按名称分组的原生 items 和 thresholds
     # @return [Hash] hostid、interface、itemids 和 triggerids
     # @raise [Invalid, Conflict] 输入、量纲或资源归属无效
     # @raise [ApiError, TransportError] 远端失败；已经确认的早期步骤不会被回滚
     def reconcile_interface(attributes)
-      input = Validation.hash!(attributes, "interface monitoring")
+      input = Validation.hash!(attributes, "interface monitoring").deep_dup
+      @workflow_mutex.synchronize { apply_interface(input) }
+    end
+
+    private
+
+    def apply_interface(input)
       input.assert_valid_keys(:host, :interface, :items, :thresholds)
       supplied_host = Validation.hash!(input[:host], "host")
       Validation.host!(supplied_host)
@@ -140,6 +147,14 @@ class ZabbixManager
         validate_items: false
       )
       host = resolve_host(supplied_host, {})
+      triggers.each_value do |trigger|
+        ownership = { managed_by: "zabbix_manager" }
+        line_tag = trigger[:tags].find { |tag| tag[:tag] == "line_id" }
+        ownership[:line_id] = line_tag[:value] if line_tag
+        @manager.triggers.find_managed_for_host(
+          hostid: host[:hostid], managed_key: trigger[:managed_key], **ownership
+        )
+      end
       ids = @manager.items.upsert_many(items.values) do |effective|
         # 读取已有配置后再次校验最终量纲和数值类型，仍在首个 item 写入之前。
         triggers = @thresholds.prepare_triggers(
@@ -152,8 +167,6 @@ class ZabbixManager
       { hostid: host[:hostid].to_i, interface: interface[:name], itemids: itemids, triggerids: triggerids }
     end
 
-    private
-
     def validate_devices!(devices)
       definitions = Validation.array!(devices, "devices").map { |device| Device.new(device) }
       validate_unique!(definitions.map(&:identity), "device host")

data/lib/zabbix_manager/resource.rb

@@ -71,7 +71,7 @@ class ZabbixManager
       id = attributes[key.to_sym]
       raise Invalid, "#{key} is required" if id.blank?
 
-      normalized_ids([id])
+      id = attributes[key.to_sym] = normalized_id_attribute(id, key)
 
       current = response_objects(dump_by_id(key.to_sym => id)).find do |item|
         response_identifier(item[key]) == id.to_i
@@ -96,6 +96,7 @@ class ZabbixManager
       id = attributes[key.to_sym]
       raise Invalid, "#{key} is required" if id.blank?
 
+      id = normalized_id_attribute(id, key)
       response_objects(get_raw(filter: { key.to_sym => id }, output: "extend"))
     end
 
@@ -190,6 +191,12 @@ class ZabbixManager
       id
     end
 
+    # 同一 ID 的正号和前导零只在输入边界出现，查询、写入和锁使用统一身份。
+    def normalized_id_attribute(value, name)
+      id = positive_id_attribute(value, name)
+      value.is_a?(Integer) ? id : id.to_s
+    end
+
     def validate_boolean!(value, name)
       raise Invalid, "#{name} must be true or false" unless value == true || value == false
     end

data/lib/zabbix_manager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class ZabbixManager
-  VERSION = "6.0.1"
+  VERSION = "6.0.3"
 end

data/zabbix_manager.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
 
   spec.name    = "zabbix_manager"
   spec.version = ZabbixManager::VERSION
-  spec.authors = ["WENWU YAN"]
+  spec.authors = ["gatework"]
   spec.email   = ["careline@foxmail.com"]
 
   spec.summary     = "Ruby client and monitoring workflows for the Zabbix 4.0 through 7.x API"

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: zabbix_manager
 version: !ruby/object:Gem::Version
-  version: 6.0.1
+  version: 6.0.3
 platform: ruby
 authors:
-- WENWU YAN
+- gatework
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z