Chatwoot на сервере: частые ошибки и решения

MAATRIX

Chatwoot — удобная альтернатива Intercom и Zendesk: чат на сайте, почта, Telegram, WhatsApp и соцсети сходятся в один инбоксе, а данные остаются на вашем сервере. Но self-hosted версия собрана из нескольких сервисов (Rails-приложение, Sidekiq, PostgreSQL, Redis), и когда что-то из этого начинает сбоить, разобраться, где именно проблема, не всегда просто. Здесь — конкретные симптомы, которые чаще всего встречаются после установки и в процессе эксплуатации Chatwoot, и рабочие способы их устранения.

Контейнер стартует и сразу падает

Самая частая ситуация после docker compose up -d: контейнер rails перезапускается по кругу, а в логах — обрыв на середине.

Первым делом смотрим логи именно приложения, а не всего стека:

docker compose logs -f rails

Типичные причины и что с ними делать:

• Не хватает памяти. Rails + Sidekiq + Redis + PostgreSQL на VPS с 1-2 ГБ RAM — почти гарантированный OOM-килл. Проверьте:

dmesg | grep -i "out of memory"
free -h

Если видите killed-процессы — либо добавляйте RAM, либо временно спасайтесь свопом (см. ниже), но для продакшена Chatwoot комфортно работает от 4 ГБ.

• SECRET_KEY_BASE не задан или сгенерирован заново при каждом рестарте. Если он не зафиксирован в .env, при каждом пересоздании контейнера сессии слетают, а иногда падает сам старт. Сгенерируйте один раз и пропишите постоянно:

docker compose run --rm rails bundle exec rails secret

Полученную строку — в .env:

SECRET_KEY_BASE=сгенерированное_значение

• База данных ещё не готова, когда стартует Rails. Классическая гонка контейнеров в Docker Compose. Помогает depends_on с условием healthcheck, а не просто порядком запуска:

depends_on:
  postgres:
    condition: service_healthy
  redis:
    condition: service_healthy

Миграции базы не проходят

После обновления версии или при первом запуске нередко падает rails db:chatwoot_prepare:

PG::UndefinedTable: ERROR: relation "..." does not exist

Порядок действий:

1. Убедитесь, что PostgreSQL действительно доступен из контейнера rails:

docker compose exec rails bundle exec rails db:version

1. Если база пустая (первый запуск) — выполните полную подготовку:

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

1. Если база уже существовала (обновление версии), а не первый деплой — не гоняйте db:chatwoot_prepare повторно, он рассчитан на чистую БД. Нужен db:migrate:

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

Отдельная больная точка — расширения PostgreSQL. Chatwoot использует pg_trgm и pgvector (для полнотекстового и AI-поиска в новых версиях). Если ловите ошибку extension "vector" is not available, значит образ PostgreSQL взят не тот — нужен pgvector/pgvector вместо обычного postgres, либо расширение придётся ставить руками через apt. Проще сразу указать правильный образ в docker-compose.yml:

postgres:
  image: pgvector/pgvector:pg16

Общие грабли самой PostgreSQL под нагрузкой (память, конфиги, блокировки) разбираются в статье PostgreSQL на сервере: частые ошибки и решения — пригодится, если проблема не в самом Chatwoot, а в СУБД под ним.

Sidekiq не обрабатывает очередь — письма и уведомления зависают

Это, пожалуй, самая частая жалоба на форумах Chatwoot: письма создаются в базе, но не отправляются, real-time обновления в интерфейсе не приходят, а фоновые задачи копятся.

Причина почти всегда одна — Sidekiq не может достучаться до Redis, либо сам процесс Sidekiq не запущен как отдельный контейнер. Проверьте, что в docker-compose.yml действительно есть отдельный сервис:

sidekiq:
  <<: *base
  command: bundle exec sidekiq -C config/sidekiq.yml
  depends_on:
    - postgres
    - redis

Если сервис есть, но очередь всё равно не двигается — смотрите логи Sidekiq отдельно от Rails:

docker compose logs -f sidekiq

Частые находки в логе:

• Redis::CannotConnectError — неверный REDIS_URL в .env (порт, хост или пароль не совпадают с сервисом redis) либо Redis требует авторизацию, а строка подключения без пароля.
• Очередь default растёт, а mailers пустая — значит письма не доходят до этапа отправки: проблема не в Sidekiq, а в SMTP (см. следующий раздел).
• Sidekiq стартовал, но использует старый код после обновления образа — не забывайте пересобирать и Sidekiq, и Rails вместе:

docker compose up -d --build rails sidekiq

Общие принципы жизни Redis на сервере — пароли, персистентность, память — описаны в статье Redis на сервере: частые ошибки и решения.

Почта не отправляется и не принимается

Chatwoot умеет быть не только чатом, но и почтовым инбоксом — а SMTP/IMAP настройка чаще всего и ломается в первую очередь.

Исходящая почта (уведомления, ответы клиентам). Проверьте блок в .env:

MAILER_SENDER_EMAIL=support@ваш-домен.ru
SMTP_ADDRESS=smtp.ваш-провайдер.ru
SMTP_PORT=587
SMTP_USERNAME=support@ваш-домен.ru
SMTP_PASSWORD=пароль
SMTP_AUTHENTICATION=plain
SMTP_ENABLE_STARTTLS_AUTO=true

