SSD Nodes Learn Hosting plans →
راهنماها Matt Connorتوسط Matt Connor

آموزش نصب Chatwoot روی VPS با Docker و Traefik

راهنمای کامل نصب Chatwoot با Docker Compose. یاد بگیرید چگونه با تنظیم دقیق SMTP، پیکربندی Postgres و استراتژی‌های بک‌آپ، یک سرویس پایدار و قابل ارتقا روی سرور خود راه‌اندازی کنید.

آنچه می‌سازید

برای میزبانی Chatwoot روی یک VPS، شما چهار کانتینر را اجرا می‌کنید: یک پردازش وب Rails، یک worker پس‌زمینه Sidekiq، دیتابیس PostgreSQL با افزونه pgvector و Redis. از آنجا که Chatwoot یک میز پشتیبانی مشتری متن‌باز است، شما یک صندوق ورودی تیمی مشترک و یک ویجت چت وب‌سایت روی سروری که کنترل آن را در دست دارید، خواهید داشت. نصب آن حدود 20 دقیقه زمان می‌برد. هر آنچه پس از آن می‌آید، یعنی ارسال ایمیل، پشتیبان‌گیری، ارتقا و تعیین ابعاد، همان چیزی است که مشخص می‌کند آیا این سرویس یک سال بعد همچنان فعال خواهد بود یا خیر.

هر کانتینر یک وظیفه مشخص دارد. Rails داشبورد اپراتور و API (رابط برنامه‌نویسی اپلیکیشن) ویجت را سرویس‌دهی می‌کند. Sidekiq کارهای زمان‌بر را انجام می‌دهد: ارسال ایمیل، بررسی کانال‌های متصل، اجرای قوانین اتوماسیون و تهیه گزارش‌ها. Postgres مکالمات، مخاطبین، حساب‌های اپراتور و تمام تنظیماتی که در داشبورد تغییر می‌دهید را ذخیره می‌کند. Redis صف‌های Sidekiq و کانال pub/sub مربوط به ActionCable را نگه می‌دارد که پیام‌های جدید را بدون نیاز به رفرش صفحه، به داشبورد باز ارسال می‌کند. در اینجا Redis یک کش موقت نیست، زیرا از دست دادن آن به معنای از دست رفتن کارهای در صف است.

ایمیج Postgres در فایل compose اصلی، pgvector/pgvector:pg16 است و نه ایمیج استاندارد postgres، زیرا طرح‌واره (schema) Chatwoot برای ویژگی‌های هوش مصنوعی خود، افزونه vector را فعال می‌کند. اگر از Postgres استاندارد استفاده کنید، اولین اجرای دیتابیس با خطای ERROR: extension "vector" is not available متوقف می‌شود، زیرا فایل کنترل این افزونه در آن ایمیج وجود ندارد. از همان ایمیجی استفاده کنید که در نسخه اصلی ارائه شده است.

این راهنما فرض می‌کند که Docker و یک reverse proxy از قبل روی سرور شما فعال هستند. اگر این‌طور نیست، ابتدا با Docker Compose روی یک VPS شروع کنید و سپس به اینجا بازگردید.

سرویس Chatwoot برای میزبانی شخصی به چه میزان منابع VPS نیاز دارد؟

تا اکتبر 2026، صفحه نیازمندی‌های رسمی، حداقل 4 گیگابایت رم و 4 هسته CPU را برای مدیریت حداکثر 10,000 گفتگو در روز توصیه می‌کند. برای 20,000 گفتگو در روز، 8 گیگابایت رم و 8 هسته پیشنهاد شده است. همچنین حداقل 1 گیگابایت Swap الزامی است تا در هنگام ارتقای نسخه، سرور با کمبود حافظه مواجه نشود. پیش از در نظر گرفتن فایل‌های آپلود شده، 5 تا 10 گیگابایت فضا برای Postgres اختصاص دهید.

واقعیت این است که یک VPS با 2 گیگابایت رم، Chatwoot را بالا می‌آورد و با دو اپراتور و ترافیک کم، مشکلی ندارد. اما در دو حالت دچار مشکل می‌شود. اول Sidekiq که در سرورهای شلوغ بیش از 1 گیگابایت رم مصرف می‌کند؛ بنابراین یک موج ایمیل یا اجرای گزارش، حافظه را پیش از سهم Rails، Postgres و Redis پر می‌کند. دوم هنگام ارتقا است، زیرا db:chatwoot_prepare یک پروسه جدید Rails برای اعمال migrationها اجرا می‌کند و بوت شدن Rails در این ایمیج، پیش از انجام هر کاری، صدها مگابایت رم مصرف می‌کند.

در این شرایط هشدار مودبانه‌ای دریافت نمی‌کنید. قابلیت OOM killer در هسته سیستم‌عامل، سیگنال SIGKILL را به پروسه انتخاب‌شده (معمولاً بزرگ‌ترین پروسه) می‌فرستد، Docker متوجه توقف کانتینر می‌شود و restart: always آن را دوباره اجرا می‌کند. سپس docker compose ps --all نشان می‌دهد که کانتینر مدام در حال ری‌استارت شدن است یا در وضعیت Exited (137) گیر کرده؛ کد 137 به معنای کشته شدن توسط سیگنال 9 است. بدون --all، کانتینر متوقف‌شده اصلاً نمایش داده نمی‌شود. کد خروج 137 به‌تنهایی ثابت نمی‌کند که علت کمبود حافظه بوده، زیرا docker kill نیز همین سیگنال را می‌فرستد؛ بنابراین با استفاده از sudo dmesg -T | grep -i "killed process" که نام پروسه انتخاب‌شده توسط هسته را نشان می‌دهد، موضوع را تأیید کنید.

