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:52:51 +08:00
parent 47e86b696f
commit 383201cacd
193 changed files with 40268 additions and 422 deletions
--- a/docs/API_CURL_EXAMPLES.md
+++ b/docs/API_CURL_EXAMPLES.md
@@ -0,0 +1,492 @@
+# Momentry API 使用說明 (curl 範例)
+
+| 項目 | 內容 |
+|------|------|
+| 版本 | V1.2 |
+| 日期 | 2026-03-23 |
+| Base URL | `http://localhost:3002` |
+
+---
+
+> **狀態說明**:
+> - ✅ **已實作**: 健康檢查、搜尋、影片管理端點
+> - ⚠️ **規劃中**: API Key 管理功能
+> - 🔧 **CLI**: 部分功能需使用命令列工具
+
+---
+
+## 目錄
+
+1. [已實作端點](#1-已實作端點)
+2. [API Key 管理](#2-api-key-管理-規劃中)
+3. [影片管理](#3-影片管理)
+4. [查詢與搜索](#4-查詢與搜索)
+5. [系統狀態](#5-系統狀態)
+
+---
+
+## URL 選擇指南
+
+### 兩種 URL 的使用情境
+
+| 環境 | URL | 說明 |
+|------|-----|------|
+| **本地開發** | `http://localhost:3002` | 直接訪問 API，繞過反向代理 |
+| **外部訪問** | `https://api.momentry.ddns.net` | 通過 Caddy 反向代理訪問，需網路可達 |
+
+### 何時使用 localhost:3002
+
+- ✅ 開發/測試環境
+- ✅ 直接在伺服器上操作
+- ✅ 當 Caddy/反向代理有問題時
+- ✅ 需要快速除錯時
+
+### 何時使用 api.momentry.ddns.net
+
+- ✅ n8n workflow 中呼叫 API
+- ✅ 外部系統整合
+- ✅ 生產環境
+- ✅ 從其他機器訪問
+
+### 快速切換範例
+
+```bash
+# 本地測試
+curl http://localhost:3002/health
+
+# 外部測試（功能相同）
+curl https://api.momentry.ddns.net/health
+```
+
+### 常見問題
+
+**Q: 為什麼有兩個 URL？**
+A: `localhost:3002` 是直接訪問，`api.momentry.ddns.net` 通過 Caddy 反向代理。
+
+**Q: 兩者功能相同嗎？**
+A: 是的，所有端點和功能完全相同。
+
+**Q: 502 錯誤時怎麼辦？**
+A: 如果 `api.momentry.ddns.net` 返回 502，檢查 Momentry API 服務是否運行：
+```bash
+launchctl list | grep momentry.api
+# 如果未運行
+sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
+```
+
+---
+
+## 1. 已實作端點
+
+### 健康檢查
+
+```bash
+curl http://localhost:3002/health
+```
+
+**回應**:
+```json
+{"status":"ok","version":"0.1.0","uptime_ms":123456}
+```
+
+### 詳細健康檢查
+
+```bash
+curl http://localhost:3002/health/detailed
+```
+
+---
+
+## 2. API Key 管理 *(規劃中)*
+
+> ⚠️ **此功能尚未實作**。以下為規劃中的 API 說明，僅供參考。
+
+### 2.1 建立 API Key
+
+```bash
+curl -X POST http://localhost:3002/api/v1/api-keys \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-admin-key" \
+  -d '{
+    "name": "my-service-key",
+    "key_type": "service",
+    "permissions": ["read", "write"],
+    "ttl_days": 90
+  }'
+```
+
+### 2.2 列出所有 API Keys
+
+```bash
+curl -X GET http://localhost:3002/api/v1/api-keys \
+  -H "X-API-Key: your-admin-key"
+```
+
+### 2.3 驗證 API Key
+
+```bash
+curl -X GET http://localhost:3002/api/v1/api-keys/validate \
+  -H "X-API-Key: key-to-validate"
+```
+
+### 2.4 撤銷 API Key
+
+```bash
+curl -X DELETE http://localhost:3002/api/v1/api-keys/msvc_a1b2c3d4_... \
+  -H "X-API-Key: your-admin-key"
+```
+
+### 2.5 請求 Key 輪換
+
+```bash
+curl -X POST http://localhost:3002/api/v1/api-keys/msvc_a1b2c3d4_.../rotate \
+  -H "X-API-Key: your-admin-key" \
+  -H "Content-Type: application/json" \
+  -d '{"reason": "scheduled_rotation"}'
+```
+
+### 2.6 取得統計資訊
+
+```bash
+curl -X GET http://localhost:3002/api/v1/api-keys/stats \
+  -H "X-API-Key: your-admin-key"
+```
+
+---
+
+## 3. 影片管理
+
+### 3.1 註冊影片 ✅
+
+```bash
+curl -X POST http://localhost:3002/api/v1/register \
+  -H "Content-Type: application/json" \
+  -d '{"path": "/path/to/video.mp4"}'
+```
+
+**回應範例**:
+
+```json
+{
+  "id": 1,
+  "uuid": "a1b2c3d4e5f6g7h8",
+  "file_path": "/path/to/video.mp4",
+  "file_name": "video.mp4",
+  "duration": 120.5,
+  "width": 1920,
+  "height": 1080
+}
+```
+
+### 3.2 列出所有影片 ✅
+
+```bash
+curl http://localhost:3002/api/v1/videos
+```
+
+### 3.3 查詢影片 ✅
+
+```bash
+# 依 UUID 查詢
+curl "http://localhost:3002/api/v1/lookup?uuid=a1b2c3d4e5f6g7h8"
+
+# 依路徑查詢
+curl "http://localhost:3002/api/v1/lookup?path=/path/to/video.mp4"
+```
+
+### 3.4 處理影片 🔧 *(CLI - 非 API)*
+
+影片處理需要使用 CLI 命令：
+
+```bash
+# 處理影片（生成 ASR, CUT, YOLO, OCR, Face, Pose 資料）
+cargo run --bin momentry -- process <uuid>
+
+# 或處理多個影片
+cargo run --bin momentry -- process <uuid1> <uuid2> <uuid3>
+```
+
+### 3.5 取得處理進度 ✅
+
+```bash
+curl http://localhost:3002/api/v1/progress/<uuid>
+```
+
+**回應範例**:
+
+```json
+{
+  "uuid": "a1b2c3d4e5f6g7h8",
+  "overall_progress": 75,
+  "processors": [
+    {
+      "name": "asr",
+      "status": "complete",
+      "current": 100,
+      "total": 100,
+      "progress": 100,
+      "message": "7 segments"
+    },
+    {
+      "name": "cut",
+      "status": "complete",
+      "current": 134,
+      "total": 134,
+      "progress": 100,
+      "message": "134 scenes"
+    },
+    {
+      "name": "yolo",
+      "status": "progress",
+      "current": 5000,
+      "total": 14315,
+      "progress": 35,
+      "message": "frame 5000"
+    }
+  ]
+}
+```
+
+---
+
+## 4. 查詢與搜索
+
+### 4.1 語意搜尋 ✅
+
+```bash
+curl -X POST http://localhost:3002/api/v1/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "測試關鍵字",
+    "limit": 5
+  }'
+```
+
+**回應範例**:
+
+```json
+{
+  "results": [
+    {
+      "uuid": "a1b2c3d4e5f6g7h8",
+      "chunk_id": "sentence_0006",
+      "chunk_type": "sentence",
+      "start_time": 48.8,
+      "end_time": 55.44,
+      "text": "fun plot twists...",
+      "score": 0.526
+    }
+  ],
+  "query": "測試關鍵字"
+}
+```
+
+### 4.2 n8n 格式搜尋 ✅
+
+```bash
+curl -X POST http://localhost:3002/api/v1/n8n/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "測試關鍵字",
+    "limit": 5
+  }'
+```
+
+**回應範例**:
+
+```json
+{
+  "query": "測試關鍵字",
+  "count": 2,
+  "hits": [
+    {
+      "id": "c_001",
+      "vid": "a1b2c3d4e5f6g7h8",
+      "start": 48.8,
+      "end": 55.44,
+      "title": "Chunk sentence_0006",
+      "text": "fun plot twists...",
+      "score": 0.92,
+      "media_url": "https://wp.momentry.ddns.net/video.mp4"
+    }
+  ]
+}
+```
+
+### 4.3 混合搜尋 ✅
+
+```bash
+curl -X POST http://localhost:3002/api/v1/search/hybrid \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "測試關鍵字",
+    "limit": 5
+  }'
+```
+
+---
+
+## 5. 系統狀態
+
+### 5.1 健康檢查 ✅
+
+```bash
+curl http://localhost:3002/health
+```
+
+**回應**:
+```json
+{"status":"ok","version":"0.1.0","uptime_ms":123456}
+```
+
+### 5.2 詳細健康檢查 ✅
+
+```bash
+curl http://localhost:3002/health/detailed
+```
+
+**回應範例**:
+
+```json
+{
+  "status":"ok",
+  "version":"0.1.0",
+  "uptime_ms":123456,
+  "services":{
+    "postgres":{"status":"ok","latency_ms":42,"error":null},
+    "redis":{"status":"ok","latency_ms":0,"error":null},
+    "qdrant":{"status":"ok","latency_ms":15,"error":null}
+  }
+}
+```
+
+---
+
+## 6. n8n Webhook 測試
+
+### 測試 n8n Workflow
+
+**重要**: 測試前請先在 n8n UI 中點擊 "Execute workflow" 按鈕
+
+```bash
+# 測試 Video RAG Workflow (Test Mode)
+curl -X POST http://localhost:5678/webhook-test/video-rag-mcp \
+  -H "Content-Type: application/json" \
+  -d '{"query":"charade","limit":3}'
+
+# 帶有 UUID 過濾的搜尋
+curl -X POST http://localhost:5678/webhook-test/video-rag-mcp \
+  -H "Content-Type: application/json" \
+  -d '{"query":"woody","limit":5,"uuid":"a1b10138a6bbb0cd"}'
+```
+
+### 生產環境 Webhook
+
+**注意**: 工作流程必須處於 Active 狀態
+
+```bash
+curl -X POST http://localhost:5678/webhook/video-rag-mcp \
+  -H "Content-Type: application/json" \
+  -d '{"query":"charade","limit":3}'
+```
+
+### n8n Webhook 常見問題
+
+**Q: webhook-test 返回 404**
+A: 需要在 n8n UI 中點擊 "Execute workflow" 按鈕後才能使用 test webhook
+
+**Q: webhook (生產環境) 返回 404**
+A: 需要將工作流程切換為 Active 狀態 (右上角開關)
+
+---
+
+## 附錄
+
+### A. 服務 URL 列表
+
+| 服務 | URL |
+|------|-----|
+| Momentry API (本地) | `http://localhost:3002` |
+| Momentry API (外部) | `https://api.momentry.ddns.net` |
+| n8n Web UI | `https://n8n.momentry.ddns.net` |
+| n8n Webhook Test | `http://localhost:5678/webhook-test/{workflow-name}` |
+| n8n Webhook Prod | `http://localhost:5678/webhook/{workflow-name}` |
+
+### B. 所有可用端點
+
+| 端點 | 方法 | 狀態 | 說明 |
+|------|------|------|------|
+| `/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 | ✅ | 查詢影片 |
+| `/api/v1/videos` | GET | ✅ | 列出所有影片 |
+| `/api/v1/progress/:uuid` | GET | ✅ | 處理進度 |
+| `/api/v1/api-keys` | * | ⚠️ | API Key 管理 (規劃中) |
+
+### C. 常見錯誤
+
+| HTTP 狀態 | 說明 | 解決方式 |
+|-----------|------|----------|
+| 200 | 成功 | - |
+| 400 | 請求格式錯誤 | 檢查 JSON 格式 |
+| 404 | 端點不存在或資源未找到 | 確認端點 URL 正確 |
+| 500 | 伺服器內部錯誤 | 檢查 API 服務日誌 |
+| **502** | **Bad Gateway** | **API 服務未啟動，見下方說明** |
+
+#### 502 Bad Gateway 錯誤
+
+**問題**: 外部 URL `https://api.momentry.ddns.net` 返回 502
+
+**原因**: Momentry Core API 服務未啟動
+
+**解決方式**:
+
+```bash
+# 1. 檢查服務狀態
+launchctl list | grep momentry.api
+
+# 2. 如果未啟動，手動啟動
+sudo launchctl load /Library/LaunchDaemons/com.momentry.api.plist
+
+# 3. 或使用本地測試（繞過反向代理）
+curl http://localhost:3002/health
+
+# 4. 檢查日誌
+tail -50 /Users/accusys/momentry/log/momentry_api.error.log
+```
+
+### D. 範例腳本
+
+```bash
+#!/bin/bash
+# api_test.sh - API 測試腳本
+
+API_URL="http://localhost:3002"
+
+# 健康檢查
+echo "=== Health Check ==="
+curl -s "$API_URL/health" | jq .
+
+# 搜尋
+echo -e "\n=== Search ==="
+curl -s -X POST "$API_URL/api/v1/search" \
+  -H "Content-Type: application/json" \
+  -d '{"query": "test", "limit": 3}' | jq .
+
+# 列出影片
+echo -e "\n=== Videos ==="
+curl -s "$API_URL/api/v1/videos" | jq '.videos | length'
+```
+
+---
+
+## 相關文件
+
+- [API_INDEX.md](./API_INDEX.md) - 文件總覽（起點）
+- [API_ENDPOINTS.md](./API_ENDPOINTS.md) - 端點完整說明
+- [API_N8N_GUIDE.md](./API_N8N_GUIDE.md) - n8n 使用範例
+- [API_WORDPRESS_GUIDE.md](./API_WORDPRESS_GUIDE.md) - WordPress 使用範例