Cài n8n trên Windows: kiểm Node, mở localhost và xử lý lỗi

Bạn muốn cài n8n trên Windows để học local, không cần mở cổng cho người ngoài truy cập. Bài này đi theo một đường kiểm tra được từng điểm: Node đang chạy từ đâu, n8n được đặt ở thư mục nào, màn hình đầu tiên có ý nghĩa gì, và dữ liệu nào phải giữ lại khi sửa lỗi.

Khoanh phạm vi trước khi cài n8n trên Windows: kiểm đúng Node và biết máy đang mở cổng cho ai

Hướng dẫn này chỉ dành cho sandbox local trên Windows, chạy n8n từ một thư mục riêng bằng npm. Nó không bao gồm triển khai lên máy chủ, cấu hình tên miền, HTTPS, reverse proxy, Docker hay cho phép người khác truy cập từ Internet. Local không có nghĩa là mọi dữ liệu đều vô hại: workflow, thông tin đăng nhập đã lưu và khóa mã hóa vẫn có thể nằm trên máy bạn. Vì vậy, đừng bắt đầu bằng việc cài global rồi chạy ở nhiều thư mục khác nhau; cách đó khiến bạn khó biết lệnh đang gọi bản n8n nào.

Có một chỗ "local" không tự đúng. Mặc định n8n mở cổng giao diện trên 0.0.0.0, tức là mọi card mạng, nên bất kỳ máy nào cùng Wi-Fi cũng gọi được vào — mà n8n giữ sẵn thông tin đăng nhập của các dịch vụ bạn đã nối. Kiểm bằng netstat -ano | findstr :5678: thấy 0.0.0.0:5678 là đang mở ra mạng, thấy 127.0.0.1:5678 mới là chỉ máy này. Muốn khoá lại thì đặt biến N8N_LISTEN_ADDRESS=127.0.0.1 trước khi chạy; tôi đã thử và cổng chuyển từ 0.0.0.0 sang 127.0.0.1 đúng như mong đợi. Tiện thể, tiến trình bên trong của n8n vốn đã chỉ nghe trên 127.0.0.1, nên phần lộ ra ngoài đúng là cổng giao diện.

Mở PowerShell và kiểm tra từng lệnh bằng where.exe node, Get-Command node và node --version. Hai lệnh đầu cho biết Windows đang tìm file thực thi ở đâu; lệnh cuối cho biết phiên bản của file đó. Nếu máy có nhiều Node, hãy mở một PowerShell mới sau khi thay đổi PATH rồi kiểm tra lại. Tiếp theo, mở trang cài đặt của đúng bản n8n bạn định dùng và đối chiếu yêu cầu n8n node version với phiên bản Node đang hiện ra. Tài liệu n8n có thể thay đổi yêu cầu giữa các bản; tôi không đưa một số phiên bản cố định vì bản mới có thể khác. Nếu tài liệu bản n8n và máy bạn không khớp, dừng ở đây để đổi Node hoặc chọn bản n8n phù hợp, thay vì cố ép npm cài tiếp.

Cài n8n local bằng npm trong một thư mục cố định

Cài vào một thư mục cố định, đừng gọi thẳng npx n8n. Thư mục cố định cho bạn biết chính xác gói nằm ở đâu khi cần xoá đi cài lại, và tránh luôn lỗi EPERM mà npx hay dính trên Windows với cây phụ thuộc lớn.

1. 1Tạo thư mục và chuyển vào đó. Chạy Get-Location sau cùng để chắc mình đang đứng đúng chỗ — bước sau sẽ ghi hàng trăm megabyte vào đây.

New-Item -ItemType Directory -Path D:\n8n-lab-1 -Force
Set-Location D:\n8n-lab-1
Get-Location

2. 2Kiểm Node trước khi cài, vì n8n 2.35.7 đòi Node từ 22.22 trở lên. Máy có nhiều bản Node thì where.exe cho biết Windows đang gọi bản nào.

where.exe node
node --version
npm --version

Số hiện ra nhỏ hơn 22.22 thì dừng ở đây và cài Node mới trước. Đi tiếp chỉ tốn thời gian: lệnh cài sẽ chạy một lúc lâu rồi mới báo không hỗ trợ.

3. 3Tạo package.json rồi cài n8n. Ghim đúng phiên bản nếu bạn muốn mọi tên nút trong bài khớp với thứ hiện trên màn hình.

npm init -y
npm install n8n@2.35.7

Bỏ @2.35.7 thì npm lấy bản mới nhất — vẫn chạy được, chỉ là giao diện có thể đã đổi so với ảnh chụp ở đây.

4. 4Chạy n8n từ chính thư mục vừa cài. Hậu tố .cmd là tệp lệnh do npm tạo cho Windows.

