n8n CLI (命令列工具) 深度教學：實現工作流的自動化部署與管理

當你從一位 n8n 的使用者，逐漸成長為需要管理數十、甚至上百個工作流 (Workflow) 的開發者或系統管理員時，你會開始遇到新的挑戰：

• 如何將開發環境中測試好的工作流，自動化地部署到正式生產環境？
• 如何將所有的工作流與 Git 版本控制系統結合，實現專業的變更管理？
• 如何透過腳本 (Script) 批次啟用、停用或刪除帶有特定標籤 (Tag) 的工作流？

這些「管理 n8n 本身」的任務，光靠圖形化介面 (UI) 的手動點擊是遠遠不夠的。為了解決這些進階需求，n8n 提供了一個專為開發者與系統管理員設計的強大工具——n8n CLI (Command-Line Interface，命令列工具)。

n8n CLI 讓你能用程式化的方式，直接從伺服器的終端機下指令來操作你的 n8n 實例。它是在 UI 和 API 之外，實現 n8n DevOps 和自動化管理的第三座橋樑。這篇文章將是你的 n8n CLI 深度教學，帶你從環境安裝開始，逐一解析核心指令，並透過精彩的 CI/CD 實戰案例，讓你學會如何將你的 n8n 管理任務也納入自動化的版圖。

為什麼你需要 n8n CLI？超越 UI 操作的 DevOps 力量

在有方便的 UI 介面的情況下，我們為什麼還需要學習使用命令列？因為 CLI 能夠解決三大 UI 無法觸及的場景：

1. CI/CD 自動化部署 (Automated Deployment): 這是 CLI 最核心的價值。你可以將 n8n 工作流的 JSON 檔案存放在 Git 儲存庫（如 GitHub, GitLab）中進行版本控制。當有新的變更被合併到主分支時，CI/CD pipeline（例如 GitHub Actions）可以自動執行 n8n import:workflow 指令，將最新的工作流版本無縫部署到你的生產環境 n8n 實例中。
2. 批次管理與腳本化 (Bulk Management & Scripting): 想像一下，你需要停用所有標籤為「舊專案」的 50 個工作流。在 UI 中，你需要一個一個地點擊、停用，非常耗時。但透過 CLI，你只需要一行簡單的 Shell 腳本，結合 n8n list:workflow --tags='舊專案' 和 n8n deactivate:workflow 指令，就能在幾秒鐘內完成任務。
3. 伺服器層級的設定與管理 (Server-level Administration): CLI 提供了一些 UI 無法進行的底層管理功能，例如使用者管理（新增、刪除、更改密碼）、設定加密金鑰等，是維運 n8n 實例不可或缺的工具。

n8n CLI 環境準備與安裝

n8n CLI 是內建於 n8n 主程式中的，你不需要額外安裝。要使用它，你需要能夠在你的 n8n 伺服器環境中執行指令。對於最常見的 Docker 安裝方式，執行 CLI 指令的方法如下：

透過 Docker 執行 CLI 指令

你需要使用 docker exec 指令，進入到正在運行的 n8n 容器 (container) 中來執行 CLI。

1. 找出你的 n8n 容器名稱或 ID: 執行 docker ps 指令，找到 n8nio/n8n 這個 image 對應的容器，記下它的 NAMES 或 CONTAINER ID。
2. 進入容器並執行指令： 假設你的容器名稱是 n8n-instance-1，你想執行 workflow:list 指令，完整的命令會是：Bashdocker exec -it --user node n8n-instance-1 n8n workflow:list
   • docker exec -it [容器名稱]: 這是進入容器執行指令的標準 Docker 命令。
   • --user node: 非常重要！ 必須指定使用 node 這個使用者來執行，否則可能會因為權限問題而失敗。
   • n8n: 這是 n8n CLI 的主執行檔。
   • workflow:list: 這是你要執行的具體指令。

為了方便起見，你可以為這長串指令設定一個 Shell 別名 (alias)，例如 alias n8n-cli="docker exec -it --user node n8n-instance-1 n8n"。

核心指令詳解：工作流 (Workflow) 管理

工作流管理是 CLI 最常用的功能，所有相關指令都在 workflow 這個子命令下。

workflow:list – 列出所有工作流

• 功能： 以列表形式顯示你 n8n 實例中所有的工作流。
• 常用參數：
  • --all: 顯示所有欄位（預設只顯示部分）。
  • --tags='tagA,tagB': 只顯示包含特定標籤的工作流。
  • --active=true/false: 只顯示啟用或停用的工作流。
  • --json: 以 JSON 格式輸出，方便腳本後續處理。
