# Momentry 系統整合指南 v0.1

## 一、專案概述

Momentry 是一個數位資產管理系統，包含服務遷移、監控系統、Storage 架構和用戶管理。

**設計目標**：
- 自動化優先：人類只需處理通知和判斷
- 分層監控：七層監控架構
- 數據納管：檔案由資料庫統一管理

---

## 二、系統架構

### 硬體
- **本地 NVMe**：熱數據 (/Users/accusys/momentry/)
- **外部 RAID**：溫數據 (/Volumes/RAID System/)
- **Object Storage**：冷數據歸檔

### 網路
- **DDNS**：momentry.ddns.net
- **VPN**：Shadowsocks (port 8388)
- **反向代理**：Caddy

### 軟體服務 (15 個)

| 服務 | Port | 用途 | 狀態 |
|------|------|------|------|
| PostgreSQL | 5432 | 主資料庫 | ✅ 運行 |
| Redis | 6379 | 快取/會話 | ✅ 運行 |
| n8n Main | 5678 | 工作流 | ✅ 運行 |
| n8n Worker | 5690 | 工作流 | ✅ 運行 |
| Caddy | 443/2019 | 反向代理 | ✅ 運行 |
| Gitea | 3000 | Git 服務 | ✅ 運行 |
| SFTPGo | 2222 | SFTP | ✅ 運行 |
| Ollama | 11434 | LLM | ✅ 運行 |
| Qdrant | 6333 | 向量資料庫 | ✅ 運行 |
| MariaDB | 3306 | WordPress | ✅ 運行 |
| PHP-FPM | - | Web 後端 | ✅ 運行 |
| RustDesk hbbs | 21116 | 遠程桌面 | ✅ 運行 |
| RustDesk hbbr | 21117 | 遠程桌面 | ✅ 運行 |
| MongoDB | 27017 | 文檔資料庫 | ✅ 運行 |
| Agent | - | 代理服務 | ✅ 運行 |

---

## 三、監控系統 (七層架構)

```
Layer 1: External 監控          - DDNS、網關、互聯網
Layer 2: Service 監控           - 15 個服務健康檢查
Layer 3: Workflow 監控           - n8n Workflow 狀態/閒置分析
Layer 4: Portal 監控             - WordPress 頁面/帳號
Layer 5: Database 監控           - PostgreSQL/Redis/Qdrant/MariaDB
Layer 6: 使用者監控              - 連線/本機/異常檢測
Layer 7: Storage 架構            - 冷溫熱/歸檔/檔案註冊
```

### 3.1 Layer 1: External 監控

**監控項目**：
- DDNS 域名解析 (momentry.ddns.net)
- 網關連通性 (192.168.110.1)
- 互聯網連接 (8.8.8.8)

**腳本**：`monitor/service/external_monitor.sh`

### 3.2 Layer 2: Service 監控

**監控項目**：
- 進程狀態
- 端口響應
- HTTP 狀態碼

**腳本**：`monitor/service/health_check.sh`

### 3.3 Layer 3: n8n Workflow 監控

**監控項目**：
- Workflow 數量與啟用狀態
- 執行次數與結果
- 閒置識別

**閒置定義**：
```
閒置 = 無排程 AND 無 API 觸發 AND 超過 30 天未執行
```

**改善建議**：
- 建議停用：閒置 > 30 天
- 建議刪除：閒置 > 90 天

**腳本**：`monitor/workflow/n8n_workflow_monitor.sh`

### 3.4 Layer 4: WordPress Portal 監控

**變動監控**：
- 版本變更 (Core/Theme/Plugin)
- 文件變更 (wp-content)
- 配置變更 (wp-config.php)
- 內容變更 (文章/頁面)
- 代碼變更
- 帳號創建/刪除/修改

**使用監控**：
- 帳號登入/失敗
- 內容操作 (發布/編輯/刪除)
- 權限變更
- 評論/媒體操作

**腳本**：`monitor/portal/page_monitor.sh`

### 3.5 Layer 5: Database 監控

**PostgreSQL**：
- 表數量/行數/大小
- 死元組
- 慢查詢

