# 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

```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/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. **確認版本需求**
   ```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 監控腳本