Files

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

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

15 KiB

Raw Blame History

Momentry n8n 整合使用手冊

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

版本歷史

版本	日期	目的	操作人	工具/模型
V1.0	2026-03-22	創建 n8n 整合手冊	Warren	OpenCode
V1.1	2026-03-23	新增 API Key 驗證與完整工作流範例	Warren	OpenCode

目標讀者: n8n 使用者、DevOps

1. 概述

1.1 什麼是 n8n？

n8n 是一個開源的工作流自動化工具，可以連接各種服務和 API。

1.2 為什麼需要整合？

場景	說明
自動化影片處理	新影片上傳時自動觸發處理流程
監控告警	API Key 異常時發送通知
定時備份	定期備份 API Key 資料
跨系統同步	與其他系統同步 API Key 狀態

1.3 架構圖

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   觸發器    │────▶│   n8n 工作流 │────▶│  Momentry   │
│  (Webhook/  │     │  (處理邏輯)  │     │   API       │
│   Cron)     │     └─────────────┘     └─────────────┘
└─────────────┘            │                   │
                           │                   │
                           ▼                   ▼
                    ┌─────────────┐     ┌─────────────┐
                    │   通知      │     │   動作      │
                    │ (Slack/Email)│     │ (建立/查詢) │
                     └─────────────┘     └─────────────┘

1.4 API URL 選擇

環境	URL	說明
本地測試	`http://localhost:3002`	直接訪問 API
n8n workflow	`https://api.momentry.ddns.net`	通過反向代理

⚠️ 重要: 在 n8n HTTP Request Node 中，請使用 https://api.momentry.ddns.net 而非 localhost:3002，因為 n8n 需要從外部訪問 API。

本地測試時:

curl http://localhost:3002/health

n8n Workflow 中:

URL: https://api.momentry.ddns.net/api/v1/n8n/search

2. 前置作業

2.1 確認服務狀態

# 檢查 Momentry API
curl http://localhost:3002/health

# 檢查 n8n
curl https://n8n.momentry.ddns.net/api/v1/workflows \
  -H "X-N8N-API-KEY: your-api-key"

2.2 取得 n8n API Key

方式 A: 透過 Momentry CLI

# 建立 n8n API Key
momentry n8n create \
  --api-key "your-existing-n8n-api-key" \
  --label "momentry-integration" \
  --expires-in-days 90

# 輸出:
# ✅ n8n API Key created successfully!
# API Key: eyJhbGciOiJIUzI1NiIs...

方式 B: 透過 n8n 介面

登入 n8n: https://n8n.momentry.ddns.net
前往 Settings → n8n API
點擊「Create an API Key」
複製 API Key

2.3 設定環境變數

在 n8n 中設定以下環境變數：

變數名稱	值	說明
`MOMENTRY_API_URL`	`http://localhost:3002`	Momentry API URL
`MOMENTRY_API_KEY`	`your-api-key`	Momentry API Key

3. 建立 n8n API Key

3.1 CLI 命令

# 基本建立
momentry n8n create \
  --api-key <existing-n8n-key> \
  --label <key-name>

# 設定過期時間
momentry n8n create \
  --api-key <existing-n8n-key> \
  --label "ci-pipeline" \
  --expires-in-days 30

3.2 範例：建立監控用 Key

momentry n8n create \
  --api-key "n8n_api_1234567890" \
  --label "monitoring-key" \
  --expires-in-days 180

# 輸出:
# ✅ n8n API Key created successfully!
# Key ID: abc123-def456
# Label: monitoring-key
# API Key: eyJhbGciOiJIUz...

3.3 列出已建立的 Key

momentry n8n list --api-key <existing-n8n-key>

# 輸出:
# 📋 n8n API Keys
# ┌────────────────────────────────────────────────────────────────────────────┐
# │ Label                       │ ID                                      │
# ├────────────────────────────────────────────────────────────────────────────┤
# │ monitoring-key              │ abc123-def456                          │
# │ ci-pipeline                 │ xyz789-abc123                          │
# └────────────────────────────────────────────────────────────────────────────┘

4. 在 n8n 中使用 Momentry API