.\node_modules\.bin\n8n.cmd start

Dấu hiệu đã xong: cửa sổ đứng lại và in ra dòng báo n8n đang lắng nghe. Cửa sổ này phải để yên — đóng nó là tắt n8n.

5. 5Khoá n8n lại cho chỉ máy này gọi được, trước khi mở trình duyệt. Mặc định n8n nghe trên mọi card mạng, tức cả máy khác trong cùng Wi-Fi cũng vào được giao diện đang giữ sẵn thông tin đăng nhập của bạn.

$env:N8N_LISTEN_ADDRESS = "127.0.0.1"
.\node_modules\.bin\n8n.cmd start

Kiểm lại bằng lệnh dưới. Thấy 127.0.0.1:5678 là đúng; thấy 0.0.0.0:5678 là vẫn đang mở ra mạng.

netstat -ano | findstr :5678

Mở n8n localhost 5678 và nhận ra màn hình cài xong

Mở trình duyệt tại http://localhost:5678. Đây là địa chỉ mặc định thường gặp của giao diện n8n, nhưng giá trị có thể bị thay đổi bởi biến môi trường hoặc cấu hình bản bạn đang dùng. Tài liệu thiết lập của n8n là nguồn cần đối chiếu nếu terminal in ra một địa chỉ khác. Lần đầu chạy, n8n có thể hiện trang tạo owner account. Điền tài khoản quản trị local theo yêu cầu trên màn hình và lưu thông tin đó ở nơi bạn kiểm soát; đây không phải bước có thể bỏ qua bằng cách xóa thư mục nếu bạn còn muốn giữ dữ liệu sau này.

Sau khi hoàn tất thiết lập, canvas trống chỉ có nghĩa là tài khoản chưa có workflow, không phải n8n cài hỏng. Dấu hiệu đáng xem trong terminal là tiến trình có tiếp tục chạy hay bị thoát cùng thông báo lỗi. Nếu trình duyệt báo không kết nối được, kiểm tra PowerShell còn đang chạy, địa chỉ có đúng cổng không, và Windows Firewall có chặn tiến trình hay không. Nếu trang hiện yêu cầu owner account hoặc mở được giao diện chỉnh workflow, phần cài cơ bản đã đi tới màn hình đầu tiên; việc chưa có node hay workflow là trạng thái dữ liệu, không phải lỗi cài đặt.

Muốn biết mình vừa cài được bản nào thì vào Settings, mục Usage and plan. Trang đó nói thẳng bạn đang chạy bản nào, và số phiên bản nằm ở góc trái dưới cùng — chỗ này hữu ích khi đối chiếu với tài liệu, vì tên các nút trong n8n đổi khá nhanh giữa các bản.

Lỗi cài n8n theo triệu chứng: Node lệch phiên bản, EPERM, ENOENT và tiến trình không lên

Nếu terminal báo Node không được hỗ trợ, trước hết chạy lại where.exe node, node --version và npm --version trong chính cửa sổ đang dùng. Có thể bạn đã đổi PATH nhưng PowerShell cũ vẫn giữ đường dẫn trước đó. Đối chiếu phiên bản Node với tài liệu của bản n8n đã cài, không chỉ với hướng dẫn của một bản n8n khác. Nếu npm install n8n đã tạo thư mục nhưng lệnh chạy vẫn báo lỗi tương thích, ghi lại tên và phiên bản n8n trong package.json, rồi kiểm tra yêu cầu của chính bản đó. Đừng xóa .n8n để sửa lỗi Node; thư mục này chứa dữ liệu chạy, không thay thế được một Node phù hợp.

Lỗi EPERM thường chỉ ra vấn đề quyền truy cập, tệp đang bị khóa hoặc phần mềm bảo vệ đang can thiệp; thông báo cụ thể mới quyết định bước tiếp theo. Đóng các terminal khác đang chạy n8n, kiểm tra bạn có quyền ghi vào D:\n8n-lab-1, rồi thử lại trong một thư mục bạn sở hữu. Nếu lỗi nhắc tới một tệp hoặc thư mục cụ thể, xem tệp đó có đang được mở bởi tiến trình khác hay không. Lỗi ENOENT thường có nghĩa là đường dẫn hoặc tệp được yêu cầu không tồn tại: kiểm tra bằng Get-Location, Test-Path .\node_modules\.bin\n8n.cmd và xem bạn có gõ nhầm thư mục hay không. Chỉ xóa node_modules và chạy lại npm install khi lỗi thực sự nằm ở cây gói bị hỏng; việc này khác với xóa dữ liệu người dùng trong .n8n.

