momentry_core/docs/USER_MANUAL.md

# Momentry 使用手冊

| 項目 | 內容 |
|------|------|
| 版本 | V1.0 |
| 日期 | 2026-03-21 |
| 目標讀者 | 系統管理員、開發者 |

---

## 目錄

1. [快速開始](#1-快速開始)
2. [安裝與設定](#2-安裝與設定)
3. [CLI 命令參考](#3-cli-命令參考)
4. [影片管理](#4-影片管理)
5. [API Key 管理](#5-api-key-管理)
6. [第三方整合](#6-第三方整合)
7. [監控與維護](#7-監控與維護)
8. [疑難排解](#8-疑難排解)

---

## 1. 快速開始

### 1.1 最小啟動流程

```bash
# 1. 啟動服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.postgresql.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.redis.plist

# 2. 設定環境變數
source .env

# 3. 啟動 API 伺服器
momentry server --host 127.0.0.1 --port 3000

# 4. 建立 API Key
momentry api-key create my-first-key --key-type user --ttl 90
```

### 1.2 驗證安裝

```bash
# 檢查系統狀態
curl http://localhost:3002/health

# 檢查版本
momentry --help
```

---

## 2. 安裝與設定

### 2.1 環境需求

| 項目 | 需求 |
|------|------|
| 作業系統 | macOS (Apple Silicon) |
| Rust | 1.70+ |
| PostgreSQL | 15+ |
| Redis | 7+ |
| Python | 3.11+ (用於 AI 處理) |

### 2.2 安裝步驟

```bash
# 1. 複製專案
git clone <repository-url>
cd momentry_core_0.1

# 2. 編譯
cargo build --release

# 3. 安裝到系統
cp target/release/momentry /usr/local/bin/
```

### 2.3 環境變數設定

建立 `.env` 檔案：

```bash
# Database
DATABASE_URL=postgres://accusys@localhost:5432/momentry

# Redis
REDIS_URL=redis://:accusys@localhost:6379

# Gitea (選用)
GITEA_URL=http://localhost:3000

# n8n (選用)
N8N_URL=https://n8n.momentry.ddns.net

# API Server
API_HOST=127.0.0.1
API_PORT=3000

# 監控目錄
WATCH_DIRECTORIES=~/Videos
```

---

## 3. CLI 命令參考

### 3.1 一般命令

| 命令 | 說明 |
|------|------|
| `momentry --help` | 顯示幫助 |
| `momentry server` | 啟動 API 伺服器 |
| `momentry register <path>` | 註冊影片 |
| `momentry process <uuid>` | 處理影片 |
| `momentry query <text>` | RAG 查詢 |

### 3.2 影片管理

```bash
# 註冊影片
momentry register /path/to/video.mp4

# 處理影片
momentry process <uuid>

# 生成縮圖
momentry thumbnails <uuid> --count 6

# 查看狀態
momentry status <uuid>
```

### 3.3 API Key 管理

```bash
# 建立 Key
momentry api-key create <name> --key-type <type> --ttl <days>

# 列出 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
```

### 3.4 Gitea 整合

```bash
# 建立 Token
momentry gitea create \
  --username <user> \
  --password <pwd> \
  --token-name <name> \
  --scopes "read:repository,write:repository"

# 列出 Tokens
momentry gitea list --username <user> --password <pwd>

# 刪除 Token
momentry gitea delete \
  --username <user> \
  --password <pwd> \
  --token-name <name>
```

### 3.5 n8n 整合

```bash
# 建立 API Key
momentry n8n create \
  --api-key <existing-key> \
  --label <name> \
  --expires-in-days 90

# 列出 Keys
momentry n8n list --api-key <key>

# 刪除 Key
momentry n8n delete --api-key <key> --label <name>
```

### 3.6 備份管理

```bash
# 列出備份
momentry backup list

# 清理舊備份
momentry backup cleanup --days 30
```

---

## 4. 影片管理

### 4.1 影片生命週期

```
上傳 → 註冊 → 處理 → 儲存 → 查詢
  │      │      │      │      │
  ▼      ▼      ▼      ▼      ▼
檔案   資料庫  AI分析  向量庫  RAG
```

### 4.2 註冊影片

```bash
# 自動偵測格式
momentry register ~/Videos/my-video.mp4

# 輸出:
# UUID: a1b2c3d4e5f6g7h8
# Duration: 120.5s
# Resolution: 1920x1080
```

### 4.3 處理流程

處理包含以下階段：

| 階段 | 說明 | 時間 (約) |
|------|------|-----------|
| Probe | 影片資訊分析 | 5s |
| ASR | 語音辨識 | 視長度 |
| OCR | 文字辨識 | 視長度 |
| YOLO | 物件偵測 | 視長度 |
| Cut | 場景切割 | 30s |
| Chunk | 內容分段 | 10s |
| Vector | 向量化 | 20s |

### 4.4 查詢影片

```bash
# RAG 查詢
momentry query "影片中有什麼內容？"

# 取得特定影片
momentry resolve <uuid>
```

---

## 5. API Key 管理

### 5.1 Key 類型

| 類型 | 前綴 | 用途 | 預設 TTL |
|------|------|------|----------|
| System | `msys_` | 系統內部 | 365 天 |
| User | `muser_` | 個人用戶 | 90 天 |
| Service | `msvc_` | 服務間通訊 | 180 天 |
| Integration | `mint_` | 第三方整合 | 30 天 |
| Emergency | `memg_` | 緊急存取 | 1 天 |

### 5.2 建立 Key

```bash
# 一般 Key
momentry api-key create my-service --key-type service --ttl 90

# 緊急 Key (24小時有效)
momentry api-key create emergency-access --key-type emergency

# 輸出:
# ✅ API Key created successfully!
# Key ID: msvc_xxxxxxxx
# API Key: msvc_xxxxxxxx_xxxxx_xxxxx
# Expires: 2026-06-19
```

### 5.3 Key 生命週期

```
建立 → 使用 → 過期/撤銷 → 清理
  │      │        │          │
  ▼      ▼        ▼          ▼
資料庫  驗證    停用      定期刪除
```

### 5.4 安全建議

| 建議 | 說明 |
|------|------|
| 定期輪換 | 每 90 天更新 Key |
| 最小權限 | 只授予必要權限 |
| 監控使用 | 定期檢查使用統計 |
| 及時撤銷 | 異常時立即撤銷 |

---

## 6. 第三方整合

### 6.1 Gitea

```bash
# 建立 CI/CD 用 Token
momentry gitea create \
  --username admin \
  --password "your-password" \
  --token-name "ci-pipeline" \
  --scopes "read:repository,write:repository"

# 在 CI 中使用
export GITEA_TOKEN="token-sha1-value"
curl -H "Authorization: token $GITEA_TOKEN" \
  http://localhost:3000/api/v1/user
```

### 6.2 n8n

```bash
# 建立工作流用 Key
momentry n8n create \
  --api-key "existing-n8n-key" \
  --label "workflow-key" \
  --expires-in-days 90

# 在 n8n 中使用
# HTTP Request Header: X-N8N-API-Key: <key>
```

### 6.3 Webhook 通知

```bash
# 設定 Webhook
export WEBHOOK_URL="https://n8n.example.com/webhook/alerts"
export WEBHOOK_EVENTS="anomaly_detected,key_expired"
```

---

## 7. 監控與維護

### 7.1 系統監控

```bash
# 檢查服務狀態
ps aux | grep momentry
ps aux | grep postgres
redis-cli -a accusys ping

# 檢查日誌
tail -f /Users/accusys/momentry/log/momentry.log
tail -f /Users/accusys/momentry/log/redis.log
```

### 7.2 資料庫維護

```bash
# 檢查資料庫大小
psql -U accusys -d momentry -c "SELECT pg_size_pretty(pg_database_size('momentry'));"

# 清理過期記錄
momentry api-key stats  # 檢查統計
# 定期清理由系統自動執行
```

### 7.3 備份

```bash
# 手動備份 PostgreSQL
pg_dump -U accusys momentry > backup_$(date +%Y%m%d).sql

# 恢復備份
psql -U accusys momentry < backup_20260321.sql
```

---

## 8. 疑難排解

### 8.1 常見問題

#### Q: 無法連接資料庫

```bash
# 檢查 PostgreSQL 狀態
pg_isready -h localhost -p 5432

# 檢查連線
psql -U accusys -d momentry -c "SELECT 1;"
```

#### Q: Redis 連線失敗

```bash
# 檢查 Redis 狀態
redis-cli -a accusys ping

# 檢查認證
redis-cli -a accusys INFO server | grep redis_version
```

#### Q: API Key 驗證失敗

```bash
# 檢查 Key 狀態
momentry api-key validate --key "your-key"

# 檢查是否過期
momentry api-key list
```

### 8.2 錯誤碼對照

| 錯誤碼 | 說明 | 解決方式 |
|--------|------|----------|
| `E001` | 資料庫連線失敗 | 檢查 PostgreSQL |
| `E002` | Redis 連線失敗 | 檢查 Redis |
| `E003` | API Key 無效 | 重新建立 Key |
| `E004` | 影片不存在 | 檢查 UUID |
| `E005` | 處理失敗 | 檢查日誌 |

### 8.3 日誌位置

| 日誌 | 路徑 |
|------|------|
| Momentry | `/Users/accusys/momentry/log/momentry.log` |
| PostgreSQL | `/Users/accusys/momentry/log/postgresql.log` |
| Redis | `/Users/accusys/momentry/log/redis.log` |
| Gitea | `/Users/accusys/momentry/log/gitea.log` |

---

## 附錄

### A. 完整命令列表

```bash
momentry --help
momentry register --help
momentry process --help
momentry api-key --help
momentry gitea --help
momentry n8n --help
momentry backup --help
```

### B. 環境變數總覽

| 變數 | 預設值 | 說明 |
|------|--------|------|
| `DATABASE_URL` | `postgres://accusys@localhost:5432/momentry` | PostgreSQL |
| `REDIS_URL` | `redis://:accusys@localhost:6379` | Redis |
| `GITEA_URL` | `http://localhost:3000` | Gitea |
| `N8N_URL` | `https://n8n.momentry.ddns.net` | n8n |
| `API_HOST` | `127.0.0.1` | API 主機 |
| `API_PORT` | `3000` | API 埠號 |

### C. 相關文件

| 文件 | 說明 |
|------|------|
| `docs/API_CURL_EXAMPLES.md` | API curl 範例 |
| `docs/N8N_INTEGRATION_GUIDE.md` | n8n 整合指南 |
| `docs/API_KEY_MANAGEMENT.md` | API Key 設計 |
| `CHANGELOG.md` | 版本記錄 |