**Redis**：
- 連線數
- 內存使用
- 命中率
- 客戶端列表

**Qdrant**：
- Collection 列表
- Points 數
- 向量維度
- 磁盤使用

**MariaDB**：
- 連線數
- WordPress 表

**腳本**：
- `monitor/database/postgres_monitor.sh`
- `monitor/database/redis_monitor.sh`
- `monitor/database/qdrant_monitor.sh`

### 3.6 Layer 6: 使用者監控

**連線使用者**：
- SSH 登入與命令
- Web 服務 (n8n/Gitea/WP)
- 資料庫連線
- SFTP 傳輸

**本機使用者**：
- 系統登入
- sudo 使用
- 服務帳戶
- 異常檢測

**異常檢測**：
- 暴力破解 (> 5次/分鐘)
- 權限提升
- 異常時間登入

**腳本**：`monitor/users/session_tracker.sh`

### 3.7 Layer 7: Storage 架構

**目錄結構**：
```
/Users/accusys/momentry/
├── var/           # 服務數據 (熱)
├── etc/           # 配置 (溫)
├── log/           # 日誌 (溫)
├── data/          # 用戶數據
│   ├── family/    # 家庭集群
│   ├── work/      # 工作集群
│   ├── wordpress/ # WP 隔離
│   └── shared/    # 共享
├── backup/        # 備份
│   ├── daily/
│   ├── weekly/
│   ├── monthly/
│   └── archive/
└── tmp/           # 臨時
```

**分層標準**：
| 等級 | 條件 | 存放 |
|------|------|------|
| 熱 | 7天內訪問 > 10次 | NVMe |
| 溫 | 30天內訪問 > 1次 | RAID |
| 冷 | 90天未訪問 | Object |

**歸檔策略**：
- 手動歸檔
- 自動歸檔 (90天)
- 深度歸檔 (1年)

**腳本**：`monitor/storage/storage_manager.sh`

---

## 四、數據表設計

### 監控相關
```sql
monitor_services          -- 服務健康狀態
monitor_workflows        -- n8n Workflow
monitor_databases        -- 資料庫指標
monitor_portal_pages     -- WP 頁面
monitor_portal_users     -- WP 用戶
monitor_sessions         -- 使用者會話
monitor_logins          -- 登入歷史
monitor_sudo_history    -- sudo 記錄
monitor_resource_usage  -- 資源使用
monitor_anomalies       -- 異常檢測
monitor_external        -- 外部監控
```

### Storage 相關
```sql
file_registry           -- 檔案註冊
storage_usage_stats    -- 存儲統計
storage_access_logs    -- 訪問日誌
file_lifecycle         -- 生命週期
```

---

## 八、實現文件結構

```
momentry_core_0.1/
├── MOMENTRY_INTEGRATION_GUIDE.md  # 本文件
├── monitor/
│   ├── MONITORING.md              # 監控詳細文檔
│   ├── config/
│   │   └── monitor_config.yaml    # 配置文件
│   ├── control/
│   │   └── monitor_control.sh    # 控制腳本
│   ├── service/
│   │   ├── health_check.sh       # 服務健康
│   │   └── external_monitor.sh   # 外部監控
│   ├── workflow/
│   │   └── n8n_workflow_monitor.sh
│   ├── portal/
│   │   └── page_monitor.sh
│   ├── database/
│   │   ├── schema.sql
│   │   ├── postgres_monitor.sh
│   │   ├── redis_monitor.sh
│   │   └── qdrant_monitor.sh
│   ├── users/
│   │   └── session_tracker.sh
│   └── storage/
│       └── storage_manager.sh
├── momentry_runtime/
│   └── plist/
│       ├── template.service.plist  # 用戶級模板
│       ├── template.root.plist    # 系統級模板
│       └── *.plist                # 服務配置文件
└── docs/
    ├── SERVICES.md                 # 服務安裝
    └── SERVICE_ADDITION_GUIDE.md  # 服務添加規範
```

---

## 六、快速使用

### 初始化
```bash
# 初始化監控資料庫
psql -U accusys -h localhost -d momentry -f monitor/database/schema.sql

# 初始化 Storage 目錄
./monitor/storage/storage_manager.sh init
```