اگر بودجه کافی برای 4 گیگابایت رم ندارید، از یک سرور 2 گیگابایتی با 2 گیگابایت Swap استفاده کنید و بپذیرید که زمان پاسخ‌دهی تحت فشار کاهش می‌یابد. Swap یک بافر برای جلوگیری از اتمام حافظه است، نه تضمین قطعی؛ بنابراین یک جهش ناگهانی در ترافیک همچنان می‌تواند باعث کشته شدن کانتینر شود. در هر صورت، تعیین سقف سخت‌گیرانه حافظه برای هر سرویس توصیه می‌شود تا پروسه worker باعث از کار افتادن دیتابیس نشود. به محدودیت‌های حافظه در Docker Compose مراجعه کنید.

فایل‌های آپلود شده بخشی هستند که بدون محدودیت رشد می‌کنند. هر اسکرین‌شاتی که مشتری پیوست می‌کند در volume ذخیره‌سازی قرار می‌گیرد و باقی می‌ماند؛ بنابراین به‌جای فرض اینکه دیتابیس دیسک را پر کرده، docker system df -v را مانیتور کنید.

دریافت فایل compose و تعیین نسخه (pin)

mkdir -p ~/chatwoot && cd ~/chatwoot
wget -O .env https://raw.githubusercontent.com/chatwoot/chatwoot/develop/.env.example
wget -O docker-compose.yaml https://raw.githubusercontent.com/chatwoot/chatwoot/develop/docker-compose.production.yaml
chmod 600 .env

فایلی که به‌تازگی دانلود کرده‌اید حاوی image: chatwoot/chatwoot:latest است. پیش از انجام هر کاری، آن را تغییر دهید.

services:
  base: &base
    image: chatwoot/chatwoot:v4.19.1
    env_file: .env
    volumes:
      - storage_data:/app/storage

استفاده از latest باعث می‌شود در اجرای بعدی docker compose pull، هر نسخه‌ای که همان روز منتشر شده است دریافت شود؛ این نسخه ممکن است یک نسخه اصلی (major) با تغییرات ساختاری (migration) باشد که شما از آن بی‌اطلاع هستید. تغییرات دیتابیس در Chatwoot عملاً غیرقابل بازگشت هستند، بنابراین یک ارتقای ناخواسته به معنای بازگردانی از نسخه پشتیبان است، نه یک عملیات undo ساده. نسخه را ثابت (pin) کنید و ارتقا را به‌صورت آگاهانه انجام دهید. نسخه v4.19.1 آخرین نسخه منتشرشده تا تاریخ 25 اکتبر 2026 است و یادداشت‌های انتشار آن، این نسخه را برای دریافت آخرین اصلاحات امنیتی و بهبودهای مقاوم‌سازی توصیه می‌کنند؛ برای اطلاع از نسخه‌ای که باید امروز ثابت کنید، صفحه نسخه‌ها را بررسی کنید. اگر از نسخه v4.18.0 یا قدیمی‌تر ارتقا می‌دهید، ابتدا یادداشت‌های v4.19.0 را بخوانید: Captain V1 بازنشسته شده است و نصب‌های self-hosted که از دستورالعمل‌های V1 استفاده می‌کنند، باید پیش از ارتقا، آن‌ها را به V2 مهاجرت دهند. هر سرویسی که دیتابیس دارد نیازمند همین سطح از احتیاط است؛ به همین دلیل است که میزبانی شخصی ردیاب تمرین openGym با ثابت کردن یک git tag آغاز می‌شود، حتی اگر آن برنامه بسیار کوچک‌تر از این مورد باشد.

سرویس base یک YAML anchor است که rails و sidekiq هر دو آن را ادغام (merge) می‌کنند، بنابراین تغییر تگ در یک نقطه، برای هر دو اعمال می‌شود. در حالی که فایل را باز کرده‌اید، خط version: '3' را در ابتدای فایل حذف کنید. نسخه‌های مدرن Compose این خط را نادیده می‌گیرند و با هر دستور، the attribute 'version' is obsolete, it will be ignored را چاپ می‌کنند.

تکمیل فایل .env

ابتدا مقدار secret را تولید کنید. توسعه‌دهندهٔ اصلی یک مقدار الفبایی-عددی (alphanumeric) توصیه می‌کند، زیرا کاراکترهای خاص هنگام عبور از shell یا parserهای YAML دچار مشکل می‌شوند.

head /dev/urandom | tr -dc A-Za-z0-9 | head -c 63 ; echo ''

سپس این کلیدها را در .env تنظیم کنید.

SECRET_KEY_BASE=<the 63 characters you just generated>
FRONTEND_URL=https://support.example.com
FORCE_SSL=true
DEFAULT_LOCALE=en
ENABLE_ACCOUNT_SIGNUP=true

POSTGRES_HOST=postgres
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=<long random string>
POSTGRES_DATABASE=chatwoot