• 範例： 找出所有已啟用且標籤為「Production」的工作流，並以 JSON 格式輸出。Bashn8n workflow:list --active=true --tags='Production' --json

workflow:export 與 workflow:import – 匯出與匯入

• workflow:export 功能： 將指定的工作流匯出成 JSON 檔案。
  • 語法： n8n workflow:export --id=[工作流ID] --output=[檔案路徑]
  • 範例： n8n workflow:export --id=5 --output=./workflows/order-processing.json
• workflow:import 功能： 將本地的 JSON 檔案匯入到 n8n 實例中。
  • 語法： n8n workflow:import --input=[檔案路徑]
  • 範例： n8n workflow:import --input=./workflows/order-processing.json
  • 注意： 如果匯入的工作流 ID 已存在，n8n 會更新現有的工作流；如果不存在，則會建立一個新的。

workflow:activate 與 workflow:deactivate – 啟用與停用

• 功能： 透過 ID 快速啟用或停用工作流。
• 語法： n8n workflow:deactivate --id=[工作流ID] 或 n8n workflow:activate --id=[工作流ID]
• 範例： n8n workflow:deactivate --id=5

核心指令詳解：執行紀錄 (Execution) 與使用者 (User) 管理

除了工作流，CLI 也能讓你管理執行紀錄和使用者。

execution:delete – 刪除執行紀錄

• 功能： 用於清理舊的執行紀錄，釋放資料庫空間。
• 常用參數：
  • --all: 刪除所有執行紀錄。
  • --older-than=[天數]: 刪除指定天數以前的紀錄。
  • --status=success/failed: 只刪除成功或失敗的紀錄。
• 範例： 刪除所有 30 天以前的、已成功執行的紀錄。Bashn8n execution:delete --status=success --older-than=30

user:create 與 user:change-password – 管理使用者

• 功能： 讓你可以在命令列中新增管理員或更改密碼，這在你忘記密碼且無法登入 UI 時特別有用。
• 範例：Bash# 建立一個新的管理員帳號 n8n user:create --firstName=Admin --lastName=User --email=admin@example.com --password='SuperSecretPassword!' # 為現有使用者重設密碼 n8n user:change-password --email=admin@example.com --password='NewSuperSecretPassword!'

實戰案例：如何透過 CI/CD Pipeline 自動部署 n8n Workflow？

這是 n8n CLI 最具價值的應用。讓我們想像一個使用 GitHub Actions 的部署流程。

1. 開發與版控：
   • 開發者在本地或開發用的 n8n 實例上修改工作流。
   • 修改完成後，使用 n8n workflow:export 指令將工作流匯出成 JSON 檔案。
   • 將這個 JSON 檔案 commit 並 push 到 GitHub 儲存庫。
2. 建立 GitHub Actions Workflow: 在你的儲存庫中建立一個 .github/workflows/deploy-n8n.yml 檔案，內容可能如下：YAMLname: Deploy n8n Workflow on: push: branches: [ main ] # 當 main 分支有更新時觸發 paths: - 'workflows/**.json' # 只在 workflows 資料夾有變動時觸發 jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout repository uses: actions/checkout@v3 - name: Import and Activate Workflow uses: appleboy/ssh-action@master with: host: ${{ secrets.N8N_HOST }} username: ${{ secrets.N8N_USERNAME }} key: ${{ secrets.N8N_SSH_KEY }} script: | # 假設你的 n8n 容器名稱為 n8n # 遍歷所有變動的 workflow JSON 檔案並匯入 for file in ${{ github.event.head_commit.modified }}; do if [[ $file == workflows/*.json ]]; then docker exec -i --user node n8n n8n workflow:import < "$file" echo "Imported $file" fi done

這個 Action 會在 workflows 資料夾有更新時，透過 SSH 連線到你的 n8n 伺服器，並執行 docker exec ... n8n workflow:import 指令，將最新的工作流檔案匯入到你的生產環境中，實現了完全自動化的部署。

結語

n8n CLI 是一座橋樑，它連接了 n8n 的視覺化世界與傳統開發維運的自動化世界。雖然對於一般使用者來說可能不是必需品，但對於任何希望將 n8n 納入專業開發流程、進行規模化管理、或實現自動化維運的開發者和系統管理員來說，精通 CLI 是不可或缺的一步。

從今天起，試著用 workflow:list 來檢視你的流程，用 workflow:export 來備份你的心血結晶。當你開始將這些指令融入你的日常管理腳本和 CI/CD pipeline 中時，你會發現你對 n8n 的掌控力，將達到一個前所未有的新高度。