### 監控命令
```bash
cd /Users/accusys/momentry_core_0.1/monitor

# 查看狀態
./control/monitor_control.sh status

# 執行檢查
./control/monitor_control.sh check all           # 全部
./control/monitor_control.sh check service      # 服務
./control/monitor_control.sh check workflow      # Workflow
./control/monitor_control.sh check database      # 資料庫
./control/monitor_control.sh check users         # 使用者
./control/monitor_control.sh check storage       # Storage

# 持續監控
./control/monitor_control.sh monitor
```

---

## 七、優先級

| 優先級 | 項目 |
|--------|------|
| P0 | Service 基礎監控 |
| P0 | Database 監控 |
| P1 | 使用者監控 |
| P1 | n8n Workflow 監控 |
| P2 | WordPress Portal 監控 |
| P2 | External 監控 |
| P3 | Storage 架構 |

---

## 九、服務添加規範

### 9.1 概述

添加新服務到 Momentry 系統的標準流程。

**重要原則**：
- 使用 `launchctl` 管理服務，勿使用 `brew services`
- 所有服務使用 `com.momentry.*` 作為 plist Label
- 數據存放於 `/Users/accusys/momentry/` 目錄
- 每個服務需提供監控腳本

### 9.2 命名規範

**Plist 文件命名**：
```
com.momentry.{service_name}.plist
```

**目錄結構**：
```
/Users/accusys/momentry/
├── var/{service_name}/     # 服務數據
├── etc/{service_name}/    # 服務配置
└── log/{service_name}.log # 服務日誌
```

### 9.3 Plist 模板

**用戶級服務模板** (`plist/template.service.plist`)：
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.momentry.{service_name}</string>
    <key>UserName</key>
    <string>accusys</string>
    <key>WorkingDirectory</key>
    <string>/Users/accusys/momentry/var/{service_name}</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/executable</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/Users/accusys/momentry/log/{service_name}.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/accusys/momentry/log/{service_name}.error.log</string>
</dict>
</plist>
```

### 9.4 添加步驟

**步驟 1：創建目錄**
```bash
mkdir -p /Users/accusys/momentry/var/{service_name}
mkdir -p /Users/accusys/momentry/etc/{service_name}
```

**步驟 2：創建 Plist 文件**
```bash
cp plist/template.service.plist plist/com.momentry.{service_name}.plist
# 編輯 plist 文件
```

**步驟 3：複製到系統**
```bash
# 系統級服務
sudo cp plist/com.momentry.{service}.plist /Library/LaunchDaemons/

# 用戶級服務
cp plist/com.momentry.{service}.plist ~/Library/LaunchAgents/
```

**步驟 4：載入服務**
```bash
sudo launchctl load /Library/LaunchDaemons/com.momentry.{service}.plist
```

**步驟 5：添加監控**
在 `monitor/config/monitor_config.yaml` 中添加服務配置。

### 9.5 服務管理命令

```bash
# 啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.{service}.plist

# 停止
sudo launchctl unload /Library/LaunchDaemons/com.momentry.{service}.plist

# 查看狀態
launchctl list | grep momentry

# 查看日誌
tail -f /Users/accusys/momentry/log/{service}.log
```

### 9.6 服務分類

| 類型 | Plist 位置 | 示例 |
|------|------------|------|
| 系統級 | `/Library/LaunchDaemons/` | PostgreSQL, Caddy |
| 用戶級 | `~/Library/LaunchAgents/` | Redis, n8n, Ollama |

### 9.7 模板文件

| 文件 | 說明 |
|------|------|
| `plist/template.service.plist` | 用戶級服務模板 |
| `plist/template.root.plist` | 系統級服務模板 |
| `docs/SERVICE_ADDITION_GUIDE.md` | 完整規範文檔 |

---

## 十、版本歷史

| 版本 | 日期 | 內容 |
|------|------|------|
| 0.1 | 2026-03-15 | 初始版本：七層監控架構、15 個服務、Storage 設計 |
| 0.2 | 2026-03-15 | 新增服務添加規範 (第九章)、模板文件 |
