warren/momentry_core
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases 2 Wiki Activity
Files
383201cacd4c663f55ec9c6c858cff1577872aef
momentry_core/docs/INSTALL_MOMENTRY_API.md
accusys 383201cacd feat: Initial v0.9 release with API Key authentication 
## v0.9.20260325_144654

### Features
- API Key Authentication System
- Job Worker System
- V2 Backup Versioning

### Bug Fixes
- get_processor_results_by_job column mapping

Co-authored-by: OpenCode
2026-03-25 14:53:41 +08:00

9.9 KiB
Raw Blame History

Momentry Core API 安裝指南 (本地部署)

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

版本歷史

版本 日期 目的 操作人 工具/模型
V1.0 2026-03-23 創建文件 OpenCode -

概述

本文檔說明如何在 macOS 上安裝 Momentry Core API 服務，配置為本地部署，並設定開機自動啟動。

Momentry Core API 是一個 Rust 編寫的數位資產管理 API 服務，提供：

  • 影片搜尋 API (/api/v1/search)
  • n8n 整合 API (/api/v1/n8n/search)
  • 健康檢查端點 (/health)
  • 影片註冊與處理功能

當前狀態

項目 狀態
Momentry Core API ✅ 已安裝 v0.1.0
Binary /Users/accusys/momentry_core_0.1/target/release/momentry
Port 3002
反向代理 Caddy (api.momentry.ddns.net)
數據庫 PostgreSQL (momentry)
向量庫 Qdrant
Cache Redis
launchd plist ✅ 已建立 (/Library/LaunchDaemons/com.momentry.api.plist)

系統需求

必要服務

服務 版本 用途
PostgreSQL 16+ 主數據庫
Redis 1.0+ 快取與佇列
Qdrant 1.7+ 向量搜尋
Ollama 最新 LLM 與 Embedding

Rust 環境

# 檢查 Rust 版本
rustc --version
cargo --version

# 如需安裝 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

安裝步驟

Step 1: 編譯 Momentry Core

# 進入專案目錄
cd /Users/accusys/momentry_core_0.1

# 編譯 release 版本
cargo build --release

# 驗證編譯結果
ls -la target/release/momentry

Step 2: 設定環境變數

建立環境變數檔案：

# 建立執行目錄
mkdir -p /Users/accusys/momentry_core_0.1/momentry_runtime/env

# 建立環境變數檔案
cat > /Users/accusys/momentry_core_0.1/momentry_runtime/env/momentry.env << 'EOF'
# Database Configuration
DATABASE_URL=postgres://accusys@localhost:5432/momentry

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

# API Server
API_HOST=127.0.0.1
API_PORT=3002

# Ollama (LLM)
OLLAMA_HOST=http://localhost:11434

# Qdrant (Vector Database)
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=momentry_chunks
EOF

Step 3: 手動啟動服務

# 啟動 API 服務
cd /Users/accusys/momentry_core_0.1
./target/release/momentry server --port 3002

# 驗證服務
curl http://localhost:3002/health
# {"status":"ok","version":"0.1.0","uptime_ms":1234}

Step 4: 設定 Caddy 反向代理

在 /Users/accusys/momentry/etc/Caddyfile 中新增：

# Momentry Core API
api.momentry.ddns.net {
    reverse_proxy localhost:3002
    import common_log momentry_api_access
}

重新載入 Caddy：

# 重新載入配置
caddy reload --config /Users/accusys/momentry/etc/Caddyfile

# 驗證
curl -sk https://api.momentry.ddns.net/health

Step 5: 建立 launchd plist (開機自動啟動)

建立 plist 檔案：

sudo tee /Library/LaunchDaemons/com.momentry.api.plist << 'EOF'
<?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.api</string>
    
    <key>UserName</key>
    <string>accusys</string>
    
    <key>GroupName</key>
    <string>staff</string>
    
    <key>WorkingDirectory</key>
    <string>/Users/accusys/momentry_core_0.1</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/Users/accusys/momentry_core_0.1/target/release/momentry</string>
        <string>server</string>
        <string>--port</string>
        <string>3002</string>
    </array>
    
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
        
        <key>DATABASE_URL</key>
        <string>postgres://accusys@localhost:5432/momentry</string>
        
        <key>REDIS_URL</key>
        <string>redis://:accusys@localhost:6379</string>
        
        <key>REDIS_PASSWORD</key>
        <string>accusys</string>
        
        <key>OLLAMA_HOST</key>
        <string>http://localhost:11434</string>
        
        <key>QDRANT_URL</key>
        <string>http://localhost:6333</string>
    </dict>
    
    <key>RunAtLoad</key>
    <true/>
    
    <key>KeepAlive</key>
    <true/>
    
    <key>StandardOutPath</key>
    <string>/Users/accusys/momentry/log/momentry_api.log</string>
    
    <key>StandardErrorPath</key>
    <string>/Users/accusys/momentry/log/momentry_api.error.log</string>
</dict>
</plist>
EOF

建立日誌檔案：

