momentry_core/docs/USER_MANUAL.md

Momentry 使用手冊

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

---

目錄

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

---

1. 快速開始

1.1 最小啟動流程

# 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 驗證安裝

# 檢查系統狀態
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 安裝步驟

# 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 檔案：

# 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 影片管理

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

# 處理影片
momentry process <uuid>

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

# 查看狀態
momentry status <uuid>

3.3 API Key 管理

# 建立 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 整合

# 建立 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 整合

# 建立 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 備份管理

# 列出備份
momentry backup list

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

---

4. 影片管理

4.1 影片生命週期

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

4.2 註冊影片

# 自動偵測格式
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 查詢影片

# 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

# 一般 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

# 建立 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

# 建立工作流用 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 通知

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

---

7. 監控與維護

7.1 系統監控

# 檢查服務狀態
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 資料庫維護

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

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

7.3 備份

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

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

---

8. 疑難排解

8.1 常見問題

Q: 無法連接資料庫

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

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

Q: Redis 連線失敗

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

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

Q: API Key 驗證失敗

# 檢查 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. 完整命令列表

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	版本記錄