REDIS_URL=redis://redis:6379
REDIS_PASSWORD=<a different long random string>

RAILS_ENV=production
INSTALLATION_ENV=docker
ACTIVE_STORAGE_SERVICE=local

عبارات POSTGRES_HOST=postgres و redis://redis:6379 نام سرویس‌های Compose هستند که در شبکهٔ پیش‌فرض پروژه resolve می‌شوند. مقدار FRONTEND_URL صرفاً تزئینی نیست. Chatwoot از این مقدار برای ساخت URL اسکریپت ویجت و تمام لینک‌های موجود در ایمیل‌های ارسالی استفاده می‌کند؛ بنابراین مقدار نادرست باعث می‌شود لینک‌های بازنشانی رمز عبور به میزبانی اشاره کنند که پاسخگو نیست.

اکنون به نکتهٔ انحرافی در فایل اصلی توجه کنید. سرویس postgres فایل .env را نمی‌خواند. این سرویس بلوک environment مخصوص به خود را دارد که در آن POSTGRES_PASSWORD= خالی رها شده است؛ بنابراین تنظیم رمز عبور فقط در .env باعث می‌شود دیتابیس بدون رمز عبور باقی بماند در حالی که اپلیکیشن دارای رمز عبور است. سرویس را به همان متغیر ارجاع دهید:

  postgres:
    image: pgvector/pgvector:pg16
    restart: always
    volumes:
      - postgres_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_DB=chatwoot
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}

سرویس Compose فایل .env را از دایرکتوری پروژه برای جایگزینی ${...} می‌خواند، بنابراین اکنون هر دو سمت از یک رشتهٔ یکسان استفاده می‌کنند. اگر این بخش را اشتباه تنظیم کنید، Rails با خطای PG::ConnectionBad: FATAL: password authentication failed for user "postgres" متوقف می‌شود.

یک رفتار خاص وجود دارد که تقریباً همه را غافلگیر می‌کند: ایمیج Postgres فقط زمانی POSTGRES_PASSWORD را اعمال می‌کند که یک دایرکتوری دادهٔ خالی را مقداردهی اولیه (initialize) کند. تغییر این مقدار در مراحل بعدی هیچ اثری ندارد، زیرا دستور initdb هرگز برای بار دوم اجرا نمی‌شود. اگر قبلاً stack را یک‌بار اجرا کرده‌اید، باید رمز عبور را مستقیماً داخل دیتابیس تغییر دهید.

docker compose exec postgres psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'the-new-password';"

مقدار ENABLE_ACCOUNT_SIGNUP=true موقتی است. این گزینه فرم ثبت‌نام عمومی را باز می‌کند تا بتوانید اولین حساب کاربری را بسازید. به محض ایجاد حساب کاربری، آن را روی false تنظیم کرده و دوباره docker compose up -d را اجرا کنید؛ در غیر این صورت هر کسی که URL را پیدا کند می‌تواند در سیستم پشتیبانی شما ثبت‌نام کند. پس از آن، ورود کارشناسان از طریق دعوت‌نامه انجام می‌شود و رمزهای عبور آن‌ها فقط در همین اپلیکیشن ذخیره می‌ماند. این وضعیت تا زمانی که تعداد سرویس‌های شما کم است مشکلی ایجاد نمی‌کند، اما وقتی تعداد سرویس‌ها به چندین مورد برسد و از مدیریت لیست‌های کاربری جداگانه خسته شوید، یک سرویس‌دهندهٔ هویت (Identity Provider) خودمیزبان مانند Authentik همان قطعه‌ای است که جایگزین این سیستم می‌شود.

فایل .env اکنون تمام اسرار این stack را به صورت متن ساده (plain text) در خود نگه می‌دارد، بنابراین دسترسی آن را روی حالت 600 تنظیم کنید و آن را در git قرار ندهید. مطلب نحوه خواندن فایل‌های env توسط Compose و محل نشت اسرار به بررسی نکات دقیق، از جمله تفاوت بین env_file و environment می‌پردازد.

قرار دادن Chatwoot پشت Traefik موجود

برای یک برنامه، پروکسی معکوس دوم ایجاد نکنید. اگر Traefik در حال حاضر وظیفه TLS (امنیت لایه انتقال) را برای سایر کانتینرها در این سرور بر عهده دارد، Chatwoot را با یک بلوک label به آن متصل کنید. اگر هنوز چنین تنظیمی ندارید، ابتدا آن را با استفاده از Traefik در مقابل چندین برنامه Docker Compose راه‌اندازی کنید و سپس به اینجا بازگردید.

فایل docker-compose.yaml بالادستی (upstream) را تا حد امکان به حالت پیش‌فرض نزدیک نگه دارید تا بتوانید بعداً آن را با نسخه‌های جدیدتر مقایسه (diff) کنید و تغییرات خود را در یک فایل override اعمال نمایید. Compose به‌طور خودکار docker-compose.override.yaml را ادغام می‌کند و تقسیم Compose در چندین فایل قوانین این ادغام را توضیح می‌دهد.

services:
  rails:
    networks:
      - default
      - proxy
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.chatwoot.rule=Host(`support.example.com`)"
      - "traefik.http.routers.chatwoot.entrypoints=websecure"
      - "traefik.http.routers.chatwoot.tls.certresolver=letsencrypt"
      - "traefik.http.services.chatwoot.loadbalancer.server.port=3000"

