آموزش نصب n۸n روی VPS با Docker

n8n یکی از قدرتمندترین ابزارهای اتوماسیون گردش کار است و نسخه Self-Hosted آن بدون محدودیت تعداد اجرا روی سرور شما کار می‌کند. در این آموزش n8n را روی VPS با Docker نصب می‌کنیم؛ همراه با پایگاه داده PostgreSQL، Nginx و گواهی SSL رایگان Let’s Encrypt، رمزهای امن، بکاپ درست و روش به‌روزرسانی. در پایان یک نصب آماده محیط عملیاتی خواهید داشت.

چرا نصب با Docker Compose؟

n8n را می‌توان با npm هم نصب کرد، اما Docker Compose برای سرور مزیت‌های مهمی دارد: نسخه Node.js و وابستگی‌ها با سیستم‌عامل تداخل ندارند، n8n و دیتابیس با یک فایل تعریف و با یک دستور اجرا می‌شوند، به‌روزرسانی و بازگشت به نسخه قبل ساده است و کل نصب به سرور دیگر قابل انتقال است. اگر هنوز بین نسخه ابری و Self-Hosted تصمیم نگرفته‌اید، مقاله n8n Self-Hosted چیست را بخوانید.

پیش‌نیازها

• یک سرور مجازی با Ubuntu ۲۲.۰۴ یا ۲۴.۰۴، حداقل ۲ هسته و ۴ گیگابایت RAM. جزئیات منابع در منابع مورد نیاز n8n.
• یک ساب‌دامنه، مثلاً n8n.example.com، که رکورد A آن به IP سرور اشاره کند. اگر با تنظیم رکورد آشنا نیستید، DNS چیست را ببینید.
• تنظیمات امنیتی اولیه سرور، به‌خصوص ورود با کلید SSH و فایروال.

گام ۱: نصب Docker

Docker را از مخزن رسمی با اسکریپت نصب کنید:

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
docker compose version

بعد از دستور usermod یک بار از SSH خارج و دوباره وارد شوید. عضویت در گروه docker معادل دسترسی root است؛ فقط کاربران مورد اعتماد را به آن اضافه کنید.

گام ۲: فایل .env و رمزها

mkdir -p ~/n8n && cd ~/n8n
cat > .env <<EOF
N8N_DOMAIN=n8n.example.com
POSTGRES_PASSWORD=$(openssl rand -hex 24)
N8N_ENCRYPTION_KEY=$(openssl rand -hex 32)
EOF
chmod 600 .env

N8N_ENCRYPTION_KEY همه Credentialهای n8n را رمزنگاری می‌کند. یک نسخه از آن را در مدیر رمز عبور نگه دارید؛ بدون آن، بکاپ دیتابیس هم برای بازیابی Credentialها کافی نیست.

گام ۳: فایل docker-compose.yml

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

  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      DB_TYPE: postgresdb
      DB_POSTGRESDB_HOST: postgres
      DB_POSTGRESDB_DATABASE: n8n
      DB_POSTGRESDB_USER: n8n
      DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
      N8N_HOST: ${N8N_DOMAIN}
      N8N_PROTOCOL: https
      WEBHOOK_URL: https://${N8N_DOMAIN}/
      N8N_PROXY_HOPS: 1
      GENERIC_TIMEZONE: Asia/Tehran
      TZ: Asia/Tehran
      EXECUTIONS_DATA_PRUNE: "true"
      EXECUTIONS_DATA_MAX_AGE: 336
    volumes:
      - n8n_data:/home/node/.n8n
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  db_data:
  n8n_data:

• پورت n8n فقط روی 127.0.0.1 منتشر شده و فقط از طریق Nginx در دسترس است. این مهم است، چون پورت‌های منتشرشده Docker از فایروال UFW عبور می‌کنند. توضیح در امنیت Docker.
• WEBHOOK_URL باید دقیقاً آدرس HTTPS عمومی باشد؛ در غیر این صورت آدرس Webhookها با localhost ساخته می‌شود و سرویس‌های خارجی مثل تلگرام نمی‌توانند به آن پیام بفرستند.
• N8N_PROXY_HOPS به n8n می‌گوید پشت یک Reverse Proxy است تا IP واقعی کاربران را درست تشخیص دهد.
• تاریخچه اجراهای قدیمی‌تر از ۱۴ روز خودکار پاک می‌شود تا دیتابیس بی‌رویه بزرگ نشود.

گام ۴: Nginx و SSL

sudo apt install -y nginx certbot python3-certbot-nginx
sudo ufw allow 'Nginx Full'

فایل /etc/nginx/sites-available/n8n را بسازید:

server {
    listen 80;
    server_name n8n.example.com;

    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-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 300s;
        client_max_body_size 50m;
    }
}

sudo ln -s /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d n8n.example.com

Certbot گواهی را دریافت می‌کند، بخش HTTPS را به پیکربندی اضافه می‌کند و تمدید خودکار را تنظیم می‌کند. هدرهای Upgrade و Connection برای اتصال WebSocket ویرایشگر n8n ضروری‌اند؛ بدون آن‌ها ویرایشگر مدام خطای «Connection lost» نشان می‌دهد.

گام ۵: اجرا و ساخت حساب مدیر

cd ~/n8n
docker compose up -d
docker compose logs -f n8n

وقتی در لاگ پیام «Editor is now accessible» را دیدید، آدرس https://n8n.example.com را باز کنید و بلافاصله حساب مالک (Owner) را بسازید. تا قبل از ساخت این حساب، هر کسی که آدرس را باز کند می‌تواند مالک شود. سپس از تنظیمات حساب، احراز هویت دومرحله‌ای را فعال کنید. سایر تنظیمات امنیتی در امنیت n8n Self-Hosted آمده است.

بکاپ و به‌روزرسانی

بکاپ: کپی کردن پوشه داده PostgreSQL در حالی که دیتابیس در حال اجراست، ممکن است بکاپ ناسازگار و غیرقابل بازیابی تولید کند. از pg_dump استفاده کنید:

docker compose exec -T postgres pg_dump -U n8n n8n | gzip > ~/backups/n8n-$(date +%F).sql.gz

این دستور را در cron روزانه قرار دهید، نسخه‌ها را به محلی خارج از سرور منتقل کنید و فایل .env را هم جداگانه و امن نگه دارید. تفاوت بکاپ و Snapshot را در تفاوت Snapshot و Backup ببینید.

به‌روزرسانی: ابتدا بکاپ بگیرید، یادداشت‌های انتشار نسخه جدید را بخوانید و سپس:

docker compose pull
docker compose up -d

در محیط عملیاتی، به‌جای latest شماره نسخه مشخص بنویسید تا ارتقا آگاهانه و قابل بازگشت باشد.

رفع مشکلات رایج

• Webhook از بیرون کار نمی‌کند: WEBHOOK_URL را بررسی کنید و مطمئن شوید ورک‌فلو فعال (Active) است؛ آدرس Test فقط هنگام اجرای دستی در ویرایشگر فعال است.
• خطای Connection lost در ویرایشگر: هدرهای WebSocket در Nginx تنظیم نشده‌اند.
• n8n به دیتابیس وصل نمی‌شود: اگر رمز را بعد از اولین اجرا در .env تغییر داده‌اید، PostgreSQL هنوز رمز قبلی را دارد. رمز باید داخل دیتابیس هم تغییر کند.
• خطای ۴۱۳ هنگام آپلود فایل: مقدار client_max_body_size در Nginx را افزایش دهید.
• زمان اجرای زمان‌بندی‌ها اشتباه است: GENERIC_TIMEZONE را بررسی کنید.

سوالات متداول