# 建立日誌目錄（如不存在）
mkdir -p /Users/accusys/momentry/log

# 建立日誌檔案
touch /Users/accusys/momentry/log/momentry_api.log
touch /Users/accusys/momentry/log/momentry_api.error.log

# 設定權限
chown accusys:staff /Users/accusys/momentry/log/momentry_api.log
chown accusys:staff /Users/accusys/momentry/log/momentry_api.error.log

載入服務：

# 載入服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 驗證服務
launchctl list | grep momentry.api

# 檢查服務狀態
curl http://localhost:3002/health

卸載步驟

Step 1: 停止並移除服務

# 停止服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist

# 移除 plist
sudo rm /Library/LaunchDaemons/com.momentry.api.plist

Step 2: 移除 Caddy 配置

從 /Users/accusys/momentry/etc/Caddyfile 中移除 api.momentry.ddns.net 區塊。

# 重新載入 Caddy
caddy reload --config /Users/accusys/momentry/etc/Caddyfile

故障排除

API 返回 502 Bad Gateway

問題: api.momentry.ddns.net 返回 502 錯誤

原因: Momentry Core API 服務未啟動

解決方案:

# 檢查服務狀態
launchctl list | grep momentry.api

# 如服務未啟動，手動啟動
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 或手動啟動測試
cd /Users/accusys/momentry_core_0.1
./target/release/momentry server --port 3002

API 返回 404 Not Found

問題: 端點返回 404

原因: Binary 過舊，缺少該端點

解決方案:

# 重新編譯
cd /Users/accusys/momentry_core_0.1
cargo build --release

# 重啟服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

服務無法啟動

問題: launchd 無法啟動服務

檢查步驟:

# 檢查日誌
tail -50 /Users/accusys/momentry/log/momentry_api.error.log

# 檢查 plist 語法
plutil -lint /Library/LaunchDaemons/com.momentry.api.plist

# 檢查權限
ls -la /Users/accusys/momentry_core_0.1/target/release/momentry

# 手動測試
/Users/accusys/momentry_core_0.1/target/release/momentry server --port 3002

檔案位置

類型 路徑 說明
Binary /Users/accusys/momentry_core_0.1/target/release/momentry 執行檔
環境變數 /Users/accusys/momentry_core_0.1/momentry_runtime/env/momentry.env 環境設定
launchd plist /Library/LaunchDaemons/com.momentry.api.plist 開機啟動配置
日誌 /Users/accusys/momentry/log/momentry_api.log 標準輸出
錯誤日誌 /Users/accusys/momentry/log/momentry_api.error.log 錯誤輸出
Caddy 配置 /Users/accusys/momentry/etc/Caddyfile 反向代理配置

常用指令

服務管理

# 啟動服務
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 停止服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist

# 重啟服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

# 檢查服務狀態
launchctl list | grep momentry.api

健康檢查

# 本地健康檢查
curl http://localhost:3002/health

# 詳細健康檢查
curl http://localhost:3002/health/detailed

# 外部健康檢查
curl -sk https://api.momentry.ddns.net/health

API 測試

# 搜尋 API
curl -X POST http://localhost:3002/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"test"}'

# n8n 搜尋 API
curl -X POST http://localhost:3002/api/v1/n8n/search \
  -H "Content-Type: application/json" \
  -d '{"query":"test"}'

# 列出影片
curl http://localhost:3002/api/v1/videos

日誌查看

# 查看最近的日誌
tail -50 /Users/accusys/momentry/log/momentry_api.log

# 即時監控日誌
tail -f /Users/accusys/momentry/log/momentry_api.log

# 查看錯誤日誌
tail -50 /Users/accusys/momentry/log/momentry_api.error.log

重新編譯

# 編譯 release 版本
cd /Users/accusys/momentry_core_0.1
cargo build --release

# 編譯後重啟服務
sudo launchctl unload /Library/LaunchDaemons/com.momentry.api.plist
sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist

API 端點

端點 方法 說明
/health GET 健康檢查
/health/detailed GET 詳細健康檢查
/api/v1/register POST 註冊影片
/api/v1/search POST 搜尋影片
/api/v1/n8n/search POST n8n 格式搜尋
/api/v1/search/hybrid POST 混合搜尋
/api/v1/lookup GET 查詢 UUID
/api/v1/videos GET 列出所有影片
/api/v1/progress/:uuid GET 查詢處理進度

版本資訊

  • 版本: 0.1.0
  • 安裝日期: 2026-03-23
  • Rust 版本: 1.xx
  • 文件更新: 2026-03-23

相關文件

  • docs/SERVICES.md - 服務總覽
  • docs/API_REFERENCE.md - API 參考
  • docs/INSTALL_POSTGRESQL.md - PostgreSQL 安裝
  • docs/INSTALL_REDIS.md - Redis 安裝
  • docs/INSTALL_QDRANT.md - Qdrant 安裝
  • docs/PENDING_ISSUES.md - 待解決問題
Reference in New Issue View Git Blame Copy Permalink