networks:
  proxy:
    external: true

از نام‌های entrypoint و certresolver اختصاصی خود استفاده کنید. کانتینر باید در همان شبکه Docker قرار بگیرد که Traefik در آن است؛ این همان کاری است که ورودی proxy انجام می‌دهد. همچنین باید در default نیز باقی بماند، در غیر این صورت دسترسی به Postgres و Redis را از دست می‌دهد. این همان خط دومی است که معمولاً فراموش می‌شود.

بلوک ports: را تغییر ندهید. نسخه بالادستی آن را به 127.0.0.1:3000 متصل می‌کند که فقط loopback است؛ بنابراین از اینترنت قابل دسترس نیست و برای تست از داخل سرور با curl -I http://127.0.0.1:3000 همچنان کاربردی باقی می‌ماند.

داشبورد عامل (agent dashboard) یک اتصال websocket را برای تحویل زنده پیام‌ها به /cable باز نگه می‌دارد. Traefik درخواست ارتقای HTTP را بدون نیاز به پیکربندی اضافی هدایت می‌کند، بنابراین چیزی برای افزودن وجود ندارد. اگر بعداً یک CDN یا پروکسی دیگری را جلوی Traefik قرار دادید، websockets را در آنجا مجاز کنید؛ زیرا نشانه مشکل این است که داشبورد به‌طور عادی بارگذاری می‌شود، اما پیام‌های جدید تنها پس از رفرش دستی ظاهر می‌شوند.

مقداردهی اولیه پایگاه داده و راه‌اندازی پشته

ابتدا سرویس‌های داده را بالا بیاورید و اجازه دهید Postgres اولین اجرای خود را به پایان برساند.

docker compose up -d postgres redis
docker compose logs postgres | tail -n 5

منتظر database system is ready to accept connections بمانید. سپس طرح‌واره (schema) را ایجاد کنید.

docker compose run --rm rails bundle exec rails db:chatwoot_prepare

این دستور در صورت عدم وجود پایگاه داده، آن را ایجاد کرده و سپس طرح‌واره و داده‌های اولیه (seed) را بارگذاری می‌کند. این دستور خطوط مهاجرت (migration) را چاپ کرده و به‌درستی خارج می‌شود. اگر دستور در حال چاپ postgres:5432 - no response متوقف شد، به این معنی است که نقطه ورود (entrypoint) منتظر پایگاه داده‌ای است که هنوز اتصالات را نمی‌پذیرد؛ در اولین اجرا، این معمولاً به این معناست که initdb هنوز در حال کار است. منتظر بمانید، لاگ‌های Postgres را بخوانید و سپس دوباره دستور را اجرا کنید. اگر روی افزونه vector متوقف شد، یعنی شما image مربوط به pgvector را با نسخه معمولی Postgres جایگزین کرده‌اید.

docker compose up -d
docker compose ps
docker compose logs --tail 30 rails

هر چهار کانتینر باید وضعیت Up را نشان دهند و لاگ rails باید با خطی از Puma که روی http://0.0.0.0:3000 گوش می‌دهد، پایان یابد. سپس مسیر عمومی را بررسی کنید:

curl -sI https://support.example.com | head -n 1

وضعیت HTTP/2 200 به این معنی است که کل زنجیره به‌درستی کار می‌کند. خطای 404 از سمت Traefik به این معنی است که قانون مسیریاب (router rule) مطابقت نداشته است که معمولاً به دلیل اشتباه تایپی در نام میزبان (hostname) است. خطای 502 به این معنی است که Traefik مسیریاب را پیدا کرده اما نتوانسته به کانتینر متصل شود؛ این مشکل تقریباً همیشه به دلیل نبود شبکه proxy یا تنظیم نبودن loadbalancer.server.port روی پورت 3000 است.

URL را باز کنید، حساب کاربری خود را در /app/auth/signup ایجاد کنید، سپس ENABLE_ACCOUNT_SIGNUP=false را تنظیم کرده و docker compose up -d را اجرا کنید تا فرم بسته شود.

چرا بازنشانی رمز عبور و مکالمات ایمیلی بدون SMTP با شکست مواجه می‌شوند

Chatwoot بدون تنظیمات SMTP (پروتکل انتقال نامه ساده)، یک میز پشتیبانی است که قادر به ارسال ایمیل نیست و این موضوع فراتر از اعلان‌ها، بخش‌های بیشتری را مختل می‌کند. بازنشانی رمز عبور از کار می‌افتد، بنابراین مدیری که دسترسی‌اش قطع شده، در همان وضعیت باقی می‌ماند. دعوت‌نامه‌های نمایندگان (Agent) نیز ارسال نمی‌شوند، زیرا دعوت‌نامه در واقع یک ایمیل است. پاسخ‌دهی به مشتری در یک مکالمه ایمیلی نیز متوقف می‌شود، بنابراین مکالمه تنها به صورت یک‌طرفه پیش می‌رود. این همان مرحله‌ای است که افراد از آن صرف‌نظر می‌کنند و در بدترین شرایط ممکن متوجه اهمیت آن می‌شوند.

