Подключение PostgreSQL

Эта инструкция описывает установку PostgreSQL 18 на сервер с Debian 12, подключение сервера базы данных к FASTPANEL, включение поддержки PostgreSQL в PHP 8.4 и создание отдельных баз для iEXExchanger.

Инструкция подходит для двух сценариев:

• первоначальная установка iEXExchanger на новый сервер;
• подготовка PostgreSQL перед переносом существующего проекта.

В обоих случаях PostgreSQL устанавливается и подключается одинаково. Первоначальная установка системы и перенос данных выполняются по отдельным инструкциям.

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

Что будет настроено

После выполнения инструкции:

• PostgreSQL 18 будет установлен на сервер;
• будет создан локальный кластер 18/main;
• PostgreSQL будет принимать только локальные подключения;
• FASTPANEL получит административную роль fastuser;
• PostgreSQL появится в списке серверов баз данных FASTPANEL;
• в PHP 8.4 будут включены модули pdo_pgsql и pgsql;
• для Backend будет создана отдельная база;
• для Laravel Pulse при необходимости будет создана база pulse_pg;
• для каждой базы будет создан отдельный пользователь;
• подключение будет проверено через psql.

PostgreSQL поддерживает Debian 12 Bookworm через официальный PGDG-репозиторий, из которого можно установить пакет postgresql-18. Официальная инструкция PostgreSQL для Debian

На момент подготовки документа в разделе приложений FASTPANEL доступны версии PostgreSQL до 17. Поэтому PostgreSQL 18 устанавливается отдельным скриптом, после чего подключается к панели как локальный сервер баз данных. Список приложений FASTPANEL

Перед началом

Убедитесь, что выполнены следующие условия:

• используется Debian 12 Bookworm;
• FASTPANEL установлена и работает;
• PHP 8.4 установлен через FASTPANEL;
• Backend iEXExchanger загружен на сервер;
• у вас есть доступ к серверу по SSH;
• доступен пользователь root;
• сервер может подключаться к apt.postgresql.org;
• в папке scripts Backend-проекта находится установщик PostgreSQL.

Файл установщика:

scripts/install-postgresql18-fastpanel.sh

Важные ограничения

При настройке соблюдайте следующие правила:

• не устанавливайте PostgreSQL 17 через раздел «Приложения»;
• не открывайте порт PostgreSQL в публичном firewall;
• не используйте пароль Linux-пользователя root в настройках PostgreSQL;
• не используйте административную роль fastuser в iEXExchanger;
• не назначайте PostgreSQL сервером баз данных по умолчанию в FASTPANEL;
• используйте отдельного пользователя для каждой базы;
• храните пароли баз данных в защищённом месте.

---

Подключение к серверу

Подключитесь к серверу от имени пользователя root:

Подключение к серверу по SSH

ssh root@SERVER_IP

Вместо SERVER_IP укажите IP-адрес сервера.

Переход в Backend-проект

Перейдите в корневую директорию Backend, где находится файл artisan.

Файлы сайта в FastPanel

Пример:

cd /var/www/ВЛАДЕЛЕЦ_САЙТА/data/www/app.ВАШ_ДОМЕН

Например:

cd /var/www/example_com_usr/data/www/app.example.com

Проверьте наличие установщика:

ls -la scripts/install-postgresql18-fastpanel.sh

Если файл отображается, можно продолжать установку.

При необходимости установите право на выполнение:

chmod 0755 scripts/install-postgresql18-fastpanel.sh

Установка PostgreSQL 18

Находясь в корневой директории Backend, запустите:

bash scripts/install-postgresql18-fastpanel.sh

Скрипт автоматически:

• проверит версию операционной системы;
• проверит запуск от root;
• проверит состояние apt и dpkg;
• подключит официальный PGDG-репозиторий;
• установит postgresql-18;
• установит postgresql-client-18;
• создаст или обнаружит кластер 18/main;
• настроит кодировку UTF8;
• включит контрольные суммы данных;
• настроит SCRAM-аутентификацию;
• ограничит подключения адресами 127.0.0.1 и ::1;
• создаст административную роль fastuser;
• сгенерирует пароль для fastuser;
• проверит основные возможности PostgreSQL;
• удалит созданную для проверки тестовую базу;
• сохранит реквизиты в защищённый файл;
• выведет параметры подключения для FASTPANEL.

При стандартной установке PostgreSQL будет работать со следующими параметрами:

