Cài n8n trên VPS Ubuntu 24.04 bằng Docker Compose từ A-Z

SSH vào VPS Ubuntu 24.04 mới tinh, việc đầu tiên mình làm là cài ngay n8n để tự động hoá mớ công việc lặp đi lặp lại. Nếu bạn cũng cần một giải pháp automation mạnh mẽ, tự host được, không bị giới hạn workflow hay phụ thuộc vào bên thứ ba, thì cài n8n trên VPS bằng Docker Compose là con đường nhanh nhất. Bài này đi từ VPS trắng (không cài gì) đến n8n chạy production chỉ trong 15 phút.

Yêu cầu trước khi bắt đầu

• VPS chạy Ubuntu 24.04 LTS, có quyền sudo (hoặc root).
• Domain trỏ sẵn về IP VPS (nếu muốn dùng HTTPS, bài này dùng localhost cho cơ bản).
• Hiểu cơ bản về Docker Compose (file YAML, volume, biến môi trường).
• Mở port 5678 trên firewall (hoặc port bạn cấu hình cho n8n).

Vì sao nên dùng Docker Compose cho n8n?

N8n có thể cài trực tiếp bằng npm, nhưng dùng Docker Compose gói gọn mọi thứ, n8n, PostgreSQL (hoặc SQLite nếu muốn nhẹ), volume dữ liệu, network, vào một file cấu hình riêng biệt. Khi cần nâng cấp, rollback, hay di chuyển sang VPS khác, bạn chạy một lệnh là xong. Không phải lục tung thư mục cài đặt, không lo xung đột phiên bản Node.js. Đây là cách mình làm cho mọi dự án production: mỗi dịch vụ một container, quản lý qua Docker Compose.

Bước 1, Cài đặt Docker và Docker Compose

Docker phiên bản mới nhất trên Ubuntu 24.04 đã bao gồm Docker Compose plugin (lệnh docker compose, không phải docker-compose). Cập nhật hệ thống và cài Docker theo cách chuẩn của Docker Inc:

sudo apt update && sudo apt upgrade -y
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify:

sudo docker --version
sudo docker compose version

Output mong đợi: Docker version 27.x.x và Docker Compose version v2.x.x.

Sau cài, thêm user hiện tại vào group docker để chạy lệnh không cần sudo:

sudo usermod -aG docker $USER
newgrp docker

Bước 2, Tạo thư mục và file docker-compose.yml

Tạo thư mục riêng cho n8n và volume dữ liệu:

mkdir -p ~/n8n-docker
cd ~/n8n-docker
mkdir -p data

Tạo file docker-compose.yml:

nano docker-compose.yml

Dán nội dung sau, đây là file cấu hình sẵn sàng production của mình, bao gồm n8n + PostgreSQL làm database backend, volume riêng cho dữ liệu và thư mệu ~/.n8n để lưu workflow:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=change_this_to_strong_password
      - POSTGRES_DB=n8n
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U n8n"]
      interval: 10s
      timeout: 5s
      retries: 5

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "5678:5678"
    environment:
      - N8N_ENCRYPTION_KEY=your_random_encryption_key_here_change_it
      - N8N_WEBHOOK_URL=https://your-domain.com/
      - N8N_HOST=localhost
      - N8N_PORT=5678
      - N8N_PROTOCOL=http
      - N8N_METRICS=false
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=change_this_to_strong_password
      - GENERIC_TIMEZONE=Asia/Ho_Chi_Minh
    volumes:
      - ./data/n8n:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy
    links:
      - postgres

Giải thích các biến quan trọng:

• N8N_ENCRYPTION_KEY: khóa mã hoá credentials. Bắt buộc phải đặt, nếu để trống, n8n tự sinh, nhưng khi restart container sẽ mất key dẫn đến lỗi không decrypt được credentials. Dùng lệnh openssl rand -hex 32 để sinh key ngẫu nhiên.
• N8N_WEBHOOK_URL: URL public để n8n tiếp nhận webhook. Nếu bạn dùng domain HTTPS, đặt URL đầy đủ. Bài này mình để localhost cho môi trường thử nghiệm.
• GENERIC_TIMEZONE: múi giờ cho workflow và lịch biểu. Asia/Ho_Chi_Minh cho Việt Nam (UTC+7).
• DB_POSTGRESDB_PASSWORD: nhập cùng giá trị với POSTGRES_PASSWORD ở service postgres.

Thay your_random_encryption_key_here_change_it và change_this_to_strong_password bằng giá trị thật trước khi chạy.

Bước 3, Khởi chạy n8n

Chạy lệnh:

docker compose up -d

Lần đầu Docker sẽ pull image PostgreSQL và n8n, mất khoảng 1-2 phút tùy tốc độ mạng. Sau khi hoàn tất, kiểm tra trạng thái:

docker compose ps

Output mong đợi: cả hai container postgres và n8n đều ở trạng thái Up.

Kiểm tra log thử:

docker compose logs n8n

Cuối log sẽ có dòng n8n ready on port 5678 (hoặc tương tự).

Verify: Mở trình duyệt truy cập http://<IP-VPS>:5678. Nếu thấy giao diện đăng ký/đăng nhập của n8n, thành công. Nếu không, kiểm tra firewall.

Bước 4, Cấu hình firewall (UFW)

Nếu VPS dùng UFW (mặc định Ubuntu 24.04 có thể tắt, hãy bật lên):

sudo ufw allow 5678/tcp comment 'n8n web interface'
sudo ufw allow OpenSSH
sudo ufw --force enable
sudo ufw status verbose

Đảm bảo port 22 (SSH) và 5678 được phép. Các port khác (80, 443) tuỳ nhu cầu.

Xử lý lỗi thường gặp

Lỗi "ECONNREFUSED" khi n8n kết nối PostgreSQL

Nguyên nhân: PostgreSQL chưa kịp khởi tạo. Kiểm tra docker compose logs postgres xem có dòng database system is ready to accept connections không. Thêm healthcheck (như file trên) giúp n8n chờ đến khi DB sẵn sàng.

Lỗi "Encryption key missing" sau restart

Nguyên nhân: không đặt N8N_ENCRYPTION_KEY. N8n sinh key tự động và lưu vào volume. Nếu bạn xoá volume hoặc chạy container mới, key cũ mất, credentials không decrypt được. Giải pháp: luôn đặt key cố định từ đầu. Nếu đã lỡ, khôi phục từ bản backup volume cũ.

Port 5678 không truy cập được từ bên ngoài

Kiểm tra UFW (sudo ufw status), kiểm tra cloud firewall (nếu dùng VPS có firewall riêng như thueVPS thì vào control panel kiểm tra). Dùng ss -tlnp | grep 5678 xem n8n có listen trên 0.0.0.0:5678 không.

Câu hỏi thường gặp

Bài viết liên quan

• n8n là gì và những ai nên dùng?
• 10 workflow n8n hữu ích webmaster nên biết
• Thuê VPS n8n giá rẻ cài sẵn, hướng dẫn chi tiết