مکانیسم این موضوع ساده است. بدون تنظیم SMTP_ADDRESS، Chatwoot برای تحویل ایمیل به سراغ sendmail می‌رود. مستندات بالادستی این مورد را به عنوان تنظیمات Postfix معرفی می‌کنند که از نسخه v2.12.0 به بعد پیش‌فرض بوده است و دستورالعمل‌های آن، Postfix را با sudo apt install -y postfix روی سرور نصب می‌کند. این تنظیمات Docker هرگز چنین کاری انجام نمی‌دهد، بنابراین هیچ سرور ایمیل پیکربندی‌شده‌ای برای تحویل ایمیل‌ها وجود ندارد. ایمیل‌ها از طریق یک background job ارسال می‌شوند، بنابراین هر خطایی که در حین تحویل رخ دهد، در لاگ Sidekiq ثبت می‌شود و هرگز در لاگ Rails دیده نمی‌شود. در همین حال، شخصی که روی "فراموشی رمز عبور" کلیک کرده، یک پیام تأیید خوش‌بینانه می‌بیند اما هرگز ایمیلی دریافت نمی‌کند.

MAILER_SENDER_EMAIL=Support <support@example.com>
SMTP_DOMAIN=example.com
SMTP_ADDRESS=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=support@example.com
SMTP_PASSWORD=<the relay password>
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

از پورت 587 با STARTTLS استفاده کنید؛ این پورت اتصال را در حالت متن ساده باز کرده و پیش از احراز هویت، آن را به حالت رمزنگاری‌شده ارتقا می‌دهد. بسیاری از ارائه‌دهندگان VPS به‌طور پیش‌فرض پورت 25 خروجی را برای محدود کردن اسپم مسدود می‌کنند. تا تاریخ 8 نوامبر 2026، Hetzner پورت‌های 25 و 465 را به‌طور پیش‌فرض روی سرورهای ابری مسدود کرده است (مسدودسازی بر اساس حساب کاربری اعمال می‌شود) و Vultr نیز پورت 25 را روی تمامی Compute Instanceهای جدید مسدود می‌کند. هر دو ارائه‌دهنده درخواست‌های رفع مسدودی را به‌صورت موردی بررسی می‌کنند؛ Hetzner شرط می‌گذارد که باید یک ماه از مشتری بودن شما بگذرد و اولین فاکتور پرداخت شده باشد تا بتوانید درخواست رفع محدودیت ارسال کنید. هیچ‌کدام پورت 587 را مسدود نمی‌کنند، بنابراین یک relay روی پورت 587 از همان لحظه بوت اول بدون نیاز به تیکت و انتظار کار می‌کند. SMTP_DOMAIN دامنه‌ای است که سرور شما در طول مکالمه SMTP اعلام می‌کند و برخی از relayها در صورت عدم تطابق، اتصال را رد می‌کنند.

تنظیمات را اعمال کنید و worker را زیر نظر بگیرید:

docker compose up -d rails sidekiq
docker compose logs -f sidekiq

یک بازنشانی رمز عبور از صفحه ورود انجام دهید. در صورت تحویل موفق، لاگ Sidekiq پایان عادی job مربوط به mailer را نشان می‌دهد. در صورت شکست، کلاس خطا نمایش داده می‌شود و سپس Sidekiq با فواصل زمانی افزایشی (backoff) تلاش مجدد می‌کند؛ به همین دلیل است که یک relay خراب، هر چند دقیقه یک‌بار برای ساعت‌ها همان خطا را تولید می‌کند.

دو نوع رد کردن (rejection) رایج است و هیچ‌کدام باگ Chatwoot نیستند. خطای 535 Authentication failed به معنای شکست در احراز هویت است؛ بنابراین اعتبارنامه‌ها، فعال بودن احراز هویت SMTP و عدم مسدودیت توسط سیاست‌های دسترسی را بررسی کنید. داشتن اعتبارنامه صحیح به تنهایی به معنای رفع این خطا نیست. برخی ارائه‌دهندگان به جای رمز عبور حساب کاربری، به یک application password نیاز دارند. خطای 550 Sender address rejected به این معناست که سرور، آدرس فرستنده را رد کرده است؛ پیش از تغییر MAILER_SENDER_EMAIL، پاسخ کامل را مطالعه کنید. مجوزهای فرستنده یا تأییدیه آن یکی از دلایل است، اما 550 5.7.27 Sender address rejected: Domain does not accept mail به دامنه‌ای اشاره دارد که دارای رکورد MX تهی (null) است.

دریافت ایمیل در یک مکالمه، یک job جداگانه است. برای فوروارد کردن از طریق ورودی (ingress) Chatwoot، به MAILER_INBOUND_EMAIL_DOMAIN و RAILS_INBOUND_EMAIL_SERVICE و همچنین یک سرور ایمیل نیاز دارید که پیام‌های دریافتی را به Chatwoot تحویل دهد. شما همچنین می‌توانید یک صندوق پستی را از طریق IMAP، شامل Google یا Microsoft OAuth، بدون نیاز به راه‌اندازی آن مسیر فوروارد، متصل کنید. اجاره یک relay سریع‌ترین راه است. اگر ترجیح می‌دهید مالکیت کامل مسیر ایمیل را در اختیار داشته باشید، اجرای سرور ایمیل شخصی با Mailcow توضیح می‌دهد که این تعهد در عمل شامل چه مواردی است.