Host: 127.0.0.1
Port: 5432
Database: postgres

Если на сервере уже работает другой кластер PostgreSQL, порт может отличаться. Используйте значение, которое покажет установщик.

Результат выполнения установщика

После успешного завершения появится блок примерно следующего вида:

============================================================
POSTGRESQL 18 ГОТОВ
============================================================
Версия:              18.x
Кластер:             18/main
Host:                127.0.0.1
Port:                5432
Database:            postgres
Username:            fastuser
Password:            СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ
Файл реквизитов:     /root/postgresql18-installer/fastpanel-postgresql18.credentials
============================================================

Поля FASTPANEL:
  Имя:               PostgreSQL 18 local
  По умолчанию:      не включать
  Тип сервера:       PostgreSQL
  Подключение:       Локальное
  Имя пользователя:  fastuser
  Пароль:            СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ
  Хост/порт в форме: оставить автоматическими

Реквизиты сохраняются в файле:

/root/postgresql18-installer/fastpanel-postgresql18.credentials

Посмотреть содержимое можно только от пользователя root:

cat /root/postgresql18-installer/fastpanel-postgresql18.credentials

Ожидаемый формат:

name=PostgreSQL 18 local
type=PostgreSQL
connection=Local
host=127.0.0.1
port=5432
database=postgres
username=fastuser
password=СГЕНЕРИРОВАННЫЙ_ПАРОЛЬ

Файл защищён следующими правами:

Владелец: root
Группа: root
Права: 0600

Не копируйте его:

• в директорию сайта;
• в публичную папку;
• в Git-репозиторий;
• в общедоступное облачное хранилище;
• в переписку с сотрудниками.

Проверка PostgreSQL

Проверьте установленную версию:

psql --version

Проверьте версию утилиты резервного копирования:

pg_dump --version

Проверьте состояние кластеров:

pg_lsclusters

Проверьте системную службу:

systemctl is-active postgresql@18-main

Проверьте готовность принимать подключения:

pg_isready -h 127.0.0.1 -p 5432

Ожидаемый результат:

18/main    5432    online
127.0.0.1:5432 - accepting connections

Если установщик показал другой порт, используйте его вместо 5432.

Проверка сетевой доступности

PostgreSQL должен принимать подключения только внутри сервера.

Выполните:

ss -ltnp | grep -E ':(5432|5433|5434|5435)\b'

Нормальный результат содержит локальные адреса:

127.0.0.1:5432
[::1]:5432

Если отображается:

0.0.0.0:5432

или публичный IP сервера, не продолжайте настройку. Сначала закройте внешний доступ.

Важно. Для локального размещения iEXExchanger порт PostgreSQL не нужно открывать в интернете.

Повторная проверка установщиком

Для проверки текущей конфигурации без изменения настроек выполните из корневой директории Backend:

bash scripts/install-postgresql18-fastpanel.sh --check

Команда проверяет:

• версию PostgreSQL;
• кластер;
• локальное подключение;
• административную роль;
• доступность необходимых компонентов;
• PHP-модули, если они уже включены.

Обычная проверка не меняет пароль fastuser.

Смена пароля fastuser

Для принудительной смены пароля выполните:

bash scripts/install-postgresql18-fastpanel.sh --rotate-password

После смены обязательно обновите пароль в настройках сервера баз данных FASTPANEL.

Если в FASTPANEL останется старый пароль, сервер получит статус «Недоступен».

---

Включение PostgreSQL в PHP 8.4

Для подключения iEXExchanger к PostgreSQL необходимо включить соответствующие PHP-модули.

FASTPANEL позволяет управлять модулями отдельно для каждой установленной версии PHP. Настройка PHP и модулей в FASTPANEL

1

Где находятся модули

В FASTPANEL откройте: «Управление» — «PHP»

Затем:

1. выберите PHP 8.4;
2. откройте управление модулями;
3. найдите pdo_pgsql;
4. найдите pgsql;
5. включите оба модуля;
6. сохраните изменения.

Убедитесь, что Backend-сайт также использует PHP 8.4.

2

Для чего нужны модули

Модуль	Для чего используется
pdo_pgsql	Подключение Laravel к PostgreSQL через PDO
pgsql	Нативные функции PostgreSQL в PHP

Для Laravel основным является pdo_pgsql, но рекомендуется включить оба модуля.

3

Проверка PHP-модулей

Выполните:

/opt/php84/bin/php -r 'echo json_encode([
    "pdo_pgsql" => extension_loaded("pdo_pgsql"),
    "pgsql" => extension_loaded("pgsql"),
    "pdo_drivers" => PDO::getAvailableDrivers(),
]), PHP_EOL;'

Ожидаемый результат:

{"pdo_pgsql":true,"pgsql":true,"pdo_drivers":["sqlite","mysql","pgsql"]}

Порядок драйверов может отличаться. В списке обязательно должен присутствовать:

pgsql

Дополнительная проверка:

/opt/php84/bin/php --ri pdo_pgsql

/opt/php84/bin/php --ri pgsql

/opt/php84/sbin/php-fpm -t

systemctl is-active fp2-php84-fpm

Ожидаемый статус:

active

Если установщик сообщил:

В PHP 8.4 не включены pdo_pgsql и/или pgsql

PostgreSQL мог быть установлен правильно. Включите модули через FASTPANEL и снова выполните:

bash scripts/install-postgresql18-fastpanel.sh --check

---

Добавление PostgreSQL 18 в FASTPANEL

FASTPANEL умеет управлять локальными и внешними серверами баз данных. После подключения PostgreSQL можно выбирать при создании новых баз. Управление серверами баз данных FASTPANEL

Где находится раздел

В FASTPANEL откройте: «Управление» — «Базы данных»

Затем откройте: «Серверы баз данных»

Нажмите: «Добавить сервер»

Страница может иметь следующий адрес:

https://SERVER_IP:8888/databases/servers

Заполнение формы

Укажите:

Поле	Значение
Имя	PostgreSQL 18 local
Использовать сервер по умолчанию	Нет
Тип сервера	PostgreSQL
Тип подключения	Локальное
Имя пользователя	fastuser
Пароль	Пароль из файла реквизитов
Хост	Оставить автоматическим
Порт	Оставить 0 или автоматическим

Нажмите «Сохранить».

Почему сервер не нужно выбирать по умолчанию

PostgreSQL 18 подключается как отдельный сервер баз данных для конкретных проектов.

Используйте значение:

Использовать сервер по умолчанию: Нет

При создании базы выбирайте PostgreSQL 18 local вручную.

Проверка сервера в FASTPANEL

Вернитесь в раздел: «Управление» — «Базы данных»

Откройте: «Серверы баз данных»

У добавленной записи должно отображаться:

PostgreSQL 18 local
Статус: Доступен

Не создавайте базы, пока сервер не получил статус «Доступен».

Проверка через CLI

Выполните:

mogwai databases servers list

В списке должна присутствовать запись с признаками:

TYPE: postgresql
LOCAL: true
USERNAME: fastuser
AVAIL: true

FASTPANEL поддерживает просмотр серверов и синхронизацию списка баз через mogwai. Команды управления базами FASTPANEL

При необходимости выполните:

mogwai databases sync

Какие пользователи используются

При подключении важно не перепутать разные учётные записи.

Учётная запись	Назначение
fastuser	Административная роль PostgreSQL для FASTPANEL
example_com_usr	Владелец Backend-сайта в FASTPANEL и Linux
app_example_com_pg	Пользователь основной базы iEXExchanger
pulse_pg	Пользователь базы Laravel Pulse

1

fastuser

Роль используется FASTPANEL для:

• создания баз;
• создания пользователей;
• управления PostgreSQL через панель.

Не используйте fastuser как пользователя iEXExchanger.

2

Владелец сайта

Поле «Владелец» в FASTPANEL относится к пользователю панели и Linux.

Пример:

example_com_usr

Это не логин PostgreSQL.

3

Пользователь основной базы

Для основной базы создаётся отдельный пользователь.

Пример:

app_example_com_pg

4

Пользователь Pulse

Для базы Laravel Pulse используется отдельный пользователь:

pulse_pg

---

Создание основной базы

FASTPANEL позволяет создать базу, назначить владельца, связать её с сайтом и выбрать сервер. Создание базы данных в FASTPANEL

Где находится раздел

В FASTPANEL откройте: «Сайты»

Выберите Backend-сайт:

app.ваш_домен

Откройте раздел:«Базы данных»

Нажмите:«Новая база данных»

Заполнение формы

Пример для сайта app.example.com:

Поле	Значение
Имя	app_example_com_pg
Кодировка	utf8
Владелец	Владелец Backend-сайта, например example_com_usr
Сервер	PostgreSQL 18 local
Пользователь	Создать нового пользователя
Логин	app_example_com_pg
Пароль	Отдельный надёжный пароль
Повторите пароль	Тот же пароль

