Hướng Dẫn Cách Cài Đặt n8n Trên Windows Bằng Docker Desktop & WSL 2

Cách cài đặt n8n trên Windows bằng Docker Desktop là giải pháp tối ưu giúp bạn sở hữu một nền tảng tự động hóa quy trình mạnh mẽ ngay trên máy tính cá nhân mà không tốn chi phí bản quyền ban đầu. Để hệ thống vận hành trơn tru và an toàn dữ liệu, bạn cần cấu hình chính xác môi trường ảo hóa WSL 2 và Docker Compose. Dưới đây là hướng dẫn chi tiết từng bước từ đội ngũ kỹ sư hạ tầng tại InterData.

1. Điều kiện tiên quyết & Kiểm tra Virtualization BIOS

n8n là công cụ tự động hóa dạng workflow mã nguồn mở (workflow automation tool), cho phép kết nối hàng trăm ứng dụng và dịch vụ khác nhau. Để thực hiện cách cài đặt n8n trên Windows bằng Docker Desktop đạt độ ổn định cao nhất, máy tính cá nhân của bạn cần đáp ứng các yêu cầu phần cứng và hệ điều hành sau:

• Hệ điều hành: Windows 10 (bản 64-bit từ Build 19041 trở lên) hoặc Windows 11 64-bit còn trong vòng đời hỗ trợ từ Microsoft.
• Phần cứng CPU: Vi xử lý 64-bit kiến trúc x86_64 (Intel hoặc AMD) có hỗ trợ ảo hóa phần cứng (Hardware Virtualization).
• Dung lượng RAM: Cấu hình tối thiểu 8 GB RAM (khuyến nghị 16 GB để phân bổ tài nguyên mượt mà cho WSL 2 và Docker Engine).
• Dung lượng ổ cứng: Tối thiểu 5–10 GB dung lượng trống trên ổ đĩa hệ thống (khuyến nghị sử dụng SSD).
• Môi trường ảo hóa: Đã kích hoạt Virtualization trong BIOS/UEFI của bo mạch chủ.

Kiểm tra trạng thái Virtualization trong Windows Task Manager

Trước khi cài bất kỳ gói phần mềm ảo hóa nào, bạn phải kiểm tra xem tính năng ảo hóa của vi xử lý đã được mở trong BIOS hay chưa:

1. Nhấn tổ hợp phím Ctrl + Shift + Esc để mở Task Manager.
2. Chuyển sang tab Performance và chọn mục CPU.
3. Quan sát dòng Virtualization ở góc dưới bên phải:
   • Nếu hiển thị Enabled: Máy tính đã sẵn sàng cho WSL 2 và Docker.
   • Nếu hiển thị Disabled: Bạn cần khởi động lại máy, truy cập vào menu BIOS/UEFI (bằng phím F2, F12 hoặc Del tùy dòng bo mạch chủ) để bật tính năng này.

Tên của tùy chọn ảo hóa trong BIOS thường hiển thị dưới các định dạng:

• Đối với CPU Intel: Intel Virtualization Technology hoặc Intel VT-x.
• Đối với CPU AMD: AMD-V hoặc SVM Mode (Secure Virtual Machine).

2. Hướng dẫn kích hoạt và cập nhật WSL 2 trên Windows

WSL 2 (Windows Subsystem for Linux thế hệ 2) là nền tảng ảo hóa nhân Linux nhẹ (lightweight Linux utility VM) chạy trực tiếp trên Windows, giúp Docker đạt hiệu năng I/O tối ưu mà không ngốn tài nguyên như Hyper-V truyền thống. Docker Desktop yêu cầu WSL phiên bản tối thiểu là 2.1.5 và khuyến nghị cập nhật bản mới nhất.

Bước 1: Mở PowerShell với quyền Administrator

1. Nhấp vào biểu tượng Start trên thanh Taskbar hoặc nhấn phím Windows.
2. Gõ từ khóa PowerShell.
3. Nhấp chuột phải vào Windows PowerShell và chọn Run as administrator.
4. Chọn Yes tại hộp thoại xác thực User Account Control (UAC).

Bước 2: Kiểm tra và cài đặt cập nhật WSL 2

Trong cửa sổ PowerShell Administrator, kiểm tra phiên bản WSL hiện có trên máy:

wsl --version

Nếu hệ thống hiển thị thông tin phiên bản, hãy chạy lệnh sau để kéo về kernel Linux mới nhất:

wsl --update

Nếu máy tính báo lỗi lệnh không tồn tại (WSL chưa từng được cài đặt), bạn thực thi lệnh sau:

wsl --install