چه مواردی را پشتیبان‌گیری کنیم و چگونه از صحت بازیابی مطمئن شویم

پشتیبان‌گیری از Chatwoot شامل چهار بخش است و نادیده گرفتن هر یک از آن‌ها، بازیابی را به یک بازسازی کامل تبدیل می‌کند.

  • پایگاه داده Postgres که شامل گفتگوها، مخاطبین، حساب‌های کاربری اپراتورها و تمامی تنظیمات است.
  • ولوم storage_data، زیرا ACTIVE_STORAGE_SERVICE=local فایل‌های آپلود شده را روی دیسک ذخیره می‌کند و در Postgres فقط یک ردیف ارجاع به آن‌ها نگه می‌دارد.
  • فایل .env، زیرا حاوی SECRET_KEY_BASE و کلیدهای ACTIVE_RECORD_ENCRYPTION_* است.
  • فایل‌های compose، زیرا نسخه دقیق image که با طرح پایگاه داده شما مطابقت دارد را ثبت می‌کنند.

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

cd ~/chatwoot
docker compose exec -T postgres pg_dump -U postgres -Fc chatwoot > db-$(date +%F).dump

استفاده از -T اهمیت دارد. بدون آن، Compose یک ترمینال مجازی اختصاص می‌دهد که بایت‌های خط جدید (newline) را در جریان داده بازنویسی می‌کند و در نتیجه فایل dump خروجی توسط pg_restore رد می‌شود. -Fc فرمت اختصاصی است که داده‌ها را فشرده کرده و به pg_restore اجازه می‌دهد به صورت انتخابی عمل کند.

docker run --rm -v chatwoot_storage_data:/data:ro -v "$PWD":/backup alpine \
  tar czf /backup/storage-$(date +%F).tgz -C /data .

نام ولوم برابر است با نام دایرکتوری پروژه شما به اضافه _storage_data. پیش از اعتماد به دستور، آن را با docker volume ls | grep storage_data تأیید کنید، زیرا اگر نامی را وارد کنید که وجود ندارد، Docker به جای خطا دادن، یک ولوم خالی ایجاد می‌کند. در این صورت شما یک آرشیو معتبر اما خالی دریافت می‌کنید و هیچ خطایی هم رخ نمی‌دهد. پس از پایان، حجم فایل را با ls -lh storage-*.tgz بررسی کنید.

هر دو فایل اکنون روی همان دیسکی قرار دارند که از آن محافظت می‌کنند، بنابراین در برابر خرابی دیسک هیچ حفاظتی ندارید. آن‌ها را به خارج از سرور منتقل و رمزنگاری کنید، زیرا dump پایگاه داده شامل تمام پیام‌های مشتریان به صورت متن ساده است. پشتیبان‌گیری رمزنگاری‌شده خارج از سایت با restic به جنبه‌های زمان‌بندی و نگهداری فایل‌ها می‌پردازد.

تمرین بازیابی، آن را پیش از نیاز واقعی انجام دهید

بازیابی را روی یک VPS دوم انجام دهید، نه روی سرور اصلی. فایل .env، فایل‌های compose و هر دو آرشیو را منتقل کنید و سپس دستور زیر را اجرا کنید:

docker compose up -d postgres
docker compose exec -T postgres pg_restore -U postgres -d chatwoot --clean --if-exists < db-2026-08-10.dump
docker run --rm -v chatwoot_storage_data:/data -v "$PWD":/backup alpine \
  sh -c 'rm -rf /data/* && tar xzf /backup/storage-2026-08-10.tgz -C /data'
docker compose up -d

دستور --clean --if-exists اشیاء موجود را پیش از بارگذاری حذف می‌کند، بنابراین آن را فقط روی پایگاه داده‌ای اجرا کنید که از دست دادن آن برایتان اهمیتی ندارد. سپس وارد سیستم شوید و گفتگویی که دارای پیوست است را باز کنید. اگر لیست پیام‌ها بارگذاری شد و فایل دانلود شد، پشتیبان‌گیری شما معتبر است.

بازیابی با SECRET_KEY_BASE متفاوت، تمام کوکی‌های نشست (session cookie) را باطل می‌کند و همه کاربران از سیستم خارج می‌شوند. بازیابی با کلیدهای ACTIVE_RECORD_ENCRYPTION_* متفاوت بدتر است: Chatwoot نمی‌تواند ستون‌های حاوی اعتبارنامه‌های کانال را رمزگشایی کند و خطای ActiveRecord::Encryption::Errors::Decryption را نمایش می‌دهد. به همین دلیل است که .env در لیست پشتیبان‌گیری قرار دارد.

نحوه ارتقای Chatwoot به یک تگ جدید

ترتیب انجام مراحل از خود دستورات اهمیت بیشتری دارد.

  1. یادداشت‌های انتشار (release notes) بین تگ فعلی و تگ مقصد را مطالعه کنید تا از مراحل دستی مورد نیاز مطلع شوید.
  2. یک نسخه پشتیبان (dump) از دیتابیس و یک آرشیو از فضای ذخیره‌سازی تهیه کنید و مطمئن شوید حجم هر دو فایل منطقی است.
  3. تگ ایمیج را در سرویس base در فایل docker-compose.yaml ویرایش کنید.
  4. ایمیج جدید را Pull کنید، استک را متوقف کنید، migrationها را اجرا کنید و سپس دوباره آن را استارت بزنید.
