Установка и настройка PostgreSQL

ФинГрад работает с PostgreSQL, развёрнутом на хосте выделенного сервера БД. Эта статья описывает развёртывание и настройку такого сервера двумя способами: автоматически (скриптом) и вручную. Раздел Параметры конфигурации ФинГрад поясняет, что и зачем настраивается.

Объём памяти, число ядер и накопитель под сервер СУБД рассчитываются согласно статье Системные требования.

Поддерживаемые ОС

Скрипт и инструкции рассчитаны на Debian-совместимые ОС: Debian, Ubuntu, Astra Linux. Они используют общий фреймворк postgresql-common (одинаковые пути /etc/postgresql/<версия>/<кластер>/, каталог conf.d/, служба postgresql@<версия>-<кластер>), поэтому настройка идентична – различается только источник пакета при установке.

Автоматизированная настройка

Описание скрипта

Автоматизированная настройка выполняется при помощи скрипта bash. Скрипт setup-postgres.sh:

определяет дистрибутив ОС по /etc/os-release;
при необходимости устанавливает PostgreSQL (INSTALL=auto|yes|no): Debian/Ubuntu – из репозитория PGDG, Astra Linux – из настроенных репозиториев;
кладёт параметры ФинГрад в conf.d/10-fingrad.conf (override поверх дистрибутивного postgresql.conf, не переписывая его);
открывает доступ в pg_hba.conf;
резервирует huge pages на хосте с проверкой: спрашивает у PostgreSQL точное число страниц, пишет vm.nr_hugepages, поднимает LimitMEMLOCK для службы. Если страниц не хватило – PostgreSQL не перезапускается (с huge_pages = on он бы не стартовал), скрипт просит перезагрузку;
запускает PostgreSQL и проверяет, что он поднялся.

Создание самой БД ФинГрад в задачи скрипта не входит – оно выполняется отдельно утилитой из дистрибутива «ФинГрад — Корпоративное казначейство» (см. После настройки: создание роли).

Получение файлов

Скачайте скрипт, шаблон конфигурации и пример параметров в один каталог на сервере БД:

mkdir -p ~/fingrad-postgres && cd ~/fingrad-postgres
curl -fLO https://dl.fingrad.com/scripts/postgres/setup-postgres.sh
curl -fLO https://dl.fingrad.com/scripts/postgres/setup-postgres.env.example
curl -fLO https://dl.fingrad.com/scripts/postgres/postgresql.fingrad.conf.template
chmod +x setup-postgres.sh

Ссылки на файлы:

setup-postgres.sh – скрипт установки и настройки;
setup-postgres.env.example – список параметров со значениями по умолчанию (копируется в setup-postgres.env);
postgresql.fingrad.conf.template – шаблон override-конфига, из которого формируется conf.d/10-fingrad.conf.

Все три файла должны лежать рядом.

Параметры

Скопируйте файл с переменными среды окружения как setup-postgres.env командой ниже и отредактируйте.

cp setup-postgres.env.example setup-postgres.env

Обязательные к заполнению параметры:

Параметр	Назначение
`MEMORY`	Память под буферный кэш СУБД (`shared_buffers`), например `64GB`. Резервируется в huge pages, т. е. закрепляется за PostgreSQL и изымается из ОЗУ под нужды ОС. Ориентир ≈ 25–50% ОЗУ (на машине с 128 ГБ типично `64GB`).
`CPU_CORES`	Число ядер ЦП под СУБД. Идёт и в `max_worker_processes`, и в `max_parallel_workers`.

Остальное имеет разумные значения по умолчанию:

Параметр	По умолчанию	Назначение
`EFFECTIVE_CACHE_SIZE`	`auto`	Подсказка планировщику о суммарном кэше. `auto` = 75% ОЗУ. Память не выделяет, должна быть больше `shared_buffers` (см. параметры).
`VERSION`	`18`	Мажорная версия PostgreSQL.
`PORT`	`5432`	Порт СУБД.
`INSTALL`	`auto`	Режим установки: `auto` – поставить, если не найден; `yes` – поставить принудительно; `no` – не ставить (только настроить).
`LOCALE`	`ru_RU.UTF-8`	Локаль кластера. Применяется только при создании нового кластера (`initdb`).
`ENCODING`	`UTF8`	Кодировка кластера (при создании).

Запуск

От root (sudo может отсутствовать – тогда запускайте под root напрямую):

sudo ./setup-postgres.sh    # или, если sudo не установлен: ./setup-postgres.sh

Режим «PostgreSQL уже установлен»

Поставьте INSTALL=no – скрипт пропустит установку и только сформирует конфиг, настроит pg_hba.conf и huge pages для существующего кластера VERSION/main. Этот же режим используйте в закрытом контуре Astra Linux, где PostgreSQL устанавливается штатными средствами ОС.

Если huge pages не зарезервировались сразу

