momentry_core/docs/MOMENTRY_CORE_REDIS_KEYS.md

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 都支援自定義前綴：

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})

{
  "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

{
  "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

{
  "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 靜態變數：

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. 環境變數

# 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 狀態監控