momentry_core_0_1/docs/NODEJS.md

Node.js 開發指南

概述

本文檔說明 Momentry 專案中 Node.js 環境的配置、管理與監控。

---

當前狀態

項目	狀態
系統預設 Node.js	v25.8.1
鎖定 Node.js (n8n)	v22.22.1
n8n 版本	v2.3.5
npm 路徑 (預設)	/opt/homebrew/bin/npm
node 路徑 (預設)	/opt/homebrew/bin/node
node@22 路徑	/opt/homebrew/opt/node@22/bin/node

---

版本策略

為什麼需要版本鎖定？

n8n 要求 Node.js 版本為 22.x LTS。系統預設的 Node.js 25.x 會導致：

• n8n 啟動警告
• Task-runner 執行錯誤
• 相容性問題

版本對照表

用途	Node.js 版本	路徑
系統預設	25.8.1	/opt/homebrew/bin/node
n8n 專用	22.22.1	/opt/homebrew/opt/node@22/bin/node
開發測試	22.x	/opt/homebrew/opt/node@22/bin/node

---

安裝步驟

安裝特定版本 Node.js

# 安裝 Node.js 22.x (LTS)
brew install node@22

# 驗證安裝
/opt/homebrew/opt/node@22/bin/node --version
# v22.22.1

安裝全局工具

# 使用 node@22 安裝全局工具
/opt/homebrew/opt/node@22/bin/npm install -g <package-name>

# 例如安裝 n8n
/opt/homebrew/opt/node@22/bin/npm install -g n8n

---

使用方式

方式 1：直接使用完整路徑

# 使用 node@22
/opt/homebrew/opt/node@22/bin/node script.js

# 使用 npm@22
/opt/homebrew/opt/node@22/bin/npm install

方式 2：修改 PATH 環境變數

在 shell 配置檔案 (~/.zshrc) 中加入：

# 優先使用 node@22
export PATH="/opt/homebrew/opt/node@22/bin:$PATH"

# 重新載入
source ~/.zshrc

# 驗證
node --version
# v22.22.1

方式 3：使用 nvm (推薦)

# 安裝 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安裝 Node.js 22.x
nvm install 22
nvm use 22

# 設定預設版本
nvm alias default 22

---

n8n 配置

環境變數設定

在 plist 或啟動腳本中設定：

<key>ProgramArguments</key>
<array>
    <string>/opt/homebrew/opt/node@22/bin/node</string>
    <string>/opt/homebrew/lib/node_modules/n8n/bin/n8n</string>
    <string>start</string>
</array>

<key>EnvironmentVariables</key>
<dict>
    <key>PATH</key>
    <string>/opt/homebrew/opt/node@22/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
</dict>

Task Runner 配置

n8n Task Runner 用於執行 Code node 中的 JavaScript 代碼。

確保 PATH 中 node@22 在前面，這樣 task-runner 子進程會使用正確版本。

---

監控配置

健康檢查

monitor/service/health_check.sh 已包含 Node.js 版本檢查：

# 檢查 n8n 進程是否使用正確的 Node.js 版本
check_node() {
    local LOCKED_NODE_VERSION="22"
    # ...
}

執行監控

# 單獨檢查 Node.js
bash /Users/accusys/momentry_core_0.1/monitor/control/monitor_control.sh check node

# 檢查 Python
bash /Users/accusys/momentry_core_0.1/monitor/control/monitor_control.sh check python

查看版本狀態

# 查詢資料庫中的版本記錄
psql -U accusys -h localhost -d momentry -c "SELECT * FROM node_version_baseline;"

---

應用Registry

記錄系統中所有使用 Node.js 的應用程式。

應用	Node.js 版本	執行路徑	Port	狀態	說明
n8n	22.22.1	/opt/homebrew/opt/node@22/bin/node	5678/5690	✅ 執行中	工作流自動化平台
-	-	-	-	-	新增應用請填入此表

---

新增 Node.js 應用決策

決策樹

新應用需要 Node.js?
    │
    ├─ 支援 Node.js 22.x ────→ 使用現有 node@22
    │                              (路徑: /opt/homebrew/opt/node@22/bin/node)
    │
    ├─ 需要特定版本 (如 18.x, 20.x) ────→ 安裝新版本 node@XX
    │                                          │
    │                                          ├─ 建立獨立目錄: /opt/homebrew/opt/node@XX/
    │                                          ├─ 更新本文檔 Registry
    │                                          └─ 建立獨立 plist 使用完整路徑
    │
    └─ 需要最新版本 ────→ 使用系統預設 node@25
                              (路徑: /opt/homebrew/bin/node)

步驟清單

1. 確認版本需求

   # 查看應用支援的 Node.js 版本
   # 通常在 package.json 或官方文件中說明
   

2. 選擇現有版本或安裝新版本

   • 若支援 22.x → 使用 node@22
   • 若需要特定版本 → 使用完整路徑隔離