Нажмите «Сохранить».

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

Используйте:

• строчные латинские буквы;
• цифры;
• символ _.

Пример:

app_example_com_pg

Не используйте:

• пробелы;
• дефисы;
• кириллицу;
• специальные символы.

Кодировка

В FASTPANEL выберите:

utf8

В PostgreSQL она отображается как:

UTF8

MySQL-кодировка:

utf8mb4

для PostgreSQL не используется.

Пароль пользователя

Создайте отдельный случайный пароль.

Он не должен совпадать с паролями:

• root;
• FASTPANEL;
• fastuser;
• владельца сайта;
• административной панели iEXExchanger.

Сохраните пароль в защищённом менеджере.

Создание базы Laravel Pulse

Если проект использует Laravel Pulse, создайте отдельную базу.

В карточке Backend-сайта снова нажмите: «Новая база данных»

Заполните форму:

Поле	Значение
Имя	pulse_pg
Кодировка	utf8
Владелец	Владелец Backend-сайта
Сервер	PostgreSQL 18 local
Пользователь	Создать нового пользователя
Логин	pulse_pg
Пароль	Отдельный надёжный пароль
Повторите пароль	Тот же пароль

Для основной базы и Pulse используйте разные пароли.

После создания должны существовать:

Основная база:
Database: app_example_com_pg
Username: app_example_com_pg

Pulse:
Database: pulse_pg
Username: pulse_pg

Если Laravel Pulse не используется, базу pulse_pg создавать не нужно.

---

Проверка основной базы

Подключитесь через psql:

psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=app_example_com_pg \
  --dbname=app_example_com_pg

Введите пароль пользователя базы.

После подключения выполните:

SELECT
    current_database(),
    current_user,
    current_setting('server_version'),
    current_setting('server_encoding');

Ожидаемый результат:

current_database | app_example_com_pg
current_user     | app_example_com_pg
server_version   | 18.x
server_encoding  | UTF8

Для выхода выполните:

\q

Проверка базы Pulse

Подключитесь:

psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=pulse_pg \
  --dbname=pulse_pg

После подключения выполните:

SELECT
    current_database(),
    current_user,
    current_setting('server_version'),
    current_setting('server_encoding');

Ожидается:

current_database | pulse_pg
current_user     | pulse_pg
server_version   | 18.x
server_encoding  | UTF8

Для выхода:

\q

Проверка новых баз

Сразу после создания базы не содержат таблиц.

Для основной базы выполните:

psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=app_example_com_pg \
  --dbname=app_example_com_pg \
  --command="\dt"

Ожидаемый результат:

Did not find any relations.

Для Pulse:

psql \
  --host=127.0.0.1 \
  --port=5432 \
  --username=pulse_pg \
  --dbname=pulse_pg \
  --command="\dt"

Ожидается:

Did not find any relations.

Это подтверждает, что базы успешно созданы и готовы к следующему этапу установки или переноса.

Параметры подключения основной базы

Сохраните следующие данные:

Driver: pgsql
Host: 127.0.0.1
Port: 5432
Database: app_example_com_pg
Username: app_example_com_pg
Password: ПАРОЛЬ_ОСНОВНОЙ_БАЗЫ
SSL mode: disable

Для новой установки эти данные используются при настройке Backend.

При переносе существующего проекта они потребуются на отдельном этапе миграции.

Пример параметров:

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=app_example_com_pg
DB_USERNAME=app_example_com_pg
DB_PASSWORD="ПАРОЛЬ_ОСНОВНОЙ_БАЗЫ"
DB_SSLMODE=disable

Не применяйте этот блок к работающему проекту до перехода на PostgreSQL.

Параметры подключения Pulse

Driver: pgsql
Host: 127.0.0.1
Port: 5432
Database: pulse_pg
Username: pulse_pg
Password: ПАРОЛЬ_БАЗЫ_PULSE
SSL mode: disable

Пример:

PULSE_DB_CONNECTION=pgsql-pulse
PULSE_DB_HOST=127.0.0.1
PULSE_DB_PORT=5432
PULSE_DB_DATABASE=pulse_pg
PULSE_DB_USERNAME=pulse_pg
PULSE_DB_PASSWORD="ПАРОЛЬ_БАЗЫ_PULSE"
PULSE_DB_SSLMODE=disable

Параметры применяются на соответствующем этапе установки или переноса проекта.

