diff --git a/docs/MOMENTRY_CORE_MONITORING.md b/docs/MOMENTRY_CORE_MONITORING.md new file mode 100644 index 0000000..2691a8c --- /dev/null +++ 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 " + 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 |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//` +- 最新備份鏈接: `/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 ` + +--- + +## 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) diff --git a/docs/MOMENTRY_CORE_REDIS_KEYS.md b/docs/MOMENTRY_CORE_REDIS_KEYS.md new file mode 100644 index 0000000..cabef36 --- /dev/null +++ b/docs/MOMENTRY_CORE_REDIS_KEYS.md @@ -0,0 +1,283 @@ +# Momentry Core Redis Key 設計規範 + +| 項目 | 內容 | +|------|------| +| 建立者 | 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 | + +--- + +## 1. 概述 + +本文檔說明 momentry_core 如何使用 Redis 作為監控和狀態管理系統。 + +## 2. 可配置 Redis Key Prefix + +### 2.1 環境變數 + +從 V1.1 開始,所有 Redis Keys 都支援自定義前綴: + +```bash +MOMENTRY_REDIS_PREFIX=momentry: +``` + +此設定允許多個 momentry 實例共用同一個 Redis 伺服器,例如: +- **生產環境**: `MOMENTRY_REDIS_PREFIX=momentry:` +- **開發環境**: `MOMENTRY_REDIS_PREFIX=momentry_dev:` + +### 2.2 Key 格式 + +所有 Key 都遵循以下格式: + +``` +{prefix}{key_type}:{uuid} +``` + +範例 (生產環境): +``` +momentry:job:5dea6618a606e7c7 +momentry:jobs:active +momentry:health:current +``` + +範例 (開發環境): +``` +momentry_dev:job:5dea6618a606e7c7 +momentry_dev:jobs:active +momentry_dev:health:current +``` + +### 2.3 預設值 + +| Binary | 預設 Port | 預設 Redis Prefix | +|--------|-----------|-------------------| +| `momentry` (生產) | 3002 | `momentry:` | +| `momentry_playground` (開發) | 3003 | `momentry_dev:` | + +## 3. UUID 使用時機 + +### 3.1 全局 Keys(無 UUID) + +- 單一實例全局狀態 +- 聚合統計數據 + +### 3.2 Per-Video Keys(UUID 必要) + +- 每個視頻獨立處理狀態 +- 即時進度追蹤 + +### 3.3 Per-Processor Keys(UUID + Processor 必要) + +- 每個 processor 獨立狀態 + +## 4. Key 命名空間 + +``` +momentry +├── health: # 健康檢查 +│ ├── current # 當前狀態 (TTL: 60s) +│ └── services # 依賴服務狀態 +├── config: # 配置 +├── stats: # 聚合統計 +│ ├── total_jobs # 總 Jobs 數 +│ ├── processed_today # 今日處理數 +│ ├── cpu:current # 當前 CPU 使用 +│ └── memory:current # 當前 Memory 使用 +├── jobs: # Jobs 管理 +│ ├── active # Set: 運行中 UUIDs +│ ├── completed # Set: 完成 UUIDs +│ └── failed # Set: 失敗 UUIDs +├── job:{uuid} # Per-Video Job 狀態 (TTL: 24h) +│ ├── status # 狀態 String +│ ├── video_path # 視頻路徑 +│ ├── current_processor # 當前 processor +│ ├── progress_total # 總進度 +│ ├── progress_current # 當前進度 +│ ├── started_at # 開始時間 +│ ├── updated_at # 最後更新 +│ └── processor:{name} # Per-Processor 狀態 +│ ├── status +│ ├── progress +│ ├── current +│ ├── total +│ └── started_at +├── progress:{uuid} # Pub/Sub 頻道 (即時進度) +├── result:{uuid} # 處理結果 Hash +├── output:{uuid} # 輸出路徑 +├── metrics:{uuid} # Per-Video 指標 +│ ├── cpu # CPU 歷史 List (100條, TTL: 1h) +│ ├── memory # Memory 歷史 List (100條, TTL: 1h) +│ └── duration # 處理時長 +└── log:{uuid} # 處理日誌 String +``` + +## 5. Key 詳細說明 + +### 全局 Keys + +| Key | Type | TTL | 說明 | +|-----|------|-----|------| +| `momentry:health:current` | String | 60s | 當前健康狀態 | +| `momentry:health:services` | Hash | 60s | 依賴服務健康狀態 | +| `momentry:stats:total_jobs` | String | - | 總 Jobs 數 | +| `momentry:stats:processed_today` | String | 86400s | 今日處理數 | +| `momentry:stats:cpu:current` | String | 10s | 當前 CPU 使用 | +| `momentry:stats:memory:current` | String | 10s | 當前 Memory 使用 | +| `momentry:jobs:active` | Set | - | 運行中 Job UUIDs | +| `momentry:jobs:completed` | Set | - | 完成 Job UUIDs | +| `momentry:jobs:failed` | Set | - | 失敗 Job UUIDs | + +### Per-Video Keys + +| Key | Type | TTL | 說明 | +|-----|------|-----|------| +| `momentry:job:{uuid}` | Hash | 24h | Job 完整狀態 | +| `momentry:job:{uuid}:status` | String | 24h | Job 狀態 | +| `momentry:progress:{uuid}` | Pub/Sub | - | 即時進度頻道 | +| `momentry:result:{uuid}` | Hash | 24h | 處理結果 | +| `momentry:output:{uuid}` | String | 24h | 輸出路徑 | +| `momentry:metrics:{uuid}:cpu` | List | 1h | CPU 歷史 (100條) | +| `momentry:metrics:{uuid}:memory` | List | 1h | Memory 歷史 (100條) | +| `momentry:metrics:{uuid}:duration` | String | 24h | 處理時長 | +| `momentry:log:{uuid}` | String | 24h | 處理日誌 | + +### Per-Processor Keys + +| Key | Type | TTL | 說明 | +|-----|------|-----|------| +| `momentry:job:{uuid}:processor:{name}` | Hash | 24h | Processor 狀態 | +| `momentry:job:{uuid}:processor:{name}:status` | String | 24h | 狀態 | +| `momentry:job:{uuid}:processor:{name}:progress` | String | 24h | 進度百分比 | +| `momentry:job:{uuid}:processor:{name}:current` | String | 24h | 當前項目 | +| `momentry:job:{uuid}:processor:{name}:total` | String | 24h | 總項目數 | +| `momentry:job:{uuid}:processor:{name}:started_at` | String | 24h | 開始時間 | + +## 6. TTL 策略 + +| Key 類型 | TTL | 原因 | +|----------|-----|------| +| Health | 60s | 需要定期更新 | +| Job | 24h | 處理完成後保留一天 | +| Processor | 24h | 處理完成後保留一天 | +| Metrics | 1h | 只保留近期歷史 | +| Progress Pub/Sub | - | 不持久,僅即時訊息 | +| Stats | 無 | 持久統計 | + +## 7. 訊息格式 + +### Pub/Sub 訊息 (progress:{uuid}) + +```json +{ + "type": "info | progress | complete | error", + "processor": "yolo | ocr | face | pose | cut | asr | asrx", + "timestamp": 1700000000, + "data": { + "message": "Processing frame 5000", + "current": 5000, + "total": 14315 + } +} +``` + +### Job 狀態 Hash + +```json +{ + "uuid": "5dea6618a606e7c7", + "video_path": "/path/to/video.mp4", + "status": "running", + "current_processor": "yolo", + "progress_total": 70, + "progress_current": 50, + "started_at": 1700000000, + "updated_at": 1700000100, + "error_count": 0, + "last_error": "" +} +``` + +### Processor 狀態 Hash + +```json +{ + "name": "yolo", + "status": "running", + "progress": 70, + "current_frame": 10000, + "total_frames": 14315, + "started_at": 1700000000, + "updated_at": 1700000100 +} +``` + +## 8. 實作函數 (Rust) + +所有 Redis Key 生成函數使用 `REDIS_KEY_PREFIX` 靜態變數: + +```rust +use crate::core::config::REDIS_KEY_PREFIX; + +fn global_key(key: &str) -> String { + format!("{}{}", REDIS_KEY_PREFIX, key) +} + +fn job_key(uuid: &str) -> String { + format!("{}job:{}", REDIS_KEY_PREFIX, uuid) +} + +fn processor_key(uuid: &str, processor: &str) -> String { + format!("{}job:{}:processor:{}", REDIS_KEY_PREFIX, uuid, processor) +} + +fn progress_channel(uuid: &str) -> String { + format!("{}progress:{}", REDIS_KEY_PREFIX, uuid) +} + +fn metrics_key(uuid: &str, metric: &str) -> String { + format!("{}metrics:{}:{}", REDIS_KEY_PREFIX, uuid, metric) +} + +fn jobs_set_key(status: &str) -> String { + format!("{}jobs:{}", REDIS_KEY_PREFIX, status) +} +``` + +**注意**: `REDIS_KEY_PREFIX` 定義於 `src/core/config.rs`,由環境變數 `MOMENTRY_REDIS_PREFIX` 控制。 + +## 9. 環境變數 + +```bash +# Redis 連接 +REDIS_URL=redis://localhost:6379 +REDIS_PASSWORD=accusys +REDIS_DB=0 + +# Redis Key Prefix (可選,預設: momentry:) +MOMENTRY_REDIS_PREFIX=momentry: + +# 生產環境範例 (.env) +MOMENTRY_SERVER_PORT=3002 +MOMENTRY_REDIS_PREFIX=momentry: + +# 開發環境範例 (.env.development) +MOMENTRY_SERVER_PORT=3003 +MOMENTRY_REDIS_PREFIX=momentry_dev: +``` + +## 11. 監控腳本 + +使用 Redis 進行監控的腳本應參考: + +- `monitor/service/momentry_redis_monitor.sh` - Redis 健康檢查 +- `monitor/service/momentry_job_monitor.sh` - Job 狀態監控