feat: backup architecture docs, source code, and scripts

2026-04-25 17:15:45 +08:00
parent 59809dae1f
commit 1f84e5469f
368 changed files with 146329 additions and 261 deletions
@@ -0,0 +1,392 @@
+---
+document_type: "architecture_design"
+service: "MOMENTRY_CORE"
+title: "Momentry Core 監控架構設計"
+date: "2026-04-22"
+version: "V1.0"
+status: "active"
+owner: "Warren"
+created_by: "OpenCode"
+tags:
+  - "momentry"
+  - "core"
+  - "監控架構設計"
+ai_query_hints:
+  - "查詢 Momentry Core 監控架構設計 的內容"
+  - "Momentry Core 監控架構設計 的主要目的是什麼？"
+  - "如何操作或實施 Momentry Core 監控架構設計？"
+---
+
+# Momentry Core 監控架構設計
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | OpenCode |
+| 建立時間 | 2026-04-22 |
+| 文件版本 | V1.0 |
+| 相關文件 | [ARCHITECTURE_OVERVIEW.md](./ARCHITECTURE_OVERVIEW.md)<br>[PERFORMANCE_AND_SCALABILITY.md](./PERFORMANCE_AND_SCALABILITY.md)<br>[SECURITY_ARCHITECTURE.md](./SECURITY_ARCHITECTURE.md) |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-04-22 | 創建監控架構設計文件 | OpenCode | OpenCode / deepseek-v3.2 |
+
+---
+
+## 1. 監控架構概述
+
+### 1.1 監控目標
+1. **系統健康**：確保所有服務正常運行
+2. **效能監控**：追蹤系統效能指標與瓶頸
+3. **業務指標**：監控關鍵業務流程與用戶行為
+4. **安全監控**：偵測安全威脅與異常行為
+5. **成本監控**：追蹤資源使用與成本優化
+
+### 1.2 監控層次
+```
+應用層監控
+    ├── 業務指標 (用戶行為、轉化率)
+    ├── 應用效能 (API 響應、錯誤率)
+    └── 用戶體驗 (頁面載入、互動延遲)
+        ↓
+系統層監控
+    ├── 服務健康 (進程狀態、端口監聽)
+    ├── 資源使用 (CPU、記憶體、磁碟)
+    └── 網絡流量 (帶寬、連接數)
+        ↓
+基礎設施監控
+    ├── 硬件狀態 (服務器、儲存)
+    ├── 網絡設備 (路由器、交換機)
+    └── 電源環境 (UPS、溫度)
+```
+
+---
+
+## 2. 監控指標體系
+
+### 2.1 系統資源監控
+
+#### 2.1.1 CPU 監控
+| 指標 | 描述 | 告警閾值 | 測量頻率 |
+|------|------|----------|----------|
+| **CPU 使用率** | 總體 CPU 使用百分比 | > 80% 持續5分鐘 | 10秒 |
+| **CPU 負載** | 平均負載 (1, 5, 15分鐘) | > 核心數×2 | 1分鐘 |
+| **CPU 核心數** | 可用 CPU 核心數量 | 變化時告警 | 5分鐘 |
+| **CPU 等待時間** | I/O 等待時間百分比 | > 20% 持續2分鐘 | 30秒 |
+
+#### 2.1.2 記憶體監控
+| 指標 | 描述 | 告警閾值 | 測量頻率 |
+|------|------|----------|----------|
+| **記憶體使用率** | 已用記憶體百分比 | > 85% 持續5分鐘 | 10秒 |
+| **Swap 使用率** | Swap 空間使用百分比 | > 50% | 30秒 |
+| **緩存使用量** | 文件緩存大小 | 監控趨勢 | 1分鐘 |
+| **OOM 事件** | Out of Memory 事件 | 發生即告警 | 實時 |
+
+#### 2.1.3 儲存監控
+| 指標 | 描述 | 告警閾值 | 測量頻率 |
+|------|------|----------|----------|
+| **磁碟使用率** | 磁碟空間使用百分比 | > 90% | 5分鐘 |
+| **磁碟 I/O** | 讀寫速度與延遲 | > 100ms 延遲 | 30秒 |
+| **Inode 使用率** | Inode 使用百分比 | > 80% | 5分鐘 |
+| **文件系統錯誤** | 文件系統錯誤數 | > 0 | 5分鐘 |
+
+### 2.2 網絡監控
+
+#### 2.2.1 網絡流量監控
+| 指標 | 描述 | 告警閾值 | 測量頻率 |
+|------|------|----------|----------|
+| **帶寬使用率** | 網絡帶寬使用百分比 | > 80% 持續5分鐘 | 30秒 |
+| **網絡錯誤率** | 錯誤包與丟包率 | > 1% | 1分鐘 |
+| **TCP 連接數** | 活躍 TCP 連接數量 | > 10000 | 30秒 |
+| **網絡延遲** | 網絡往返延遲 | > 100ms | 10秒 |
+
+#### 2.2.2 端口監控
+| 端口 | 服務 | 監控內容 | 告警條件 |
+|------|------|----------|----------|
+| **3002** | Momentry API | 端口監聽、響應時間 | 端口關閉、響應>1秒 |
+| **3003** | Playground | 端口監聽、可用性 | 端口關閉、無法訪問 |
+| **5432** | PostgreSQL | 連接數、查詢延遲 | 連接失敗、查詢>500ms |
+| **6379** | Redis | 內存使用、命中率 | 內存>90%、命中率<80% |
+| **6333** | Qdrant | 向量搜索延遲 | 搜索>100ms |
+
+### 2.3 應用監控
+
+#### 2.3.1 API 監控
+| 端點 | 監控指標 | 告警閾值 | SLO 目標 |
+|------|----------|----------|----------|
+| `GET /api/health` | 響應時間、狀態碼 | 響應>200ms、非200狀態 | 99.9% 可用性 |
+| `POST /api/videos/register` | 處理時間、成功率 | 處理>5分鐘、成功率<95% | 95% 成功率 |
+| `GET /api/search` | 響應時間、召回率 | 響應>2秒、召回率<85% | P95 < 1.5秒 |
+| `GET /api/chunks/{id}` | 緩存命中率、延遲 | 命中率<70%、延遲>500ms | 80% 緩存命中 |
+
+#### 2.3.2 處理器監控
+| 處理器 | 監控指標 | 告警閾值 | 恢復策略 |
+|--------|----------|----------|----------|
+| **ASR** | 處理時間、錯誤率 | 超時(3600s)、錯誤>10% | 重試、降級處理 |
+| **OCR** | GPU 使用率、準確率 | GPU>90%、準確率<80% | 調整批量大小 |
+| **CUT** | 算法複雜度、內存使用 | 內存泄漏、O(n²)增長 | 優化算法 |
+| **YOLO** | 推理時間、檢測準確率 | 推理>100ms/幀、準確率下降 | 模型優化 |
+
+---
+
+## 3. 監控工具棧
+
+### 3.1 監控系統架構
+```
+數據收集層
+    ├── Prometheus (指標收集)
+    ├── Fluentd (日誌收集)
+    ├── OpenTelemetry (追蹤數據)
+    └── Filebeat (文件日誌)
+        ↓
+數據存儲層
+    ├── Prometheus TSDB (指標存儲)
+    ├── Elasticsearch (日誌存儲)
+    ├── Jaeger (追蹤存儲)
+    └── InfluxDB (時序數據)
+        ↓
+可視化層
+    ├── Grafana (儀表板)
+    ├── Kibana (日誌分析)
+    └── Jaeger UI (追蹤可視化)
+        ↓
+告警層
+    ├── Alertmanager (告警管理)
+    ├── PagerDuty (值班管理)
+    └── Slack/Email (通知渠道)
+```
+
+### 3.2 監控工具配置
+
+#### 3.2.1 Prometheus 配置
+```yaml
+# prometheus.yml
+global:
+  scrape_interval: 15s
+  evaluation_interval: 15s
+
+scrape_configs:
+  - job_name: 'momentry-api'
+    static_configs:
+      - targets: ['localhost:3002']
+        labels:
+          service: 'momentry-api'
+          environment: 'production'
+
+  - job_name: 'postgresql'
+    static_configs:
+      - targets: ['localhost:9187']  # postgres_exporter
+        labels:
+          service: 'postgresql'
+
+  - job_name: 'redis'
+    static_configs:
+      - targets: ['localhost:9121']  # redis_exporter
+        labels:
+          service: 'redis'
+
+  - job_name: 'node'
+    static_configs:
+      - targets: ['localhost:9100']  # node_exporter
+        labels:
+          service: 'node'
+```
+
+#### 3.2.2 Grafana 儀表板
+| 儀表板 | 用途 | 關鍵面板 |
+|--------|------|----------|
+| **系統概覽** | 整體系統健康 | CPU/記憶體/磁碟使用率 |
+| **API 監控** | API 效能監控 | 響應時間、錯誤率、QPS |
+| **數據庫監控** | 數據庫效能 | 查詢延遲、連接數、鎖等待 |
+| **處理器監控** | 視頻處理監控 | 處理時間、隊列長度、錯誤率 |
+| **業務監控** | 業務指標 | 註冊數、搜索數、用戶活躍度 |
+
+---
+
+## 4. 日誌管理
+
+### 4.1 日誌分級與格式
+
+#### 4.1.1 日誌級別
+| 級別 | 描述 | 使用場景 |
+|------|------|----------|
+| **ERROR** | 錯誤，需要立即處理 | 系統崩潰、數據丟失 |
+| **WARN** | 警告，需要注意 | 效能下降、配置問題 |
+| **INFO** | 信息，正常操作 | 用戶操作、系統狀態 |
+| **DEBUG** | 調試，開發使用 | 詳細調試信息 |
+| **TRACE** | 追蹤，詳細追蹤 | 性能分析、調試 |
+
+#### 4.1.2 日誌格式規範
+```json
+{
+  "timestamp": "2026-04-22T10:30:00Z",
+  "level": "INFO",
+  "service": "momentry-api",
+  "module": "video_processor",
+  "message": "Video processing completed",
+  "video_id": "video_123",
+  "duration_ms": 12345,
+  "user_id": "user_456",
+  "request_id": "req_789",
+  "correlation_id": "corr_abc"
+}
+```
+
+### 4.2 日誌收集與分析
+
+#### 4.2.1 日誌收集配置
+```yaml
+# fluentd 配置
+<source>
+  @type tail
+  path /var/log/momentry/*.log
+  tag momentry.*
+  format json
+</source>
+
+<filter momentry.**>
+  @type record_transformer
+  <record>
+    hostname ${hostname}
+    environment production
+  </record>
+</filter>
+
+<match momentry.**>
+  @type elasticsearch
+  host elasticsearch.local
+  port 9200
+  logstash_format true
+</match>
+```
+
+#### 4.2.2 日誌分析用例
+| 分析場景 | 查詢語句 | 告警條件 |
+|----------|----------|----------|
+| **錯誤率分析** | `level:ERROR | stats count by service` | 錯誤數 > 10/分鐘 |
+| **效能分析** | `message: /processing.*duration_ms/ | stats avg(duration_ms)` | 平均處理時間 > 警告閾值 |
+| **用戶行為** | `message: /user.*action/ | stats count by user_id,action` | 異常行為模式 |
+| **安全審計** | `message: /(login|auth|access)/ | search suspicious_pattern` | 登錄失敗 > 5次 |
+
+---
+
+## 5. 告警管理
+
+### 5.1 告警策略
+
+#### 5.1.1 告警級別
+| 級別 | 響應時間 | 通知方式 | 處理流程 |
+|------|----------|----------|----------|
+| **P0 - 緊急** | 立即 | 電話、短信、推送 | 立即處理，全員通知 |
+| **P1 - 高** | 15分鐘 | Slack、Email | 值班工程師處理 |
+| **P2 - 中** | 1小時 | Email、儀表板 | 工作日處理 |
+| **P3 - 低** | 24小時 | 儀表板 | 計劃性處理 |
+
+#### 5.1.2 告警規則示例
+```yaml
+# alertmanager 配置
+groups:
+  - name: momentry-critical
+    rules:
+      - alert: APIDown
+        expr: up{job="momentry-api"} == 0
+        for: 1m
+        labels:
+          severity: critical
+        annotations:
+          summary: "API service is down"
+          description: "{{ $labels.instance }} has been down for more than 1 minute"
+      
+      - alert: HighCPUUsage
+        expr: rate(process_cpu_seconds_total[5m]) * 100 > 80
+        for: 5m
+        labels:
+          severity: warning
+        annotations:
+          summary: "High CPU usage detected"
+          description: "CPU usage is above 80% for 5 minutes"
+```
+
+### 5.2 值班管理
+
+#### 5.2.1 值班排班
+| 時段 | 值班人員 | 聯繫方式 | 覆蓋範圍 |
+|------|----------|----------|----------|
+| **工作日 9:00-18:00** | 開發團隊 | Slack、內部電話 | P0-P2 告警 |
+| **工作日 18:00-9:00** | 值班工程師 | 手機、短信 | P0-P1 告警 |
+| **週末/節假日** | 輪值工程師 | 手機、緊急電話 | P0 告警 |
+
+#### 5.2.2 告警升級流程
+```
+檢測到告警 → 初始響應
+    ↓
+    評估嚴重程度
+    ↓
+P0/P1: 立即通知值班人員
+P2/P3: 記錄到工單系統
+    ↓
+    開始處理
+    ↓
+    問題解決
+    ↓
+    撰寫事後報告
+    ↓
+    改進預防措施
+```
+
+---
+
+## 6. 監控最佳實踐
+
+### 6.1 監控設計原則
+1. **關鍵指標優先**：監控最重要的業務指標
+2. **分層監控**：從基礎設施到應用層全面監控
+3. **自動化監控**：自動發現、配置、告警
+4. **可視化優先**：儀表板清晰展示關鍵信息
+5. **告警有效性**：避免告警疲勞，確保告警有意義
+
+### 6.2 效能優化建議
+1. **指標採樣**：合理設置採樣頻率，平衡精度與成本
+2. **日誌輪轉**：自動清理舊日誌，控制儲存成本
+3. **查詢優化**：使用索引、聚合優化監控告警
+4. **儲存分層**：熱數據快速訪問，冷數據歸檔存儲
+
+### 6.3 成本控制策略
+1. **監控成本分析**：定期分析監控系統成本
+2. **資源優化**：根據使用模式調整資源配置
+3. **數據保留策略**：設置合理的數據保留期限
+4. **雲服務優化**：選擇合適的雲監控服務方案
+
+---
+
+## 7. 未來發展方向
+
+### 7.1 近期改進（1-3個月）
+1. **AI 異常檢測**：使用機器學習檢測異常模式
+2. **預測性監控**：基於歷史數據預測潛在問題
+3. **自動化修復**：簡單問題自動修復機制
+
+### 7.2 中期規劃（3-6個月）
+1. **跨區域監控**：支持多區域部署監控
+2. **多租戶監控**：為不同客戶提供隔離監控
+3. **移動監控**：移動端監控應用
+
+### 7.3 長期願景（6-12個月）
+1. **智能運維**：AI 驅動的智能運維平台
+2. **業務影響分析**：監控事件對業務影響分析
+3. **自動擴展預測**：基於監控數據的自動擴展
+
+---
+
+## 8. 總結
+
+Momentry Core 的監控架構設計提供：
+1. **全面覆蓋**：從基礎設施到應用層的完整監控
+2. **實時響應**：快速檢測問題並通知相關人員
+3. **數據驅動**：基於數據的決策與優化
+4. **持續改進**：不斷優化監控策略與工具
+
+通過完善的監控體系，確保系統穩定運行，快速發現並解決問題，為用戶提供高質量的服務。