Что делать дальше

После успешного подключения выберите подходящую инструкцию:

• для нового проекта — продолжите первоначальную установку iEXExchanger;
• для существующего проекта — перейдите к отдельной инструкции по переносу базы данных.

Эта статья завершается проверкой подключения. Создание структуры таблиц и перенос данных выполняются на следующем этапе.

---

Частые ошибки

FASTPANEL не подключается к PostgreSQL

Проверьте:

1. В форме используется пользователь fastuser.
2. Введён пароль из файла:

/root/postgresql18-installer/fastpanel-postgresql18.credentials

1. Выбран тип сервера PostgreSQL.
2. Выбрано локальное подключение.
3. Хост и порт оставлены автоматическими.
4. PostgreSQL работает:

pg_isready -h 127.0.0.1 -p 5432

1. Установщик успешно проходит проверку:

bash scripts/install-postgresql18-fastpanel.sh --check

Если пароль fastuser изменён, внесите новое значение в FASTPANEL.

Сервер имеет статус «Недоступен»

Проверьте:

systemctl is-active postgresql@18-main

pg_isready -h 127.0.0.1 -p 5432

mogwai databases servers list

Также проверьте пароль fastuser и фактический порт кластера.

PHP показывает could not find driver

Причина — модуль pdo_pgsql не включён в PHP 8.4.

Проверьте:

/opt/php84/bin/php --ri pdo_pgsql

/opt/php84/bin/php --ri pgsql

Убедитесь, что Backend-сайт назначен на PHP 8.4.

Пользователь уже существует

Удаление базы не всегда удаляет PostgreSQL-пользователя.

Используйте другой уникальный логин или удалите старого пользователя через FASTPANEL, если уверены, что он больше нигде не используется.

Не выполняйте DROP ROLE вручную, пока не проверите принадлежность объектов.

Не удаётся подключиться через psql

Проверьте:

• имя базы;
• имя пользователя;
• пароль;
• порт;
• состояние PostgreSQL;
• отсутствие лишних пробелов в реквизитах.

Имя базы и имя пользователя могут совпадать, но являются разными объектами PostgreSQL.

База не отображается в FASTPANEL

Выполните синхронизацию:

mogwai databases sync

Затем обновите страницу панели.

Установщик не найден

Убедитесь, что вы находитесь в корневой директории Backend:

pwd

Проверьте файл:

ls -la scripts/install-postgresql18-fastpanel.sh

Если файл отсутствует, повторно загрузите полный архив Backend или добавьте установщик в папку scripts.

---

Проверка результата

После выполнения инструкции должно быть подтверждено:

1. PostgreSQL 18 установлен.
2. Кластер 18/main работает.
3. PostgreSQL принимает локальные подключения.
4. Публичный доступ к порту отсутствует.
5. PHP 8.4 видит драйвер pgsql.
6. FASTPANEL показывает PostgreSQL как доступный сервер.
7. Создана основная база.
8. Для основной базы создан отдельный пользователь.
9. При необходимости создана база pulse_pg.
10. Для Pulse создан пользователь pulse_pg.
11. Подключение к базам через psql работает.
12. Реквизиты сохранены для следующего этапа.

Контрольный список

• PostgreSQL 18 установлен.
• Кластер 18/main имеет статус online.
• PostgreSQL доступен на 127.0.0.1.
• Публичный порт PostgreSQL закрыт.
• Создана роль fastuser.
• Реквизиты fastuser сохранены в защищённом файле.
• В PHP 8.4 включены pdo_pgsql и pgsql.
• Backend-сайт использует PHP 8.4.
• В FASTPANEL добавлен сервер PostgreSQL 18 local.
• Сервер имеет статус «Доступен».
• PostgreSQL не выбран сервером по умолчанию.
• Создана отдельная основная база.
• Для основной базы создан отдельный пользователь.
• При необходимости создана база pulse_pg.
• Для Pulse создан пользователь pulse_pg.
• Использована кодировка UTF8.
• Подключение к основной базе проверено.
• Подключение к Pulse проверено.
• Реквизиты сохранены для установки или переноса.

Коротко

PostgreSQL 18 устанавливается из официального PGDG-репозитория и подключается к FASTPANEL как отдельный локальный сервер баз данных.

FASTPANEL использует административную роль fastuser. Для iEXExchanger создаётся отдельная основная база и пользователь, а для Laravel Pulse — база и пользователь pulse_pg.

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