docker compose pull
docker compose down
docker compose run --rm rails bundle exec rails db:chatwoot_prepare
docker compose up -d
docker compose images

پیش از اجرای migration، ایمیج جدید را Pull کنید؛ زیرا migration باید از داخل ایمیج جدید اجرا شود و ایمیج قدیمی حاوی فایل‌های migration جدید نیست. پیش از اجرای migration، استک را متوقف کنید؛ زیرا کد قدیمی با طرح (schema) جدید دیتابیس ناسازگار است و اجرای پروسه قدیمی Rails ممکن است باعث بروز خطا یا درج ردیف‌هایی شود که طرح جدید آن‌ها را نمی‌پذیرد. توقف سرویس همچنین حافظه مورد نیاز برای migration را آزاد می‌کند؛ این دقیقاً همان دلیلی است که توسعه‌دهندگان اصلی (upstream) استفاده از swap را توصیه می‌کنند.

دستور docker compose images تگی که هر کانتینر در حال حاضر با آن اجرا می‌شود را نمایش می‌دهد. این دستور به شما کمک می‌کند تا متوجه شوید اگر تگ را ویرایش کرده‌اید اما فراموش کرده‌اید Pull کنید، چه وضعیتی برقرار است.

میزان پرش بین نسخه‌ها به قدمت نصب شما بستگی دارد. برای نصبی که یک یا دو نسخه عقب‌تر است، یادداشت‌های انتشار بین تگ فعلی و مقصد را بررسی کنید، تگ مقصد را تنظیم کرده و مراحل بالا را یک‌بار اجرا کنید. تنها در صورتی که نصب شما بسیار قدیمی باشد، راهنمای Docker توسعه‌دهندگان اصلی به شما می‌گوید که به جای پرش مستقیم به آخرین ایمیج، به‌صورت مرحله‌به‌مرحله و از طریق تگ‌های میانی ارتقا دهید. در این حالت، مراحل تغییر تگ، Pull کردن و آماده‌سازی را برای هر تگ میانی تکرار کنید، زیرا توسعه‌دهندگان اصلی پس از هر ارتقا اجرای db:chatwoot_prepare را الزامی می‌دانند.

اگر Rails پیش از اجرای migration شروع به کار کند، از سرویس‌دهی خودداری کرده و خطای ActiveRecord::PendingMigrationError: Migrations are pending را در لاگ ثبت می‌کند. با تنظیم restart: always، کانتینر وارد چرخه ری‌استارت می‌شود و در نتیجه docker compose ps نشان می‌دهد که uptime هر چند ثانیه یک‌بار ریست می‌شود. با اجرای مرحله آماده‌سازی، این مشکل برطرف خواهد شد.

بازگشت به نسخه قبل (Rollback) به معنای بازگرداندن تگ قدیمی و بازیابی نسخه پشتیبان دیتابیس است. هیچ مسیر بازگشت (reverse migration) قابل‌اطمینانی وجود ندارد و به همین دلیل است که مرحله 2 اهمیت حیاتی دارد.

حالت‌های شکست و پیام‌هایی که مشاهده خواهید کرد

خطای 502 Bad Gateway از سمت Traefik. روتر درخواست را تطبیق داده اما سرویس مقصد (backend) پاسخی نداده است. بررسی کنید که docker compose ps وضعیت rails را به صورت Up نشان می‌دهد، سپس دستور docker network inspect proxy را اجرا کنید و مطمئن شوید که کانتینر rails در لیست کانتینرها ظاهر می‌شود. کانتینری که متصل نباشد برای Traefik نامرئی است؛ بنابراین درخواست با روتر تطبیق می‌خورد اما به مقصد نمی‌رسد.

داشبورد بارگذاری می‌شود اما پیام‌های جدید نیاز به رفرش دارند. اتصال websocket به /cable برقرار نمی‌شود، یا FRONTEND_URL با آدرس موجود در نوار آدرس مرورگر مطابقت ندارد. عدم تطابق باعث می‌شود صفحه سعی کند یک websocket به مبدأ (origin) متفاوتی باز کند که مرورگر آن را مسدود می‌کند.

FATAL: password authentication failed for user "postgres". رمز عبور در .env با رمز عبور ذخیره‌شده در volume داده‌های Postgres متفاوت است. این مشکل را با اجرای ALTER USER در داخل کانتینر در حال اجرا حل کنید، زیرا ویرایش مجدد .env تغییری در دیتابیسی که قبلاً مقداردهی اولیه شده است، ایجاد نمی‌کند.

NOAUTH Authentication required.. سرویس Redis با --requirepass در حال اجراست اما برنامه بدون رمز عبور متصل شده است؛ بنابراین REDIS_PASSWORD در .env وجود ندارد یا اعمال نشده است. رمز عبوری که Redis انتظار دارد را مستقیماً با docker compose exec redis sh -c 'redis-cli -a "$REDIS_PASSWORD" ping' تست کنید که باید پاسخ PONG را برگرداند. استفاده از تک‌کوتیشن مهم است: این کار باعث می‌شود متغیر در داخل کانتینر بسط یابد (که .env را می‌خواند)، نه در shell شما که معمولاً خالی است.

