383201cacd
## 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
490 lines
11 KiB
Markdown
490 lines
11 KiB
Markdown
# n8n 安裝指南 (本地部署)
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 建立者 | Warren |
|
||
| 建立時間 | 2026-03-16 |
|
||
| 文件版本 | V1.0 |
|
||
|
||
---
|
||
|
||
## 版本歷史
|
||
|
||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||
|------|------|------|--------|-----------|
|
||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本文檔說明如何在 macOS 上安裝 n8n 工作流自動化平台，配置為本地部署，使用 Queue 模式。
|
||
|
||
---
|
||
|
||
## 當前狀態
|
||
|
||
| 項目 | 狀態 |
|
||
|------|------|
|
||
| n8n | ✅ 已安裝 v2.12.3 |
|
||
| 數據目錄 | /Users/accusys/momentry/var/n8n/ |
|
||
| 日誌目錄 | /Users/accusys/momentry/log/ |
|
||
| Main Plist | /Library/LaunchDaemons/com.momentry.n8n.main.plist |
|
||
| Worker Plist | /Library/LaunchDaemons/com.momentry.n8n.worker.plist |
|
||
| 數據庫 | PostgreSQL (n8n) |
|
||
| 隊列 | Redis |
|
||
| Launchd 狀態 | ✅ Main + Worker 已註冊 |
|
||
| RunAtLoad | ✅ 已設定 |
|
||
| KeepAlive | ✅ 已設定 |
|
||
|
||
### 重要更新 (2026-03-24)
|
||
|
||
1. **n8n Main + Worker**: 兩個服務都使用自定義 plist
|
||
2. **Runner 禁用**: 為避免端口衝突，Main 服務設定 `N8N_RUNNERS_ENABLED=false`
|
||
3. **Worker 端口**: Worker 使用 5681, 5682, 5690, 5691 端口
|
||
|
||
---
|
||
|
||
## 安裝步驟
|
||
|
||
### Step 1: 安裝 n8n (使用 brew)
|
||
|
||
```bash
|
||
# 安裝 n8n
|
||
brew install n8n
|
||
```
|
||
|
||
**驗證**:
|
||
```bash
|
||
n8n --version
|
||
# 2.12.3
|
||
```
|
||
|
||
---
|
||
|
||
### Step 2: 建立目錄
|
||
|
||
```bash
|
||
# 建立數據目錄
|
||
mkdir -p /Users/accusys/momentry/var/n8n
|
||
|
||
# 建立配置目錄
|
||
mkdir -p /Users/accusys/momentry/etc/n8n
|
||
|
||
# 建立日誌目錄
|
||
mkdir -p /Users/accusys/momentry/log
|
||
|
||
# 建立日誌文件
|
||
touch /Users/accusys/momentry/log/n8n.main.log
|
||
touch /Users/accusys/momentry/log/n8n.main.error.log
|
||
touch /Users/accusys/momentry/log/n8n.worker.log
|
||
touch /Users/accusys/momentry/log/n8n.worker.error.log
|
||
|
||
# 設定權限
|
||
chown -R accusys:staff /Users/accusys/momentry/var/n8n
|
||
chown -R accusys:staff /Users/accusys/momentry/etc/n8n
|
||
chown -R accusys:staff /Users/accusys/momentry/log
|
||
```
|
||
|
||
---
|
||
|
||
### Step 3: 數據遷移 (如果從舊位置遷移)
|
||
|
||
```bash
|
||
# 停止舊服務
|
||
sudo launchctl unload /Library/LaunchDaemons/com.n8n.main.plist
|
||
sudo launchctl unload /Library/LaunchDaemons/com.n8n.worker.plist
|
||
|
||
# 複製數據
|
||
cp -r /Users/accusys/.n8n/* /Users/accusys/momentry/var/n8n/
|
||
|
||
# 設定權限
|
||
chown -R accusys:staff /Users/accusys/momentry/var/n8n
|
||
```
|
||
|
||
---
|
||
|
||
### Step 4: 使用 plist 開機自動啟動
|
||
|
||
```bash
|
||
# 複製 plist 到 LaunchDaemons 目錄
|
||
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.n8n.main.plist /Library/LaunchDaemons/
|
||
sudo cp /Users/accusys/momentry_core_0.1/momentry_runtime/plist/com.momentry.n8n.worker.plist /Library/LaunchDaemons/
|
||
|
||
# 移除舊 plist (如果存在)
|
||
sudo launchctl unload /Library/LaunchDaemons/com.n8n.main.plist 2>/dev/null
|
||
sudo launchctl unload /Library/LaunchDaemons/com.n8n.worker.plist 2>/dev/null
|
||
sudo rm /Library/LaunchDaemons/com.n8n.main.plist 2>/dev/null
|
||
sudo rm /Library/LaunchDaemons/com.n8n.worker.plist 2>/dev/null
|
||
|
||
# 載入並啟動
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
```
|
||
|
||
---
|
||
|
||
## 監控配置
|
||
|
||
### 添加到監控配置
|
||
|
||
在 `monitor/config/monitor_config.yaml` 中添加：
|
||
|
||
```yaml
|
||
service:
|
||
services:
|
||
- name: "n8n"
|
||
type: "http"
|
||
port: 5678
|
||
host: "localhost"
|
||
check_url: "http://localhost:5678/"
|
||
timeout: 5
|
||
enabled: true
|
||
```
|
||
|
||
### 添加健康檢查函數
|
||
|
||
在 `monitor/service/health_check.sh` 中添加：
|
||
|
||
```bash
|
||
check_n8n() {
|
||
local start=$(date +%s%N)
|
||
if curl -s http://localhost:5678/ > /dev/null 2>&1; then
|
||
local end=$(date +%s%N)
|
||
local ms=$(( (end - start) / 1000000 ))
|
||
echo -e "${GREEN}✓${NC} n8n (5678) - ${ms}ms"
|
||
record_service "n8n" "up" "$ms" ""
|
||
return 0
|
||
else
|
||
echo -e "${RED}✗${NC} n8n (5678) - Down"
|
||
record_service "n8n" "down" "0" "Connection failed"
|
||
return 1
|
||
fi
|
||
}
|
||
```
|
||
|
||
### n8n Workflow 監控
|
||
|
||
n8n 有專門的工作流監控腳本，請參考 `monitor/workflow/n8n_workflow_monitor.sh`。
|
||
|
||
---
|
||
|
||
## 卸載步驟
|
||
|
||
### 重要: 路徑說明
|
||
|
||
| 路徑 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `/Users/accusys/momentry/var/n8n/` | 數據 | **不要刪除** - n8n 數據 |
|
||
| `/Users/accusys/momentry/etc/n8n/` | 配置 | **不要刪除** - n8n 配置 |
|
||
| `/Users/accusys/momentry/log/` | 日誌 | **不要刪除** - n8n 日誌 |
|
||
| `/opt/homebrew/lib/node_modules/n8n/` | 安裝 | **刪除** - n8n 安裝目錄 |
|
||
|
||
### Step 1: 停止 n8n
|
||
|
||
```bash
|
||
# 停止 n8n 服務
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
|
||
# 確認停止
|
||
ps aux | grep n8n | grep -v grep || echo "n8n 已停止"
|
||
```
|
||
|
||
---
|
||
|
||
### Step 2: 卸載 n8n
|
||
|
||
```bash
|
||
# 卸載 n8n
|
||
brew uninstall n8n
|
||
|
||
# 移除 plist
|
||
sudo rm /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo rm /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
```
|
||
|
||
---
|
||
|
||
### Step 3: 刪除專屬檔案
|
||
|
||
```bash
|
||
# 刪除數據目錄 (可選)
|
||
rm -rf /Users/accusys/momentry/var/n8n
|
||
|
||
# 刪除日誌 (可選)
|
||
rm -f /Users/accusys/momentry/log/n8n-*.log
|
||
```
|
||
|
||
**注意: 不要刪除以下共用目錄**:
|
||
```bash
|
||
# 這些是共用的，不要刪除!
|
||
# /Users/accusys/momentry/var
|
||
# /Users/accusys/momentry/log
|
||
# PostgreSQL n8n 數據庫 (如需保留)
|
||
```
|
||
|
||
---
|
||
|
||
### Step 4: 卸載後檢查清單
|
||
|
||
```bash
|
||
echo "=== n8n 卸載後檢查 ==="
|
||
|
||
# 1. 檢查 n8n 進程
|
||
echo "1. n8n Main 進程:"
|
||
ps aux | grep "n8n.*start" | grep -v grep && echo " ✗ 仍在運行" || echo " ✓ 已停止"
|
||
|
||
echo "2. n8n Worker 進程:"
|
||
ps aux | grep "n8n.*worker" | grep -v grep && echo " ✗ 仍在運行" || echo " ✓ 已停止"
|
||
|
||
# 2. Port 8085
|
||
echo "3. Port 8085:"
|
||
lsof -i :8085 > /dev/null 2>&1 && echo " ✗ 仍被佔用" || echo " ✓ 已釋放"
|
||
|
||
# 3. Port 5679 (Worker)
|
||
echo "4. Port 5679 (Worker):"
|
||
lsof -i :5679 > /dev/null 2>&1 && echo " ✗ 仍被佔用" || echo " ✓ 已釋放"
|
||
|
||
# 4. n8n 命令
|
||
echo "5. n8n 命令:"
|
||
which n8n > /dev/null 2>&1 && echo " ✗ 仍存在" || echo " ✓ 已移除"
|
||
|
||
# 5. brew 安裝
|
||
echo "6. brew 安裝:"
|
||
brew list n8n > /dev/null 2>&1 && echo " ✗ 仍存在" || echo " ✓ 已移除"
|
||
|
||
# 6. launchctl 服務
|
||
echo "7. launchctl 服務:"
|
||
sudo launchctl list | grep n8n > /dev/null 2>&1 && echo " ✗ 仍存在" || echo " ✓ 已移除"
|
||
```
|
||
|
||
---
|
||
|
||
## 備份步驟
|
||
|
||
### 備份 n8n 數據
|
||
|
||
```bash
|
||
# 建立備份目錄
|
||
mkdir -p /Users/accusys/momentry/var/n8n_backup
|
||
|
||
# 1. 備份 PostgreSQL 數據庫
|
||
PGPASSWORD=accusys pg_dump -U accusys -d n8n > /Users/accusys/momentry/var/n8n_backup/n8n_database_$(date +%Y%m%d).sql
|
||
|
||
# 2. 備份用戶數據夾
|
||
cp -r /Users/accusys/momentry/var/n8n /Users/accusys/momentry/var/n8n_backup/
|
||
|
||
# 3. 壓縮備份
|
||
cd /Users/accusys/momentry/var && tar -czvf n8n_backup_$(date +%Y%m%d).tar.gz n8n_backup/
|
||
|
||
# 4. 清理臨時備份
|
||
rm -rf /Users/accusys/momentry/var/n8n_backup
|
||
```
|
||
|
||
### 還原數據
|
||
|
||
```bash
|
||
# 1. 停止 n8n
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
|
||
# 2. 還原 PostgreSQL 數據庫
|
||
PGPASSWORD=accusys psql -U accusys -d n8n < /Users/accusys/momentry/var/n8n_backup/n8n_database_20260314.sql
|
||
|
||
# 3. 還原用戶數據夾
|
||
rm -rf /Users/accusys/momentry/var/n8n
|
||
cp -r /Users/accusys/momentry/var/n8n_backup/n8n /Users/accusys/momentry/var/n8n
|
||
chown -R accusys:staff /Users/accusys/momentry/var/n8n
|
||
|
||
# 4. 啟動 n8n
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
```
|
||
|
||
---
|
||
|
||
## 手動檢查命令
|
||
|
||
```bash
|
||
# 1. 檢查進程
|
||
ps aux | grep n8n | grep -v grep
|
||
|
||
# 2. 檢查 Port
|
||
lsof -i :5678
|
||
lsof -i :5679
|
||
|
||
# 3. 測試連線
|
||
curl http://localhost:5678/
|
||
|
||
# 4. 查看版本
|
||
n8n --version
|
||
|
||
# 5. 查看日誌
|
||
tail -20 /Users/accusys/momentry/log/n8n-main.log
|
||
tail -20 /Users/accusys/momentry/log/n8n-worker.log
|
||
|
||
# 6. 查看錯誤日誌
|
||
tail -20 /Users/accusys/momentry/log/n8n-main.error.log
|
||
tail -20 /Users/accusys/momentry/log/n8n-worker.error.log
|
||
|
||
# 7. 檢查 launchctl 狀態
|
||
sudo launchctl list | grep n8n
|
||
```
|
||
|
||
---
|
||
|
||
## 連線資訊
|
||
|
||
| 項目 | 值 |
|
||
|------|-----|
|
||
| URL | http://localhost:5678 |
|
||
| Domain | n8n.momentry.ddns.net |
|
||
| 數據庫 | PostgreSQL (n8n) |
|
||
| 隊列 | Redis |
|
||
| Encryption Key | Test3200Test3200Test3200 |
|
||
|
||
### Queue 模式端口
|
||
|
||
| 服務 | Port |
|
||
|------|------|
|
||
| Main | 5678 |
|
||
| Task Broker (Worker 連接) | 5679 |
|
||
|
||
---
|
||
|
||
## 環境變數
|
||
|
||
在 `.env` 中:
|
||
|
||
```env
|
||
N8N_URL=http://localhost:5678
|
||
N8N_USER_FOLDER=/Users/accusys/momentry/var/n8n
|
||
```
|
||
|
||
---
|
||
|
||
## 故障排除
|
||
|
||
### n8n 無法啟動
|
||
|
||
```bash
|
||
# 檢查日誌
|
||
tail -f /Users/accusys/momentry/log/n8n-main.log
|
||
tail -f /Users/accusys/momentry/log/n8n-worker.log
|
||
|
||
# 檢查環境變數
|
||
launchctl list | grep n8n
|
||
|
||
# 檢查數據庫連線
|
||
PGPASSWORD=accusys psql -U accusys -d n8n -c "SELECT 1"
|
||
|
||
# 檢查 Redis 連線
|
||
redis-cli -a accusys ping
|
||
```
|
||
|
||
### Port 被佔用
|
||
|
||
```bash
|
||
# 檢查哪個程序佔用 port
|
||
lsof -i :8085
|
||
|
||
# 終止佔用程序
|
||
kill <PID>
|
||
```
|
||
|
||
### 數據庫連線失敗
|
||
|
||
```bash
|
||
# 檢查 PostgreSQL
|
||
pg_isready -h 127.0.0.1 -p 5432 -U n8n
|
||
|
||
# 測試連線
|
||
PGPASSWORD=accusys psql -h 127.0.0.1 -U n8n -d n8n -c "SELECT version();"
|
||
```
|
||
|
||
### 需要重新載入 plist
|
||
|
||
```bash
|
||
# 卸載舊服務
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
|
||
# 載入新服務
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.worker.plist
|
||
```
|
||
|
||
---
|
||
|
||
## 檔案位置
|
||
|
||
| 類型 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| 安裝 | `/opt/homebrew/lib/node_modules/n8n/` | n8n 安裝目錄 |
|
||
| 執行檔 | `/opt/homebrew/bin/n8n` | n8n 執行檔 |
|
||
| 數據目錄 | `/Users/accusys/momentry/var/n8n/` | 數據儲存 |
|
||
| 配置目錄 | `/Users/accusys/momentry/etc/n8n/` | 配置儲存 |
|
||
| Main 日誌 | `/Users/accusys/momentry/log/n8n.main.log` | 主服務日誌 |
|
||
| Main 錯誤日誌 | `/Users/accusys/momentry/log/n8n.main.error.log` | 主服務錯誤日誌 |
|
||
| Worker 日誌 | `/Users/accusys/momentry/log/n8n.worker.log` | Worker 日誌 |
|
||
| Worker 錯誤日誌 | `/Users/accusys/momentry/log/n8n.worker.error.log` | Worker 錯誤日誌 |
|
||
| Main Plist | `/Library/LaunchDaemons/com.momentry.n8n.main.plist` | 主服務開機啟動 |
|
||
| Worker Plist | `/Library/LaunchDaemons/com.momentry.n8n.worker.plist` | Worker 開機啟動 |
|
||
| 備份 | `/Users/accusys/momentry/var/n8n_backup/` | 數據備份 |
|
||
|
||
---
|
||
|
||
## 數據庫資訊
|
||
|
||
n8n 使用 PostgreSQL 作為數據庫:
|
||
|
||
| 項目 | 值 |
|
||
|------|-----|
|
||
| Database | n8n |
|
||
| User | n8n |
|
||
| Host | 127.0.0.1:5432 |
|
||
| Password | accusys |
|
||
|
||
### Redis 隊列資訊
|
||
|
||
| 項目 | 值 |
|
||
|------|-----|
|
||
| Host | 127.0.0.1:6379 |
|
||
| Password | accusys |
|
||
| Mode | Queue (Bull) |
|
||
|
||
---
|
||
|
||
## 常用指令
|
||
|
||
```bash
|
||
# 啟動 n8n Main
|
||
n8n start
|
||
|
||
# 啟動 n8n Worker
|
||
n8n worker
|
||
|
||
# 查看版本
|
||
n8n --version
|
||
|
||
# 備份數據
|
||
PGPASSWORD=accusys pg_dump -U accusys -d n8n > n8n_backup.sql
|
||
|
||
# 重新載入服務
|
||
sudo launchctl unload /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
sudo launchctl load /Library/LaunchDaemons/com.momentry.n8n.main.plist
|
||
```
|
||
|
||
---
|
||
|
||
## 版本資訊
|
||
|
||
- 版本: 2.3.5
|
||
- Main Port: 5678
|
||
- Task Broker (Worker): 5679
|
||
- 數據目錄: /Users/accusys/momentry/var/n8n/
|
||
- 日誌目錄: /Users/accusys/momentry/log/
|
||
- 數據庫: PostgreSQL n8n
|
||
- 隊列: Redis
|