Files

Warren 82955504f3 feat: 新增 Job Worker 系統與 API 文檔全面更新

2026-03-26 16:16:34 +08:00

8.9 KiB

Raw Blame History

Momentry 使用手冊

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

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-21	創建使用手冊	Warren	OpenCode

目標讀者: 系統管理員、開發者

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

8.9 KiB Raw Blame History

Momentry 使用手冊

版本歷史

目錄

1. 快速開始

1.1 最小啟動流程

1.2 驗證安裝

2. 安裝與設定

2.1 環境需求

2.2 安裝步驟

2.3 環境變數設定

3. CLI 命令參考

3.1 一般命令

3.2 影片管理

3.3 API Key 管理

3.4 Gitea 整合

3.5 n8n 整合

3.6 備份管理

4. 影片管理

4.1 影片生命週期

4.2 註冊影片

4.3 處理流程

4.4 查詢影片

5. API Key 管理

5.1 Key 類型

5.2 建立 Key

5.3 Key 生命週期

5.4 安全建議

6. 第三方整合

6.1 Gitea

6.2 n8n

6.3 Webhook 通知

7. 監控與維護

7.1 系統監控

7.2 資料庫維護

7.3 備份

8. 疑難排解

8.1 常見問題

Q: 無法連接資料庫

Q: Redis 連線失敗

Q: API Key 驗證失敗

8.2 錯誤碼對照

8.3 日誌位置

附錄

A. 完整命令列表

B. 環境變數總覽

C. 相關文件

8.9 KiB

Raw Blame History