وقتی n8n را با Docker روی سرور نصب می‌کنید، اجرای اولیه برنامه تنها قدم اول است. پس از راه‌اندازی، ممکن است بخواهید منطقه زمانی را تغییر دهید، یک متغیر محیطی جدید اضافه کنید، تنظیمات اتصال را اصلاح کنید، وضعیت کانتینر را بررسی کنید یا سرویس را بدون از دست دادن اطلاعات به‌روزرسانی کنید.
برای انجام این کارها، آشنایی با Docker Compose اهمیت زیادی دارد.
Docker Compose ابزاری برای تعریف و مدیریت سرویس‌های کانتینری است. به‌جای اجرای چندین دستور طولانی Docker، می‌توانید تنظیمات سرویس‌ها را در یک فایل نگهداری کنید و با چند دستور، آن‌ها را اجرا، متوقف یا بازآفرینی کنید.
در این مقاله یاد می‌گیریم Docker Compose چگونه کار می‌کند، فایل compose.yaml چه کاربردی دارد، متغیرهای محیطی چگونه تنظیم می‌شوند و چگونه از حذف ناخواسته اطلاعات n8n جلوگیری کنیم.
۱. Docker Compose چیست و چه کاربردی دارد؟
فرض کنید n8n را روی سرور نصب کرده‌اید. برای اجرای آن باید تصویر نرم‌افزار، پورت‌ها، متغیرهای محیطی، محل ذخیره اطلاعات و سیاست راه‌اندازی مجدد را مشخص کنید.
اگر همه این تنظیمات را در دستورهای طولانی Docker وارد کنید، مدیریت و تغییر آن‌ها دشوار می‌شود.
Docker Compose این تنظیمات را در قالب یک فایل YAML نگهداری می‌کند.
برای مثال، یک سرویس ساده n8n می‌تواند به این شکل تعریف شود:
services:
n8n:
image: docker.n8n.io/n8nio/n8n
restart: unless-stopped
ports:
- "127.0.0.1:5678:5678"
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
این فایل به Docker Compose می‌گوید:
- از تصویر n8n استفاده کند.
- سرویس را در شرایط مناسب پس از توقف دوباره اجرا کند.
- پورت داخلی n8n را فقط روی Loopback سرور منتشر کند.
- اطلاعات برنامه را در یک Volume پایدار نگهداری کند.
نکته مهم این است که Docker Compose خودش جایگزین Docker Engine نیست؛ بلکه از Docker برای مدیریت سرویس‌های تعریف‌شده استفاده می‌کند.
مستندات رسمی: https://docs.docker.com/compose/
۲. فایل compose.yaml از چه بخش‌هایی تشکیل شده است؟
در فایل Compose، هر بخش مسئولیت مشخصی دارد. مهم‌ترین بخش‌هایی که در مدیریت n8n با آن‌ها سروکار خواهید داشت عبارت‌اند از:
| بخش | کاربرد |
|---|---|
services | تعریف سرویس‌هایی مانند n8n و PostgreSQL |
image | تعیین تصویر کانتینر |
ports | انتشار پورت‌های سرویس |
environment | تعریف متغیرهای محیطی |
env_file | خواندن متغیرها از فایل جداگانه |
volumes | نگهداری داده‌ها یا اتصال مسیرهای فایل‌سیستم |
restart | تعیین سیاست راه‌اندازی مجدد |
networks | تعریف ارتباط شبکه‌ای میان سرویس‌ها |
depends_on | مشخص کردن وابستگی ترتیب راه‌اندازی سرویس‌ها |
همه این گزینه‌ها برای هر نصب ضروری نیستند. برای مثال، اگر n8n به پایگاه داده خارجی متصل باشد، لزوماً نیازی به تعریف سرویس PostgreSQL در همان فایل ندارید.
۳. چگونه فایل Compose را ایجاد یا ویرایش کنیم؟
فرض می‌کنیم n8n در مسیر /opt/n8n نصب شده است.
ابتدا وارد پوشه شوید:
cd /opt/n8n
فایل‌های موجود را ببینید:
ls -la
اگر فایل compose.yaml وجود دارد، آن را باز کنید:
nano compose.yaml
اگر فایل با نام docker-compose.yml ذخیره شده باشد، می‌توانید همان فایل را ویرایش کنید. Docker Compose از هر دو نام متداول پشتیبانی می‌کند، اما بهتر است در هر پروژه یک فایل اصلی مشخص داشته باشید.
پس از ویرایش، پیش از اعمال تغییرات، پیکربندی را بررسی کنید:
docker compose config
این دستور تنظیمات Compose را پردازش می‌کند و به شناسایی برخی خطاهای ساختاری یا متغیرهای تعریف‌نشده کمک می‌کند.
اگر فایل در مسیر دیگری قرار دارد، ابتدا وارد همان پوشه شوید یا مسیر فایل را با گزینه -f مشخص کنید.
۴. متغیرهای محیطی در n8n چه هستند؟
متغیرهای محیطی یا Environment Variables به شما اجازه می‌دهند تنظیمات برنامه را بدون تغییر کد اصلی آن تعیین کنید.
برای مثال، n8n از متغیرهایی برای تنظیم منطقه زمانی، آدرس عمومی، نوع پایگاه داده و برخی قابلیت‌های اجرایی استفاده می‌کند.
نمونه:
services:
n8n:
image: docker.n8n.io/n8nio/n8n
environment:
- TZ=Asia/Tehran
- GENERIC_TIMEZONE=Asia/Tehran
در این مثال، منطقه زمانی محیط اجرا و منطقه زمانی عمومی مورد استفاده n8n تنظیم شده است.
بااین‌حال، همه متغیرهای محیطی کاربرد یکسانی ندارند. پیش از اضافه کردن هر متغیر، باید مستندات همان گزینه را بررسی کنید؛ زیرا ممکن است یک متغیر به نسخه مشخصی وابسته باشد یا فقط در شرایط خاص کاربرد داشته باشد.
مستندات رسمی متغیرهای محیطی n8n:
https://docs.n8n.io/hosting/configuration/environment-variables/
۵. چگونه متغیرهای محیطی را در فایل .env نگهداری کنیم؟
وقتی تعداد متغیرها زیاد می‌شود، قرار دادن همه آن‌ها در فایل Compose خوانایی فایل را کاهش می‌دهد.
در چنین شرایطی می‌توانید از فایل .env استفاده کنید.
برای ایجاد فایل:
cd /opt/n8n
nano .env
برای مثال، محتوای زیر را وارد کنید:
TZ=Asia/Tehran
GENERIC_TIMEZONE=Asia/Tehran
N8N_HOST=n8n.example.com
N8N_PROTOCOL=https
WEBHOOK_URL=https://n8n.example.com/
مقادیر دامنه در این مثال فرضی هستند و باید با دامنه واقعی شما جایگزین شوند.
سپس فایل Compose را به این شکل تنظیم کنید:
services:
n8n:
image: docker.n8n.io/n8nio/n8n
restart: unless-stopped
ports:
- "127.0.0.1:5678:5678"
environment:
TZ: ${TZ}
GENERIC_TIMEZONE: ${GENERIC_TIMEZONE}
N8N_HOST: ${N8N_HOST}
N8N_PROTOCOL: ${N8N_PROTOCOL}
WEBHOOK_URL: ${WEBHOOK_URL}
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
در این ساختار، Docker Compose مقادیر تعریف‌شده در فایل .env را در تنظیمات Compose جای‌گذاری می‌کند.
تفاوت .env و env_file چیست؟
این دو مفهوم شبیه یکدیگرند، اما دقیقاً یک کار انجام نمی‌دهند.
فایل .env کنار فایل Compose معمولاً برای جای‌گذاری متغیرها در خود فایل Compose استفاده می‌شود؛ مانند ${TZ}.
در مقابل، گزینه env_file در تعریف سرویس برای انتقال متغیرهای یک فایل به محیط اجرای کانتینر استفاده می‌شود.
برای مثال:
services:
n8n:
image: docker.n8n.io/n8nio/n8n
env_file:
- n8n-runtime.env
در این مثال، مقادیر فایل n8n-runtime.env به محیط اجرای کانتینر منتقل می‌شوند.
اگر از ${VARIABLE} در فایل Compose استفاده می‌کنید، باید مطمئن شوید Compose می‌تواند مقدار متغیر را از منبع مناسب پیدا کند.
مستندات رسمی Docker درباره متغیرها:
https://docs.docker.com/compose/how-tos/environment-variables/
نکته امنیتی درباره فایل .env
فایل .env ممکن است حاوی رمز عبور، توکن یا اطلاعات حساس باشد. بنابراین:
- دسترسی فایل را محدود کنید.
- آن را در مخزن عمومی Git قرار ندهید.
- نسخه پشتیبان آن را در محل امن نگهداری کنید.
- از قرار دادن رمزهای واقعی در نمونه کدهای آموزشی خودداری کنید.
برای محیط‌های حساس، استفاده از روش‌های مدیریت Secret متناسب با زیرساخت می‌تواند از نگهداری ساده رمزها در فایل‌های متنی مناسب‌تر باشد.
۶. Volume چیست و چرا برای n8n مهم است؟
کانتینرها را می‌توان حذف و دوباره ایجاد کرد. بنابراین، نباید اطلاعات مهم را صرفاً به لایه موقت کانتینر وابسته کنید.
Volume در Docker امکان نگهداری داده‌ها خارج از چرخه عمر کانتینر را فراهم می‌کند.
برای n8n معمولاً باید مسیر ذخیره اطلاعات برنامه به‌صورت پایدار نگهداری شود.
نمونه:
services:
n8n:
image: docker.n8n.io/n8nio/n8n
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
در این تنظیم، n8n_data نام Volume است و /home/node/.n8n مسیر داخل کانتینر محسوب می‌شود.
با اجرای Compose، اگر Volume وجود نداشته باشد، Docker آن را ایجاد می‌کند. اگر Volume موجود باشد و همان Volume به سرویس متصل شود، اطلاعات آن قابل استفاده مجدد خواهد بود.
چگونه Volumeهای موجود را بررسی کنیم؟
برای مشاهده Volumeها:
docker volume ls
برای مشاهده جزئیات یک Volume:
docker volume inspect N8N_VOLUME_NAME
به‌جای N8N_VOLUME_NAME باید نام واقعی Volume را قرار دهید.
نام نهایی Volume ممکن است با نام پروژه Compose ترکیب شده باشد؛ بنابراین آن را از خروجی دستور قبلی پیدا کنید.
آیا Volume همان نسخه پشتیبان است؟
خیر. Volume برای نگهداری پایدار داده‌ها است، اما به‌تنهایی از اطلاعات در برابر خرابی دیسک، حذف ناخواسته یا از دست رفتن سرور محافظت نمی‌کند.
برای سرویس عملیاتی باید برنامه پشتیبان‌گیری جداگانه داشته باشید و بازیابی اطلاعات را نیز آزمایش کنید.
۷. تفاوت Named Volume و Bind Mount چیست؟
در Docker Compose دو روش رایج برای اتصال داده‌ها به کانتینر وجود دارد.
روش اول: Named Volume
volumes:
- n8n_data:/home/node/.n8n
در این روش، Docker محل ذخیره‌سازی Volume را مدیریت می‌کند. این روش برای نگهداری داده‌های برنامه گزینه‌ای ساده و متداول است.
روش دوم: Bind Mount
volumes:
- /opt/n8n/data:/home/node/.n8n
در این روش، یک مسیر مشخص از سیستم‌عامل میزبان به مسیر داخل کانتینر متصل می‌شود.
Bind Mount زمانی مفید است که بخواهید مسیر فایل‌ها روی سرور را خودتان تعیین کنید یا به فایل‌ها از بیرون کانتینر دسترسی داشته باشید.
بااین‌حال، باید مجوزهای فایل و مالکیت مسیر را با کاربر اجراکننده n8n سازگار کنید. تنظیم نادرست مجوزها ممکن است باعث شود برنامه نتواند اطلاعات را بخواند یا بنویسد.
توصیه: اگر هدف شما فقط نگهداری پایدار داده‌های n8n است و نیاز خاصی به تعیین مسیر میزبان ندارید، Named Volume معمولاً انتخاب ساده‌تری است.
۸. چگونه سرویس n8n را با Docker Compose مدیریت کنیم؟
پس از نصب، نیازی نیست برای هر عملیات دوباره دستور طولانی اجرای کانتینر را بنویسید.
در پوشه‌ای که فایل Compose قرار دارد، می‌توانید از دستورهای زیر استفاده کنید.
مشاهده وضعیت سرویس
docker compose ps
این دستور وضعیت سرویس‌های تعریف‌شده در پروژه را نمایش می‌دهد.
مشاهده لاگ‌ها
docker compose logs --tail=100 n8n
برای مشاهده زنده لاگ‌ها:
docker compose logs -f n8n
این دستورات هنگام بررسی خطاهای راه‌اندازی، اتصال پایگاه داده یا مشکلات پیکربندی مفید هستند.
راه‌اندازی سرویس
docker compose up -d
گزینه -d باعث می‌شود سرویس در پس‌زمینه اجرا شود.
متوقف کردن سرویس
docker compose stop n8n
این دستور سرویس را متوقف می‌کند، اما کانتینر و Volumeهای آن را برای استفاده مجدد نگه می‌دارد.
شروع دوباره سرویس متوقف‌شده
docker compose start n8n
راه‌اندازی مجدد سرویس
docker compose restart n8n
توجه داشته باشید که restart برای اعمال هر نوع تغییر پیکربندی کافی نیست. اگر متغیر محیطی یا تنظیمات تعریف‌شده در Compose را تغییر داده‌اید، معمولاً باید سرویس را با پیکربندی جدید بازآفرینی کنید.
۹. چگونه تغییرات Compose را اعمال کنیم؟
فرض کنید مقدار منطقه زمانی را تغییر داده‌اید یا متغیر جدیدی به فایل اضافه کرده‌اید.
ابتدا فایل‌ها را ذخیره کنید و تنظیمات نهایی را بررسی کنید:
docker compose config
سپس سرویس را با تنظیمات جدید بازآفرینی کنید:
docker compose up -d
Docker Compose تغییرات پیکربندی را تشخیص می‌دهد و در صورت نیاز کانتینر را بازسازی می‌کند. اگر داده‌ها در Volume مناسب نگهداری شوند، بازآفرینی کانتینر به‌خودی‌خود به معنی حذف آن داده‌ها نیست.
برای مشاهده وضعیت بعد از تغییر:
docker compose ps
docker compose logs --tail=100 n8n
اگر سرویس به‌درستی اجرا نشد، تنظیمات جدید و پیام خطا را بررسی کنید.
هشدار: قبل از تغییرات مهم روی محیط عملیاتی، نسخه پشتیبان تهیه کنید. همچنین از دستورهای پاک‌سازی گسترده یا حذف Volumeها بدون شناخت اثر آن‌ها استفاده نکنید.
۱۰. چگونه n8n و PostgreSQL را در یک Compose مدیریت کنیم؟
در پروژه‌های بزرگ‌تر ممکن است بخواهید n8n و PostgreSQL را در یک پروژه Compose اجرا کنید.
در این حالت، دو سرویس در یک فایل تعریف می‌شوند و می‌توانند از طریق شبکه داخلی Compose با یکدیگر ارتباط برقرار کنند.
نمونه ساده ساختار:
services:
n8n:
image: docker.n8n.io/n8nio/n8n
restart: unless-stopped
environment:
DB_TYPE: postgresdb
DB_POSTGRESDB_HOST: postgres
DB_POSTGRESDB_PORT: 5432
DB_POSTGRESDB_DATABASE: n8n
DB_POSTGRESDB_USER: n8n
DB_POSTGRESDB_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- n8n_data:/home/node/.n8n
depends_on:
- postgres
postgres:
image: postgres:16
restart: unless-stopped
environment:
POSTGRES_DB: n8n
POSTGRES_USER: n8n
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
volumes:
n8n_data:
postgres_data:
این نمونه برای توضیح ساختار است و پیش از استفاده واقعی باید با نسخه‌های پشتیبانی‌شده، متغیرهای مستندشده n8n، سیاست سلامت سرویس و نیازهای امنیتی شما تطبیق داده شود.
چند نکته مهم:
- فایل
.envباید مقدار مناسبPOSTGRES_PASSWORDرا داشته باشد. - رمز واقعی نباید در مخزن عمومی ذخیره شود.
- در این نمونه، پورت PostgreSQL به میزبان منتشر نشده است؛ سرویس n8n از نام سرویس
postgresبرای اتصال داخلی استفاده می‌کند. depends_onبه‌تنهایی تضمین نمی‌کند PostgreSQL کاملاً آماده پذیرش اتصال باشد.- برای محیط عملیاتی، Healthcheck و سیاست مدیریت خطا را در نظر بگیرید.
- پیش از انتقال نصب موجود از SQLite به PostgreSQL، باید برای مهاجرت داده‌ها برنامه‌ریزی کنید؛ تغییر متغیرهای اتصال به‌تنهایی داده‌های قبلی را منتقل نمی‌کند.
مستندات تنظیمات پایگاه داده n8n:
https://docs.n8n.io/hosting/configuration/environment-variables/database/
۱۱. چگونه خطاهای رایج Docker Compose را برطرف کنیم؟
خطای YAML یا پیکربندی نامعتبر
اگر تورفتگی‌ها یا ساختار فایل YAML اشتباه باشند، ممکن است Compose نتواند فایل را پردازش کند.
دستور زیر را اجرا کنید:
docker compose config
ساختار بخش‌ها، تورفتگی‌ها، نام متغیرها و علامت‌های نقل‌قول را بررسی کنید.
متغیر محیطی خالی است
اگر مقدار یک متغیر در فایل Compose تعریف نشده باشد، ممکن است مقدار نهایی آن خالی شود یا هشدار دریافت کنید.
برای مثال، اگر نوشته باشید:
environment:
WEBHOOK_URL: ${WEBHOOK_URL}
اما متغیر WEBHOOK_URL در محیط یا فایل .env موجود نباشد، پیکربندی نهایی مطابق انتظار شما نخواهد بود.
وجود متغیر را بررسی کنید و سپس خروجی docker compose config را ببینید. هنگام بررسی خروجی، مراقب باشید مقادیر محرمانه در ترمینال یا لاگ‌های اشتراکی افشا نشوند.
کانتینر در وضعیت Restarting است
ابتدا لاگ‌های سرویس را ببینید:
docker compose logs --tail=200 n8n
دلایل احتمالی می‌تواند شامل تنظیمات نامعتبر، خطای اتصال به پایگاه داده، مشکل مجوزهای فایل یا ناسازگاری پیکربندی باشد.
اطلاعات پس از بازآفرینی کانتینر ناپدید شده‌اند
Volume متصل به سرویس را بررسی کنید. ممکن است کانتینر جدید از Volume دیگری استفاده کند یا تنظیمات ذخیره‌سازی تغییر کرده باشند.
از حذف و ساخت مجدد Volume برای رفع سریع مشکل خودداری کنید؛ این کار می‌تواند بازیابی اطلاعات را دشوارتر کند.
پورت در دسترس نیست
اگر پورت موردنظر قبلاً توسط سرویس دیگری استفاده شده باشد، Compose ممکن است نتواند آن را منتشر کند.
برای بررسی پورت 5678 روی سرور:
sudo ss -ltnp | grep 5678
اگر n8n را پشت Reverse Proxy قرار داده‌اید، بررسی کنید پورت داخلی و آدرس انتشار آن با معماری شبکه هماهنگ باشد.
۱۲. نکات مهم برای مدیریت امن n8n
مدیریت صحیح Compose فقط به اجرای دستورها محدود نمی‌شود. برای استفاده عملیاتی، این نکات را رعایت کنید:
- پورت‌ها: پنل مدیریتی را بدون نیاز واقعی روی اینترنت منتشر نکنید.
- رمزها: اطلاعات حساس را در مخزن عمومی یا فایل‌های قابل‌دسترسی همگانی قرار ندهید.
- Volumeها: پیش از حذف یا تغییر مسیر آن‌ها، اثر کار را بررسی کنید.
- به‌روزرسانی: نسخه مورد استفاده را آگاهانه انتخاب کنید و پیش از ارتقا پشتیبان بگیرید.
- لاگ‌ها: هنگام ارسال لاگ برای عیب‌یابی، توکن‌ها و اطلاعات محرمانه را حذف کنید.
- پشتیبان‌گیری: فقط به نگهداری داده‌ها در Volume اکتفا نکنید؛ بازیابی نسخه پشتیبان را نیز آزمایش کنید.
- دسترسی‌ها: دسترسی مدیریتی به سرور و پنل n8n را محدود کنید.
اگر چندین سرویس روی یک سرور دارید، بهتر است برای هر پروژه ساختار پوشه، نام‌گذاری، شبکه و سیاست پشتیبان‌گیری مشخصی تعریف کنید تا مدیریت و عیب‌یابی آسان‌تر شود.
پرسش‌های متداول
آیا برای مدیریت n8n باید هر بار کانتینر را حذف کنم؟
خیر. برای عملیات معمول مانند مشاهده لاگ‌ها، توقف و شروع سرویس، دستورهای Docker Compose کافی هستند. برای اعمال تغییرات پیکربندی نیز معمولاً می‌توانید از docker compose up -d استفاده کنید.
آیا تغییر فایل Compose اطلاعات n8n را پاک می‌کند؟
ویرایش فایل به‌تنهایی اطلاعات را پاک نمی‌کند. بااین‌حال، اگر Volume حذف شود، مسیر ذخیره‌سازی تغییر کند یا سرویس به محل داده دیگری متصل شود، ممکن است اطلاعات قبلی در دسترس نباشند.
آیا فایل .env برای نگهداری رمزها کاملاً امن است؟
خیر. فایل .env ابزار ساده‌ای برای مدیریت تنظیمات است، اما اگر حاوی رمز باشد باید دسترسی آن محدود شود و نباید در مخزن عمومی قرار بگیرد. برای محیط‌های حساس، روش مدیریت Secret مناسب زیرساخت را بررسی کنید.
تفاوت stop و down چیست؟
docker compose stop سرویس‌ها را متوقف می‌کند و کانتینرها را برای شروع مجدد نگه می‌دارد.
docker compose down کانتینرها و شبکه‌های ایجادشده توسط Compose را حذف می‌کند؛ اما Named Volumeها به‌طور معمول با این دستور حذف نمی‌شوند، مگر اینکه گزینه حذف Volume نیز استفاده شود. بنابراین قبل از اجرای دستورهای حذف، اثر آن‌ها را بررسی کنید.
آیا می‌توان چند سرویس را با یک فایل Compose مدیریت کرد؟
بله. می‌توانید سرویس‌هایی مانند n8n، PostgreSQL و ابزارهای جانبی را در یک فایل تعریف کنید. بااین‌حال، نحوه اتصال شبکه‌ای، ذخیره‌سازی و وابستگی‌ها باید مطابق معماری پروژه طراحی شود.
جمع‌بندی
Docker Compose ابزار مهمی برای مدیریت نصب n8n است. با استفاده از فایل compose.yaml می‌توانید سرویس‌ها، متغیرهای محیطی، شبکه‌ها و Volumeها را به‌شکل منظم تعریف کنید.
برای مدیریت روزمره، دستورهایی مانند docker compose ps، docker compose logs، docker compose stop و docker compose up -d بسیار کاربردی هستند. مهم‌تر از همه، باید میان تنظیمات سرویس و داده‌های پایدار تفاوت قائل شوید و پیش از تغییرات مهم، از اطلاعات خود پشتیبان بگیرید.
پس از تسلط بر این مفاهیم، می‌توانید سراغ تنظیمات پیشرفته‌تر n8n، پایگاه داده PostgreSQL، Reverse Proxy و مدیریت سرویس‌های متعدد بروید.
