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
451 lines
10 KiB
Markdown
451 lines
10 KiB
Markdown
# Node.js 開發指南
|
||
|
||
| 項目 | 內容 |
|
||
|------|------|
|
||
| 建立者 | Warren |
|
||
| 建立時間 | 2026-03-16 |
|
||
| 文件版本 | V1.0 |
|
||
|
||
---
|
||
|
||
## 版本歷史
|
||
|
||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||
|------|------|------|--------|-----------|
|
||
| V1.0 | 2026-03-16 | 創建文件 | Warren | OpenCode / MiniMax M2.5 |
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
本文檔說明 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
|
||
|
||
```bash
|
||
# 安裝 Node.js 22.x (LTS)
|
||
brew install node@22
|
||
|
||
# 驗證安裝
|
||
/opt/homebrew/opt/node@22/bin/node --version
|
||
# v22.22.1
|
||
```
|
||
|
||
### 安裝全局工具
|
||
|
||
```bash
|
||
# 使用 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：直接使用完整路徑
|
||
|
||
```bash
|
||
# 使用 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) 中加入：
|
||
|
||
```bash
|
||
# 優先使用 node@22
|
||
export PATH="/opt/homebrew/opt/node@22/bin:$PATH"
|
||
|
||
# 重新載入
|
||
source ~/.zshrc
|
||
|
||
# 驗證
|
||
node --version
|
||
# v22.22.1
|
||
```
|
||
|
||
### 方式 3：使用 nvm (推薦)
|
||
|
||
```bash
|
||
# 安裝 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 或啟動腳本中設定：
|
||
|
||
```xml
|
||
<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 版本檢查：
|
||
|
||
```bash
|
||
# 檢查 n8n 進程是否使用正確的 Node.js 版本
|
||
check_node() {
|
||
local LOCKED_NODE_VERSION="22"
|
||
# ...
|
||
}
|
||
```
|
||
|
||
### 執行監控
|
||
|
||
```bash
|
||
# 單獨檢查 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
|
||
```
|
||
|
||
### 查看版本狀態
|
||
|
||
```bash
|
||
# 查詢資料庫中的版本記錄
|
||
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/5679 | ✅ 執行中 | 工作流自動化平台 |
|
||
| markdownlint-cli | 25.x | /opt/homebrew/bin/npm | - | ✅ 已安裝 | Markdown lint 工具 |
|
||
| - | - | - | - | - | 新增應用請填入此表 |
|
||
|
||
---
|
||
|
||
## 新增 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. **確認版本需求**
|
||
```bash
|
||
# 查看應用支援的 Node.js 版本
|
||
# 通常在 package.json 或官方文件中說明
|
||
```
|
||
|
||
2. **選擇現有版本或安裝新版本**
|
||
- 若支援 22.x → 使用 node@22
|
||
- 若需要特定版本 → 使用完整路徑隔離
|
||
|
||
3. **安裝新版本 (如需要)**
|
||
```bash
|
||
# 安裝特定版本
|
||
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 |
|
||
|
||
### 診斷命令
|
||
|
||
```bash
|
||
# 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. 重載服務：
|
||
```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
|
||
```
|
||
|
||
### 問題：Task Runner 使用錯誤版本
|
||
|
||
**原因**：PATH 環境變數設定不正確
|
||
|
||
**診斷**：
|
||
```bash
|
||
# 查看 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 版本安裝
|
||
|
||
**解決方案**：
|
||
```bash
|
||
# 確認使用的是哪個 node
|
||
which node
|
||
node --version
|
||
|
||
# 使用正確版本重新安裝
|
||
/opt/homebrew/opt/node@22/bin/npm install -g <package>
|
||
```
|
||
|
||
---
|
||
|
||
## 版本切換腳本
|
||
|
||
建立快速切換腳本 `~/bin/switch-node.sh`：
|
||
|
||
```bash
|
||
#!/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
|
||
```
|
||
|
||
賦予執行權限：
|
||
```bash
|
||
chmod +x ~/bin/switch-node.sh
|
||
```
|
||
|
||
使用方式：
|
||
```bash
|
||
~/bin/switch-node.sh 22 # 切換到 22.x
|
||
~/bin/switch-node.sh system # 切換到系統預設
|
||
```
|
||
|
||
---
|
||
|
||
## 常用指令
|
||
|
||
```bash
|
||
# 查看 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 | 開機啟動 |
|
||
|
||
---
|
||
|
||
## 版本速查
|
||
|
||
| 版本 | 用途 | 路徑 |
|
||
|------|------|------|
|
||
| 22.22.1 | n8n 專用 | /opt/homebrew/opt/node@22/bin/node |
|
||
| 25.x | 系統預設 | /opt/homebrew/bin/node |
|
||
|
||
---
|
||
|
||
## 相關文件
|
||
|
||
- [INSTALL_N8N.md](./INSTALL_N8N.md) - n8n 安裝指南 (包含 Node.js 配置範例)
|
||
- [RUST_DEVELOPMENT.md](./RUST_DEVELOPMENT.md) - Rust 開發規範
|
||
- [monitor_config.yaml](../monitor/config/monitor_config.yaml) - 監控配置
|
||
- [node_monitor.sh](../monitor/service/node_monitor.sh) - Node.js 監控腳本
|