Initial commit: Momentry Core v0.1

- Rust-based digital asset management system - Video analysis: ASR, OCR, YOLO, Face, Pose - RAG capabilities with Qdrant vector database - Multi-database support: PostgreSQL, Redis, MongoDB - Monitoring system with launchd plists - n8n workflow automation integration
2026-03-16 15:07:33 +08:00
commit de14bd6afa
101 changed files with 19858 additions and 0 deletions
--- a/docs/INSTALL_POSTGRESQL.md
+++ b/docs/INSTALL_POSTGRESQL.md
@@ -0,0 +1,372 @@
+# PostgreSQL 安裝指南 (本地部署)
+
+## 概述
+
+本文檔說明如何在 macOS 上安裝 PostgreSQL，配置為本地部署，支援遠端訪問。
+
+---
+
+## 當前狀態
+
+| 項目 | 狀態 |
+|------|------|
+| PostgreSQL | ✅ 已安裝 v18.1 |
+| 數據目錄 | /Users/accusys/momentry/var/postgresql/ |
+| 日誌目錄 | /Users/accusys/momentry/log/ |
+| Plist | /Library/LaunchDaemons/com.momentry.postgresql.plist |
+
+---
+
+## 安裝步驟
+
+### Step 1: 安裝 PostgreSQL (使用 brew)
+
+```bash
+# 安裝 PostgreSQL
+brew install postgresql@18
+```
+
+**驗證**:
+```bash
+postgres --version
+# postgres (PostgreSQL) 18.1
+```
+
+---
+
+### Step 2: 建立目錄結構
+
+```bash
+# 建立數據目錄
+mkdir -p /Users/accusys/momentry/var/postgresql
+
+# 建立配置目錄
+mkdir -p /Users/accusys/momentry/etc/postgresql
+
+# 建立日誌目錄
+mkdir -p /Users/accusys/momentry/log
+
+# 建立日誌文件
+touch /Users/accusys/momentry/log/postgresql.log
+touch /Users/accusys/momentry/log/postgresql.error.log
+
+# 設定權限
+chown -R accusys:staff /Users/accusys/momentry/var/postgresql
+chown -R accusys:staff /Users/accusys/momentry/etc/postgresql
+chown -R accusys:staff /Users/accusys/momentry/log
+```
+
+**注意**: 如果需要從舊數據遷移，需要先初始化新目錄:
+```bash
+# 初始化新數據目錄 (會創建默認數據庫)
+initdb -D /Users/accusys/momentry/var/postgresql -U accusys
+```
+
+---
+
+### Step 3: 使用 plist 開機自動啟動
+
+```bash
+# 複製 plist 到 LaunchDaemons 目錄
+sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.postgresql.plist /Library/LaunchDaemons/
+
+# 載入並啟動
+sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
+```
+
+---
+
+## 監控配置
+
+### 添加到監控配置
+
+在 `monitor/config/monitor_config.yaml` 中添加：
+
+```yaml
+database:
+  postgresql:
+    enabled: true
+    host: "localhost"
+    port: 5432
+    user: "accusys"
+    database: "momentry"
+```
+
+### 添加健康檢查函數
+
+在 `monitor/database/postgres_monitor.sh` 中已包含 PostgreSQL 監控。
+
+---
+
+## 卸載步驟
+
+### 重要: 路徑說明
+
+| 路徑 | 類型 | 說明 |
+|------|------|------|
+| `/Users/accusys/momentry/var/postgresql/` | 數據 | **不要刪除** - 數據目錄 |
+| `/Users/accusys/momentry/etc/postgresql/` | 配置 | **不要刪除** - 配置目錄 |
+| `/Users/accusys/momentry/log/` | 日誌 | **不要刪除** - 日誌目錄 |
+| `/opt/homebrew/opt/postgresql@18/` | 安裝 | **刪除** - PostgreSQL 安裝目錄 |
+
+### Step 1: 停止 PostgreSQL
+
+```bash
+# 找到 PostgreSQL 進程
+ps aux | grep postgres | grep -v grep
+
+# 停止 PostgreSQL
+pg_ctl -D /opt/homebrew/var/postgresql@18 stop
+# 或
+pkill -f postgresql
+
+# 確認停止
+ps aux | grep postgres | grep -v grep || echo "PostgreSQL 已停止"
+```
+
+---
+
+### Step 2: 卸載 PostgreSQL
+
+```bash
+# 卸載 PostgreSQL
+brew uninstall postgresql@18
+
+# 移除 plist
+sudo launchctl unload /Library/LaunchDaemons/com.momentry.postgresql.plist
+sudo rm /Library/LaunchDaemons/com.momentry.postgresql.plist
+```
+
+---
+
+### Step 3: 刪除專屬檔案
+
+```bash
+# 刪除數據目錄 (可選)
+rm -rf /Users/accusys/momentry/var/postgresql
+
+# 刪除日誌 (可選)
+rm -f /Users/accusys/momentry/log/postgresql.log
+rm -f /Users/accusys/momentry/log/postgresql.error.log
+```
+
+**注意: 不要刪除以下共用目錄**:
+```bash
+# 這些是共用的，不要刪除!
+# /Users/accusys/momentry/var
+# /Users/accusys/momentry/log
+```
+
+---
+
+### Step 4: 卸載後檢查清單
+
+```bash
+echo "=== PostgreSQL 卸載後檢查 ==="
+
+# 1. 檢查 PostgreSQL 進程
+echo "1. PostgreSQL 進程:"
+ps aux | grep postgres | grep -v grep && echo "   ✗ 仍在運行" || echo "   ✓ 已停止"
+
+# 2. Port 5432
+echo "2. Port 5432:"
+lsof -i :5432 > /dev/null 2>&1 && echo "   ✗ 仍被佔用" || echo "   ✓ 已釋放"
+
+# 3. postgres 命令
+echo "3. postgres 命令:"
+which postgres > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"
+
+# 4. brew 安裝
+echo "4. brew 安裝:"
+brew list postgresql@18 > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"
+
+# 5. launchctl 服務
+echo "5. launchctl 服務:"
+sudo launchctl list | grep postgresql > /dev/null 2>&1 && echo "   ✗ 仍存在" || echo "   ✓ 已移除"
+
+# 6. 數據目錄 (可選刪除)
+echo "6. 數據目錄:"
+[ -d "/Users/accusys/momentry/var/postgresql" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"
+
+# 7. 日誌目錄 (可選刪除)
+echo "7. 日誌目錄:"
+[ -d "/Users/accusys/momentry/log" ] && echo "   ✓ 保留" || echo "   ✗ 已刪除"
+```
+
+**預期結果**:
+```
+=== PostgreSQL 卸載後檢查 ===
+1. PostgreSQL 進程:
+   ✓ 已停止
+2. Port 5432:
+   ✓ 已釋放
+3. postgres 命令:
+   ✓ 已移除
+4. brew 安裝:
+   ✓ 已移除
+5. launchctl 服務:
+   ✓ 已移除
+6. 數據目錄:
+   ✓ 保留 (或 ✗ 已刪除)
+7. 日誌目錄:
+   ✓ 保留 (或 ✗ 已刪除)
+```
+
+---
+
+## 手動檢查命令
+
+```bash
+# 1. 檢查進程
+ps aux | grep postgres | grep -v grep
+
+# 2. 檢查 Port
+lsof -i :5432
+
+# 3. 測試連線
+psql -U accusys -l
+
+# 4. 查看所有數據庫
+psql -U accusys -c "\l"
+
+# 5. 查看連接
+psql -U accusys -c "\conninfo"
+
+# 6. 查看表
+psql -U accusys -d momentry -c "\dt"
+
+# 7. 查看日誌
+tail -20 /Users/accusys/momentry/log/postgresql.log
+```
+
+---
+
+## 連線資訊
+
+| 項目 | 值 |
+|------|-----|
+| Host | localhost |
+| Port | 5432 |
+| User | accusys |
+| Database | momentry, video_register, gitea, n8n |
+
+---
+
+## 環境變數
+
+在 `.env` 中:
+
+```env
+POSTGRES_URL=postgresql://accusys@localhost:5432
+POSTGRES_DB=momentry
+```
+
+---
+
+## 遠端訪問
+
+- PostgreSQL 綁定到所有網路介面 (0.0.0.0)
+- 本地網路其他機器可透過 IP 訪問
+- 請設定 `pg_hba.conf` 限制訪問 IP
+
+---
+
+## 故障排除
+
+### PostgreSQL 無法啟動
+
+```bash
+# 檢查日誌
+tail -f /Users/accusys/momentry/log/postgresql.log
+
+# 檢查目錄權限
+ls -la /Users/accusys/momentry/var/postgresql/
+
+# 重新設定權限
+chown -R $(whoami):staff /Users/accusys/momentry/var/postgresql
+```
+
+### Port 被佔用
+
+```bash
+# 檢查哪個程序佔用 port 5432
+lsof -i :5432
+
+# 終止佔用程序
+kill <PID>
+```
+
+### 需要重新載入 plist
+
+```bash
+# 卸載舊服務 (如果存在)
+sudo launchctl unload /Library/LaunchDaemons/com.momentry.postgresql.plist 2>/dev/null
+
+# 載入新服務
+sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
+```
+
+---
+
+## 檔案位置
+
+| 類型 | 路徑 | 說明 |
+|------|------|------|
+| 安裝 | `/opt/homebrew/opt/postgresql@18/` | PostgreSQL 安裝目錄 |
+| 執行檔 | `/opt/homebrew/opt/postgresql@18/bin/postgres` | PostgreSQL 執行檔 |
+| 數據目錄 | `/Users/accusys/momentry/var/postgresql/` | 數據儲存 |
+| 日誌 | `/Users/accusys/momentry/log/postgresql.log` | 執行日誌 |
+| 錯誤日誌 | `/Users/accusys/momentry/log/postgresql.error.log` | 錯誤日誌 |
+| plist | `/Library/LaunchDaemons/com.momentry.postgresql.plist` | 開機啟動 |
+| 備份 | `/Users/accusys/momentry/var/momentry_db_backup_latest.sql` | momentry 數據庫備份 |
+| 備份 | `/Users/accusys/momentry/var/video_register_db_backup_latest.sql` | video_register 數據庫備份 |
+
+---
+
+## 備份與恢復
+
+### 備份 (pg_dump)
+
+```bash
+# 備份 momentry 數據庫
+pg_dump -U accusys momentry > /Users/accusys/momentry/var/momentry_db_backup_latest.sql
+
+# 備份 video_register 數據庫
+pg_dump -U accusys video_register > /Users/accusys/momentry/var/video_register_db_backup_latest.sql
+```
+
+### 恢復 (psql)
+
+```bash
+# 恢復 momentry 數據庫
+psql -U accusys -d momentry < /Users/accusys/momentry/var/momentry_db_backup_latest.sql
+
+# 恢復 video_register 數據庫
+psql -U accusys -d video_register < /Users/accusys/momentry/var/video_register_db_backup_latest.sql
+```
+
+### 數據目錄複製 (完整遷移)
+
+```bash
+# 1. 停止 PostgreSQL
+pg_ctl -D /Users/accusys/momentry/var/postgresql stop
+
+# 2. 複製數據目錄
+cp -r /opt/homebrew/var/postgresql@18/* /Users/accusys/momentry/var/postgresql/
+
+# 3. 設定權限
+chown -R $(whoami):staff /Users/accusys/momentry/var/postgresql
+
+# 4. 啟動 PostgreSQL
+sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
+```
+
+---
+
+## 版本資訊
+
+- 版本: 18.1
+- Port: 5432
+- User: accusys
+- 數據目錄: /Users/accusys/momentry/var/postgresql/
+- 日誌目錄: /Users/accusys/momentry/log/