Sau khi tiến trình cài đặt hoàn tất, hãy khởi động lại Windows. Sau khi máy bật lên, mở lại PowerShell và chạy wsl --update một lần nữa để hoàn tất việc đồng bộ kernel Linux.

3. Cài đặt và thiết lập Docker Desktop trên Windows

Docker Desktop đóng vai trò quản trị container, image và networking cho n8n. Việc cài đặt đúng backend WSL 2 sẽ giúp n8n hoạt động mượt mà và không gặp lỗi phân quyền file.

Bước 1: Tải bộ cài đặt chính thức

Truy cập trang tài liệu chính thức của Docker và tải file cài đặt phiên bản Windows dành cho kiến trúc vi xử lý x86_64 (Intel/AMD thông thường): Docker Desktop for Windows – x86_64. Tránh tải nhầm bản ARM nếu máy tính của bạn không sử dụng chip Snapdragon hay chip nền ARM.

Link tải Docker Desktop Windows: https://docs.docker.com/desktop/setup/install/windows-install/

Bước 2: Cài đặt và cấu hình backend

1. Chạy file thực thi Docker Desktop Installer.exe với quyền Administrator.
2. Tại màn hình Configuration, đánh dấu tích bắt buộc vào ô: Use WSL 2 instead of Hyper-V (recommended).
3. Nhấn OK để bắt đầu quá trình trích xuất và triển khai file hệ thống.
4. Sau khi cài đặt xong, chọn Close and restart nếu hệ thống yêu cầu khởi động lại máy.

Bước 3: Khởi chạy và thiết lập Docker Desktop

1. Mở menu Start, tìm và mở ứng dụng Docker Desktop.
2. Chọn Accept tại bảng điều khoản dịch vụ (Docker Subscription Service Agreement).
3. Tại bước đăng nhập tài khoản, bạn có thể bấm Continue without signing in hoặc Skip survey vì Docker không bắt buộc đăng nhập để kéo image n8n công khai.
4. Đợi vài giây đến khi biểu tượng góc dưới cùng bên trái của Docker Desktop chuyển sang màu xanh lá cây báo trạng thái Engine running.
5. Nhấp vào biểu tượng bánh răng Settings > chọn mục General > đảm bảo tùy chọn Use the WSL 2 based engine đã được bật. Bấm Apply & restart nếu có thay đổi.

Bước 4: Kiểm tra CLI trong PowerShell

Đóng các cửa sổ PowerShell cũ đã mở từ trước khi cài Docker. Mở một cửa sổ PowerShell mới (không cần quyền Admin) và kiểm tra:

docker --version

Tiếp tục kiểm tra công cụ điều phối container Docker Compose đi kèm:

docker compose version

Nếu cả hai lệnh đều hiển thị thông tin phiên bản (ví dụ Docker version 27.x và Docker Compose version v2.x), môi trường Docker trên Windows của bạn đã hoàn tất.

4. Cách cài đặt n8n trên Windows bằng Docker Desktop và Docker Compose

Để quy trình vận hành n8n chuyên nghiệp, an toàn và dễ sao lưu, chúng ta sẽ quản lý dự án thông qua thư mục cấu hình độc lập kết hợp với Docker Compose thay vì chạy lệnh docker run đơn lẻ. Nếu bạn quan tâm đến cách cấu hình trên máy chủ Linux, có thể tham khảo thêm bài viết về hướng dẫn cài Docker Compose của InterData.

Bước 1: Tạo thư mục lưu trữ dự án n8n

Mở PowerShell thông thường và tạo thư mục n8n tại ổ đĩa D:\ để tiện quản lý:

mkdir D:\n8n
cd D:\n8n
pwd

Đảm bảo kết quả trả về từ lệnh pwd là D:\n8n. Tất cả các lệnh thao tác tiếp theo đều được thực hiện từ thư mục này.

Bước 2: Tạo khóa mã hóa ngẫu nhiên 32 bytes (N8N_ENCRYPTION_KEY)

n8n sử dụng khóa mã hóa để mã hóa toàn bộ dữ liệu nhạy cảm (API Keys, OAuth Tokens, mật khẩu cơ sở dữ liệu) trước khi lưu vào database. Nếu không chỉ định khóa cố định, n8n sẽ tự sinh khóa ngẫu nhiên và lưu nội bộ; nếu volume bị lỗi, bạn sẽ mất toàn bộ kết nối credential.

Tại PowerShell ở thư mục D:\n8n, chạy đoạn mã sau để tạo chuỗi mã hóa chuẩn 32-byte ngẫu nhiên và lưu vào file .env:

