proxsync 2.1.0__tar.gz → 2.1.2__tar.gz

{proxsync-2.1.0/proxsync.egg-info → proxsync-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxsync
-Version: 2.1.0
+Version: 2.1.2
 Summary: NetBox plugin for Proxmox VE inventory synchronization
 Author-email: lixiujie85 <lixiujie85@gmail.com>
 License-Expression: MIT
@@ -36,7 +36,7 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 
 # proxsync
 
-[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/XiuJie2/proxsync)
+[![Version](https://img.shields.io/badge/version-2.1.1-blue.svg)](https://github.com/XiuJie2/proxsync)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
 [![NetBox 4.5–4.6](https://img.shields.io/badge/NetBox-4.5%20–%204.6-green.svg)](https://netbox.dev/)
 [![Proxmox VE](https://img.shields.io/badge/Proxmox-VE%20%2B%20PBS-orange.svg)](https://www.proxmox.com/)
@@ -46,6 +46,49 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 
 ---
 
+## 目錄
+
+- [專案截圖](#專案截圖)
+- [功能特色](#功能特色)
+- [系統需求](#系統需求)
+- [安裝](#安裝)
+- [設定](#設定)
+- [使用方式](#使用方式)
+- [資料對應](#資料對應)
+- [專案結構](#專案結構)
+- [設定優先級](#設定優先級)
+- [常見問題](#常見問題)
+- [開發](#開發)
+- [授權](#授權)
+- [致謝](#致謝)
+
+---
+
+## 專案截圖
+
+<!--
+  將截圖放進 docs/screenshots/ 目錄，檔名對應下方即可自動顯示。
+  建議尺寸：1600x900 或以上，PNG 格式。
+-->
+
+### Dashboard
+
+![Dashboard](docs/screenshots/dashboard.png)
+
+### PVE Cluster 詳情
+
+![PVE Cluster](docs/screenshots/pve-cluster.png)
+
+### Sync Jobs 同步歷史
+
+![Sync Jobs](docs/screenshots/sync-jobs.png)
+
+### Telegram 通知
+
+![Telegram Notification](docs/screenshots/telegram-notification.png)
+
+---
+
 ## 功能特色
 
 ### Proxmox VE 同步
@@ -54,6 +97,8 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 - VM / CT → NetBox **Virtual Machine**（狀態、規格、磁碟、標籤）
 - QEMU Guest Agent 整合，從執行中 VM 取得實際 IP 位址
 - 配置漂移偵測：自動發現 VM 的 CPU / 記憶體設定變更
+- 節點放置檢查：VM 描述 (Notes) 內若標記 `node: <預期節點>`，當實際所在節點與標記不符時透過 Telegram 提醒
+- Guest Agent 異常提醒：VM 執行中卻取不到 IP（QEMU Guest Agent 未啟用或未安裝）時透過 Telegram 提醒
 - 增量同步：透過 SQLite state_db 追蹤變更，避免全量更新
 
 ### 多叢集支援

{proxsync-2.1.0 → proxsync-2.1.2}/README.md

@@ -1,6 +1,6 @@
 # proxsync
 
-[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/XiuJie2/proxsync)
+[![Version](https://img.shields.io/badge/version-2.1.1-blue.svg)](https://github.com/XiuJie2/proxsync)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
 [![NetBox 4.5–4.6](https://img.shields.io/badge/NetBox-4.5%20–%204.6-green.svg)](https://netbox.dev/)
 [![Proxmox VE](https://img.shields.io/badge/Proxmox-VE%20%2B%20PBS-orange.svg)](https://www.proxmox.com/)
@@ -10,6 +10,49 @@
 
 ---
 
+## 目錄
+
+- [專案截圖](#專案截圖)
+- [功能特色](#功能特色)
+- [系統需求](#系統需求)
+- [安裝](#安裝)
+- [設定](#設定)
+- [使用方式](#使用方式)
+- [資料對應](#資料對應)
+- [專案結構](#專案結構)
+- [設定優先級](#設定優先級)
+- [常見問題](#常見問題)
+- [開發](#開發)
+- [授權](#授權)
+- [致謝](#致謝)
+
+---
+
+## 專案截圖
+
+<!--
+  將截圖放進 docs/screenshots/ 目錄，檔名對應下方即可自動顯示。
+  建議尺寸：1600x900 或以上，PNG 格式。
+-->
+
+### Dashboard
+
+![Dashboard](docs/screenshots/dashboard.png)
+
+### PVE Cluster 詳情
+
+![PVE Cluster](docs/screenshots/pve-cluster.png)
+
+### Sync Jobs 同步歷史
+
+![Sync Jobs](docs/screenshots/sync-jobs.png)
+
+### Telegram 通知
+
+![Telegram Notification](docs/screenshots/telegram-notification.png)
+
+---
+
 ## 功能特色
 
 ### Proxmox VE 同步
@@ -18,6 +61,8 @@
 - VM / CT → NetBox **Virtual Machine**（狀態、規格、磁碟、標籤）
 - QEMU Guest Agent 整合，從執行中 VM 取得實際 IP 位址
 - 配置漂移偵測：自動發現 VM 的 CPU / 記憶體設定變更
+- 節點放置檢查：VM 描述 (Notes) 內若標記 `node: <預期節點>`，當實際所在節點與標記不符時透過 Telegram 提醒
+- Guest Agent 異常提醒：VM 執行中卻取不到 IP（QEMU Guest Agent 未啟用或未安裝）時透過 Telegram 提醒
 - 增量同步：透過 SQLite state_db 追蹤變更，避免全量更新
 
 ### 多叢集支援

{proxsync-2.1.0 → proxsync-2.1.2/proxsync.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: proxsync
-Version: 2.1.0
+Version: 2.1.2
 Summary: NetBox plugin for Proxmox VE inventory synchronization
 Author-email: lixiujie85 <lixiujie85@gmail.com>
 License-Expression: MIT
@@ -36,7 +36,7 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 
 # proxsync
 
-[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/XiuJie2/proxsync)
+[![Version](https://img.shields.io/badge/version-2.1.1-blue.svg)](https://github.com/XiuJie2/proxsync)
 [![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
 [![NetBox 4.5–4.6](https://img.shields.io/badge/NetBox-4.5%20–%204.6-green.svg)](https://netbox.dev/)
 [![Proxmox VE](https://img.shields.io/badge/Proxmox-VE%20%2B%20PBS-orange.svg)](https://www.proxmox.com/)
@@ -46,6 +46,49 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 
 ---
 
+## 目錄
+
+- [專案截圖](#專案截圖)
+- [功能特色](#功能特色)
+- [系統需求](#系統需求)
+- [安裝](#安裝)
+- [設定](#設定)
+- [使用方式](#使用方式)
+- [資料對應](#資料對應)
+- [專案結構](#專案結構)
+- [設定優先級](#設定優先級)
+- [常見問題](#常見問題)
+- [開發](#開發)
+- [授權](#授權)
+- [致謝](#致謝)
+
+---
+
+## 專案截圖
+
+<!--
+  將截圖放進 docs/screenshots/ 目錄，檔名對應下方即可自動顯示。
+  建議尺寸：1600x900 或以上，PNG 格式。
+-->
+
+### Dashboard
+
+![Dashboard](docs/screenshots/dashboard.png)
+
+### PVE Cluster 詳情
+
+![PVE Cluster](docs/screenshots/pve-cluster.png)
+
+### Sync Jobs 同步歷史
+
+![Sync Jobs](docs/screenshots/sync-jobs.png)
+
+### Telegram 通知
+
+![Telegram Notification](docs/screenshots/telegram-notification.png)
+
+---
+
 ## 功能特色
 
 ### Proxmox VE 同步
@@ -54,6 +97,8 @@ Requires-Dist: pytest-cov>=4.0; extra == "dev"
 - VM / CT → NetBox **Virtual Machine**（狀態、規格、磁碟、標籤）
 - QEMU Guest Agent 整合，從執行中 VM 取得實際 IP 位址
 - 配置漂移偵測：自動發現 VM 的 CPU / 記憶體設定變更
+- 節點放置檢查：VM 描述 (Notes) 內若標記 `node: <預期節點>`，當實際所在節點與標記不符時透過 Telegram 提醒
+- Guest Agent 異常提醒：VM 執行中卻取不到 IP（QEMU Guest Agent 未啟用或未安裝）時透過 Telegram 提醒
 - 增量同步：透過 SQLite state_db 追蹤變更，避免全量更新
 
 ### 多叢集支援

{proxsync-2.1.0 → proxsync-2.1.2}/pve_sync.py

@@ -44,6 +44,8 @@ class OptimizedPVEToNetBoxSync:
             'config_drifts_detected': 0,
             'tag_changes': 0,
             'resources_alert': 0,
+            'node_mismatch_alerts': 0,
+            'no_ip_alerts': 0,
             'total_vms': 0,
             'success_vms': 0,
             'elapsed_time': 0
@@ -125,12 +127,25 @@ class OptimizedPVEToNetBoxSync:
         self.error_log = []
 
     # ---------- Telegram ----------
-    def send_telegram_notification(self, message: str):
+    # Max Telegram messages per sync run; excess are counted and reported in the summary.
+    _MAX_TELEGRAM_PER_SYNC = 20
+
+    def send_telegram_notification(self, message: str) -> bool:
+        if not getattr(self, 'notify_on_sync', True):
+            return False
+        if not self.telegram_bot_token or not self.telegram_chat_id:
+            return False
+        # Throttle: cap messages per sync run to avoid flooding on bulk changes.
+        sent = getattr(self, '_telegram_sent', 0)
+        if sent >= self._MAX_TELEGRAM_PER_SYNC:
+            self._telegram_suppressed = getattr(self, '_telegram_suppressed', 0) + 1
+            return False
         try:
             url = f"https://api.telegram.org/bot{self.telegram_bot_token}/sendMessage"
             payload = {'chat_id': self.telegram_chat_id, 'text': message, 'parse_mode': 'HTML'}
             response = requests.post(url, data=payload, timeout=10)
             if response.status_code == 200:
+                self._telegram_sent = sent + 1
                 print(f"✓ Telegram 通知已發送")
                 return True
             else:
@@ -233,6 +248,10 @@ class OptimizedPVEToNetBoxSync:
             extras.append(f"🏷️ 標籤變更: {self.stats['tag_changes']}")
         if self.stats.get('resources_alert', 0) > 0:
             extras.append(f"⚠️ 資源告警: {self.stats['resources_alert']}")
+        if self.stats.get('node_mismatch_alerts', 0) > 0:
+            extras.append(f"📍 節點放置異常: {self.stats['node_mismatch_alerts']}")
+        if self.stats.get('no_ip_alerts', 0) > 0:
+            extras.append(f"🌐 運行中但無 IP: {self.stats['no_ip_alerts']}")
         if extras:
             message += "\n🔍 檢測發現:\n" + "\n".join(extras)
         if self.error_log:
@@ -241,6 +260,9 @@ class OptimizedPVEToNetBoxSync:
                 message += f"• {error['vm_name']} - {error['ip_address']}\n"
             if len(self.error_log) > 5:
                 message += f"• ... 還有 {len(self.error_log) - 5} 個錯誤\n"
+        suppressed = getattr(self, '_telegram_suppressed', 0)
+        if suppressed:
+            message += f"\n📵 本輪通知已達上限，{suppressed} 則訊息被壓制（詳見 NetBox 漂移事件記錄）"
         self.send_telegram_notification(message)
 
     # ---------- API 連接 ----------
@@ -327,6 +349,7 @@ class OptimizedPVEToNetBoxSync:
             self.nb_cache['platforms'][platform.name.lower()] = platform
         for role in self.nb_api.dcim.device_roles.all():
             self.nb_cache['roles'][role.name.lower()] = role
+            self.nb_cache['device_roles'][role.name.lower()] = role
         for cluster in self.nb_api.virtualization.clusters.all():
             self.nb_cache['clusters'][str(cluster.id)] = cluster
         for site in self.nb_api.dcim.sites.all():
@@ -335,8 +358,6 @@ class OptimizedPVEToNetBoxSync:
             self.nb_cache['manufacturers'][manufacturer.name.lower()] = manufacturer
         for device_type in self.nb_api.dcim.device_types.all():
             self.nb_cache['device_types'][device_type.model.lower()] = device_type
-        for device_role in self.nb_api.dcim.device_roles.all():
-            self.nb_cache['device_roles'][device_role.name.lower()] = device_role
         for cluster_type in self.nb_api.virtualization.cluster_types.all():
             self.nb_cache['cluster_types'][cluster_type.name.lower()] = cluster_type
         elapsed = time.time() - start_time
@@ -393,13 +414,13 @@ class OptimizedPVEToNetBoxSync:
                     vm['node'] = node_name
                     all_vms.append(vm)
                 self.pve_cache['vms_by_node'][node_name] = all_vms
-                for vm in all_vms[:10]:
+                for vm in all_vms:
                     try:
                         if vm['type'] == 'qemu':
                             vm['config'] = self.pve_api.nodes(node_name).qemu(vm['vmid']).config.get()
                         else:
                             vm['config'] = self.pve_api.nodes(node_name).lxc(vm['vmid']).config.get()
-                    except:
+                    except Exception:
                         pass
             except Exception as e:
                 print(f"  加載節點 {node_name} 的虛擬機失敗: {e}")
@@ -1147,6 +1168,25 @@ class OptimizedPVEToNetBoxSync:
                 disks[key] = m.group(1) if m else val_str[:80]
         return disks
 
+    @staticmethod
+    def _norm_desc(s) -> str:
+        """Normalize description: unify line endings, strip whitespace."""
+        return (s or '').replace('\r\n', '\n').replace('\r', '\n').strip()
+
+    @staticmethod
+    def _parse_expected_node(description: str) -> Optional[str]:
+        """從 VM 描述 (Notes) 解析使用者標記的預期節點。
+
+        支援格式如 "node: 181" 或 "node：181"（半形/全形冒號皆可，
+        且不區分大小寫，Node/NODE/node 皆可），必須獨佔一行。
+        找不到則回傳 None。
+        """
+        import re
+        if not description:
+            return None
+        m = re.search(r'(?im)^\s*node\s*[:：]\s*(\S+)\s*$', description)
+        return m.group(1).strip() if m else None
+
     def _write_drift_event(self, vm_name: str, vmid: int, drift_type: str,
                            field_name: str, old_value: str, new_value: str,
                            notified: bool = False):
@@ -1169,13 +1209,13 @@ class OptimizedPVEToNetBoxSync:
         except Exception as e:
             print(f"  ⚠ 無法寫入漂移事件記錄: {e}")
 
-    def detect_new_vm(self, vm_id: int, vm_name: str, node_name: str):
+    def detect_new_vm(self, vm_id: int, vm_name: str, node_name: str, last_config=None):
         """若此 vmid 在先前同步中不存在（但叢集有先前記錄），視為新增 VM。"""
         if not self.enhanced_mode or not self.state_db:
             return
         if not self._known_vmids:
             return  # 首次同步，無先前記錄，不觸發
-        if self.state_db.get_last_vm_config(vm_id, self.cluster_name):
+        if last_config:
             return  # 已有記錄，不是新增
         print(f"🆕 VM {vm_name} 新增偵測 (ID: {vm_id}, 節點: {node_name})")
         self.stats['config_drifts_detected'] += 1
@@ -1314,15 +1354,29 @@ class OptimizedPVEToNetBoxSync:
                 print(f"  🧹 Log 清理：刪除 {d_del} 筆漂移事件、{t_del} 筆操作記錄（>{days} 天）")
         except Exception as exc:
             print(f"  ⚠️ Log 清理失敗: {exc}")
+        # Also clean up state_db vm_config_history (keep latest row per VM, remove old history)
+        if self.state_db:
+            try:
+                from pve_sync_plugin.models import PvePluginSettings
+                days = PvePluginSettings.load().log_retention_days
+                if days:
+                    h_del = self.state_db.cleanup_old_history(self.cluster_name, days)
+                    if h_del:
+                        print(f"  🧹 state_db 清理：刪除 {h_del} 筆舊配置歷史（>{days} 天）")
+            except Exception as exc:
+                print(f"  ⚠️ state_db 歷史清理失敗: {exc}")
 
     def sync_vm_tasks(self):
         """從 PVE 各節點抓取 VM 操作記錄（建立/刪除/Clone/遷移）並同步到 NetBox。"""
+        import calendar
+        import datetime as _dt
         try:
             from django.utils import timezone
             from pve_sync_plugin.models import PveVmTaskLog
         except ImportError:
             return
 
+        _utc = _dt.timezone.utc
         VM_TASK_TYPES = {
             "qmcreate", "qmdestroy", "qmclone", "qmmigrate", "qmrestore",
             "qmstart", "qmstop", "qmshutdown", "qmreboot",
@@ -1356,10 +1410,18 @@ class OptimizedPVEToNetBoxSync:
             cluster_name=self.cluster_name
         ).order_by("-start_time").values_list("start_time", flat=True).first()
         if latest:
-            import calendar
             since_ts = int(calendar.timegm(latest.utctimetuple())) + 1
         else:
             since_ts = int(time.time()) - 30 * 86400
+
+        # Pre-fetch existing UPIDs in the window → O(1) lookup instead of N+1 queries
+        since_dt = _dt.datetime.fromtimestamp(since_ts, tz=_utc)
+        existing_upids: set = set(
+            PveVmTaskLog.objects
+            .filter(cluster_name=self.cluster_name, start_time__gte=since_dt)
+            .values_list("upid", flat=True)
+        )
+        new_upids: set = set()  # UPIDs inserted this run (avoid duplicates within same run)
         new_count = 0
 
         for node_name in self.pve_cache.get("vms_by_node", {}):
@@ -1383,8 +1445,8 @@ class OptimizedPVEToNetBoxSync:
                 except (ValueError, TypeError):
                     continue
 
-                # UPID 去重
-                if PveVmTaskLog.objects.filter(upid=upid).exists():
+                # UPID 去重（使用預先撈取的集合，避免 N+1 查詢）
+                if upid in existing_upids or upid in new_upids:
                     continue
 
                 task_type = task.get("type")
@@ -1394,8 +1456,6 @@ class OptimizedPVEToNetBoxSync:
                 status    = task.get("status", "") or ""
                 vm_name   = vmid_to_name.get(vmid, f"VM-{vmid}")
 
-                import datetime as _dt
-                _utc = _dt.timezone.utc
                 start_dt = _dt.datetime.fromtimestamp(start_ts, tz=_utc) if start_ts else timezone.now()
                 end_dt   = _dt.datetime.fromtimestamp(end_ts,   tz=_utc) if end_ts   else None
 
@@ -1412,6 +1472,7 @@ class OptimizedPVEToNetBoxSync:
                     status=status,
                     notified_telegram=False,
                 )
+                new_upids.add(upid)
                 new_count += 1
 
                 # Telegram 通知（僅近期且已完成的操作）
@@ -1439,11 +1500,12 @@ class OptimizedPVEToNetBoxSync:
 
     def detect_config_drift(self, vm_id: int, vm_name: str, vm_config: Dict[str, Any],
                             current_tags: List[str], network_interfaces: List[Dict] = None,
-                            current_node: str = None) -> List[Dict]:
+                            current_node: str = None, last_config=None) -> List[Dict]:
         if not self.enhanced_mode or not self.state_db:
             return []
         drifts = []
-        last_config = self.state_db.get_last_vm_config(vm_id, self.cluster_name)
+        if last_config is None:
+            last_config = self.state_db.get_last_vm_config(vm_id, self.cluster_name)
         if not last_config:
             return drifts
         current_memory = int(vm_config.get('memory', 0))
@@ -1524,8 +1586,8 @@ class OptimizedPVEToNetBoxSync:
                     self._write_drift_event(vm_name, vm_id, 'disk_change', k, old_v, new_v, notified=True)
 
         # VM 描述變更偵測
-        current_desc = (vm_config.get('description') or '').strip()[:500]
-        old_desc = (last_config.get('description') or '').strip()
+        current_desc = self._norm_desc(vm_config.get('description'))[:500].strip()
+        old_desc = self._norm_desc(last_config.get('description'))[:500].strip()
         if old_desc and old_desc != current_desc:
             self.stats['config_drifts_detected'] += 1
             print(f"📝 VM {vm_name} 描述變更")
@@ -1565,7 +1627,7 @@ class OptimizedPVEToNetBoxSync:
         return drifts
 
     def should_sync_vm(self, vm_id: int, vm_config: Dict[str, Any], tags: List[str],
-                       network_interfaces: List[Dict] = None) -> bool:
+                       network_interfaces: List[Dict] = None, last_config=None) -> bool:
         if not self.sync_config.get('incremental', True):
             return True
         if self.sync_config.get('force_full_sync', False):
@@ -1573,34 +1635,35 @@ class OptimizedPVEToNetBoxSync:
         current_hash = compute_config_hash(vm_config, tags, network_interfaces)
         if not self.state_db:
             return True
-        last_config = self.state_db.get_last_vm_config(vm_id, self.cluster_name)
+        if last_config is None:
+            last_config = self.state_db.get_last_vm_config(vm_id, self.cluster_name)
         if not last_config:
             return True
         if current_hash != last_config.get('config_hash'):
             return True
         return False
 
-    def detect_tag_changes(self, vm_id: int, vm_name: str, current_tags: List[str]) -> List[Dict]:
+    def detect_tag_changes(self, vm_id: int, vm_name: str, current_tags: List[str],
+                           last_config=None) -> List[Dict]:
         if not self.enhanced_mode or not self.state_db:
             return []
-        changes = []
-        last_config = self.state_db.get_last_vm_config(vm_id, self.cluster_name)
+        if last_config is None:
+            last_config = self.state_db.get_last_vm_config(vm_id, self.cluster_name)
         if not last_config:
-            return changes
+            return []
         old_tags = set(last_config.get('tags', []))
         new_tags = set(current_tags)
         added = new_tags - old_tags
         removed = old_tags - new_tags
+        changes = []
         for tag in added:
             changes.append({'type': 'added', 'tag': tag})
             self.stats['tag_changes'] += 1
             print(f"🏷️  VM {vm_name} 新增標籤: {tag}")
-            self._write_drift_event(vm_name, vm_id, 'tag_change', 'tags', '', tag, notified=False)
         for tag in removed:
             changes.append({'type': 'removed', 'tag': tag})
             self.stats['tag_changes'] += 1
             print(f"🏷️  VM {vm_name} 移除標籤: {tag}")
-            self._write_drift_event(vm_name, vm_id, 'tag_change', 'tags', tag, '', notified=False)
         if changes:
             added_list = [c['tag'] for c in changes if c['type'] == 'added']
             removed_list = [c['tag'] for c in changes if c['type'] == 'removed']
@@ -1616,7 +1679,12 @@ class OptimizedPVEToNetBoxSync:
                 f"📅 時間: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n"
                 f"{detail}\n請確認是否為預期變更。"
             )
-            self.send_telegram_notification(tag_msg)
+            notified = self.send_telegram_notification(tag_msg)
+            for c in changes:
+                if c['type'] == 'added':
+                    self._write_drift_event(vm_name, vm_id, 'tag_change', 'tags', '', c['tag'], notified=notified)
+                else:
+                    self._write_drift_event(vm_name, vm_id, 'tag_change', 'tags', c['tag'], '', notified=notified)
         return changes
 
     def detect_ip_change(self, vm_id: int, vm_name: str, current_ip: str):
@@ -1643,6 +1711,36 @@ class OptimizedPVEToNetBoxSync:
         self.send_telegram_notification(ip_msg)
         self._write_drift_event(vm_name, vm_id, 'ip_change', 'primary_ip', old_ip, current_ip, notified=True)
 
+    def check_agent_ip_missing(self, vm_id: str, vm_name: str, vm_type: str, is_template: bool,
+                               vm_status: str, qemu_agent_enabled: bool, ip_str: str):
+        """VM 已在執行中，卻完全取不到 IP —— 多半是 QEMU Guest Agent 未啟用/未安裝。
+
+        每次同步皆檢查（非一次性事件），只要問題未解決就會持續提醒。
+        """
+        if vm_type != 'qemu' or is_template or vm_status != 'running' or ip_str:
+            return
+        print(f"🌐 VM {vm_name} 運行中但無法取得 IP")
+        self.stats['no_ip_alerts'] = self.stats.get('no_ip_alerts', 0) + 1
+        if qemu_agent_enabled:
+            detail = (
+                "⚠️ QEMU Guest Agent 已在設定中啟用，但仍無法取得 IP，"
+                "請確認 VM 內部的 qemu-guest-agent 服務是否已安裝並執行中。"
+            )
+        else:
+            detail = (
+                "⚠️ 此 VM 尚未啟用 QEMU Guest Agent（Options → QEMU Guest Agent），"
+                "請啟用後於 VM 內安裝對應套件（qemu-guest-agent）。"
+            )
+        msg = (
+            f"🌐 <b>VM 運行中但無法取得 IP</b>\n\n"
+            f"🖥️ 名稱: <b>{vm_name}</b> (ID: {vm_id})\n"
+            f"🔀 叢集: {self.cluster_name}\n"
+            f"📅 時間: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+            f"{detail}"
+        )
+        self.send_telegram_notification(msg)
+        self._write_drift_event(vm_name, int(vm_id), 'agent_ip_missing', 'primary_ip', '', '', notified=True)
+
     # ---------- 虛擬機處理主邏輯 ----------
     def process_virtual_machine(self, vm_data: Dict, device, cluster: Dict, force: bool = False) -> bool:
         vm_id = str(vm_data['vmid'])
@@ -1660,7 +1758,9 @@ class OptimizedPVEToNetBoxSync:
                 else:
                     vm_config = self.pve_api.nodes(node_name).lxc(vm_data['vmid']).config.get()
         except Exception as e:
-            print(f"  獲取 VM 配置失敗: {e}")
+            error_msg = str(e)
+            print(f"  獲取 VM 配置失敗: {error_msg}")
+            self.log_vm_sync_error(original_vm_name, int(vm_id), f"無法取得 PVE 配置: {error_msg}")
             return False
         is_template = vm_data.get('is_template', False) or vm_config.get('template', 0) == 1
         boot_choice = 'on' if vm_config.get('onboot', 0) == 1 else 'off'
@@ -1684,10 +1784,16 @@ class OptimizedPVEToNetBoxSync:
                             tag_ids.append(tag.id)
                         except Exception as e:
                             print(f"  建立標籤失敗 {tag_name}: {e}")
+        # Read last_config once; share with detect_new_vm / detect_tag_changes /
+        # detect_config_drift / should_sync_vm to avoid repeated SQLite round-trips.
+        last_config = (
+            self.state_db.get_last_vm_config(int(vm_id), self.cluster_name)
+            if (self.enhanced_mode and self.state_db) else None
+        )
         if self.enhanced_mode:
-            self.detect_new_vm(int(vm_id), original_vm_name, node_name)
+            self.detect_new_vm(int(vm_id), original_vm_name, node_name, last_config=last_config)
         if self.enhanced_mode and tag_names:
-            self.detect_tag_changes(int(vm_id), original_vm_name, tag_names)
+            self.detect_tag_changes(int(vm_id), original_vm_name, tag_names, last_config=last_config)
         vm_status = vm_data.get('status', '')
         if tag_names and vm_status in ('running', 'stopped'):
             first_tag = tag_names[0].lower()
@@ -1716,6 +1822,26 @@ class OptimizedPVEToNetBoxSync:
 ⚠️ 虛擬機應處於關機狀態，請確認開機原因。
 """
                 self.send_telegram_notification(message)
+
+        # 節點放置檢查：VM 描述 (Notes) 內若標記 "node: <預期節點>"，
+        # 而目前實際所在節點與其不符，則提醒（每次同步皆檢查，非一次性事件）。
+        expected_node = self._parse_expected_node(vm_config.get('description', ''))
+        if expected_node and expected_node != node_name:
+            print(f"📍 VM {original_vm_name} 節點不符期望: 目前={node_name}, 期望={expected_node}")
+            self.stats['node_mismatch_alerts'] += 1
+            node_mismatch_msg = (
+                f"📍 <b>VM 節點與 Notes 標記不符</b>\n\n"
+                f"🖥️ 名稱: <b>{original_vm_name}</b> (ID: {vm_id})\n"
+                f"🔀 叢集: {self.cluster_name}\n"
+                f"📅 時間: {time.strftime('%Y-%m-%d %H:%M:%S')}\n\n"
+                f"📌 目前節點: <code>{node_name}</code>\n"
+                f"📋 Notes 標記節點: <code>{expected_node}</code>\n\n"
+                f"⚠️ 請確認此 VM 是否應遷回指定節點。"
+            )
+            self.send_telegram_notification(node_mismatch_msg)
+            self._write_drift_event(original_vm_name, int(vm_id), 'node_mismatch', 'node',
+                                    node_name, expected_node, notified=True)
+
         role_id = None
         vm_pool = self.get_vm_pool(vm_data['vmid'], vm_type)
         if vm_pool:
@@ -1770,8 +1896,9 @@ class OptimizedPVEToNetBoxSync:
                 })
         if self.enhanced_mode:
             self.detect_config_drift(int(vm_id), original_vm_name, vm_config, tag_names,
-                                     network_interfaces, current_node=node_name)
-            if not force and not self.should_sync_vm(int(vm_id), vm_config, tag_names, network_interfaces):
+                                     network_interfaces, current_node=node_name, last_config=last_config)
+            if not force and not self.should_sync_vm(int(vm_id), vm_config, tag_names, network_interfaces,
+                                                     last_config=last_config):
                 cached_vm = self.nb_cache['virtual_machines_by_serial'].get(f"{vm_id}::{cluster['id']}")
                 if cached_vm is None:
                     # VM 在 NetBox 中不存在（例如隨節點被連帶刪除），
@@ -1817,18 +1944,20 @@ class OptimizedPVEToNetBoxSync:
                         except Exception as e:
                             print(f"  設定 VM 主 IP 失敗: {e}")
                     print(f"  ℹ️  VM {original_vm_name} 無配置變更，跳過同步")
+                    cur_ip = getattr(skip_primary_ip, 'address', None) \
+                        or getattr(getattr(cached_vm, 'primary_ip4', None), 'address', None) or ''
+                    self.check_agent_ip_missing(vm_id, original_vm_name, vm_type, is_template,
+                                                vm_status, qemu_agent_enabled, cur_ip)
                     if self.state_db:
                         try:
                             config_hash = compute_config_hash(vm_config, tag_names, network_interfaces)
                             memory = int(vm_config.get('memory', 0))
                             vcpus_save = int(vm_config.get('vcpus', vcpus))
-                            cur_ip = getattr(skip_primary_ip, 'address', None) \
-                                or getattr(getattr(cached_vm, 'primary_ip4', None), 'address', None) or ''
                             self.state_db.save_vm_config_snapshot(
                                 vm_id=int(vm_id), cluster_name=self.cluster_name, config_hash=config_hash,
                                 memory=memory, vcpus=vcpus_save, tags=tag_names,
                                 node=node_name, primary_ip=cur_ip, vm_name=original_vm_name,
-                                description=(vm_config.get('description') or '').strip()[:500],
+                                description=self._norm_desc(vm_config.get('description'))[:500].strip(),
                                 disk_summary=json.dumps(self._parse_disk_summary(vm_config)),
                             )
                         except Exception as _snap_err:
@@ -1885,7 +2014,7 @@ class OptimizedPVEToNetBoxSync:
                 update_data = {
                     'name': vm_name, 'cluster': cluster['id'], 'device': device.id, 'role': role_id,
                     'vcpus': vcpus, 'memory': int(vm_config.get('memory', 0)), 'status': status,
-                    'description': (vm_config.get('description') or '')[:200], 'platform': platform_id,
+                    'description': self._norm_desc(vm_config.get('description'))[:200], 'platform': platform_id,
                     'start_on_boot': boot_choice
                 }
                 if tag_ids:
@@ -1904,7 +2033,7 @@ class OptimizedPVEToNetBoxSync:
                 vm_data_dict = {
                     'serial': vm_id, 'name': vm_name, 'cluster': cluster['id'], 'device': device.id,
                     'role': role_id, 'vcpus': vcpus, 'memory': int(vm_config.get('memory', 0)),
-                    'status': status, 'description': (vm_config.get('description') or '')[:200],
+                    'status': status, 'description': self._norm_desc(vm_config.get('description'))[:200],
                     'platform': platform_id, 'start_on_boot': boot_choice
                 }
                 if tag_ids:
@@ -1932,6 +2061,8 @@ class OptimizedPVEToNetBoxSync:
                     print(f"  設定 VM 主 IP 失敗: {e}")
             if self.enhanced_mode and primary_ip_str:
                 self.detect_ip_change(int(vm_id), original_vm_name, primary_ip_str)
+            self.check_agent_ip_missing(vm_id, original_vm_name, vm_type, is_template,
+                                        vm_status, qemu_agent_enabled, primary_ip_str)
             print(f"  標籤: {len(tag_ids)}個, 介面: {interface_count}個, 磁碟: {disk_count}個, 大小: {disk_size}MB")
             if self.enhanced_mode and self.state_db:
                 config_hash = compute_config_hash(vm_config, tag_names, network_interfaces)
@@ -1941,7 +2072,7 @@ class OptimizedPVEToNetBoxSync:
                     vm_id=int(vm_id), cluster_name=self.cluster_name, config_hash=config_hash,
                     memory=memory, vcpus=vcpus_save, tags=tag_names,
                     node=node_name, primary_ip=primary_ip_str, vm_name=original_vm_name,
-                    description=(vm_config.get('description') or '').strip()[:500],
+                    description=self._norm_desc(vm_config.get('description'))[:500].strip(),
                     disk_summary=json.dumps(self._parse_disk_summary(vm_config)),
                 )
             return True
@@ -1967,7 +2098,7 @@ class OptimizedPVEToNetBoxSync:
                             node=node_name,
                             primary_ip=_ip,
                             vm_name=original_vm_name,
-                            description=(vm_config.get('description') or '').strip()[:500],
+                            description=self._norm_desc(vm_config.get('description'))[:500].strip(),
                             disk_summary=json.dumps(self._parse_disk_summary(vm_config)),
                         )
                 except Exception:
@@ -2010,6 +2141,18 @@ class OptimizedPVEToNetBoxSync:
         print("=" * 50)
         if self.enhanced_mode and self.state_db:
             self.sync_log_id = self.state_db.start_sync_log(self.cluster_name)
+        # Load notify_on_sync from PveClusterConfig (DB setting takes precedence over default True)
+        self.notify_on_sync = True
+        try:
+            from pve_sync_plugin.models import PveClusterConfig
+            cfg = PveClusterConfig.objects.filter(name=self.cluster_name).first()
+            if cfg is not None:
+                self.notify_on_sync = cfg.notify_on_sync
+        except Exception:
+            pass
+        # Reset per-sync Telegram counters
+        self._telegram_sent = 0
+        self._telegram_suppressed = 0
         sync_mode = "增量" if self.sync_config.get('incremental', True) else "全量"
         start_message = f"""
 🔄 <b>PVE-NetBox 同步開始</b>

{proxsync-2.1.0 → proxsync-2.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "proxsync"
-version = "2.1.0"
+version = "2.1.2"
 description = "NetBox plugin for Proxmox VE inventory synchronization"
 readme = "README.md"
 requires-python = ">=3.10"

{proxsync-2.1.0 → proxsync-2.1.2}/state_db.py

@@ -154,7 +154,7 @@ class StateDB:
             with sqlite3.connect(self.db_path) as conn:
                 conn.execute(
                     """
-                    INSERT INTO vm_config_history
+                    INSERT OR REPLACE INTO vm_config_history
                     (vm_id, cluster_name, config_hash, memory, vcpus, tags_json,
                      node, primary_ip, vm_name, description, disk_summary)
                     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
@@ -256,6 +256,28 @@ class StateDB:
                     })
                 return changes
 
+    def cleanup_old_history(self, cluster_name: str, days: int) -> int:
+        """Delete vm_config_history rows older than `days`, keeping the latest row per VM."""
+        import datetime as _dt
+        cutoff = (_dt.datetime.utcnow() - _dt.timedelta(days=days)).strftime('%Y-%m-%d %H:%M:%S')
+        with self._lock:
+            with sqlite3.connect(self.db_path) as conn:
+                result = conn.execute(
+                    """
+                    DELETE FROM vm_config_history
+                    WHERE cluster_name = ?
+                      AND sync_time < ?
+                      AND sync_time NOT IN (
+                          SELECT MAX(sync_time) FROM vm_config_history
+                          WHERE cluster_name = ?
+                          GROUP BY vm_id
+                      )
+                    """,
+                    (cluster_name, cutoff, cluster_name),
+                )
+                conn.commit()
+                return result.rowcount
+
     # ========== 节点状态历史 ==========
 
     def save_node_status(self, node_name: str, cluster_name: str, status: str):
@@ -507,7 +529,7 @@ def compute_config_hash(vm_config: Dict[str, Any], tags: List[str], network_inte
         'ostype': vm_config.get('ostype', ''),
         'cores': vm_config.get('cores', 1),
         'sockets': vm_config.get('sockets', 1),
-        'description': vm_config.get('description', '')[:200],  # 限制长度
+        'description': (vm_config.get('description') or '').replace('\r\n', '\n').replace('\r', '\n').strip()[:200].strip(),
         'tags': sorted(tags),  # 排序以确保一致性
         'networks': net_config  # 添加网络接口配置
     }