При фрагментации памяти выделить много huge pages в рантайме не всегда возможно. Скрипт запишет vm.nr_hugepages (применится при загрузке) и завершится с кодом 2, не трогая работающий PostgreSQL. Варианты:

перезагрузить сервер и запустить скрипт повторно (он пропустит установку и довершит настройку); либо
задать huge pages при загрузке ядра через GRUB: добавить hugepages=<N> в GRUB_CMDLINE_LINUX (где <N> – число из вывода скрипта), затем update-grub и перезагрузка.

Ручная настройка

Если автоматический скрипт неприменим, те же шаги выполняются вручную. Ниже – для версии 18 и кластера main; подставьте свои значения.

1. Установка PostgreSQL

Debian / Ubuntu (репозиторий PGDG):

sudo apt-get install -y curl ca-certificates gnupg locales
sudo install -d /usr/share/postgresql-common/pgdg
sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc \
  -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(. /etc/os-release; echo $VERSION_CODENAME)-pgdg main" \
  | sudo tee /etc/apt/sources.list.d/pgdg.list
sudo apt-get update
sudo apt-get install -y postgresql-18

Astra Linux – из настроенных репозиториев:

sudo apt-get update
sudo apt-get install -y postgresql-18

Пакет postgresql-18 автоматически создаёт кластер main. Если нужного кластера нет – создайте его с локалью ФинГрад:

sudo pg_createcluster --locale ru_RU.UTF-8 -e UTF8 18 main

2. Генерация локали

Параметры lc_* требуют, чтобы локаль была сгенерирована в системе, иначе PostgreSQL отвергнет конфиг (invalid value for parameter lc_messages):

sudo sed -i 's/^# *\(ru_RU.UTF-8\)/\1/' /etc/locale.gen
sudo locale-gen

3. Параметры конфигурации

Рекомендуемый способ – не править дистрибутивный postgresql.conf, а положить параметры ФинГрад в drop-in conf.d/10-fingrad.conf. За основу возьмите шаблон postgresql.fingrad.conf.template, заменив плейсхолдеры @…@ своими значениями (@PORT@, @MEMORY@, @EFFECTIVE_CACHE_SIZE@, @CPU_CORES@, @LC@):

sudo install -d -o postgres -g postgres /etc/postgresql/18/main/conf.d
# отредактируйте шаблон и сохраните как conf.d/10-fingrad.conf:
sudo cp postgresql.fingrad.conf.template /etc/postgresql/18/main/conf.d/10-fingrad.conf

Убедитесь, что основной postgresql.conf подключает каталог conf.d (в Debian-сборках это уже так):

include_dir = 'conf.d'

Полный разбор параметров – в разделе Параметры конфигурации ФинГрад.

4. Доступ в `pg_hba.conf`

Добавьте в /etc/postgresql/18/main/pg_hba.conf правила доступа со всех адресов методом scram-sha-256 (при необходимости ограничьте подсетью сервера приложения):

host    all    all    0.0.0.0/0    scram-sha-256
host    all    all    ::/0         scram-sha-256

5. Huge pages

С остановленным сервером вычислите точное число страниц (postgres -C берёт блокировку каталога данных, поэтому не должен конфликтовать с работающим сервером):

sudo systemctl stop postgresql@18-main
DATA_DIR=$(pg_lsclusters -h | awk '$1==18 && $2=="main" {print $6}')
sudo -u postgres /usr/lib/postgresql/18/bin/postgres \
  -C shared_memory_size_in_huge_pages \
  -D "$DATA_DIR" -c config_file=/etc/postgresql/18/main/postgresql.conf

Зарезервируйте полученное число N (с небольшим запасом) и поднимите лимит заблокированной памяти для службы:

echo 'vm.nr_hugepages = N' | sudo tee /etc/sysctl.d/30-fingrad-postgresql.conf
sudo sysctl --system
sudo systemctl edit postgresql@18-main   # добавить:  [Service]\n LimitMEMLOCK=infinity
sudo systemctl start postgresql@18-main

Проверьте, что страниц выделено не меньше требуемого (grep HugePages_Total /proc/meminfo) и что сервер поднялся. С huge_pages = on при нехватке страниц PostgreSQL не запустится.

Параметры конфигурации ФинГрад

ФинГрад поставляет рекомендованный набор параметров (формируется в conf.d/10-fingrad.conf). Он делится на две группы.

Где менять параметры

conf.d/10-fingrad.conf загружается после postgresql.conf и переопределяет его. Поэтому правка одноимённых параметров в самом postgresql.conf эффекта не даст. Для дальнейшего тюнинга правьте conf.d/10-fingrad.conf либо используйте ALTER SYSTEM SET … (пишется в postgresql.auto.conf с наивысшим приоритетом). Повторный запуск setup-postgres.sh перезаписывает 10-fingrad.conf.