Частая ошибка — SMTP_DOMAIN не указан или не совпадает с доменом, от которого отправляете: некоторые почтовые провайдеры (в том числе self-hosted Postfix) заворачивают такие письма как подозрительные. Проверить факт отправки со стороны сервера:

docker compose exec rails bundle exec rails runner "
ActionMailer::Base.mail(
  from: 'support@ваш-домен.ru',
  to: 'ваша-личная-почта@example.com',
  subject: 'test',
  body: 'test'
).deliver_now"

Если команда падает с ошибкой аутентификации или таймаутом — проблема на уровне SMTP-провайдера или файрвола (проверьте, что исходящий 587/465 порт не заблокирован хостером). Если своя почта развёрнута на Postfix, полезно свериться со статьёй Postfix: письма не отправляются наружу — причины и решение.

Входящая почта (создание тикетов из писем). Здесь два рабочих варианта: через IMAP-опрос (проще, но с задержкой в пределах минуты) или через прямую доставку на сервер (webhook-приём писем, быстрее, но требует настройки MX и приёмного скрипта). Для старта чаще берут IMAP — он настраивается прямо в интерфейсе Chatwoot, канал за каналом, без правки конфигов на сервере.

Nginx отдаёт 502/504 или не пробрасывает WebSocket

Chatwoot держит real-time соединение через ActionCable (WebSocket), и если reverse proxy настроен «по умолчанию», без явного проброса апгрейда соединения — интерфейс работает, но обновления в реальном времени не приходят, а иногда весь фронт виснет с 502.

Рабочий блок для Nginx:

server {
    listen 443 ssl http2;
    server_name chat.ваш-домен.ru;

    ssl_certificate     /etc/letsencrypt/live/chat.ваш-домен.ru/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.ваш-домен.ru/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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_read_timeout 86400;
    }
}

Ключевые строки — proxy_set_header Upgrade и Connection "upgrade", без них WebSocket-хендшейк не проходит. proxy_read_timeout тоже важен: значение по умолчанию (обычно 60 секунд) рвёт долгоживущее соединение ActionCable, из-за чего браузер переподключается каждую минуту с видимыми лагами в интерфейсе.

Если после правки конфиг не подхватывается — не забывайте nginx -t и systemctl reload nginx; типовые промахи с этим разобраны в статье Nginx не видит изменения конфига, а конкретно по 502/504 — в Nginx отдаёт 504 Gateway Timeout: причины и решение.

Виджет чата не появляется на сайте или не подключается

Если сам Chatwoot работает, но виджет на клиентском сайте молчит — проверяйте в таком порядке:

1. CORS/CSP заголовки на сайте клиента. Если у сайта настроен строгий Content-Security-Policy, скрипт виджета с домена Chatwoot может блокироваться браузером. В консоли разработчика (F12) будет явная ошибка вида Refused to load the script.
2. HUB_URL не совпадает с реальным адресом. В .env переменная FRONTEND_URL должна указывать именно на публичный HTTPS-адрес вашего Chatwoot, а не на localhost или внутренний IP — иначе виджет пытается открыть WebSocket не туда.

FRONTEND_URL=https://chat.ваш-домен.ru

После смены значения — обязательно пересоздать контейнер, переменные окружения Rails не подхватывает на лету:

docker compose up -d --force-recreate rails

1. Смешанный контент (HTTP-виджет на HTTPS-сайте). Если сертификат на Chatwoot ещё не выпущен или просрочен, браузер молча блокирует скрипт. Проверьте валидность через curl -vI https://chat.ваш-домен.ru — на этапе сертификата не будет ошибок TLS-хендшейка.

Диск и память заканчиваются со временем

Chatwoot копит логи, вложения из тикетов и Sidekiq-джобы в базе, и через несколько месяцев эксплуатации сервер может внезапно упереться в диск.

Что чистить регулярно:

# логи Docker-контейнеров (могут разрастаться до гигабайтов)
docker system df
docker system prune -a --volumes

# старые задачи Sidekiq в Redis (dead set, retry set)
docker compose exec redis redis-cli
> LLEN queue:default

Если Sidekiq копит retry-очередь из-за постоянно падающих джоб (например, письма не уходят из-за неверного SMTP — см. выше), эти джобы будут пересчитываться днями, нагружая CPU и Redis впустую. Почистить retry-set после исправления первопричины:

docker compose exec rails bundle exec rails runner "Sidekiq::RetrySet.new.clear"

Для памяти — если Redis настроен без ограничения maxmemory, он может занять всю доступную RAM на сервере под кэш и очереди. Разумный лимит на небольшой инсталляции — 256-512 МБ с политикой вытеснения:

maxmemory 512mb
maxmemory-policy allkeys-lru

Если VPS небольшой и есть риск упереться в RAM при пиках (импорт контактов, массовая рассылка), временный своп спасает от OOM-килла, но не заменяет апгрейд тарифа — подробнее в статье Правильный размер swap для VPS.

Частые вопросы