خروج کانتینرها با کد 137. این کد به معنای SIGKILL است. در سرورهای کوچک، عامل معمولاً قابلیت out of memory killer هسته سیستم‌عامل است، اما docker kill نیز همین سیگنال را ارسال می‌کند؛ بنابراین پیش از آنکه مشکل را به گردن کمبود حافظه بیندازید، sudo dmesg -T | grep -i "killed process" را بررسی کنید. اگر مشکل از حافظه است، swap اضافه کنید، محدودیت حافظه برای هر سرویس تعیین کنید یا به پلن بزرگ‌تری مهاجرت کنید.

FAQ

حداقل رم مورد نیاز برای یک VPS جهت میزبانی Chatwoot چقدر است؟

از اکتبر 2026، مستندات رسمی حداقل 4 گیگابایت رم و 4 هسته CPU را برای حداکثر 10,000 مکالمه در روز، و 8 گیگابایت رم با 8 هسته برای حداکثر 20,000 مکالمه پیشنهاد می‌دهند. حداقل 1 گیگابایت swap اضافه کنید، زیرا در هنگام ارتقا، یک پردازش Rails دوم برای اعمال migrationها اجرا می‌شود و در این مرحله سرورهای کوچک با کمبود حافظه مواجه می‌شوند. یک VPS با 2 گیگابایت رم بوت می‌شود و برای چند اپراتور کار می‌کند، اما Sidekiq به‌تنهایی تحت بار می‌تواند از 1 گیگابایت رم فراتر رود؛ بنابراین انتظار داشته باشید که در دوره‌های شلوغ یا هنگام ارتقا، کانتینرها با کد خطای 137 متوقف شوند.

چرا ایمیل‌های بازنشانی رمز عبور Chatwoot ارسال نمی‌شوند؟

زیرا هیچ SMTP_ADDRESS تنظیم نشده است؛ بنابراین Chatwoot از روش پیش‌فرض sendmail استفاده می‌کند که برای یک سرور Postfix نصب‌شده روی میزبان طراحی شده است، در حالی که این setup داکر فاقد آن است. این عملیات در Sidekiq اجرا می‌شود، بنابراین هر خطای ارسال در لاگ Sidekiq ثبت می‌شود، در حالی که مرورگر همچنان پیام موفقیت‌آمیز نشان می‌دهد. مقادیر SMTP_ADDRESS، SMTP_PORT، SMTP_USERNAME، SMTP_PASSWORD و MAILER_SENDER_EMAIL را در .env تنظیم کنید، سرویس‌های rails و sidekiq را restart کنید و سپس هنگام درخواست بازنشانی، docker compose logs -f sidekiq را مانیتور کنید.

برای بازیابی Chatwoot از چه چیزهایی باید نسخه پشتیبان تهیه کنم؟

پایگاه داده Postgres، دایرکتوری داکر storage_data، فایل .env و فایل‌های compose. داشتن پایگاه داده به‌تنهایی کافی نیست، زیرا فایل‌های آپلودشده در volume قرار دارند و Postgres فقط ارجاع به آن‌ها را نگه می‌دارد؛ بنابراین بازیابی فقط پایگاه داده منجر به مکالماتی با پیوست‌های خراب می‌شود. فایل .env اهمیت دارد زیرا تغییر SECRET_KEY_BASE باعث خروج (logout) تمام کاربران می‌شود و کلیدهای ACTIVE_RECORD_ENCRYPTION_* متفاوت، ستون‌های رمزنگاری‌شده را غیرقابل خواندن می‌کنند.

چگونه Chatwoot را بدون آسیب به پایگاه داده ارتقا دهم؟

ابتدا نسخه پشتیبان تهیه کنید، یادداشت‌های انتشار (release notes) بین تگ فعلی و تگ مقصد را مطالعه کنید، تگ image را در فایل compose تغییر دهید و سپس دستورات docker compose pull، docker compose down، docker compose run --rm rails bundle exec rails db:chatwoot_prepare و docker compose up -d را اجرا کنید. ابتدا image را pull کنید زیرا migrationها باید از روی image جدید اجرا شوند و ابتدا stack را متوقف کنید، زیرا اجرای کد قدیمی روی schema جدید باعث بروز خطا می‌شود. فقط در نصب‌های بسیار قدیمی نیاز است که به‌جای پرش مستقیم به آخرین نسخه، مرحله‌به‌مرحله از تگ‌های میانی عبور کنید و پس از هر مرحله، مرحله آماده‌سازی (prepare) را اجرا کنید.

آیا می‌توانم به‌جای pgvector از image استاندارد postgres استفاده کنم؟

خیر. schema برنامه Chatwoot افزونه vector را فعال می‌کند، بنابراین image پیش‌فرض postgres در حین db:chatwoot_prepare با خطای ERROR: extension "vector" is not available مواجه می‌شود، زیرا فایل کنترل این افزونه در آن image موجود نیست. از pgvector/pgvector:pg16 موجود در فایل compose رسمی استفاده کنید یا image دیگری را به کار ببرید که pgvector را برای نسخه اصلی Postgres شما ارائه می‌دهد.

آیا این مقاله مفید بود؟