Внешняя PostgreSQL

Последнее обновление 25 сентября 2026Копировать как MarkdownОткрыть как Markdown

По умолчанию база работает в контейнере postgres из состава дистрибутива. Режим external отключает этот контейнер и подключает инстанс к вашей PostgreSQL — выделенному серверу, кластеру Patroni или пулеру соединений.

Внешняя база нужна в двух случаях: когда СУБД в организации администрируется централизованно и когда строится отказоустойчивая схема на двух нодах — там общая база обязательна.

Что меняется

	Встроенная БД (embedded)	Внешняя БД (external)
Контейнер postgres	Запускается, профиль compose db	Не запускается, профиль db не включается
POSTGRES_HOST	postgres — имя сервиса в docker-сети	Ваш адрес: VIP, pgbouncer или endpoint Patroni
Данные	data/postgres/ в каталоге дистрибутива	На вашей стороне
Резервное копирование	Дамп базы и файлы настроек — см. «Резервное копирование и восстановление»	База — по правилам вашей СУБД; файлы настроек с сервера инстанса — см. «Резервное копирование и восстановление»

Остальное не меняется: обращения к базе идут из контейнеров, поэтому адрес должен резолвиться и быть доступен из контейнеров, а не только с хоста.

Требования к базе

• PostgreSQL 15 или новее. Установщик проверяет server_version_num и прерывается на более старой версии.
• Отдельная база и роль. Права суперпользователя не нужны.
• Роли требуются CONNECT на базу, USAGE и CREATE на схему (обычно public) и владение создаваемыми объектами: миграции Flyway создают таблицы от её имени.
• Один адрес мастера. Список хостов в POSTGRES_HOST не поддерживается — используйте VIP, pgbouncer или endpoint Patroni.

Пример подготовки:

CREATE ROLE simple2fa LOGIN PASSWORD '…';
CREATE DATABASE simple2fa_local OWNER simple2fa;
-- в созданной базе:
GRANT CONNECT ON DATABASE simple2fa_local TO simple2fa;
GRANT USAGE, CREATE ON SCHEMA public TO simple2fa;

Установка

Режим задаётся при установке. В интерактивном режиме на вопросе о PostgreSQL укажите external, дальше установщик спросит адрес, порт, режим TLS и учётные данные.

Неинтерактивно:

./install.sh --non-interactive \
  --tls-mode none --host 10.0.0.5 \
  --db-mode external \
  --postgres-host pgvip.example.local \
  --postgres-port 5432 \
  --postgres-database simple2fa_local \
  --postgres-user simple2fa \
  --postgres-password '…' \
  --generate-admin-password

Флаги режима БД:

• --db-mode — embedded (по умолчанию) или external.
• --postgres-host — обязателен для external.
• --postgres-port — по умолчанию 5432.
• --postgres-database, --postgres-user, --postgres-password — реквизиты подключения.
• --postgres-ssl-mode — disable (по умолчанию), require или verify-full.
• --postgres-ssl-ca — файл CA для verify-full; копируется в certs/directory/postgres-ca.pem.
• --database-url — альтернатива отдельным параметрам: строка вида postgres://user:pass@host:5432/db?sslmode=require. Дискретные переменные при этом остаются — их использует панель.
• --migrate — только применить миграции и выйти, без запуска стека.

Предварительная проверка

Перед запуском стека установщик подключается к базе одноразовым контейнером postgres:16-alpine и проверяет три вещи:

1. соединение с указанными реквизитами и режимом TLS;
2. версию сервера — не ниже 15;
3. право CREATE на текущей схеме.

Если любая проверка не проходит, установка прерывается до того, как что-либо будет создано.

TLS до базы

Режим	Поведение
disable	Без шифрования. По умолчанию
require	Шифрование обязательно, сертификат сервера не проверяется
verify-full	Шифрование и полная проверка сертификата по вашему CA

Файл CA помещается в certs/directory/postgres-ca.pem — туда же, где хранятся корневые сертификаты каталогов. Установщик копирует его сам, если передать --postgres-ssl-ca.

Режим и путь применяются одинаково к local-backend и к панели администратора: обе части стека обращаются к базе с одинаковыми настройками TLS.

Права на каталог сертификатов

certs/directory должен быть доступен на чтение непривилегированному пользователю контейнера — каталог 755, файлы 644. Иначе local-backend не прочитает CA и будет перезапускаться.

Миграции

Схему применяет одноразовый сервис migrate — тот же образ local-backend, запущенный с APP_MIGRATE_ONLY. Его запускают install.sh и update.sh до старта основных контейнеров.

Шаг ограничен примерно 90 секундами: зависший контейнер снимается, и при необходимости схема применяется уже при старте local-backend. Flyway использует таблицу блокировок, поэтому одновременный старт двух нод на пустой базе безопасен — но при обновлении нод их всё равно обновляют по одной.

Применить миграции отдельно, не запуская стек:

./install.sh --migrate

Проверка

./doctor.sh в режиме external проверяет:

• доступность базы с указанными реквизитами;
• версию не ниже 15 и право CREATE;
• наличие таблицы flyway_schema_history — то есть что миграции хотя бы раз применялись;
• маркерную таблицу схемы;
• health-статус local-backend — если контейнер здоров, схема совместима с образом.

Контейнер postgres при этом не ожидается, и его отсутствие ошибкой не считается.

Типовые ошибки:

Строка doctor.sh	Причина	Действие
[FAIL] Внешняя PostgreSQL недоступна или права недостаточны	Сеть, реквизиты, TLS или права роли	Проверить доступ из контейнеров, режим TLS и права CONNECT, USAGE, CREATE
[FAIL] Нет flyway_schema_history	Миграции не применялись	./install.sh --migrate или ./update.sh на одной ноде
[FAIL] Схема неполная	Миграции применились не до конца	Смотреть docker compose logs backend-local --tail 80

Имя сервиса backend

В командах docker compose сервис backend называется backend-local. В прежних версиях дистрибутива он назывался local-backend. Если команда отвечает no such service: backend-local, стенд ещё не обновлён — используйте прежнее имя или обновите стенд командой ./update.sh.

Смотрите также

• Установка локального инстанса
• Отказоустойчивость на двух нодах
• Резервное копирование и восстановление
• Особые сценарии развёртывания