docs: add configurable Redis key prefix to Redis Keys and Monitoring docs

- Add new section 2 in MOMENTRY_CORE_REDIS_KEYS.md explaining configurable prefix - Update environment variables to include MOMENTRY_REDIS_PREFIX - Update Rust implementation examples to use REDIS_KEY_PREFIX static - Add warning note in MOMENTRY_CORE_MONITORING.md about configurable prefix - Update shell scripts to use REDIS_PREFIX environment variable - Document default prefixes: momentry: (production), momentry_dev: (development)
2026-03-25 01:11:10 +08:00
parent 732ef9296b
commit a95e5c7e5c
2 changed files with 875 additions and 0 deletions
--- a/docs/MOMENTRY_CORE_MONITORING.md
+++ b/docs/MOMENTRY_CORE_MONITORING.md
@@ -0,0 +1,592 @@
+# Momentry Core 監控規範 (暫定)
+
+| 項目 | 內容 |
+|------|------|
+| 建立者 | Warren |
+| 建立時間 | 2026-03-17 |
+| 文件版本 | V1.0 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
+|------|------|------|--------|-----------|
+| V1.0 | 2026-03-17 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
+| V1.1 | 2026-03-25 | 新增可配置 Redis Key Prefix 說明 | Warren | OpenCode / GLM-5 |
+
+---
+
+> **⚠️ 狀態**: 此文檔為暫定版本，momentry_core 仍在開發中，待開發完成後再正式納入監控系統。
+
+---
+
+## 1. 概述
+
+momentry_core 是 Rust 開發的數字資產管理系統，專注於視頻分析和 RAG 功能。
+
+## 2. 監控架構
+
+### Layer 2: Service 監控
+
+| 項目 | 類型 | 檢查方式 | Port | 狀態 |
+|------|------|----------|------|------|
+| postgresql | TCP | `pg_isready` | 5432 | ✅ 運行中 |
+| redis | TCP | `redis-cli ping` | 6379 | ✅ 運行中 |
+| n8n | HTTP | `/healthz` | 5678 | ✅ 運行中 |
+| sftpgo | HTTP | `/healthz`, `/api/v2/token` | 8080 | ✅ 運行中 |
+| qdrant | HTTP | `/collections` | 6333 | ✅ 運行中 |
+| momentry_core | CLI | `momentry --version` | - | ⚠️ 待編譯 |
+
+**附屬服務狀態** (非核心但相關):
+| gitea | HTTP | `/` | 3000 | ✅ 運行中 |
+| ollama | HTTP | `/api/tags` | 11434 | ✅ 運行中 |
+| caddy | HTTP | `/` | 80 | ✅ 運行中 |
+
+### Layer 7: Backup 監控
+
+| 項目 | 類型 | 位置 |
+|------|------|------|
+| momentry | data | `/Users/accusys/momentry/backup/momentry` |
+| sftpgo | config + db | `/Users/accusys/momentry/backup/daily/sftpgo/` |
+
+---
+
+## 3. Redis 監控架構
+
+> **⚠️ 注意**: 從 V1.1 開始，所有 Redis Keys 都支援自定義前綴。
+> 預設前綴：生產環境為 `momentry:`，開發環境為 `momentry_dev:`
+>
+> 若使用非預設前綴，請將下方命令中的 `momentry:` 替換為實際前綴。
+
+### 3.1 健康檢查
+
+```bash
+# 檢查 Redis 連線
+redis-cli -a accusys ping
+
+# 檢查 momentry 健康狀態
+redis-cli GET momentry:health:current
+```
+
+### 3.2 Job 狀態監控
+
+```bash
+# 查看運行中的 Jobs
+redis-cli SMEMBERS momentry:jobs:active
+
+# 查看 Job 狀態
+redis-cli HGETALL momentry:job:5dea6618a606e7c7
+```
+
+### 3.3 即時進度監控
+
+```bash
+# 訂閱進度頻道
+redis-cli SUBSCRIBE momentry:progress:5dea6618a606e7c7
+```
+
+---
+
+## 4. 監控腳本
+
+### 4.1 健康檢查項目細節
+
+基於當前系統狀態，需要監控的核心項目:
+
+#### 4.1.1 資料庫服務檢查
+
+```bash
+# PostgreSQL - 檢查伺服器運行與關鍵資料庫
+check_postgresql() {
+    if pg_isready -h localhost -p 5432 > /dev/null 2>&1; then
+        echo -e "${GREEN}✓${NC} PostgreSQL"
+        # 檢查關鍵資料庫是否存在
+        local missing_dbs=()
+        for db in momentry video_register n8n sftpgo; do
+            if ! psql -h localhost -U postgres -lqt 2>/dev/null | cut -d\| -f1 | grep -qw "$db"; then
+                missing_dbs+=("$db")
+            fi
+        done
+        if [ ${#missing_dbs[@]} -gt 0 ]; then
+            echo -e "   ${YELLOW}⚠${NC} 缺失資料庫: ${missing_dbs[*]}"
+            record_service "postgresql" "warning" "1" "Missing databases: ${missing_dbs[*]}"
+        else
+            record_service "postgresql" "up" "1" ""
+        fi
+    else
+        echo -e "${RED}✗${NC} PostgreSQL"
+        record_service "postgresql" "down" "0" "PostgreSQL not responding"
+    fi
+}
+```
+
+#### 4.1.2 Redis 檢查
+
+```bash
+check_redis() {
+    if redis-cli -a "$REDIS_PASSWORD" ping 2>/dev/null | grep -q PONG; then
+        echo -e "${GREEN}✓${NC} Redis"
+        record_service "redis" "up" "1" ""
+    else
+        echo -e "${RED}✗${NC} Redis"
+        record_service "redis" "down" "0" "Redis not responding"
+    fi
+}
+```
+
+#### 4.1.3 SFTPGo 檢查
+
+```bash
+check_sftpgo() {
+    # 1. 檢查 HTTP API
+    if curl -s http://localhost:8080/healthz > /dev/null 2>&1; then
+        # 2. 檢查 API 認證
+        if TOKEN=$(curl -s -X GET http://localhost:8080/api/v2/token -u "admin:$SFTPGO_ADMIN_PASSWORD" 2>/dev/null | jq -r '.access_token') && [ -n "$TOKEN" ]; then
+            echo -e "${GREEN}✓${NC} SFTPGo"
+            record_service "sftpgo" "up" "1" ""
+        else
+            echo -e "${YELLOW}⚠${NC} SFTPGo (API認證失敗)"
+            record_service "sftpgo" "warning" "1" "API authentication failed"
+        fi
+    else
+        echo -e "${RED}✗${NC} SFTPGo"
+        record_service "sftpgo" "down" "0" "HTTP API not responding"
+    fi
+}
+```
+
+#### 4.1.4 n8n 檢查
+
+```bash
+check_n8n() {
+    if curl -s http://localhost:5678/healthz > /dev/null 2>&1; then
+        echo -e "${GREEN}✓${NC} n8n"
+        record_service "n8n" "up" "1" ""
+    else
+        echo -e "${RED}✗${NC} n8n"
+        record_service "n8n" "down" "0" "API not responding"
+    fi
+}
+```
+
+#### 4.1.5 Qdrant 檢查
+
+```bash
+check_qdrant() {
+    if curl -s http://localhost:6333/collections > /dev/null 2>&1; then
+        echo -e "${GREEN}✓${NC} Qdrant"
+        record_service "qdrant" "up" "1" ""
+    else
+        echo -e "${RED}✗${NC} Qdrant"
+        record_service "qdrant" "down" "0" "API not responding"
+    fi
+}
+```
+
+#### 4.1.6 Momentry Core 檢查
+
+```bash
+check_momentry_core() {
+    local binary="/Users/accusys/momentry/target/release/momentry"
+    if [ ! -f "$binary" ]; then
+        binary="/Users/accusys/momentry/target/debug/momentry"
+    fi
+
+    if [ -f "$binary" ] && $binary --version > /dev/null 2>&1; then
+        echo -e "${GREEN}✓${NC} Momentry Core"
+        record_service "momentry_core" "up" "1" ""
+    else
+        echo -e "${RED}✗${NC} Momentry Core"
+        record_service "momentry_core" "down" "0" "Binary not found or not executable"
+    fi
+}
+```
+
+### 4.2 檢查腳本範例完整實現
+
+```bash
+#!/bin/bash
+# monitor/service/health_check.sh
+
+export REDIS_PASSWORD="accusys"
+export SFTPGO_ADMIN_PASSWORD="Test3200Test3200"
+
+check_postgresql
+check_redis
+check_sftpgo
+check_n8n
+check_qdrant
+check_momentry_core
+```
+
+### 4.2 Redis Job 監控腳本
+
+**檔案**: `monitor/service/redis_job_monitor.sh`
+
+此腳本專門監控 Redis 中的 Job 狀態與即時進度:
+
+```bash
+#!/bin/bash
+# Momentry Core Redis Job 監控
+
+REDIS_PASSWORD="${REDIS_PASSWORD:-accusys}"
+REDIS_PREFIX="${REDIS_PREFIX:-momentry:}"# 可配置前綴，預設 momentry:
+
+# 檢查 Job 狀態
+check_job_status() {
+    local active_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:active" 2>/dev/null || echo "0")
+    local completed_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:completed" 2>/dev/null || echo "0")
+    local failed_jobs=$(redis-cli -a "$REDIS_PASSWORD" SCARD "${REDIS_PREFIX}jobs:failed" 2>/dev/null || echo "0")
+
+    echo "Momentry Jobs: Active=$active_jobs, Completed=$completed_jobs, Failed=$failed_jobs"
+    echo "$active_jobs $completed_jobs $failed_jobs"
+}
+
+# 檢查特定 Job 進度
+check_job_progress() {
+    local job_uuid=$1
+    if [ -z "$job_uuid" ]; then
+        echo "Usage: $0 progress <uuid>"
+        return 1
+    fi
+
+    local progress=$(redis-cli -a "$REDIS_PASSWORD" HGETALL "${REDIS_PREFIX}job:$job_uuid" 2>/dev/null)
+    if [ -n "$progress" ]; then
+        echo "Job $job_uuid progress:"
+        echo "$progress" | while read -r key value; do
+            [ -n "$key" ] && echo "  $key: $value"
+        done
+    else
+        echo "No progress data for job $job_uuid"
+    fi
+}
+
+# 訂閱即時進度頻道
+subscribe_progress() {
+    local job_uuid=$1
+    if [ -z "$job_uuid" ]; then
+        echo "Subscribing to all progress channels..."
+        redis-cli -a "$REDIS_PASSWORD" PSUBSCRIBE "${REDIS_PREFIX}progress:*" 2>/dev/null
+    else
+        echo "Subscribing to job $job_uuid progress..."
+        redis-cli -a "$REDIS_PASSWORD" SUBSCRIBE "${REDIS_PREFIX}progress:$job_uuid" 2>/dev/null
+    fi
+}
+
+# 列出所有活動 Job
+list_active_jobs() {
+    echo "Active Jobs:"
+    redis-cli -a "$REDIS_PASSWORD" SMEMBERS "${REDIS_PREFIX}jobs:active" 2>/dev/null | while read -r uuid; do
+        [ -n "$uuid" ] && echo "  - $uuid"
+    done
+}
+
+# 主程序
+case "$1" in
+    status)
+        check_job_status
+        ;;
+    progress)
+        check_job_progress "$2"
+        ;;
+    subscribe)
+        subscribe_progress "$2"
+        ;;
+    list)
+        list_active_jobs
+        ;;
+    *)
+        echo "Usage: $0 {status|progress <uuid>|subscribe [uuid]|list}"
+        exit 1
+        ;;
+esac
+```
+
+### 4.3 監控腳本排程
+
+使用 cron 定期執行健康檢查：
+
+```bash
+# crontab -e
+# 每 5 分鐘執行一次健康檢查
+*/5 * * * * /Users/accusys/momentry/scripts/health_check.sh >> /Users/accusys/momentry/log/health_check.log 2>&1
+```
+
+### 4.4 監控數據記錄
+
+健康檢查結果應寫入監控數據庫，建議的 `monitor_services` 表結構:
+
+```sql
+CREATE TABLE monitor_services (
+    id SERIAL PRIMARY KEY,
+    service_name VARCHAR(50) NOT NULL,
+    status VARCHAR(20) NOT NULL,  -- up, down, warning
+    error_message TEXT,
+    checked_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_monitor_services_checked ON monitor_services(checked_at);
+CREATE INDEX idx_monitor_services_name ON monitor_services(service_name);
+```
+
+---
+
+## 5. 配置更新
+
+### 5.1 環境變數
+
+必需監控相關環境變數配置在 `.env` 或系統中：
+
+```bash
+# Redis 連接
+REDIS_URL=redis://localhost:6379
+REDIS_PASSWORD=accusys
+
+# Redis Key Prefix (可選，預設: momentry:)
+REDIS_PREFIX=momentry:
+
+# SFTPGo 管理員密碼 (用於 API 健康檢查)
+SFTPGO_ADMIN_PASSWORD=Test3200Test3200
+
+# Momentry Core 路徑 (可選，如果不在標準位置)
+MOMENTRY_BINARY_PATH="/Users/accusys/momentry/target/release/momentry"
+```
+
+### 5.2 監控配置範例
+
+**檔案**: `monitor/config/monitor_config.yaml`
+
+```yaml
+services:
+  # Redis - 消息隊列與狀態存儲
+  - name: "redis"
+    type: "tcp"
+    host: "localhost"
+    port: 6379
+    timeout: 3
+    enabled: true
+
+  # PostgreSQL - 數據庫
+  - name: "postgresql"
+    type: "tcp"
+    host: "localhost"
+    port: 5432
+    timeout: 5
+    enabled: true
+    check_sql: "SELECT 1;"  # 可選：執行 SQL 驗證
+
+  # n8n - 工作流引擎
+  - name: "n8n"
+    type: "http"
+    host: "localhost"
+    port: 5678
+    check_url: "http://localhost:5678/healthz"
+    timeout: 5
+    enabled: true
+
+  # SFTPGo - 文件上傳服務
+  - name: "sftpgo"
+    type: "http"
+    host: "localhost"
+    port: 8080
+    check_url: "http://localhost:8080/healthz"
+    timeout: 5
+    enabled: true
+    # 附加認證檢查（每小時一次）
+    auth_check:
+      endpoint: "/api/v2/token"
+      method: "GET"
+      username: "admin"
+      password_env: "SFTPGO_ADMIN_PASSWORD"
+
+  # Qdrant - 向量數據庫
+  - name: "qdrant"
+    type: "http"
+    host: "localhost"
+    port: 6333
+    check_url: "http://localhost:6333/collections"
+    timeout: 5
+    enabled: true
+
+  # Momentry Core CLI
+  - name: "momentry_core"
+    type: "cli"
+    binary_path: "/Users/accusys/momentry/target/release/momentry"
+    args: ["--version"]
+    timeout: 3
+    enabled: true
+```
+
+### 5.3 備份配置更新
+
+統一備份系統 (`backup_all.sh`) 已包含 SFTPGo 備份，無需額外配置。
+
+備份保留策略 (預設):
+- **每日備份**: 保留 7 天
+- **每週備份**: 保留 4 週
+- **每月備份**: 保留 12 個月
+
+備份存儲位置:
+- 配置文件: `/Users/accusys/momentry/backup/daily/<service>/`
+- 最新備份鏈接: `/Users/accusys/momentry/backup/latest/` (由 backup_monitor.sh 管理)
+
+### 5.4 監控腳本配置
+
+建立符號鏈接到監控腳本目錄:
+
+```bash
+ln -sf /Users/accusys/momentry/scripts/backup_all.sh /usr/local/bin/backup_all
+ln -sf /Users/accusys/momentry/scripts/health_check.sh /usr/local/bin/health_check
+```
+
+這樣可以在任何地方執行:
+```bash
+health_check
+backup_all status
+backup_all restore sftpgo 20260321_101928
+```
+
+---
+
+## 6. 報警規則
+
+| 層級 | 異常類型 | 等級 | 處理 |
+|------|----------|------|------|
+| Service | PostgreSQL 未運行 | Critical | 記錄 + 通知 |
+| Service | Redis 未運行 | Critical | 記錄 + 通知 |
+| Service | n8n API 無回應 | Critical | 記錄 + 通知 |
+| Service | SFTPGo API 無回應 | Critical | 記錄 + 通知 |
+| Service | Qdrant 未運行 | Critical | 記錄 + 通知 |
+| Service | Momentry CLI 缺失 | Critical | 記錄 + 通知 |
+| Database | 關鍵資料庫不存在 | Warning | 記錄 |
+| Backup | 備份失敗 | Critical | 記錄 |
+| Backup | 備份過期 | Warning | 記錄 |
+| Job | 處理失敗 | Warning | 記錄 |
+| Job | 處理超時 | Warning | 記錄 |
+
+### 6.1 資料庫缺失處理
+
+當檢查到以下資料庫不存在時，應記錄警告:
+- `momentry` - Momentry Core 主資料庫
+- `video_register` - 視頻註冊資料庫
+- `n8n` - n8n 工作流資料庫
+- `sftpgo` - SFTPGo 資料庫
+
+**處理程序**:
+1. 確認是否為首次安裝（資料庫尚未建立）
+2. 檢查備份並執行還原
+3. 如果是意外刪除，立即從最新備份恢復
+
+### 6.2 SFTPGo 監控特殊注意
+
+SFTPGo 使用雙重認證檢查:
+1. **健康檢查**: `/healthz` (無需認證)
+2. **API 可用性**: `/api/v2/token` (需要 Basic Auth)
+
+若 `/healthz` 正常但 `/api/v2/token` 失敗，可能是:
+- admin 密碼被重置
+- 數據庫連接問題
+- API 配置錯誤
+
+應立即檢查:
+```bash
+tail -20 /Users/accusys/momentry/log/sftpgo.log
+tail -20 /Users/accusys/momentry/log/sftpgo.error.log
+```
+
+---
+
+## 7. 數據庫記錄
+
+### monitor_jobs 表
+
+```sql
+CREATE TABLE monitor_jobs (
+    id SERIAL PRIMARY KEY,
+    uuid VARCHAR(16) NOT NULL,
+    video_path VARCHAR(512),
+    status VARCHAR(20),
+    current_processor VARCHAR(20),
+    progress_total INT,
+    progress_current INT,
+    error_count INT DEFAULT 0,
+    last_error TEXT,
+    started_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_monitor_jobs_uuid ON monitor_jobs(uuid);
+CREATE INDEX idx_monitor_jobs_status ON monitor_jobs(status);
+CREATE INDEX idx_monitor_jobs_created_at ON monitor_jobs(created_at);
+```
+
+---
+
+## 8. 環境變數
+
+```bash
+# 輸出目錄
+MOMENTRY_OUTPUT_DIR=/path/to/output
+
+# 備份
+MOMENTRY_BACKUP_ENABLED=true
+MOMENTRY_BACKUP_DIR=/Users/accusys/momentry/backup/momentry
+
+# Redis
+REDIS_URL=redis://localhost:6379
+REDIS_PASSWORD=accusys
+```
+
+---
+
+## 9. 待實作項目
+
+| # | 項目 | 狀態 | 更新日期 |
+|---|------|------|---------|
+| 1 | 實作 Redis Pub/Sub 客戶端 | ✅ 已實作 | 2026-03-21 |
+| 2 | 修改 Python processors 使用 Redis | ✅ 已實作 | 2026-03-21 |
+| 3 | 設計並實現 health_check.sh | ✅ 已實作 | 2026-03-22 |
+| 4 | 創建 monitor_jobs 表 | ✅ 已實作 | 2026-03-21 |
+| 5 | SFTPGo 備份與還原流程 | ✅ 已實作 | 2026-03-22 |
+| 6 | SFTPGo API 管理工具 | ✅ 已實作 | 2026-03-22 |
+| 7 | SFTPGo Hook 自動註冊 | ✅ 已實作 | 2026-03-22 |
+| 8 | 文檔化監控規範 | ✅ 已實作 | 2026-03-22 |
+| 9 | 整合測試 | 🔜 待實作 | - |
+| 10 | 生產環境部署驗證 | ⏳ 待開始 | - |
+
+### 已完成實作 (2026-03-22)
+
+**監控系統**:
+- 完整健康檢查腳本設計: `docs/MOMENTRY_CORE_MONITORING.md`
+- 多層次服務監控 (Layer 2: Service, Layer 7: Backup)
+- Redis Job 監控腳本: `monitor/service/redis_job_monitor.sh`
+- SFTPGo 特殊監控 (API 認證檢查)
+
+**SFTPGo 管理**:
+- 備份還原機制: `backup_all.sh` (第 325-546 行)
+- API 管理用戶與組 (完整文件於 `docs/INSTALL_SFTPGO.md`)
+- Hook 自動註冊流程: `/Users/accusys/sftpgo_test/register_hook.sh`
+- Demo 用戶與組完整測試環境
+
+**文檔更新**:
+- `docs/INSTALL_SFTPGO.md`: 新增備份還原、API管理、Hook配置章節
+- `docs/MOMENTRY_CORE_MONITORING.md`: 完善監控規範
+
+### 待驗證功能
+
+- [ ] 端到端測試: SFTP 上傳 → Hook → Momentry 註冊 → n8n 工作流
+- [ ] Momentry Core API 搜索功能: `GET /api/v1/searchable`
+- [ ] 背景處理自動觸發: `cargo run -- process <uuid>`
+
+---
+
+## 10. 參考文檔
+
+- [Redis Key 設計規範](./MOMENTRY_CORE_REDIS_KEYS.md)
+- [監控系統總覽](../monitor/MONITORING.md)
+- [備份規範](./SERVICE_ADDITION_GUIDE.md)
+- [SFTPGo 安裝與管理指南](./INSTALL_SFTPGO.md)
+- [API 參考文件](../docs/API_REFERENCE.md)
+- [n8n 整合指南](./N8N_INTEGRATION_GUIDE.md)