momentry_core/docs/MOMENTRY_CORE_MONITORING.md

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
V1.2	2026-03-25	新增 Job Worker 監控、processor_results 表	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 健康檢查

# 檢查 Redis 連線
redis-cli -a accusys ping

# 檢查 momentry 健康狀態
redis-cli GET momentry:health:current

3.2 Job 狀態監控

# 查看運行中的 Jobs
redis-cli SMEMBERS momentry:jobs:active

# 查看 Job 狀態
redis-cli HGETALL momentry:job:5dea6618a606e7c7

3.3 即時進度監控

# 訂閱進度頻道
redis-cli SUBSCRIBE momentry:progress:5dea6618a606e7c7

---

4. 監控腳本

4.1 健康檢查項目細節

基於當前系統狀態，需要監控的核心項目:

4.1.1 資料庫服務檢查

# 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 檢查

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 檢查

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 檢查

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 檢查

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 檢查

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 檢查腳本範例完整實現

#!/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 狀態與即時進度:

#!/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 定期執行健康檢查：

# crontab -e
# 每 5 分鐘執行一次健康檢查
*/5 * * * * /Users/accusys/momentry/scripts/health_check.sh >> /Users/accusys/momentry/log/health_check.log 2>&1

4.4 監控數據記錄

健康檢查結果應寫入監控數據庫，建議的 monitor_services 表結構:

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 或系統中：

# 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

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 監控腳本配置

建立符號鏈接到監控腳本目錄:

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

這樣可以在任何地方執行:

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 配置錯誤

應立即檢查:

tail -20 /Users/accusys/momentry/log/sftpgo.log
tail -20 /Users/accusys/momentry/log/sftpgo.error.log

---

7. 數據庫記錄

monitor_jobs 表

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

processor_results 表

CREATE TABLE processor_results (
    id SERIAL PRIMARY KEY,
    job_id INTEGER REFERENCES monitor_jobs(id) ON DELETE CASCADE,
    video_id BIGINT REFERENCES videos(id),
    processor VARCHAR(20) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    started_at TIMESTAMP,
    completed_at TIMESTAMP,
    error_message TEXT,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX idx_processor_results_job ON processor_results(job_id);
CREATE INDEX idx_processor_results_video ON processor_results(video_id);
CREATE INDEX idx_processor_results_status ON processor_results(status);

processor 狀態值:

• pending - 等待處理
• running - 處理中
• completed - 已完成
• failed - 處理失敗
• skipped - 跳過（已在其他處理中完成）

---

8. 環境變數

# 輸出目錄
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	Job Worker 輪詢機制	✅ 已實作	2026-03-25
10	processor_results 表	✅ 已實作	2026-03-25
11	Probe API 端點	✅ 已實作	2026-03-25
12	整合測試	🔜 待實作	-
13	生產環境部署驗證	⏳ 待開始	-

Job Worker 監控 (2026-03-25 新增)

Worker 服務狀態檢查:

# 檢查 Worker 程序
ps aux | grep momentry

# 查看 Worker 日誌
tail -f /Users/accusys/momentry/log/worker.log

monitor_jobs 狀態查詢:

# 查看待處理工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'pending';"

# 查看執行中工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'running';"

# 查看失敗工作
psql -U accusys -d momentry -c "SELECT * FROM monitor_jobs WHERE status = 'failed';"

processor_results 狀態查詢:

# 查看特定工作的處理器狀態
psql -U accusys -d momentry -c "
SELECT pr.*, mj.uuid 
FROM processor_results pr 
JOIN monitor_jobs mj ON pr.job_id = mj.id 
WHERE mj.uuid = 'a1b10138a6bbb0cd';
"

# 查看所有失敗的處理器
psql -U accusys -d momentry -c "
SELECT pr.processor, COUNT(*) as failures 
FROM processor_results pr 
WHERE pr.status = 'failed' 
GROUP BY pr.processor;
"

Redis 工作狀態:

# 查看活躍工作
redis-cli SMEMBERS momentry:jobs:active

# 查看工作詳情
redis-cli HGETALL momentry:job:{uuid}

已完成實作 (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 設計規範
• 監控系統總覽
• 備份規範
• SFTPGo 安裝與管理指南
• API 參考文件
• n8n 整合指南