momentry_core/docs/BACKUP_VERSIONING.md

Momentry 備份版本管理規範

項目	內容
建立者	Warren / OpenCode
建立時間	2026-03-25
文件版本	V1.0

---

版本歷史

版本	日期	目的	操作人
V1.0	2026-03-25	建立備份版本管理規範	OpenCode

---

1. 概述

本文檔定義 Momentry 系統的備份版本管理規範，確保新舊架構之間的回滾相容性。

1.1 版本定義

版本	日期	說明
v1	2026-03-18	初始備份架構（不包含新架構組件）
v2	2026-03-25	新架構備份（包含 monitor_jobs, processor_results, Output 目錄）

1.2 備份版本格式

版本	檔案命名格式
v1	{service}_{type}_{YYYYMMDD}_{HHMMSS}.{ext}
v2	{service}_{type}_v2_{YYYYMMDD}_{HHMMSS}.{ext}

1.3 各版本涵蓋範圍

組件	v1	v2
PostgreSQL (videos, chunks)	✅	✅
PostgreSQL (monitor_jobs)	❌	✅
PostgreSQL (processor_results)	❌	✅
Redis	✅	✅
MongoDB Cache	⚠️	⚠️
Output (probe.json)	❌	✅

⚠️ MongoDB 備份目前存在路徑問題，正在修復中

---

2. 備份版本識別

2.1 檔名識別

# 識別版本
detect_version() {
    local backup_file=$1
    if echo "$backup_file" | grep -q "_v2_"; then
        echo "v2"
    else
        echo "v1"
    fi
}

# 使用範例
detect_version "postgresql_db_momentry_v2_20260325_030000.sql.gz"
# 輸出: v2

detect_version "postgresql_db_momentry_20260324_030000.sql.gz"
# 輸出: v1

2.2 內容識別

# 檢查是否為 v2 備份
is_v2_backup() {
    local backup_file=$1
    gzip -dc "$backup_file" 2>/dev/null | grep -q "monitor_jobs" && echo "yes" || echo "no"
}

# 檢查是否包含 processor_results
has_processor_results() {
    local backup_file=$1
    gzip -dc "$backup_file" 2>/dev/null | grep -q "processor_results" && echo "yes" || echo "no"
}

2.3 檔案大小比較

版本	PostgreSQL 備份大小	說明
v1	~18-19 MB	基本資料表
v2	>19 MB	包含新表格和索引

---

3. 回滾策略

3.1 回滾流程圖

┌─────────────────────────────────────────┐
│           選擇還原目標                      │
└─────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│         選擇備份版本                      │
│   ┌───────────┐    ┌───────────┐       │
│   │   v1 備份  │    │   v2 備份  │       │
│   └───────────┘    └───────────┘       │
└─────────────────────────────────────────┘
                    │
          ┌─────────┴─────────┐
          ▼                   ▼
    ┌──────────┐        ┌──────────┐
    │  v1 回滾 │        │  v2 回滾  │
    └──────────┘        └──────────┘
          │                   │
          ▼                   ▼
    ┌──────────┐        ┌──────────┐
    │ 基本資料庫 │        │ 完整還原  │
    └──────────┘        └──────────┘

3.2 回滾矩陣

還原目標	v1 備份	v2 備份
基本資料庫	✅	✅
+ monitor_jobs	❌	✅
+ processor_results	❌	✅
+ Output 檔案	❌	✅
+ MongoDB Cache	⚠️	⚠️

3.3 回滾相容性說明

v1 → v2（支援）

• v1 備份可以還原到 v2 架構
• 新架構組件會從空白狀態開始
• 不會造成資料損壞

v2 → v1（⚠️ 警告）

⚠️ v2 回滾到 v1 可能導致資料丟失

影響範圍：
- monitor_jobs 資料會消失
- processor_results 資料會消失
- Output 檔案參照可能失效

建議：
1. 在還原前建立 v2 快照
2. 或使用隔離還原（staging restore）

---

4. 還原腳本保護機制

4.1 還原前檢查

# 還原前檢查版本相容性
pre_restore_check() {
    local backup_file=$1
    local version=$(detect_version "$backup_file")
    local current_db_version=$(check_current_db_version)
    
    echo "備份版本: $version"
    echo "目前版本: $current_db_version"
    
    # v2 → v1: 警告但允許（使用者需確認）
    if [ "$version" = "v1" ] && [ "$current_db_version" = "v2" ]; then
        echo "⚠️ 警告：即將回滾到 v1"
        echo "影響：monitor_jobs 和 processor_results 資料將被清除"
        read -p "確認繼續？(y/N): " confirm
        [ "$confirm" != "y" ] && exit 1
    fi
    
    # v1 → v2: 直接允許
    if [ "$version" = "v1" ] && [ "$current_db_version" = "v2" ]; then
        echo "ℹ️ 提示：新架構組件將重新初始化"
    fi
    
    # v2 → v2: 直接允許
    # v1 → v1: 直接允許
}

