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

MAATRIX

Appsmith — удобный конструктор внутренних админ-панелей и дашбордов поверх существующих БД и API, но на своём сервере он ведёт себя не так гладко, как в облачной версии разработчиков. Контейнер падает после обновления, подключение к PostgreSQL рвётся без видимой причины, а после миграции на новый сервер приложения вообще не открываются. Ниже — конкретные симптомы, причины и рабочие исправления, собранные на практике самостоятельного хостинга Appsmith.

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

Самый частый сценарий: docker compose up -d отрабатывает, но через 10-30 секунд контейнер уходит в restart loop. Первым делом смотрим логи:

docker compose logs -f appsmith --tail=200

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

• Не хватает памяти. Appsmith внутри поднимает несколько процессов (backend на Java, RTS-сервис, MongoDB, Redis если используется встроенный образ) — на VPS с 1-2 ГБ RAM это частая причина OOM-killer. Проверьте: dmesg | grep -i "out of memory" или journalctl -k | grep -i oom. Решение — либо апгрейд до 4 ГБ RAM (минимум, который реально рекомендуют для self-hosted Appsmith), либо добавить swap-файл как временную меру.
• Конфликт портов. Появляется ошибка bind: address already in use. Проверьте, что порт 80/443 (или тот, что указан в docker-compose.yml) не занят другим сервисом:

sudo ss -tulpn | grep -E ':80|:443'

• Повреждённый volume после неудачного апдейта. Если контейнер падает сразу после docker compose pull && docker compose up -d, откатитесь на предыдущий тег образа и разбирайтесь отдельно, не трогая продакшн-данные.

Полезно сразу настроить restart: unless-stopped в compose-файле — это не лечит причину, но не даёт сервису просто лежать мёртвым после временного сбоя, пока вы разбираетесь.

Appsmith не открывается через браузер после установки

Контейнер запущен (docker ps показывает Up), но браузер отдаёт ERR_CONNECTION_REFUSED или таймаут. Порядок диагностики:

1. Проверьте, что сервис слушает нужный порт локально: curl -I http://localhost:80 на самом сервере.
2. Если curl отвечает, а снаружи — нет, дело в файрволе. Откройте порт:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

1. Если стоит облачный файрвол хостинга (security group), проверьте правила там отдельно от ufw внутри ОС — это разные слои, и открытый порт в одном не значит открытый в другом.
2. Если используете Appsmith за reverse proxy (рекомендуемый вариант для продакшена — с ним заодно получаете нормальный SSL), убедитесь, что proxy_pass указывает на правильный внутренний порт контейнера, а не на 80 по умолчанию:

location / {
    proxy_pass http://127.0.0.1:8080;
    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 300s;
}

Таймаут proxy_read_timeout стоит увеличить намеренно — некоторые запросы в Appsmith (сложные запросы к БД, генерация отчётов) выполняются дольше стандартных 60 секунд, и без этой настройки вы будете видеть 504 на ровном месте. Подробнее о настройке самого reverse proxy — в статье про Nginx как reverse proxy.

Обрыв подключения к внешней БД (PostgreSQL/MySQL)

Appsmith хранит свои данные (пользователи, приложения) в собственной MongoDB внутри контейнера, но обычно подключается к внешней PostgreSQL или MySQL как к источнику данных для дашбордов. Здесь всплывает своя категория ошибок.

Connection timed out при добавлении datasource. Проверьте:

• Слушает ли БД внешние подключения. Для PostgreSQL — listen_addresses = '*' в postgresql.conf (по умолчанию часто стоит localhost).
• Разрешены ли подключения в pg_hba.conf с IP сервера Appsmith:

host    all    all    <IP_appsmith_servera>/32    md5

• Открыт ли порт 5432 (или 3306 для MySQL) в файрволе именно для этого IP, а не для всех подряд — открывать порт БД в мир небезопасно, даже с паролем.

Если Appsmith и база на одном сервере в разных Docker-сетях — классическая ошибка новичков: контейнеры просто не видят друг друга. Убедитесь, что они в общей сети (docker network) либо подключайтесь по IP хоста, а не по localhost изнутри контейнера. Более детальный разбор похожих проблем — в статье PostgreSQL не принимает подключения.

