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

MAATRIX

Budibase — low-code платформа для сборки внутренних приложений и форм поверх своих данных, и на бумаге self-hosted установка выглядит просто: один скрипт, один docker-compose. На практике всё чуть сложнее — установка обрывается на середине, app-service не видит CouchDB, обновление ломает связку сервисов, а email-приглашения молча не уходят. Ниже — конкретные симптомы, причины и рабочие исправления по каждому из этих сценариев.

Установка через hosting.sh падает или зависает

Стандартный способ развернуть Budibase на своём сервере — официальный скрипт:

git clone https://github.com/Budibase/budibase
cd budibase/hosting
./hosting.sh

Скрипт спрашивает порт (по умолчанию 10000), генерирует .env и docker-compose.yaml, поднимает стек. Частые сбои на этом шаге:

• Порт занят. Если на сервере уже что-то слушает 10000 (или порт, который вы указали), контейнер proxy либо не стартует, либо стартует, но снаружи ничего не отвечает. Проверьте заранее:

sudo ss -tulpn | grep 10000

Если порт занят — либо остановите конфликтующий сервис, либо при повторном запуске hosting.sh укажите другой порт и пропишите его же в конфиге вашего reverse proxy.

• Docker Compose V1 vs V2. Скрипт рассчитан на современный docker compose (плагин, без дефиса). Проверьте версию: docker compose version — если команда не найдена, ставьте плагин compose отдельно, не полагаясь на старый бинарник docker-compose.
• Нет прав на запись в текущую директорию. hosting.sh создаёт .env и docker-compose.yaml рядом с собой — если репозиторий склонирован от root, а скрипт запущен от обычного пользователя, файлы молча не создаются.
• Недостаточно памяти уже на этапе docker compose up. Стек поднимает сразу несколько контейнеров (proxy, app-service, worker-service, couchdb, redis) — на VPS с 1 ГБ RAM часть из них может не подняться из-за OOM ещё до первого открытия страницы. Смотрите dmesg | grep -i "out of memory".

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

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

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

1. Проверьте локально на самом сервере, что proxy-контейнер вообще отвечает:

curl -I http://localhost:10000

1. Если curl отвечает 200/302, а снаружи ничего — дело в файрволе. Откройте нужный порт:

sudo ufw allow 10000/tcp

1. Облачный файрвол хостинга (security group) — отдельный слой поверх ufw, проверяйте правила там тоже.
2. Для продакшена нужен домен и SSL, а не голый IP:порт. Правильная схема — внешний Nginx или Caddy на 80/443 с валидным сертификатом, проксирующий на внутренний порт Budibase:

