خلاصه تصمیم: برای ربات تلگرام و وب‌هوک پرداخت، n8n باید روی VPS لینوکسی با دامنه، HTTPS، volume پایدار، فایروال و بک‌آپ بالا باشد — نه روی لپ‌تاپ. این راهنما مسیر Docker Compose + nginx + Let’s Encrypt را با دستور واقعی می‌دهد؛ همین مسیری که در پروژه‌های کوچک بارها جواب داده.

بخشی از خوشه‌ی اتوماسیون با n8n. اگر هنوز بین n8n و Make مرددید، اول ماتریس تصمیم را ببینید.

ترفند: همه‌ی دستورها را روی یک ساب‌دامین اختصاصی مثل n8n.yourdomain.com اجرا کنید. n8n را روی دامنه‌ی اصلی سایت فروشگاهی نگذارید — جداسازی، دیباگ و SSL را ساده‌تر می‌کند.

پیش‌نیازها و فرض‌ها

فرض این راهنما: دامنه را دارید، DNS به IP سرور پوینت شده، و روی سرور خارج از ایران یا دیتاسنتری با دسترسی پایدار به Docker Hub کار می‌کنید. اگر pull ایمیج از داخل ایران کند/قطع است، بخش «ایران و دانلود ایمیج» را جدی بگیرید.

گام ۰ — آماده‌سازی سرور

به‌عنوان کاربر با sudo:

sudo apt update && sudo apt -y upgrade
sudo apt -y install ca-certificates curl gnupg ufw fail2ban

کاربر غیر‌root (اگر ندارید):

sudo adduser n8nadmin
sudo usermod -aG sudo n8nadmin

از این به بعد با n8nadmin کار کنید.

گام ۱ — نصب Docker و Compose

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] 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 -y install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER

از SSH خارج شوید و دوباره وارد شوید تا گروه docker اعمال شود. تست:

docker version
docker compose version

عیب‌یابی: اگر permission denied روی ساکت داکر دیدید، یا relogin نکرده‌اید یا کاربر در گروه docker نیست: groups را چک کنید.

گام ۲ — فایروال (UFW) قبل از باز کردن سرویس

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status verbose

پورت ۵۶۷۸ n8n را به اینترنت باز نکنید. فقط nginx از localhost به آن وصل می‌شود.

ترفند امنیتی: اگر IP ثابت اداری دارید، SSH را با sudo ufw allow from YOUR.IP.TO.IP to any port 22 محدود کنید و قانون عمومی OpenSSH را حذف کنید.

گام ۳ — پوشه پروژه، کلید رمزنگاری، فایل‌های env

sudo mkdir -p /opt/n8n
sudo chown $USER:$USER /opt/n8n
cd /opt/n8n
mkdir -p n8n_data local-files

کلید رمزنگاری credential بسازید و نگه دارید — اگر عوض شود بدون بک‌آپ، credentialهای ذخیره‌شده می‌میرند:

openssl rand -hex 32

خروجی را در جای امن تیم ذخیره کنید. سپس:

nano /opt/n8n/.env

محتوای نمونه (مقادیر را عوض کنید):

# دامنه عمومی شما
N8N_HOST=n8n.example.com
N8N_PORT=5678
N8N_PROTOCOL=https
WEBHOOK_URL=https://n8n.example.com/

# منطقه زمانی گزارش تیم
GENERIC_TIMEZONE=Asia/Tehran
TZ=Asia/Tehran

# کلید رمزنگاری — همان خروجی openssl
N8N_ENCRYPTION_KEY=REPLACE_WITH_OPENSSL_HEX

# امنیت پایه UI
N8N_BASIC_AUTH_ACTIVE=false
N8N_USER_MANAGEMENT_DISABLED=false

# محدودیت‌های عملی
N8N_PAYLOAD_SIZE_MAX=16
EXECUTIONS_DATA_PRUNE=true
EXECUTIONS_DATA_MAX_AGE=168

نکته تصمیم: WEBHOOK_URL باید دقیقاً همان آدرس HTTPS عمومی باشد که تلگرام و درگاه می‌بینند. اشتباه رایج: گذاشتن http://IP:5678.

مجوز:

chmod 600 /opt/n8n/.env

گام ۴ — Docker Compose برای n8n

nano /opt/n8n/docker-compose.yml

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "127.0.0.1:5678:5678"
    env_file:
      - .env
    environment:
      - NODE_ENV=production
      - N8N_SECURE_COOKIE=true
    volumes:
      - ./n8n_data:/home/node/.n8n
      - ./local-files:/files
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:5678/healthz || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5

بالا آوردن:

cd /opt/n8n
docker compose pull
docker compose up -d
docker compose ps
docker compose logs -f --tail=100

با Ctrl+C از لاگ خارج شوید (کانتینر می‌ماند). تست لوکال:

curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5678/healthz

باید 200 ببینید.

ایران و دانلود ایمیج: اگر docker compose pull تایم‌اوت شد: (۱) از VPS با دسترسی پایدار به رجیستری استفاده کنید، (۲) ایمیج را روی ماشین دیگر pull و docker save کنید و با scp بفرستید، (۳) آینه‌ی مجاز ارائه‌دهنده را اگر دارد به کار بگیرید. این راهنما مسیر دور زدن فیلتر نیست — مسیر عملی انتقال ایمیج است.

پین کردن نسخه (پیشنهادی بعد از پایدار شدن):

docker images | grep n8n
# سپس در compose به‌جای latest بگذارید مثلاً n8n:1.XX.X

گام ۵ — nginx به‌عنوان reverse proxy

sudo apt -y install nginx
sudo nano /etc/nginx/sites-available/n8n

server {
    listen 80;
    listen [::]:80;
    server_name n8n.example.com;

    location / {
        proxy_pass http://127.0.0.1:5678;
        proxy_http_version 1.1;
        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 3600;
        proxy_buffering off;
    }
}

فعال‌سازی:

sudo ln -sf /etc/nginx/sites-available/n8n /etc/nginx/sites-enabled/n8n
sudo nginx -t
sudo systemctl reload nginx

DNS را چک کنید:

dig +short n8n.example.com
curl -I http://n8n.example.com

گام ۶ — SSL با Certbot (Let’s Encrypt)

sudo apt -y install certbot python3-certbot-nginx
sudo certbot --nginx -d n8n.example.com

پیشنهاد‌های certbot را برای redirect HTTP→HTTPS بپذیرید. تمدید خودکار معمولاً با systemd timer می‌آید؛ تست dry-run:

sudo certbot renew --dry-run

بعد از SSL، در مرورگر بروید به https://n8n.example.com و کاربر ادمین بسازید.

ترفند: بلافاصله بعد از ساخت ادمین، اگر نسخه گزینه‌ی دعوت/ثبت‌نام عمومی دارد، آن را قفل کنید. یک پنل n8n باز روی اینترنت = سطح حمله رایگان.

گام ۷ — سخت‌سازی سریع بعد از بالا آمدن

1. پسورد ادمین قوی + ذخیره در پسورد‌منیجر تیم
2. ۲FA را اگر در نسخه‌تان هست فعال کنید
3. توکن‌ها فقط داخل Credentials
4. fail2ban را برای ssh فعال نگه دارید:

sudo systemctl enable --now fail2ban
sudo fail2ban-client status sshd

1. مالکیت volume:

# اگر خطای permission روی /home/node/.n8n دیدید:
docker compose down
sudo chown -R 1000:1000 /opt/n8n/n8n_data
docker compose up -d

گام ۸ — تست وب‌هوک (قبل از تلگرام)

در n8n یک workflow موقت:

1. نود Webhook (Method: POST، path مثلاً hook-test)
2. نود Respond to Webhook با body {"ok":true}
3. Active کنید

از بیرون:

curl -X POST https://n8n.example.com/webhook/hook-test \
  -H "Content-Type: application/json" \
  -d '{"ping":1}'

باید {"ok":true} بگیرید. اگر ۴۰۴/۵۰۲: بخش عیب‌یابی پایین.

گام ۹ — بک‌آپ که واقعاً کار می‌کند

۹.۱ اسکریپت بک‌آپ روزانه

nano /opt/n8n/backup.sh

