feat: add v2 backup versioning system
- Add BACKUP_VERSIONING.md with comprehensive backup management
- Update backup_all.sh with v2 version marking
- v2 naming format: {service}_{type}_v2_{date}_{time}.{ext}
- Fixed MongoDB backup path to /opt/homebrew/var/mongodb
- Added momentry_output backup for probe.json files
- Added restore functions for v2 format
- Update backup_monitor.sh for v2 filename parsing
- Updated VIDEO_REGISTRATION.md with Probe API documentation
- Updated JOB_WORKER_IMPLEMENTATION_PLAN.md status to implemented
- Updated MOMENTRY_CORE_MONITORING.md with Job Worker monitoring
- Updated SERVICES.md with Momentry Playground and Job Worker info
This commit is contained in:
accusys
450
docs/BACKUP_VERSIONING.md
Normal file
450
docs/BACKUP_VERSIONING.md
Normal file
@@ -0,0 +1,450 @@
|
||||
# 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 檔名識別
|
||||
|
||||
```bash
|
||||
# 識別版本
|
||||
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 內容識別
|
||||
|
||||
```bash
|
||||
# 檢查是否為 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 還原前檢查
|
||||
|
||||
```bash
|
||||
# 還原前檢查版本相容性
|
||||
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）
|
||||
|
||||
```bash
|
||||
# 只還原到暫存資料庫，不影響生產
|
||||
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 版本驗證命令
|
||||
|
||||
```bash
|
||||
# 識別所有備份版本
|
||||
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 遷移驗證清單
|
||||
|
||||
```bash
|
||||
#!/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 緊急回滾流程
|
||||
|
||||
```bash
|
||||
#!/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](./SERVICES.md) | 服務說明 |
|
||||
| [MOMENTRY_CORE_MONITORING.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 備份完整性檢查清單
|
||||
|
||||
```bash
|
||||
#!/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 "=== 檢查完成 ==="
|
||||
```
|
||||
Reference in New Issue
Block a user