Hướng dẫn cài đặt N8N Queue Mode trên Production

n8n là nền tảng workflow automation mã nguồn mở, cho phép xây dựng quy trình tích hợp kéo‑thả, tự host để kiểm soát dữ liệu và chi phí. Trong Production, thay vì chạy Standalone (mọi thứ xử lý trên một tiến trình), Queue Mode tách biệt điều phối và thực thi: job được đẩy vào Redis, nhiều worker xử lý song song, dễ scale ngang, ổn định hơn, cô lập sự cố tốt hơn và nâng thông lượng đáng kể. Đây là lựa chọn phù hợp khi cần hiệu năng cao, độ sẵn sàng tốt và khả năng mở rộng linh hoạt.

Bài viết này hướng dẫn đầy đủ cách cài đặt và triển khai N8N ở Queue Mode trên Ubuntu, bao gồm các bước cài đặt Docker, Docker Compose, cấu hình PostgreSQL, Redis, Nginx reverse proxy cơ bản (tùy chọn) và scale worker để xử lý song song.

Yêu cầu hệ thống

• Ubuntu 20.04/22.04 LTS (user có quyền sudo)
• Cổng mạng trống: 5678 (N8N), 6379 (Redis – có thể giữ internal), 5432 (Postgres – nên internal)
• RAM khuyến nghị: 2GB+ cho môi trường dev/test; production tùy tải

---

Bước 1: Cài đặt Docker trên Ubuntu

• Cập nhật hệ thống:

sudo apt update && sudo apt upgrade -y

• Cài đặt gói phụ trợ:

apt-get update

apt-get install \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common -y

• Thêm Docker GPG key và repo:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -

apt-key fingerprint 0EBFCD88

add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
   $(lsb_release -cs) \
   stable"

• Cài Docker Engine, CLI, containerd:

apt-get update -y 
apt-get -y  install docker-ce docker-ce-cli containerd.io

• Bật và kiểm tra Docker:

sudo systemctl restart docker
sudo systemctl enable  docker
sudo systemctl status docker
sudo docker version
sudo docker run --rm hello-world

• (Tùy chọn) Cho phép chạy Docker không cần sudo:

sudo usermod -aG docker $USER
newgrp docker

---

Bước 2: Cài đặt Docker Compose

Docker Compose V2 đã tích hợp vào docker CLI dưới dạng plugin “docker compose” trên các bản cài đặt mới. Nếu hệ thống chưa có plugin, có thể cài nhanh bản standalone:

• Nếu chưa có, cài bản standalone (chọn phiên bản ổn định):

version="v2.39.1"
curl -L  https://github.com/docker/compose/releases/download/$version/docker-compose-linux-x86_64  -o /usr/local/bin/docker-compose \
&& chmod +x /usr/local/bin/docker-compose \
&& docker-compose --version

Lưu ý: Trong bài này, dùng “docker-compose” cho nhất quán; nếu đã có plugin, có thể thay bằng “docker compose”.

---

Bước 3: Chuẩn bị thư mục dự án và file docker-compose.yml

• Tạo file docker-compose.yml với nội dung sau (đã hiệu chỉnh một vài chi tiết để phù hợp Ubuntu/production cơ bản):

services:
  postgres:
    image: postgres:16
    restart: always
    environment:
      - POSTGRES_USER=n8n
      - POSTGRES_PASSWORD=strongpassword
      - POSTGRES_DB=n8n
    volumes:
      - postgres-data:/var/lib/postgresql/data

  redis:
    image: redis:latest
    restart: always
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    command: ["redis-server", "--appendonly", "yes"]

  n8n:
    image: n8nio/n8n:latest
    restart: always
    ports:
      - "5678:5678"
    depends_on:
      - postgres
      - redis
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=strongpassword
      - N8N_ENCRYPTION_KEY=longsecretkeychangeit
      - N8N_HOST=n8n.local
      - N8N_PROTOCOL=http
      - WEBHOOK_URL=http://n8n.local:5678/

      # Queue Mode
      - N8N_QUEUE_MODE=true
      - EXECUTIONS_MODE=queue
      - N8N_RUNNERS_ENABLED=true
      - OFFLOAD_MANUAL_EXECUTIONS_TO_WORKERS=true
      - QUEUE_MODE=redis
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379

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

  n8n-worker:
    image: n8nio/n8n:latest
    restart: always
    depends_on:
      - postgres
      - redis
    command: worker
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_PORT=5432
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n
      - DB_POSTGRESDB_PASSWORD=strongpassword
      - N8N_QUEUE_MODE=true
      - N8N_RUNNERS_ENABLED=true
      - QUEUE_MODE=redis
      - QUEUE_BULL_REDIS_HOST=redis
      - QUEUE_BULL_REDIS_PORT=6379
      - EXECUTIONS_PROCESS_CONCURRENCY=10  # Mỗi worker xử lý 10 job song song
      - N8N_ENCRYPTION_KEY=longsecretkeychangeit

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