#!/usr/bin/env bash
set -euo pipefail
STAMP=$(date +%Y%m%d-%H%M)
DEST=/opt/n8n/backups/$STAMP
mkdir -p "$DEST"
cp /opt/n8n/.env "$DEST/env.gpg.tmp"
# بهتر: قبل از کپی، .env را با gpg رمز کنید؛ اینجا ساده نگه داشتیم
cp /opt/n8n/.env "$DEST/.env"
cp /opt/n8n/docker-compose.yml "$DEST/"
tar -C /opt/n8n -czf "$DEST/n8n_data.tgz" n8n_data
# نگه‌داری ۱۴ روز
find /opt/n8n/backups -mindepth 1 -maxdepth 1 -type d -mtime +14 -exec rm -rf {} \;
echo "Backup done: $DEST"

chmod 700 /opt/n8n/backup.sh
mkdir -p /opt/n8n/backups
/opt/n8n/backup.sh

Cron:

crontab -e
# هر روز ۰۳:۱۵ به وقت سرور
15 3 * * * /opt/n8n/backup.sh >> /var/log/n8n-backup.log 2>&1

۹.۲ Export ورک‌فلو از UI

Settings → Workflows → Download؛ فایل JSON را در ریپوی خصوصی یا درایو امن تیم بگذارید.

۹.۳ اسنپ‌شات VPS

قبل از هر آپدیت بزرگ ایمیج، از پنل ارائه‌دهنده اسنپ‌شات بگیرید.

ضد‌الگو: بک‌آپی که هرگز restore نشده. ماهی یک‌بار روی VPS تست، tar را باز کنید و ببینید n8n_data سالم است.

گام ۱۰ — آپدیت بدون غافلگیری

cd /opt/n8n
/opt/n8n/backup.sh
docker compose pull
docker compose up -d
docker compose logs --tail=50
curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:5678/healthz

بعد از آپدیت، webhook تست و یک workflow حیاتی را دستی Run کنید.

عیب‌یابی رایج (جدول جنگی)

لاگ nginx:

sudo tail -n 100 /var/log/nginx/error.log

وضعیت کانتینر:

docker compose -f /opt/n8n/docker-compose.yml logs -f n8n

نکات وب‌هوک تلگرام مخصوص ایران (سطح عملی)

• مسیر ترافیک تلگرام → سرور شما است؛ کیفیت دیتاسنتر و SSL مهم‌تر از ترفند کلاینت است.
• setWebhook را فقط روی https://n8n.example.com/webhook/... بزنید (مسیر واقعی نود).
• اگر گاهی Telegram API از سرور timeout می‌دهد، روی نودها Retry بگذارید و شکست را به گروه ادمین بفرستید.
• توکن BotFather را در چت گروهی و اسکرین‌شات نگذارید.

ادامه‌ی پروژه: ربات پشتیبانی تلگرام با n8n.

چک‌لیست نهایی «آماده‌ی تولید»

• [ ] https://n8n.example.com با قفل SSL باز می‌شود
• [ ] پورت ۵۶۷۸ از اینترنت بسته است (فقط 127.0.0.1)
• [ ] UFW فقط ۲۲/۸۰/۴۴۳
• [ ] .env مجوز ۶۰۰ و کلید encryption بک‌آپ شده
• [ ] volume n8n_data بعد از compose down/up داده را نگه می‌دارد
• [ ] webhook تست از بیرون ۲۰۰ می‌دهد
• [ ] backup.sh حداقل یک‌بار خروجی داده
• [ ] کاربر ادمین ساخته شده و ثبت‌نام عمومی قفل است

جمع‌بندی و مسیر بعدی

نصب موفق = آدرس پایدار + HTTPS + داده پایدار + فایروال + بک‌آپ. زیبایی UI اولویت چهارم است.

• تصویر بزرگ خوشه: اتوماسیون با n8n
• پروژه اول: ربات تلگرام
• هنوز مردد؟ n8n یا Make

اگر می‌خواهید همین مسیر را با یک پروژه‌ی واقعی و قدم‌به‌قدم جلو ببرید، دوره‌ی n8n همیار از راه‌اندازی سرور تا ساخت ورک‌فلو تولید را پوشش می‌دهد.