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
This commit is contained in:
accusys
464
docs/INSTALL_MOMENTRY_API.md
Normal file
464
docs/INSTALL_MOMENTRY_API.md
Normal file
@@ -0,0 +1,464 @@
|
||||
# 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` - 待解決問題
|
||||
Reference in New Issue
Block a user