Nếu chạy .\node_modules\.bin\n8n.cmd start rồi cửa sổ quay về dấu nhắc ngay, hãy đọc dòng cuối trước khi chạy lại. Nếu n8n đã chạy nhưng trình duyệt không mở được, kiểm tra cổng bằng Get-NetTCPConnection -LocalPort 5678 -ErrorAction SilentlyContinue và xem terminal có in cổng khác không. Nếu muốn thử lệnh npx n8n, chỉ dùng nó như một phép chẩn đoán sau khi hiểu npx đang chọn gói nào; nó không phải cách tốt để giữ hai sandbox tách biệt. Khi cần tìm nguyên nhân, giữ nguyên log lỗi, tên thư mục, phiên bản Node và phiên bản n8n. Bốn thông tin này hữu ích hơn việc cài lại ngẫu nhiên nhiều lần.

Chạy hai sandbox: tách thư mục người dùng, cổng web và n8n port 5679

Bản thứ hai cần tách ít nhất thư mục dự án và thư mục dữ liệu người dùng. Tạo D:\n8n-lab-2, cài n8n local ở đó như sandbox thứ nhất, rồi trong PowerShell đặt $env:N8N_USER_FOLDER = "D:\n8n-data-2" và $env:N8N_PORT = "5679". Sau đó chạy .\node_modules\.bin\n8n.cmd start. N8N_USER_FOLDER làm cho dữ liệu của phiên thứ hai đi vào thư mục riêng thay vì dùng thư mục mặc định của tài khoản Windows; N8N_PORT đổi cổng giao diện web cho phiên đó. Các biến đặt theo cách này chỉ có hiệu lực trong cửa sổ PowerShell hiện tại. Nếu mở cửa sổ mới, phải đặt lại hoặc cấu hình biến môi trường theo cách khác.

Đổi giao diện sang n8n port 5679 chưa chắc đã đủ. Một số cấu hình hoặc bản n8n có thành phần Task Broker dùng một cổng nội bộ riêng; nếu cổng đó trùng với tiến trình khác, phiên thứ hai vẫn có thể không khởi động dù trình duyệt dùng cổng 5679. Kiểm tra log lúc khởi động và tài liệu cấu hình của đúng bản n8n để xác định biến dành cho broker, chẳng hạn N8N_RUNNERS_BROKER_PORT nếu bản đó hỗ trợ, rồi đặt sang một cổng chưa dùng như $env:N8N_RUNNERS_BROKER_PORT = "5680". Tôi chưa thể khẳng định tên biến và cổng mặc định giống nhau ở mọi bản, nên không nên sao chép mù một cấu hình từ bài hướng dẫn cũ. Dùng Get-NetTCPConnection -State Listen để xem các cổng đang lắng nghe trước khi chọn.

Thư mục .n8n ở đâu, chứa gì và những thứ không nên xóa để sửa lỗi

Nếu không đặt N8N_USER_FOLDER, n8n thường dùng thư mục .n8n bên trong thư mục người dùng của hệ điều hành; trên Windows, hãy kiểm tra $env:USERPROFILE rồi ghép thêm \.n8n. Cách chắc hơn là xem log khởi động của chính phiên n8n hoặc đặt N8N_USER_FOLDER rõ ràng ngay từ đầu. Trong đó có thể có database.sqlite, tệp config và các dữ liệu cấu hình khác tùy bản. Database có thể chứa workflow, thông tin owner và dữ liệu vận hành; tệp cấu hình có thể chứa khóa dùng để mã hóa thông tin đăng nhập. Tài liệu n8n nói khóa mã hóa phải được giữ ổn định để đọc lại dữ liệu đã mã hóa, vì vậy không xóa .n8n chỉ vì canvas đang trống hoặc một lệnh chạy thất bại.

Trước khi cài lại hoặc đổi cấu hình, dừng n8n rồi sao chép cả thư mục .n8n (hoặc thư mục bạn trỏ N8N_USER_FOLDER tới) sang nơi khác, chứ đừng chỉ nhặt hai tệp: bản sau có thể thêm tệp mới mà bạn không biết. Ghi lại luôn những biến môi trường bạn đã đặt, vì khoá mã hoá có thể nằm ngoài tệp config nếu bạn đặt nó bằng biến. Đồng thời ghi lại đường dẫn N8N_USER_FOLDER đang dùng. Bản sao chỉ có giá trị nếu bạn biết nó thuộc sandbox nào và được tạo khi tiến trình đã dừng; tôi chưa kiểm tra tình trạng tệp trên máy bạn nên không thể hứa bản sao nào cũng khôi phục được. Nếu mất khóa mã hóa, database vẫn có thể còn đó nhưng thông tin đăng nhập đã mã hóa có thể không giải mã được. Sau khi bản thứ nhất chạy ổn, hãy tạo bản thứ hai bằng thư mục dữ liệu riêng và kiểm tra từng cổng trong terminal trước khi xóa bất cứ thứ gì.