# 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 環境

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

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

---

## 安裝步驟

### Step 1: 編譯 Momentry Core

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

# 編譯 release 版本
cargo build --release

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

---

### Step 2: 設定環境變數

建立環境變數檔案：

```bash
# 建立執行目錄
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: 手動啟動服務

```bash
# 啟動 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` 中新增：

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

重新載入 Caddy：

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

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

---

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

建立 plist 檔案：

```bash
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
```

建立日誌檔案：

```bash
# 建立日誌目錄（如不存在）
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
```

載入服務：

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

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

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

---

## 卸載步驟

### Step 1: 停止並移除服務

```bash
# 停止服務
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` 區塊。

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

---

## 故障排除

### API 返回 502 Bad Gateway

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

**原因**: Momentry Core API 服務未啟動

**解決方案**:

```bash
# 檢查服務狀態
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 過舊，缺少該端點

**解決方案**:

```bash
# 重新編譯
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 無法啟動服務

**檢查步驟**:

```bash
# 檢查日誌
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` | 反向代理配置 |

---

## 常用指令

### 服務管理

```bash
# 啟動服務
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
```

### 健康檢查

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

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

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

### API 測試

```bash
# 搜尋 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
```

### 日誌查看

```bash
# 查看最近的日誌
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
```

### 重新編譯

```bash
# 編譯 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` - 待解決問題