"N8N_ENCRYPTION_KEY=$key" | Set-Content -Encoding ascii .env
$bytes = New-Object byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$key = -join ($bytes | ForEach-Object { $_.ToString("x2") })
"N8N_ENCRYPTION_KEY=$key" | Set-Content -Encoding ascii .env

Kiểm tra sự tồn tại của file .env:

dir -Force

Lưu ý bảo mật: Không chia sẻ công khai file .env hoặc chuỗi mã hóa này lên GitHub hay diễn đàn công cộng.

Bước 3: Tạo file cấu hình docker-compose.yml

Mở trình soạn thảo Notepad để tạo file cấu hình Docker Compose:

notepad docker-compose.yml

Khi Notepad hiện thông báo hỏi tạo file mới, chọn Yes. Sao chép và dán toàn bộ đoạn cấu hình chuẩn sau vào Notepad:

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    container_name: n8n
    restart: unless-stopped

    ports:
      - "127.0.0.1:5678:5678"

    environment:
      - GENERIC_TIMEZONE=Asia/Ho_Chi_Minh
      - TZ=Asia/Ho_Chi_Minh
      - N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
      - N8N_RUNNERS_ENABLED=true
      - N8N_ENCRYPTION_KEY=${N8N_ENCRYPTION_KEY}

    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:
    name: n8n_data

Nhấn Ctrl + S để lưu file và đóng Notepad. Hãy đảm bảo định dạng file là docker-compose.yml chứ không phải docker-compose.yml.txt. Kiểm tra tính hợp lệ của cú pháp YAML bằng lệnh:

docker compose config

Nếu lệnh in ra toàn bộ cấu hình mà không báo lỗi cú pháp, tệp tin đã sẵn sàng.

Bước 4: Khởi động container n8n và tạo tài khoản Admin

Tại thư mục D:\n8n, chạy lệnh kéo image và khởi chạy container dưới chế độ chạy nền (detached mode):

docker compose up -d

Kiểm tra trạng thái hoạt động của container:

docker compose ps

Khi cột STATUS hiển thị Up hoặc running, bạn mở trình duyệt web (Google Chrome hoặc Microsoft Edge) và truy cập vào địa chỉ:

http://localhost:5678

Tại màn hình thiết lập ban đầu (Set up owner account), bạn tiến hành điền Email quản trị, Họ tên và Mật khẩu đăng nhập. Đây là tài khoản Owner quản lý instance n8n nội bộ của bạn.

Bước 5: Thử nghiệm workflow đầu tiên

Để xác thực môi trường n8n vừa dựng hoạt động trơn tru, bạn hãy tạo một kịch bản test nhanh:

1. Nhấn Create Workflow (hoặc Start from scratch).
2. Nhấp vào nút dấu cộng (+) trên khung vẽ, tìm kiếm node tên là Manual Trigger. Đây là một dạng Trigger Node trong n8n dùng để kích hoạt luồng thủ công khi click chuột.
3. Kéo một đường nối từ node Manual Trigger sang node tiếp theo và chọn node Edit Fields (hoặc Set Node).
4. Trong bảng cấu hình Edit Fields, thiết lập trường message có giá trị là n8n đã hoạt động.
5. Nhấn nút Execute Workflow (hoặc Test step). Kết quả trả về dữ liệu JSON mẫu minh chứng hệ thống n8n đã sẵn sàng để bạn xây dựng từ các luồng cơ bản đến các tác vụ nâng cao như cách tạo chatbot AI bằng n8n.

5. Vận hành, cập nhật và sao lưu dữ liệu n8n an toàn

Quá trình vận hành n8n bằng Docker trên Windows đòi hỏi người dùng nắm vững các thao tác điều khiển chu kỳ sống (lifecycle) của container để tránh sự cố mất mát dữ liệu.

Quản lý n8n hằng ngày

1/ Dừng container n8n (khi không sử dụng):

cd D:\n8n
docker compose stop

2/ Bật lại n8n:

cd D:\n8n
docker compose start

3/ Theo dõi log hệ thống thời gian thực (để debug):

docker compose logs -f

(Nhấn tổ hợp phím Ctrl + C để thoát màn hình xem log mà không làm tắt container n8n).

Quy trình cập nhật (Update) n8n lên bản mới nhất

Nhờ sử dụng Docker volume gắn ngoài (n8n_data), việc nâng cấp n8n diễn ra nhanh chóng mà vẫn bảo toàn toàn bộ dữ liệu workflow:

cd D:\n8n
docker compose pull
docker compose down
docker compose up -d