Подключение рвётся спустя время, хотя изначально работало. Часто причина — исчерпание пула соединений на стороне БД (too many connections) при большом числе одновременно открытых виджетов/запросов. Проверьте текущее число соединений:

SELECT count(*) FROM pg_stat_activity;

и при необходимости увеличьте max_connections, либо настройте connection pooling (PgBouncer) между Appsmith и базой — это правильнее, чем просто задирать лимит.

Медленные запросы и зависающие дашборды

Когда сам Appsmith отвечает, но конкретный запрос к БД выполняется по 10-20 секунд и виджет крутит спиннер — проблема почти всегда не в Appsmith, а в самом запросе или индексах.

• Включите EXPLAIN ANALYZE на проблемном SQL прямо в консоли БД, не через интерфейс Appsmith — так вы видите реальный план выполнения без накладных расходов на сериализацию JSON.
• Проверьте, не гоняете ли вы SELECT * из таблицы на миллионы строк без LIMIT — в builder-режиме Appsmith это легко сделать случайно при первом подключении datasource.
• Для тяжёлой аналитики поверх той же БД иногда разумнее вынести отчётные запросы на реплику или отдельный аналитический слой — если у вас растущая нагрузка, почитайте про выбор между ClickHouse и PostgreSQL для аналитики.

Отдельно — таймауты самого JS-runtime в Appsmith. Если у вас сложные JS-трансформации данных внутри виджетов, при большом объёме данных они могут просто зависать в браузере клиента, а не на сервере — это стоит проверить через DevTools, прежде чем чинить сервер.

Ошибки при обновлении версии Appsmith

Appsmith часто обновляется, и минорные версии иногда меняют формат внутренних данных. Правило, которое избавляет от большинства проблем: никогда не обновляйте продакшн без бэкапа volume заранее.

docker compose down
docker run --rm -v appsmith_stacks:/data -v $(pwd)/backup:/backup \
  alpine tar czf /backup/appsmith-stacks-$(date +%F).tar.gz -C /data .

Если после docker compose pull && docker compose up -d приложение открывается с ошибкой миграции в логах (Error running migrations), не пытайтесь чинить руками через MongoDB shell — откатитесь на предыдущий тег образа из бэкапа тома, разберитесь в спокойном режиме на копии сервера, и только потом накатывайте апдейт повторно. Про откат и работу с образами полезно почитать в статье про размер Docker-образов и их уменьшение, если апдейты у вас идут медленно из-за размера слоёв.

Проблемы с правами доступа и переменными окружения

Отдельный класс ошибок — не техническая поломка, а неверная конфигурация окружения:

Заведите .env как обязательную часть бэкапа — многие теряют доступ именно потому, что скопировали volume с данными, но не скопировали ключи шифрования, которыми эти данные защищены. Без ключа расшифровать креды datasource из старого дампа MongoDB не получится.

Появление после миграции на другой сервер

Перенос Appsmith между серверами (например, при смене хостинга или локации) — отдельный источник ошибок, которые не встречаются при обычной эксплуатации:

1. Изменился внешний IP/домен — если в .env или переменных окружения зашит старый APPSMITH_CUSTOM_DOMAIN, приложение может редиректить не туда или ломать cookie-based авторизацию. Обновите домен и перевыпустите SSL-сертификат заново на новом сервере.
2. Разная версия Docker/Docker Compose между старым и новым сервером — иногда меняется поведение сетей по умолчанию. После переноса тома проверьте docker compose config на предупреждения перед стартом.
3. Забытые cron-задачи для бэкапов, которые указывают на старый путь — легко упустить при миграции и обнаружить пропажу бэкапов через месяц.

Если переносите Appsmith вместе с остальным стеком на новый сервер, стоит заранее прогнать чек-лист по production-конфигурации Docker Compose — большая часть типовых граблей общая для любого self-hosted сервиса на compose, не только для Appsmith.

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