⚠️ 注意: API Key 管理端點 (/api/v1/api-keys/*) 目前仍在規劃中，尚未實作。以下為規劃中的 API 說明。

4.1 設定 HTTP Request 節點

Method: POST
URL: {{ $env.MOMENTRY_API_URL }}/api/v1/api-keys
Headers:
  X-API-Key: {{ $env.MOMENTRY_API_KEY }}
  Content-Type: application/json
Body:
  {
    "name": "auto-generated-key",
    "key_type": "service",
    "ttl_days": 90
  }

4.2 可用的 API 端點

⚠️ API Key 管理端點為規劃功能，目前尚未實作

已實作端點

方法	端點	說明
GET	`/health`	健康檢查
POST	`/api/v1/search`	語意搜尋
POST	`/api/v1/n8n/search`	n8n 格式搜尋
GET	`/api/v1/videos`	列出所有影片
GET	`/api/v1/lookup`	查詢影片
GET	`/api/v1/progress/:uuid`	處理進度

規劃中端點 (尚未實作)

方法	端點	說明
GET	`/api/v1/api-keys`	列出所有 API Keys
POST	`/api/v1/api-keys`	建立新的 API Key
DELETE	`/api/v1/api-keys/{id}`	刪除 API Key
POST	`/api/v1/api-keys/{id}/rotate`	請求 Key 輪換

5. 工作流範例

範例 1：定時檢查 API Key 狀態

目的: 每天早上 9 點檢查即將過期的 API Keys

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Schedule   │────▶│ HTTP        │────▶│ Filter      │────▶│ Slack       │
│  (每天 9AM) │     │ Request     │     │ (7天內過期) │     │ 通知        │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

HTTP Request 設定:

{
  "method": "GET",
  "url": "{{ $env.MOMENTRY_API_URL }}/api/v1/api-keys",
  "headers": {
    "X-API-Key": "{{ $env.MOMENTRY_API_KEY }}"
  }
}

Filter 設定:

// 檢查是否在 7 天內過期
const expiresAt = new Date($json.expires_at);
const now = new Date();
const sevenDaysLater = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);

return expiresAt <= sevenDaysLater && expiresAt > now;

Slack 通知格式:

⚠️ API Key 即將過期提醒

以下 API Key 將在 7 天內過期：
{{ $json.map(k => `• ${k.name} (${k.key_id}) - 過期時間: ${k.expires_at}`).join('\n') }}

請及時處理！

範例 2：新影片上傳時自動建立 API Key

目的: 當有新影片上傳時，自動為該影片建立專用 API Key

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Webhook    │────▶│ HTTP        │────▶│ Set         │────▶│ Respond     │
│  觸發器     │     │ Request     │     │ (組裝回應)  │     │ Webhook     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Webhook 設定:

Method: POST
Path: /new-video

HTTP Request 設定:

{
  "method": "POST",
  "url": "{{ $env.MOMENTRY_API_URL }}/api/v1/api-keys",
  "headers": {
    "X-API-Key": "{{ $env.MOMENTRY_API_KEY }}"
  },
  "body": {
    "name": "video-{{ $json.video_id }}",
    "key_type": "service",
    "permissions": ["read"],
    "ttl_days": 30
  }
}

回應格式:

{
  "success": true,
  "video_id": "{{ $json.video_id }}",
  "api_key_id": "{{ $json.key_id }}",
  "message": "API Key 已建立"
}

範例 3：API Key 異常告警

目的: 監控 API Key 異常使用，發送告警通知

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Webhook    │────▶│ Switch      │────▶│ Email       │     │ Slack       │
│  (異常通知) │     │ (嚴重程度)  │────▶│ 通知        │     │ 通知        │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Webhook 觸發設定 (在 Momentry 中):

export WEBHOOK_URL="https://n8n.momentry.ddns.net/webhook/anomaly-alert"
export WEBHOOK_EVENTS="anomaly_detected,rate_limited,ip_blocked"

Switch 節點設定:

// 根據嚴重程度分流
switch ($json.data.severity) {
  case 'critical':
    return 0;  // Email + Slack
  case 'high':
    return 1;  // Slack only
  default:
    return 2;  // Log only
}

Email 通知格式:

Subject: [{{ $json.data.severity }}] API Key 異常告警 - {{ $json.data.key_id }}

Dear Admin,

偵測到 API Key 異常使用：

Key ID: {{ $json.data.key_id }}
異常類型: {{ $json.data.anomaly_type }}
嚴重程度: {{ $json.data.severity }}
時間: {{ $json.timestamp }}

請立即檢查系統狀態。

Best regards,
Momentry Monitoring

範例 4：定時備份 API Key 統計

目的: 每週一早上備份 API Key 統計報表

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Schedule   │────▶│ HTTP        │────▶│ Google      │
│  (每週一)   │     │ Request     │     │ Sheets      │
└─────────────┘     └─────────────┘     └─────────────┘

HTTP Request 設定:

{
  "method": "GET",
  "url": "{{ $env.MOMENTRY_API_URL }}/api/v1/api-keys/stats",
  "headers": {
    "X-API-Key": "{{ $env.MOMENTRY_API_KEY }}"
  }
}

Google Sheets 設定:

Spreadsheet: Momentry API Key Reports
Sheet: Weekly Stats
Append Row:
  - Date: {{ $now }}
  - Total Keys: {{ $json.total_keys }}
  - Active Keys: {{ $json.active_keys }}
  - Expired Keys: {{ $json.expired_keys }}
  - Anomalies (24h): {{ $json.anomalies_last_24h }}

範例 5：自動輪換即將過期的 Key

目的: 自動為即將過期的 Key 請求輪換

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Schedule   │────▶│ HTTP        │────▶│ Filter      │────▶│ HTTP        │
│  (每天)     │     │ (取得 Keys) │     │ (即將過期)  │     │ (請求輪換)  │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

第一個 HTTP Request (取得 Keys):

{
  "method": "GET",
  "url": "{{ $env.MOMENTRY_API_URL }}/api/v1/api-keys",
  "headers": {
    "X-API-Key": "{{ $env.MOMENTRY_API_KEY }}"
  }
}

Filter 設定:

// 14 天內過期且未請求輪換的 Key
const expiresAt = new Date($json.expires_at);
const now = new Date();
const fourteenDaysLater = new Date(now.getTime() + 14 * 24 * 60 * 60 * 1000);

return expiresAt <= fourteenDaysLater && 
       !$json.rotation_required &&
       $json.status === 'active';

第二個 HTTP Request (請求輪換):

{
  "method": "POST",
  "url": "{{ $env.MOMENTRY_API_URL }}/api/v1/api-keys/{{ $json.key_id }}/rotate",
  "headers": {
    "X-API-Key": "{{ $env.MOMENTRY_API_KEY }}"
  },
  "body": {
    "reason": "auto_rotation_approaching_expiry"
  }
}

6. 常見問題

Q1: n8n 無法連接到 Momentry API

檢查項目:

# 1. 確認 API 是否運行
curl http://localhost:3002/health

# 2. 確認 API Key 是否有效
momentry api-key validate --key "your-key"

# 3. 檢查防火牆設定
nc -zv localhost 3002

Q2: API Key 建立失敗

可能原因:

API Key 已存在
權限不足
格式錯誤

解決方式:

# 檢查現有 Keys
momentry api-key list

# 使用不同的 label
momentry n8n create --api-key "..." --label "unique-label-$(date +%s)"

Q3: Webhook 通知沒有收到

檢查項目:

# 1. 確認 Webhook URL 設定
echo $WEBHOOK_URL

# 2. 測試 Webhook
curl -X POST $WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# 3. 檢查 n8n 工作流是否啟用
# 登入 n8n → 檢查工作流狀態

Q4: 如何撤銷 n8n API Key

# 列出所有 Keys
momentry n8n list --api-key "your-admin-key"

# 刪除指定 Key
momentry n8n delete \
  --api-key "your-admin-key" \
  --label "key-to-delete"

附錄

A. n8n 工作流匯出

將上述範例工作流匯入 n8n：

複製工作流 JSON
登入 n8n
點擊「+」→「Import from File」
貼上 JSON 並儲存

B. 環境變數總覽

# Momentry
MOMENTRY_API_URL=http://localhost:3002
MOMENTRY_API_KEY=your-api-key

# n8n
N8N_URL=https://n8n.momentry.ddns.net
N8N_API_KEY=your-n8n-api-key

# Webhook
WEBHOOK_URL=https://n8n.momentry.ddns.net/webhook/alerts
WEBHOOK_SECRET=your-secret
WEBHOOK_EVENTS=anomaly_detected,key_expired,key_revoked

C. 相關文件

文件	說明
API_INDEX.md	文件總覽（起點）
API_N8N_GUIDE.md	n8n 快速使用指南
`docs/API_KEY_MANAGEMENT.md`	API Key 管理系統設計
`docs/API_KEY_ARCHITECTURE.md`	系統架構圖
`docs/API_KEY_INTEGRATION_TESTS.md`	整合測試文件

15 KiB Raw Blame History Unescape Escape

Momentry n8n 整合使用手冊

版本歷史

目錄

1. 概述

1.1 什麼是 n8n？

1.2 為什麼需要整合？

1.3 架構圖

1.4 API URL 選擇

2. 前置作業

2.1 確認服務狀態

2.2 取得 n8n API Key

方式 A: 透過 Momentry CLI

方式 B: 透過 n8n 介面

2.3 設定環境變數

3. 建立 n8n API Key

3.1 CLI 命令

3.2 範例：建立監控用 Key

3.3 列出已建立的 Key

4. 在 n8n 中使用 Momentry API

4.1 設定 HTTP Request 節點

4.2 可用的 API 端點

已實作端點

規劃中端點 (尚未實作)

5. 工作流範例

範例 1：定時檢查 API Key 狀態

範例 2：新影片上傳時自動建立 API Key

範例 3：API Key 異常告警

範例 4：定時備份 API Key 統計

範例 5：自動輪換即將過期的 Key

6. 常見問題

Q1: n8n 無法連接到 Momentry API

Q2: API Key 建立失敗

Q3: Webhook 通知沒有收到

Q4: 如何撤銷 n8n API Key

附錄

A. n8n 工作流匯出

B. 環境變數總覽

C. 相關文件

15 KiB

Raw Blame History