Files

Warren 1f84e5469f feat: backup architecture docs, source code, and scripts

2026-04-25 17:15:45 +08:00

22 KiB

Raw Blame History

待解決問題追蹤

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

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-17	創建文件	Warren	OpenCode / MiniMax M2.5
V1.1	2026-03-21	更新問題狀態	OpenCode	-
V1.2	2026-03-21	添加備份機制優化待辦	OpenCode	-
V1.3	2026-03-21	完成清理硬編碼密碼	OpenCode	-
V1.4	2026-03-21	完成 OpenCode n8n MCP 整合	OpenCode	-
V1.5	2026-03-21	完成 API Key Management 核心模組	OpenCode	-
V1.6	2026-03-23	添加 Momentry Core API launchd 待辦	OpenCode	-
V1.7	2026-03-23	完成 Momentry Core API launchd 設定	OpenCode	-
V1.8	2026-03-24	完成服務統一遷移，所有服務使用自定義 plist	OpenCode	big-pickle
V1.9	2026-03-24	建立統一會員系統實作計畫	OpenCode	big-pickle
V2.0	2026-03-24	建立 Job Worker 實作計畫	OpenCode	big-pickle

問題 #1: sqlx async INSERT 不會實際寫入數據庫

問題描述

使用 sqlx async 執行 INSERT 時，報告成功（rows_affected=1），但數據沒有實際寫入數據庫。

嘗試過的解決方案

#	嘗試方法	結果
1	使用 `execute()`	報告成功但未寫入
2	使用 `fetch()`	同樣問題
3	使用交易	同樣問題
4	使用連接池 `acquire()`	同樣問題
5	每個操作創建新連接池	同樣問題
6	使用 `std::process::Command` 同步調用 psql	同樣問題
7	使用 `tokio::task::spawn_blocking`	同樣問題

觀察到的現象

直接用 psql 命令行可以成功寫入
用另一個 PostgreSQL client 可以成功寫入
sqlx 查詢 COUNT(*) 可以正確讀取數據
但 sqlx INSERT 報告成功卻不寫入

懷疑方向

sqlx 連接池與 PostgreSQL 的某種交互問題
Rust async runtime 與 PostgreSQL client 的問題
postgresql.conf 配置問題

臨時解決方案

Qdrant 向量存儲正常工作（不受影響）
存儲狀態追蹤功能正常運作

負責人

建立日期

2026-03-17

備註

影響 store_vector 函數，PVector 存儲無法正常工作，但 QVector 正常運作

2026-03-21 調查結果

測試結果

直接 psql INSERT: ✅ 成功
資料寫入驗證: ✅ 成功

發現的問題

store_vector 函數 (postgres_db.rs:819-860) 存在以下問題：

// 問題 1: 錯誤被靜默忽略
match join_result {
    Ok((cid, Ok(output))) => {
        if !output.status.success() {
            let err = String::from_utf8_lossy(&output.stderr);
            tracing::error!("psql error for {}: {}", cid, err);
            // 沒有返回錯誤！只是記錄日誌
        }
    }
    // ...
}
Ok(())  // 即使失敗也返回 Ok

建議修復

讓 store_vector 返回實際結果
在失敗時返回 Err
添加單元測試驗證

下一步

修復 store_vector 錯誤處理
添加單元測試
重現並確認問題根因

2026-03-21 修復完成

已修復 store_vector 函數的錯誤處理：

// 修復前：錯誤被靜默忽略
match join_result {
    Ok((cid, Ok(output))) => {
        if !output.status.success() {
            tracing::error!("...");  // 只記錄，不返回錯誤
        }
    }
}
Ok(())  // 即使失敗也返回 Ok

// 修復後：正確傳播錯誤
let (cid, output) = result;
let output = output.map_err(|e| anyhow::anyhow!(...))?;
if !output.status.success() {
    anyhow::bail!("psql INSERT failed...");
}

問題 #2: TUI 與 stdout 輸出混合

問題描述

Python processors 的 progress 輸出蓋過 TUI，導致使用者無法清楚看到處理進度。

解決方案

~~使用 TUI 渲染到 stderr~~ → 使用 Redis Pub/Sub 作為消息總線

當前狀態

子項目	狀態
RedisPublisher Python 端	✅ 已實作
Rust Redis 客戶端	✅ 已實作 (`redis_client.rs`)
Rust 訂閱更新 TUI	✅ 已實作 (main.rs)
中斷後繼續/重做	🔜 待實作

負責人

建立日期

2026-03-17

更新日期

2026-03-21

參考文檔

docs/MOMENTRY_CORE_REDIS_KEYS.md
scripts/redis_publisher.py
src/core/db/redis_client.rs

問題 #3: Redis Message Bus 尚未實作

問題描述

