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

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

### processor_results 表

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

```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 | 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 服務狀態檢查**:
```bash
# 檢查 Worker 程序
ps aux | grep momentry

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

**monitor_jobs 狀態查詢**:
```bash
# 查看待處理工作
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 狀態查詢**:
```bash
# 查看特定工作的處理器狀態
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 工作狀態**:
```bash
# 查看活躍工作
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 設計規範](./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)