server {
    listen 443 ssl;
    server_name apps.example.com;

    location / {
        proxy_pass http://127.0.0.1:10000;
        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_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Заголовки Upgrade/Connection обязательны — часть внутреннего взаимодействия app-service и браузера идёт через websocket, без них builder-режим будет работать со странными задержками или обрывами соединения. Подробный разбор настройки самого reverse proxy — в статье Nginx как reverse proxy. Выпуск и продление сертификата — тема отдельная, если сомневаетесь между инструментами, сравнение есть в статье про Certbot и acme.sh.

App-service не может подключиться к CouchDB

Budibase хранит метаданные приложений (структуру таблиц, автоматизации, пользователей) в CouchDB — отдельном контейнере внутри того же стека. Если в логах app-service или worker-service вы видите что-то вроде ECONNREFUSED или Error: connect couchdb, проверяйте по порядку:

docker compose logs -f app-service --tail=100

• Контейнер couchdb вообще не поднялся. docker compose ps couchdb-service — если статус не Up, смотрите его логи отдельно, часто причина в повреждённом volume после нештатной перезагрузки сервера.
• Неверный COUCH_DB_URL в .env. Если вы вручную редактировали .env или переносили конфиг с другого сервера, значение должно указывать на имя сервиса в Docker-сети (http://couchdb-service:5984), а не на localhost — частая ошибка при ручной правке compose-файла.
• Сервисы в разных Docker-сетях. Если вы добавляли в стек свои сервисы или разносили конфиг по нескольким compose-файлам, легко случайно разорвать общую сеть — контейнеры Budibase должны оставаться в одной Docker-сети, иначе не видят друг друга по имени.
• CouchDB не успела подняться до старта app-service. На медленном диске app-service может стартовать раньше, чем CouchDB готова принимать соединения, и упасть с ошибкой один раз. Обычно restart: unless-stopped сам лечит это на втором рестарте — если нет, поднимайте сервисы по отдельности: сначала docker compose up -d couchdb-service, дождитесь готовности, потом остальное.

Подключение к внешним источникам данных обрывается

Budibase умеет подключаться не только к своей внутренней CouchDB, но и к внешним PostgreSQL, MySQL, MongoDB, REST API как к источникам данных для таблиц и форм. Здесь всплывают типичные сетевые проблемы:

• Connection timed out при добавлении datasource PostgreSQL/MySQL. Убедитесь, что база слушает внешние подключения (listen_addresses = '*' в postgresql.conf), и что в pg_hba.conf разрешён IP сервера с Budibase:

host    all    all    <IP_servera_budibase>/32    md5

• SSL-ошибки при подключении к managed-базам (облачный PostgreSQL, RDS-подобные сервисы) — если провайдер требует SSL, а в настройках datasource SSL не включён, подключение будет либо падать, либо висеть без внятной ошибки. Проверьте галочку SSL/TLS в форме источника данных.
• Budibase и база на одном сервере, но подключение всё равно не проходит. Если база тоже в Docker, а Budibase указывает на неё через localhost изнутри своего контейнера — это не сработает, контейнеры видят друг друга по имени сервиса, а не через localhost хоста. Похожие сетевые нюансы разобраны в статье PostgreSQL не принимает подключения.
• Долгая синхронизация схемы на больших таблицах. При первом подключении datasource с сотнями тысяч строк Budibase может подвисать на анализе схемы на минуту и больше — это не обрыв, торопиться перезапускать контейнер не стоит.

Email-приглашения и уведомления не отправляются

Self-hosted Budibase не идёт с готовым почтовым релеем — это ожидаемо, но новички часто не понимают, почему кнопка «пригласить пользователя» просто ничего не делает. Проверьте настройки в разделе организации (Settings → SMTP):

• Указан ли вообще SMTP-хост, порт, логин и пароль — без этого приглашения и письма о сбросе пароля не отправляются, а ошибка иногда даже не всплывает в интерфейсе.
• Совпадает ли порт с типом шифрования: 587 обычно требует STARTTLS, 465 — SSL напрямую. Неверная комбинация — самая частая причина тихого молчания SMTP.
• Не блокирует ли исходящий трафик на 587/465 файрвол хостинга — некоторые провайдеры по умолчанию закрывают исходящую почту для борьбы со спамом.

Для проверки, что дело именно в SMTP, а не в Budibase, протестируйте те же креды через swaks прямо с сервера — если письмо не уходит и оттуда, проблема на уровне сети или провайдера, а не приложения.

Контейнер падает по памяти или после обновления версии

Два разных по природе, но одинаково частых сценария поломки уже работающего Budibase.

Нехватка памяти. App-service на Node.js под нагрузкой (построение сложных автоматизаций, индексация больших таблиц в builder-режиме) может потреблять заметно больше памяти, чем кажется на старте. На серверах с 1-2 ГБ RAM это частая причина внезапных падений в OOM. Как ориентир — для стабильной работы полного стека (proxy + app-service + worker-service + couchdb + redis) закладывайте от 4 ГБ, но это именно ориентир из практики, не норматив: цифра зависит от числа пользователей и сложности приложений. Если апгрейд RAM пока не вариант — временная мера, swap-файл: он не решает вопрос производительности под нагрузкой, но не даёт серверу падать намертво.

Рассинхронизация версий сервисов после обновления. Budibase — это связка из нескольких образов (budibase/proxy, budibase/apps, budibase/worker), и они должны быть одной версии друг с другом. Если вручную обновить тег только одного образа в compose-файле, забыв про остальные, получите непонятные ошибки на стыке сервисов — от несовпадения API до отказа авторизации. Правильный путь обновления:

cd budibase/hosting
docker compose pull
docker compose up -d

Это подтягивает согласованный набор версий из официального docker-compose.yaml, а не отдельные образы вручную. Перед любым обновлением обязательно бэкапьте volume с данными CouchDB:

docker run --rm -v hosting_couchdb3_data:/data -v $(pwd)/backup:/backup \
  alpine tar czf /backup/couchdb-$(date +%F).tar.gz -C /data .

Имя volume уточните через docker volume ls | grep couch — оно зависит от того, как называется каталог проекта при разворачивании.

Перенос Budibase на другой сервер и бэкап данных

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

1. Забыли перенести .env. Файл содержит JWT_SECRET, пароли CouchDB, ключи MinIO. Без этих значений старые сессии и API-ключи станут нерабочими, а часть зашифрованных данных в CouchDB — нечитаемой. Копируйте .env вместе с volume как единое целое.
2. Перенесли volume, но не остановили сервисы перед копированием. Копирование "живого" volume CouchDB может дать несогласованный снимок. Правильно: docker compose down на старом сервере → архивирование volume → перенос → распаковка на новом → docker compose up -d.
3. Изменился домен, но не обновили конфиг proxy. Если внешний Nginx на новом сервере не перевыпустил сертификат и не подхватил новую DNS-запись, сессии могут вести себя странно из-за cookie, привязанных к старому домену.
4. Не проверили место на диске заранее. CouchDB и вложения из форм со временем разрастаются — на VPS с меньшим диском распаковка архива может просто не поместиться. Проверьте размер volume заранее: docker run --rm -v hosting_couchdb3_data:/data alpine du -sh /data.

Если параллельно с Budibase на сервере крутятся другие приложения, стоит настроить регулярный автоматический бэкап всего стека, а не только ручной перед миграцией — например, через BorgBackup, он хорошо подходит для инкрементальных снимков Docker-volume.

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