4.2 隔離還原（Staging Restore）

# 只還原到暫存資料庫，不影響生產
restore_to_staging() {
    local backup_file=$1
    local version=$(detect_version "$backup_file")
    
    echo "執行隔離還原..."
    echo "版本: $version"
    
    # 建立暫存資料庫
    PGPASSWORD="$PG_PASSWORD" psql -U "$PG_USER" -d postgres << EOF
    DROP DATABASE IF EXISTS momentry_staging;
    CREATE DATABASE momentry_staging;
    EOF
    
    # 還原到暫存資料庫
    PGPASSWORD="$PG_PASSWORD" pg_restore -U "$PG_USER" -d "momentry_staging" \
        --no-owner --no-acl "$backup_file"
    
    echo "✅ 還原完成：momentry_staging"
    echo "驗證命令：psql -U accusys -d momentry_staging -c '\\dt'"
}

4.3 版本驗證命令

# 識別所有備份版本
ls /Users/accusys/momentry/backup/daily/postgresql/*.sql.gz | \
    xargs -I {} sh -c 'echo "{}: $(detect_version {})"'

# 驗證 v2 備份內容
verify_v2_backup() {
    local backup_file=$1
    
    echo "驗證備份: $backup_file"
    
    # 檢查 monitor_jobs
    if gzip -dc "$backup_file" | grep -q "monitor_jobs"; then
        echo "✅ 包含 monitor_jobs"
    else
        echo "❌ 缺少 monitor_jobs"
        return 1
    fi
    
    # 檢查 processor_results
    if gzip -dc "$backup_file" | grep -q "processor_results"; then
        echo "✅ 包含 processor_results"
    else
        echo "❌ 缺少 processor_results"
        return 1
    fi
    
    echo "✅ v2 備份驗證通過"
}

---

5. 版本遷移

5.1 v1 → v2 遷移步驟

步驟	說明	驗證
1	確認所有 v1 備份已完成	ls *.sql.gz | grep -v v2
2	修改 backup_all.sh 加入 v2 標記	確認 TIMESTAMP 包含 v2_
3	修正 MongoDB 路徑	確認指向正確目錄
4	新增 Output 目錄備份	確認 probe.json 被備份
5	執行測試備份	驗證命名格式正確
6	驗證 v2 備份完整性	verify_v2_backup
7	正式啟用 v2 備份	確認 crontab 使用新版

5.2 遷移驗證清單

#!/bin/bash
# verify_v2_migration.sh

echo "=== v2 遷移驗證 ==="

# 1. 檢查備份腳本
echo "1. 檢查備份腳本..."
if grep -q "v2_" /Users/accusys/momentry/scripts/backup_all.sh; then
    echo "   ✅ 版本標記已啟用"
else
    echo "   ❌ 版本標記未啟用"
fi

# 2. 檢查 MongoDB 路徑
echo "2. 檢查 MongoDB 路徑..."
if grep -q "/opt/homebrew/var/mongodb" /Users/accusys/momentry/scripts/backup_all.sh; then
    echo "   ✅ MongoDB 路徑已修正"
else
    echo "   ❌ MongoDB 路徑未修正"
fi

# 3. 檢查 Output 目錄備份
echo "3. 檢查 Output 目錄備份..."
if grep -q "momentry_output" /Users/accusys/momentry/scripts/backup_all.sh; then
    echo "   ✅ Output 目錄備份已啟用"
else
    echo "   ❌ Output 目錄備份未啟用"
fi

# 4. 檢查最新備份
echo "4. 檢查最新備份..."
latest_backup=$(ls -t /Users/accusys/momentry/backup/daily/postgresql/*.sql.gz 2>/dev/null | head -1)
if [ -n "$latest_backup" ]; then
    version=$(detect_version "$latest_backup")
    echo "   最新備份: $(basename $latest_backup)"
    echo "   版本: $version"
    if [ "$version" = "v2" ]; then
        verify_v2_backup "$latest_backup"
    fi
fi

echo "=== 驗證完成 ==="

---

6. 疑難排解

6.1 常見問題

問題	原因	解決方案
無法識別版本	檔名被修改	使用內容分析 gzip -dc | grep "monitor_jobs"
v2 備份還原失敗	磁碟空間不足	清理空間後重試
v1 還原覆蓋 v2	操作失誤	使用隔離還原保護生產資料
MongoDB 備份為空	路徑錯誤	修正為 /opt/homebrew/var/mongodb

6.2 緊急回滾流程

#!/bin/bash
# emergency_restore.sh

set -e

BACKUP_FILE=$1
VERSION=$2

echo "=== 緊急回滾 ==="
echo "備份檔案: $BACKUP_FILE"
echo "目標版本: $VERSION"

# 1. 建立當前狀態快照
echo "1. 建立當前狀態快照..."
NOW=$(date +%Y%m%d_%H%M%S)
pg_dump -U accusys -d momentry | gzip > "/tmp/momentry_emergency_$NOW.sql.gz"
echo "   快照: /tmp/momentry_emergency_$NOW.sql.gz"

# 2. 執行還原
echo "2. 執行還原..."
gunzip -c "$BACKUP_FILE" | psql -U accusys -d momentry

# 3. 驗證
echo "3. 驗證還原..."
psql -U accusys -d momentry -c "SELECT COUNT(*) FROM monitor_jobs;"

echo "=== 回滾完成 ==="

---

7. 備份清單（v2）

7.1 每日備份（v2 格式）

服務	備份項目	檔案命名	說明
PostgreSQL	momentry	postgresql_db_momentry_v2_{date}_{time}.sql.gz	完整資料庫
PostgreSQL	video_register	postgresql_db_video_register_v2_{date}_{time}.sql.gz	影片註冊資料
Redis	RDB	redis_rdb_v2_{date}_{time}.rdb	Redis 快照
MongoDB	資料	mongodb_data_v2_{date}_{time}.tar.gz	MongoDB 資料
n8n	資料+DB	n8n_{date}_{time}.tar.gz, n8n_db_{date}_{time}.sql.gz	n8n 完整
SFTPGo	配置+DB	sftpgo_{date}_{time}.tar.gz, sftpgo_db_{date}_{time}.sql.gz	SFTPGo
Gitea	資料	gitea_{date}_{time}.tar.gz	Gitea
Output	檔案	momentry_output_v2_{date}_{time}.tar.gz	probe.json 等

7.2 備份保留策略

類型	保留期限	位置
每日備份	7 天	backup/daily/
每週備份	4 週	backup/weekly/
每月備份	12 個月	backup/monthly/
歸檔	1 年+	backup/archive/

---

8. 相關文件

文件	說明
SERVICES.md	服務說明
MOMENTRY_CORE_MONITORING.md	監控規範
/Users/accusys/momentry/scripts/backup_all.sh	備份腳本
/Users/accusys/momentry/scripts/restore_all.sh	還原腳本
/Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh	備份監控

---

附錄 A：v2 備份完整性檢查清單

#!/bin/bash
# check_v2_integrity.sh

BACKUP_DIR="/Users/accusys/momentry/backup/daily"

echo "=== v2 備份完整性檢查 ==="

# 檢查 PostgreSQL
echo "1. PostgreSQL..."
pg_backup=$(ls -t "$BACKUP_DIR/postgresql"/postgresql_db_momentry_v2_*.sql.gz 2>/dev/null | head -1)
if [ -n "$pg_backup" ]; then
    echo "   備份: $(basename $pg_backup)"
    verify_v2_backup "$pg_backup"
else
    echo "   ❌ 未找到 v2 備份"
fi

# 檢查 Output
echo "2. Output 目錄..."
output_backup=$(ls -t "$BACKUP_DIR/momentry"/momentry_output_v2_*.tar.gz 2>/dev/null | head -1)
if [ -n "$output_backup" ]; then
    echo "   備份: $(basename $output_backup)"
    echo "   ✅ Output 備份已存在"
else
    echo "   ❌ 未找到 Output 備份"
fi

# 檢查 MongoDB
echo "3. MongoDB..."
mongo_backup=$(ls -t "$BACKUP_DIR/mongodb"/mongodb_data_v2_*.tar.gz 2>/dev/null | head -1)
if [ -n "$mongo_backup" ]; then
    size=$(stat -f%z "$mongo_backup" 2>/dev/null || stat -c%s "$mongo_backup" 2>/dev/null)
    echo "   備份: $(basename $mongo_backup)"
    echo "   大小: $size bytes"
    if [ "$size" -gt 1000 ]; then
        echo "   ✅ MongoDB 備份有效"
    else
        echo "   ⚠️ MongoDB 備份可能為空"
    fi
else
    echo "   ❌ 未找到 MongoDB 備份"
fi

echo "=== 檢查完成 ==="