volumes:
  postgres-data:
  redis-data:
  n8n-data:

Ghi chú nhanh:

• Redis và Postgres không publish port ra ngoài để tăng bảo mật, truy cập nội bộ qua mạng Docker.
• N8N bind 127.0.0.1:5678 để chỉ lộ cổng trên localhost; khuyến nghị đặt reverse proxy ở phía trước.

---

Bước 4: Khởi chạy N8N Queue Mode

• Chạy nền:

docker-compose up -d

• Kiểm tra tình trạng:

docker-compose ps
docker-compose logs -f n8n

• Truy cập giao diện:
• Nếu chạy trên máy cục bộ: http://localhost:5678
• Nếu chạy trên server: cấu hình reverse proxy hoặc SSH tunnel để truy cập an toàn.

---

Bước 5: Scale worker để tăng thông lượng

Có thể tăng số lượng worker theo tải thực tế:

docker-compose up -d --scale n8n-worker=3

Mỗi worker có thể xử lý song song theo biến EXECUTIONS_PROCESS_CONCURRENCY, điều chỉnh phù hợp CPU/RAM.

---

(Tùy chọn) Bước 6: Cấu hình Nginx Reverse Proxy + Firewall

• Cài Nginx:

sudo apt install -y nginx

• Tạo server block đơn giản (HTTP demo – production nên bật HTTPS với Certbot):

sudo tee /etc/nginx/sites-available/n8n.conf > /dev/null <<'EOF'
server {
    listen 80;
    server_name n8n.local;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
EOF

• Kích hoạt cấu hình:

sudo ln -s /etc/nginx/sites-available/n8n.conf /etc/nginx/sites-enabled/n8n.conf
sudo nginx -t && sudo systemctl reload nginx

• Cập nhật DNS/hosts để trỏ n8n.local (hoặc domain thật) tới server:

# máy client (tạm thời cho dev)
# Mac/Linux:
echo "SERVER_IP n8n.local" | sudo tee -a /etc/hosts
# Windows: chỉnh C:\Windows\System32\drivers\etc\hosts

• Mở firewall cần thiết (ví dụ UFW):

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
sudo ufw status

• Bật HTTPS với Certbot (khuyến nghị production):

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Đừng quên cập nhật biến môi trường N8N_HOST, N8N_PROTOCOL=https, WEBHOOK_URL=https://your-domain.com/ khi đã dùng HTTPS.

---

Thực hành tốt cho Production

• Đổi ngay mật khẩu DB và N8N_ENCRYPTION_KEY bằng giá trị mạnh; dùng Docker secrets hoặc biến môi trường bên ngoài repo.
• Backup định kỳ: volume postgres-data, redis-data, n8n-data.
• Giám sát: tích hợp Prometheus/Grafana hoặc ELK, theo dõi log workers và hàng đợi Redis.
• Cập nhật định kỳ image: docker-compose pull && docker-compose up -d.
• Giới hạn tài nguyên: dùng deploy.resources (Swarm) hoặc –cpus/–memory với Docker Compose v2 profiles nếu cần.

---

Khắc phục sự cố nhanh

• N8N không lên cổng 5678:
• Kiểm tra logs: docker-compose logs -f n8n
• Kiểm tra biến N8N_HOST, WEBHOOK_URL, xung đột cổng
• Workflow không chạy/treo:
• Kiểm tra Redis đang hoạt động: docker-compose logs -f redis
• Worker có kết nối Redis: QUEUE_BULL_REDIS_HOST/PORT đúng
• Lỗi database:
• DB_* khớp với service postgres, volume còn dung lượng, logs postgres

---

Kết luận

Kết lại, triển khai n8n ở Queue Mode trên Ubuntu với Docker Compose mang lại nền tảng tự động hóa ổn định, dễ mở rộng và tối ưu chi phí vận hành. Kiến trúc tách biệt UI/điều phối với worker giúp xử lý song song, cô lập sự cố và tăng thông lượng rõ rệt, phù hợp cho Production. Hãy bắt đầu với cấu hình cơ bản trong bài, sau đó bổ sung reverse proxy, HTTPS, backup và giám sát để hệ thống vận hành an toàn, bền vững và sẵn sàng scale theo nhu cầu thực tế. Nếu cần, mình có thể tiếp tục với hướng dẫn hardening bảo mật, CI/CD và chiến lược autoscaling worker.

What is n8n? Install n8n pro full license