Функциональные параметры

ФинГрад настраивает их для корректной работы и совместимости с Linux-сервером. Менять обычно не следует.

Параметр	Значение	Назначение
`huge_pages`	`on`	Размещает `shared_buffers` в huge pages (прирост производительности на больших буферах). При нехватке страниц сервер не стартует – поэтому скрипт резервирует их с проверкой.
`track_commit_timestamp`	`on`	Включает запись времени фиксации транзакций.
`dynamic_shared_memory_type`	`posix`	Механизм динамической разделяемой памяти для Linux.
`lc_messages`, `lc_monetary`, `lc_numeric`, `lc_time`	`ru_RU.UTF-8`	Локаль сообщений и форматов чисел/денег/времени (на Linux вместо windows-значения `Russian_Russia.1251`). Требует сгенерированной в системе локали.
`datestyle`	`iso, dmy`	Формат вывода и порядок разбора дат (день-месяц-год).
`timezone`, `log_timezone`	`Europe/Moscow`	Часовой пояс сервера и логов.
`default_text_search_config`	`pg_catalog.russian`	Конфигурация полнотекстового поиска по умолчанию (русская морфология).
`shared_preload_libraries`	`pg_prewarm, pg_stat_statements`	Предзагрузка библиотек: `pg_prewarm` (прогрев буферного кэша), `pg_stat_statements` (статистика запросов). Требует contrib-модулей PostgreSQL.
`log_destination`, `logging_collector`, `log_file_mode`	`stderr`, `on`, `0640`	Сбор логов сервера в файлы.

Параметры производительности

Подбираются под объём памяти, число ядер и нагрузку сервера. Именно их вы настраиваете под себя; при автоматической настройке большинство вычисляется из MEMORY и CPU_CORES.

Параметр	Значение в профиле	Назначение
`shared_buffers`	`= MEMORY`	Основной буфер СУБД. Резервируется в huge pages. Ориентир ≈ 25–50% ОЗУ.
`effective_cache_size`	`auto` (≈75% ОЗУ)	Оценка суммарного кэша (`shared_buffers` + кэш страниц ОС) для планировщика. Память не выделяет; должна быть больше `shared_buffers`.
`work_mem`	`512MB`	Память на одну операцию сортировки/хеширования. Под нагрузкой суммируется по соединениям и параллелизму – отсюда запас ОЗУ сверх `shared_buffers`.
`maintenance_work_mem`	`1GB`	Память под обслуживающие операции (`VACUUM`, построение индексов).
`min_dynamic_shared_memory`	`2GB`	Резерв динамической разделяемой памяти под параллельные запросы.
`max_connections`	`1000`	Максимум одновременных подключений.
`max_worker_processes`, `max_parallel_workers`	`= CPU_CORES`	Общее число фоновых и параллельных рабочих процессов; приравниваются к числу ядер ЦП.
`max_parallel_workers_per_gather`	`6`	Параллельных воркеров на один узел `Gather` (один запрос).
`max_parallel_maintenance_workers`	`6`	Параллелизм обслуживающих операций.
`checkpoint_completion_target`, `max_wal_size`, `min_wal_size`	`0.9`, `4GB`, `1GB`	Контрольные точки и WAL: сглаживают запись на диск.
`autovacuum_worker_slots`	`16`	Число слотов процессов автовакуума.

После настройки: создание роли

Скрипт не создаёт учётную запись БД. Приложение и DbManager подключаются по TCP, поэтому нужна роль PostgreSQL с паролем (у суперпользователя postgres пароля нет – он доступен только локально через peer-аутентификацию). DbManager требует прав SUPERUSER, поэтому создаваемая роль должна быть суперпользователем:

# под root (sudo может отсутствовать):
runuser -u postgres -- psql -c "CREATE ROLE fingrad LOGIN SUPERUSER PASSWORD 'ПАРОЛЬ';"
# или, если установлен sudo:
sudo -u postgres psql -c "CREATE ROLE fingrad LOGIN SUPERUSER PASSWORD 'ПАРОЛЬ';"

Затем:

Создайте БД ФинГрад утилитой DbManager под этой ролью (команда выполняется с сервера приложения – см. Создание базы данных).
Укажите эту же роль и пароль в строках подключения приложения (WEB_DB_CONNECTION_STRING / TS_DB_CONNECTION_STRING в .env).

Автоматизированная настройка​

Описание скрипта​

Получение файлов​

Параметры​

Запуск​

Режим «PostgreSQL уже установлен»​

Если huge pages не зарезервировались сразу​

Ручная настройка​

1. Установка PostgreSQL​

2. Генерация локали​

3. Параметры конфигурации​

4. Доступ в pg_hba.conf​

5. Huge pages​

Параметры конфигурации ФинГрад​

Функциональные параметры​

Параметры производительности​

После настройки: создание роли​