根據設計規範，需要使用 Redis 作為監控和狀態管理系統。

當前狀態

實作項目	狀態	說明
Redis 客戶端 (Hash)	✅	`redis_client.rs`
Redis 客戶端 (Pub/Sub)	✅	`redis_client.rs::subscribe_progress()`
Python RedisPublisher	✅	`scripts/redis_publisher.py`
Rust 訂閱頻道	✅	`main.rs` 中的 redis 訂閱邏輯
監控腳本	✅	`monitor/service/health_check.sh`

負責人

建立日期

2026-03-17

更新日期

2026-03-21

優先級

高 → 中 - 核心功能已完成

參考文檔

docs/MOMENTRY_CORE_REDIS_KEYS.md
docs/MOMENTRY_CORE_MONITORING.md

架構優化待評估

詳細內容請參考 ARCHITECTURE_EVALUATION.md

項目	複雜度	優先級
PostgreSQL → Redis 故障轉移	中	待評估
連接池監控	低	待評估
Processor 重試機制	中	待評估
PyO3 整合	高	低
HTTP 健康端點	低	✅ 已完成
Commit Message Lint	低	✅ 已完成

備份機制優化 (2026-03-21)

問題分析

問題	嚴重性	說明
溫冷分層未啟用	中	weekly/monthly/archive 目錄為空
清理策略未執行	高	每日備份保留過多，空間浪費
無異地備份	高	無遠程備份（雲端/另一設備）
備份驗證未自動化	中	只檢查文件存在，沒驗證可恢復性
Gitea 大文件	中	每次備份 1GB，頻率過高
密碼硬編碼	高	腳本中有多處明文密碼

待辦事項

#	任務	優先級	狀態
1	啟用溫冷分層 (`backup_monitor.sh tier`)	高	待辦
2	啟用清理策略 (`backup_monitor.sh cleanup`)	高	待辦
3	添加備份驗證腳本	高	待辦
4	優化 Gitea 備份頻率 (改為週備份)	中	待辦
5	創建外部備份腳本 (rsync/雲端)	高	待辦
6	清理腳本中的硬編碼密碼	高	✅ 已完成

層級	保留時間	頻率	目標
Hot	7 天	每日	本地 SSD
Warm	30 天	每週	本地 HDD
Cold	90 天	每月	外部存儲
Archive	1 年	每季	離線/雲端

建議的 Crontab

# 每日備份 (排除 Gitea)
0 3 * * 1-6 /Users/accusys/momentry/scripts/backup_all.sh all_except_gitea

# 每週完整備份 (含 Gitea)
0 3 * * 0 /Users/accusys/momentry/scripts/backup_all.sh all

# 每週溫冷分層
0 4 * * 0 /Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh tier

# 每週清理
0 5 * * 0 /Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh cleanup

# 每月驗證
0 6 1 * * /Users/accusys/momentry/scripts/verify_backup.sh

負責人

參考文件

/Users/accusys/momentry/scripts/backup_all.sh
/Users/accusys/momentry_core_0.1/monitor/storage/backup_monitor.sh
/Users/accusys/momentry/backup/

OpenCode n8n MCP 整合 (2026-03-21)

完成狀態

項目	狀態	說明
n8n REST API 啟用	✅	`N8N_PUBLIC_API_ENABLED=true`
API Key 生成	✅	Settings → API
MCP Server 安裝	✅	`@nextoolsolutions/mcp-n8n`
OpenCode 設定	✅	`~/.config/opencode/opencode.json`
43 工具可用	✅	workflows, executions, datatables, tags 等

設定檔案

~/.config/opencode/opencode.json:

{
  "mcp": {
    "gitea": {
      "type": "local",
      "enabled": true,
      "command": [
        "/opt/homebrew/bin/gitea-mcp-server",
        "-token", "<GITEA_TOKEN>",
        "-host", "http://localhost:3000"
      ]
    },
    "n8n": {
      "type": "local",
      "enabled": true,
      "command": ["/opt/homebrew/bin/mcp-n8n"],
      "environment": {
        "N8N_BASE_URL": "http://localhost:5678",
        "N8N_API_KEY": "<N8N_API_KEY>"
      }
    }
  }
}

重要提醒

API Key 安全: 避免提交到 Git
n8n 需通過反向代理: localhost:5678 無法直接訪問 API，需通過 Caddy
重啟生效: 修改 opencode.json 後需重啟 OpenCode

參考文件

docs/OPENCODE_GUIDE.md - MCP 設定章節
docs/INSTALL_N8N.md - n8n 安裝指南

n8n API 備份腳本 (2026-03-21)

腳本位置

腳本	說明	依賴
`monitor/workflow/backup_n8n_api.py`	REST API 備份	requests
`monitor/workflow/backup_n8n_mcp.py`	MCP 備份（開發中）	mcp SDK