Lệnh docker compose down tiêu chuẩn chỉ loại bỏ container cũ mà không xóa volume dữ liệu (trừ khi gắn thêm cờ -v).

Cách sao lưu (Backup) Docker Volume và khóa mã hóa

Dữ liệu n8n nằm gọn bên trong Docker volume mang tên n8n_data. Bạn có thể trích xuất toàn bộ dữ liệu này ra một file nén .tar.gz bằng một container tạm thời chạy image Alpine Linux:

1/ Tạo thư mục chứa bản backup:

mkdir D:\n8n\backup

2/ Dừng n8n để tránh tình trạng ghi đè cơ sở dữ liệu SQLite trong lúc sao lưu:

cd D:\n8n
docker compose stop

3/ Chạy lệnh đóng gói dữ liệu volume:

docker run --rm -v n8n_data:/data -v D:\n8n\backup:/backup alpine tar -czf /backup/n8n-data-backup.tar.gz -C /data .

Sao lưu file cấu hình D:\n8n\.env sang một thiết bị lưu trữ ngoài an toàn (USB hoặc Cloud Drive cá nhân).

4/ Khởi động lại n8n:

docker compose start

Các câu lệnh nguy hiểm tuyệt đối không được tự ý chạy

Nếu không nắm rõ kiến trúc Docker, bạn tuyệt đối không thực thi các lệnh sau vì chúng sẽ xóa sạch toàn bộ volume và mất vĩnh viễn các workflow đã xây dựng:

• docker compose down -v (Cờ -v sẽ xóa toàn bộ named volume kèm theo).
• docker volume rm n8n_data (Xóa trực tiếp phân vùng dữ liệu n8n).
• docker system prune --volumes (Dọn dẹp và xóa mọi volume không được gắn kết trực tiếp).

6. So sánh n8n Localhost Windows vs n8n trên VPS Máy chủ

Mặc dù cách cài đặt n8n trên Windows bằng Docker Desktop rất tiện lợi để nghiên cứu và học tập, nhưng khi đưa vào vận hành thực tế cho doanh nghiệp hoặc tự động hóa công việc kinh doanh, môi trường máy tính cá nhân bộc lộ nhiều điểm hạn chế. Bạn có thể xem thêm hướng dẫn cài đặt n8n bằng Docker trên VPS để thấy sự khác biệt về hạ tầng.

Khi bạn xây dựng quy trình tiếp nhận thông tin từ Google Forms, đơn hàng Facebook hoặc CRM, việc hiểu rõ khái niệm Webhook sẽ giúp bạn nhận ra tại sao môi trường localhost không thể phục vụ việc lắng nghe dữ liệu liên tục từ môi trường mạng bên ngoài.

7. Xử lý 6 lỗi thường gặp khi triển khai n8n Docker

1. Lỗi ‘docker’ is not recognized as an internal or external command

Nguyên nhân: PowerShell chưa nhận diện biến môi trường Path của Docker Desktop do cửa sổ dòng lệnh được mở trước khi tiến trình cài Docker hoàn tất.

Khắc phục: Đóng toàn bộ cửa sổ PowerShell, mở ứng dụng Docker Desktop để hệ thống nạp daemon, sau đó mở lại PowerShell mới và kiểm tra lại bằng lệnh docker --version.

2. Lỗi Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Nguyên nhân: Docker Desktop đang trong trạng thái khởi động dở dang hoặc dịch vụ nền (Docker Engine Service) chưa chạy.

Khắc phục: Mở giao diện Docker Desktop, nhìn biểu tượng góc dưới cùng xem đã hiển thị Engine running màu xanh chưa. Khi Docker đã chạy, quay lại PowerShell và thực thi lại lệnh docker compose up -d.

3. Lỗi WSL 2 Kernel update hoặc Virtualization Disabled

Nguyên nhân: Gói kernel Linux của Microsoft chưa được cập nhật bản vá mới nhất hoặc phân vùng ảo hóa bị tắt trong BIOS.

Khắc phục: Mở PowerShell bằng quyền Administrator và chạy lần lượt các lệnh sau:

wsl --update
wsl --shutdown

Sau đó khởi động lại Docker Desktop.

4. Lỗi Bind for 0.0.0.0:5678 failed: port is already allocated

Nguyên nhân: Cổng 5678 trên máy tính đang bị chiếm dụng bởi một phần mềm khác hoặc một container n8n chạy ngầm từ trước.

Khắc phục: Mở file docker-compose.yml bằng lệnh notepad docker-compose.yml, điều chỉnh cổng host bên ngoài sang cổng khác (ví dụ 5679):

ports:
  - "127.0.0.1:5679:5678"