3. 安裝新版本 (如需要)

   # 安裝特定版本
   brew install node@20
   # 或
   brew install node@18
   
   # 驗證安裝
   /opt/homebrew/opt/node@20/bin/node --version
   

4. 建立隔離的服務配置

   • 使用完整路徑，不要依賴 PATH
   • plist 中明确指定 node 路徑
   • 設定獨立的環境變數

5. 更新文件

   • 更新本文檔 Registry 表格
   • 新增應用的安裝文檔
   • 更新監控配置

隔離原則

原則	說明
完整路徑	使用 /opt/homebrew/opt/node@XX/bin/node 而非 node
獨立 PATH	plist 中設定隔離的 PATH 環境變數
獨立目錄	不同版本的 node 安裝在各自目錄
獨立全局套件	每個版本有自己的 node_modules

---

版本衝突處理

常見衝突場景

場景	原因	解決方案
n8n 顯示版本警告	使用 Node.js 25.x 啟動	確認 plist 使用 node@22 路徑
task-runner 執行錯誤	子進程繼承錯誤版本	在 plist 中設定正確的 PATH
全域套件找不到	跨版本安裝	使用正確版本的 npm
Port 被佔用	多個應用使用相同 Port	分配獨立 Port

診斷命令

# 1. 查看程序使用的 node 版本
ps aux | grep node

# 2. 查看程序 PID 使用的執行檔
lsof -p <PID> | grep bin/node

# 3. 確認路徑優先順序
echo $PATH

# 4. 查看 launchctl 服務的環境變數
sudo launchctl list | grep <service-name>

# 5. 檢查 Port 佔用
lsof -i :<port-number>

預防措施

1. 每次新增服務都更新 Registry
2. 使用完整路徑而非 PATH
3. 建立服務時指定版本
4. 定期檢查執行中的程序

---

故障排除

問題：n8n 顯示 Node.js 版本警告

原因：n8n 檢測到 Node.js 版本不是 22.x

解決方案：

1. 確認 plist 中 ProgramArguments 使用正確路徑
2. 確認 PATH 環境變數中 node@22 在前面
3. 重載服務：

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

問題：Task Runner 使用錯誤版本

原因：PATH 環境變數設定不正確

診斷：

# 查看 task-runner 進程使用的 node
ps aux | grep "task-runner"
lsof -p <PID> | grep "txt" | grep node

解決方案： 更新 plist 中的 PATH，確保 /opt/homebrew/opt/node@22/bin 在最前面。

問題：npm 全域套件找不到

原因：使用錯誤的 node 版本安裝

解決方案：

# 確認使用的是哪個 node
which node
node --version

# 使用正確版本重新安裝
/opt/homebrew/opt/node@22/bin/npm install -g <package>

---

版本切換腳本

建立快速切換腳本 ~/bin/switch-node.sh：

#!/bin/bash

VERSION=$1

case $VERSION in
    22)
        export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
        echo "切換到 Node.js 22.x"
        ;;
    system|25)
        export PATH="/opt/homebrew/bin:$PATH"
        echo "切換到系統 Node.js 25.x"
        ;;
    *)
        echo "用法: $0 {22|system}"
        echo "  22    - Node.js 22.x (n8n)"
        echo "  system - Node.js 25.x (系統預設)"
        exit 1
        ;;
esac

node --version

賦予執行權限：

chmod +x ~/bin/switch-node.sh

使用方式：

~/bin/switch-node.sh 22      # 切換到 22.x
~/bin/switch-node.sh system  # 切換到系統預設

---

常用指令

# 查看 node 版本
node --version

# 查看 npm 版本
npm --version

# 查看 node 安裝位置
which node

# 查看 node@22 版本
/opt/homebrew/opt/node@22/bin/node --version

# 安裝全域套件 (使用 node@22)
/opt/homebrew/opt/node@22/bin/npm install -g n8n

# 檢查 n8n 進程
ps aux | grep n8n | grep -v grep

# 檢查 task-runner
ps aux | grep task-runner | grep -v grep

# 查看 task-runner 使用的 node 版本
lsof -p <PID> | grep "txt" | grep node

---

檔案位置

類型	路徑	說明
node (系統)	/opt/homebrew/bin/node	預設 node
node@22	/opt/homebrew/opt/node@22/bin/node	n8n 專用
npm (系統)	/opt/homebrew/bin/npm	預設 npm
npm@22	/opt/homebrew/opt/node@22/bin/npm	n8n 專用
n8n 安裝	/opt/homebrew/lib/node_modules/n8n/	n8n 目錄
n8n main plist	/Library/LaunchDaemons/com.momentry.n8n.main.plist	開機啟動
n8n worker plist	/Library/LaunchDaemons/com.momentry.n8n.worker.plist	開機啟動

---

相關文件

• INSTALL_N8N.md - n8n 安裝指南 (包含 Node.js 配置範例)
• monitor_config.yaml - 監控配置
• node_monitor.sh - Node.js 監控腳本