使用方式

# 備份所有 workflows
N8N_API_KEY="..." python3.11 backup_n8n_api.py

# 只顯示變更（不備份）
N8N_API_KEY="..." python3.11 backup_n8n_api.py --diff

# 差異備份（只備份變更的 workflows）
N8N_API_KEY="..." python3.11 backup_n8n_api.py --incremental

# 列出可用備份
python3.11 backup_n8n_api.py --list

# 驗證最新備份
python3.11 backup_n8n_api.py --verify

# 顯示備份統計
python3.11 backup_n8n_api.py --stats

# 只備份啟用的 workflows
N8N_API_KEY="..." python3.11 backup_n8n_api.py --active-only

# 備份失敗的執行記錄
N8N_API_KEY="..." python3.11 backup_n8n_api.py --failed-only

功能

REST API 備份
變更偵測
SHA256 校驗
備份版本化
差異備份（--incremental）
備份驗證（--verify）
備份統計（--stats）
失敗執行記錄備份（--failed-only）
選擇性備份（按 Tags）

備份位置

/Users/accusys/momentry/backup/n8n_workflows/api/
├── 20260321_122059/
│   ├── workflows.json         # 21 workflows
│   ├── workflows.json.sha256  # SHA256 校驗
│   ├── tags.json             # Tags（若有）
│   └── manifest.json         # 元數據
└── ...

Crontab 建議

# 每日備份（下午 3 點）
0 15 * * * N8N_API_KEY="..." /opt/homebrew/bin/python3.11 /Users/accusys/momentry_core_0.1/monitor/workflow/backup_n8n_api.py >> /Users/accusys/momentry/log/monitor/workflow_backup_api.log 2>&1

API Key Management System (2026-03-21)

設計目標

為 Momentry Core 實現完整的 API Key 管理系統，包括：

API Key 生成（安全隨機）
Key 哈希（SHA256）
異常檢測
強制輪換機制
審計日誌

模組架構

src/core/api_key/
├── mod.rs         # 模組導出
├── models.rs      # 數據模型和類型
├── service.rs    # 核心服務邏輯
├── anomaly.rs    # 異常檢測
└── rotation.rs   # 輪換管理

Key 類型

類型	前綴	默認 TTL	寬限期
System	`msys_`	365 天	72 小時
User	`muser_`	90 天	24 小時
Service	`msvc_`	180 天	48 小時
Integration	`mint_`	30 天	24 小時
Emergency	`memg_`	1 天	0 小時

Key 格式

{prefix}{uuid}_{timestamp}_{random}
例如: muser_a1b2c3d4e5f6_1710998400_abc12345

異常檢測閾值

指標	閾值
每分鐘請求數	1000
每小時請求數	10000
錯誤率	50%
每小時唯一 IP 數	5
鎖定閾值	3 次觸發

實現狀態

組件	狀態	說明
數據模型	✅ 完成	`models.rs`
Key 生成/哈希	✅ 完成	`service.rs`
異常檢測	✅ 完成	`anomaly.rs`
輪換機制	✅ 完成	`rotation.rs`
CLI 命令	✅ 完成	`main.rs`
數據庫集成	✅ 完成	`postgres_db.rs`
Redis 告警	✅ 完成	`redis_client.rs`
數據庫遷移	✅ 完成	`migrations/001_api_key_management.sql`
單元測試	✅ 完成	55 個測試通過

CLI 命令

# 創建 API Key
momentry api-key create <name> --key-type service --ttl 90

# 列出所有 Keys
momentry api-key list

# 驗證 Key
momentry api-key validate --key <key>

# 撤銷 Key
momentry api-key revoke --key <key>

# 請求輪換
momentry api-key rotate --key <key>

# 顯示統計
momentry api-key stats

參考文件

src/core/api_key/ - API Key 模組
docs/API_KEY_MANAGEMENT.md - 設計文檔
migrations/001_api_key_management.sql - 數據庫遷移

問題 #5: Redis 用戶名問題 (2026-03-21)

問題描述

Redis 僅有 default 用戶，無 accusys 用戶。.env 檔案使用 redis://accusys:accusys@localhost:6379 格式會導致認證失敗。

測試結果

URL 格式	結果
`redis://accusys:accusys@localhost:6379`	❌ AUTH failed
`redis://:accusys@localhost:6379`	✅ PONG

Redis ACL 狀態

user default on sanitize-payload #1bd51c... ~* &* +@all
requirepass: accusys

根本原因

Redis 啟動時僅設定 --requirepass accusys
未建立自訂用戶 accusys
ACL 變更不會持久化（無 config file）

已執行修復

項目	修改
`.env`	`redis://accusys:accusys@localhost:6379` → `redis://:accusys@localhost:6379`