Sau đó khởi động lại bằng lệnh docker compose down rồi docker compose up -d và truy cập n8n qua http://localhost:5679.

5. Không thể truy cập địa chỉ http://localhost:5678 trên trình duyệt

Nguyên nhân: Container bị dừng đột ngột (Exited) hoặc ứng dụng bên trong chưa khởi tạo xong cơ sở dữ liệu.

Khắc phục: Kiểm tra log chi tiết của container bằng câu lệnh:

cd D:\n8n
docker compose logs --tail=100

6. Lỗi Docker đang chạy ở chế độ Windows containers

Nguyên nhân: Docker Desktop đang ở chế độ build container của Windows nguyên bản thay vì Linux VM.

Khắc phục: Nhấp chuột phải vào biểu tượng cá voi Docker dưới thanh Taskbar (System Tray) và chọn Switch to Linux containers…, sau đó khởi chạy lại n8n.

8. Câu hỏi thường gặp khi cài đặt n8n trên Windows (FAQ)

1. Tôi có thể tự host n8n hoàn toàn miễn phí trên máy tính cá nhân không?

Có. n8n cung cấp phiên bản Community Edition hoàn toàn miễn phí khi bạn tự host trên máy tính qua Docker. Bạn có thể xây dựng số lượng workflow không giới hạn mà không mất phí bản quyền hàng tháng như bản Cloud của hãng.

2. Tắt máy tính hoặc chuyển sang chế độ Sleep thì n8n có chạy ngầm không?

Không. Khi máy tính Windows tắt nguồn, khởi động lại hoặc đi vào chế độ Sleep (ngủ), toàn bộ tiến trình ảo hóa của WSL 2 và Docker Desktop sẽ bị ngắt kết nối. Các lịch trình định kỳ (Cron Trigger) hay luồng nhận dữ liệu sẽ dừng lại cho đến khi bạn bật lại máy tính.

3. Tại sao tôi không nhận được Webhook từ Google Forms hay Facebook gửi về localhost?

Địa chỉ localhost:5678 hoặc 127.0.0.1 chỉ có phạm vi truy cập nội bộ trong mạng máy tính của bạn. Các dịch vụ trực tuyến từ bên ngoài Internet không thể gửi dữ liệu trực tiếp vào IP nội bộ nếu không có IP tĩnh Public và chứng chỉ SSL hợp lệ.

4. Chuyện gì xảy ra nếu tôi làm mất file .env chứa N8N_ENCRYPTION_KEY?

Nếu mất chuỗi mã hóa N8N_ENCRYPTION_KEY ban đầu, hệ thống n8n sẽ không thể giải mã các thông tin đăng nhập, token và mật khẩu đã lưu trong credential. Khi đó, bạn sẽ phải nhập lại thông tin xác thực cho từng node trong toàn bộ workflow.

5. Khi nào tôi nên chuyển n8n từ máy tính bàn lên máy chủ ảo VPS?

Bạn nên cân nhắc chuyển sang sử dụng máy chủ ảo VPS khi kịch bản tự động hóa cần hoạt động ổn định 24/7/365, cần tiếp nhận Webhook từ Internet theo thời gian thực hoặc phục vụ các quy trình quan trọng trong hoạt động kinh doanh của doanh nghiệp.

Kết luận

Áp dụng đúng cách cài đặt n8n trên Windows bằng Docker Desktop kết hợp WSL 2 mang lại cho bạn một môi trường phát triển workflow tự động hóa mạnh mẽ, an toàn và hoàn toàn độc lập. Hãy luôn tuân thủ nguyên tắc bảo mật khóa N8N_ENCRYPTION_KEY và định kỳ sao lưu dữ liệu volume trước các đợt cập nhật phiên bản.

Khi bạn đã thành thạo việc tạo workflow và muốn đưa vào vận hành thực tế không gián đoạn, việc chuyển dịch lên hạ tầng Cloud VPS với tính năng 1-Click cài đặt sẵn n8n của InterData sẽ là bước đi tối ưu nhất giúp tiết kiệm thời gian vận hành và nâng cao hiệu suất công việc.

Lưu ý kỹ thuật: Bài hướng dẫn được xây dựng dựa trên phiên bản Docker Desktop và n8n mới nhất tại thời điểm xuất bản. Trong quá trình cấu hình, hãy đảm bảo sao lưu file .env chứa N8N_ENCRYPTION_KEY cẩn thận. InterData không chịu trách nhiệm đối với các trường hợp mất dữ liệu credential do sơ suất xóa file môi trường hoặc xóa nhầm Docker volume.