HQbird Replication Cluster Guide

Руководство по кластеру репликации HQbird: hqclusternode и hqbirdrcm (RCM). Установщики: HQbird 2027 Download. English: English version.

Содержание

• 0. Введение
• 1. Установка узлов и hqbirdrcm
• 2. Конфигурация кластера
• 3. Добавление базы в мастер
• 4. Как сделать базу репликой: этапы и место на диске
• 5. Инициализация (reinit)
• 6. Настройка публикации
• 7. Другие опции репликации
• 8. Как перевести реплику в обычную базу

0. Введение

Это руководство описывает, как установить и использовать кластер репликации HQbird: узлы hqclusternode и менеджер кластера hqbirdrcm (RCM).

Руководство для администратора Firebird. Мы считаем, что вы знаете Firebird, gfix и nbackup. Внутреннее устройство узла знать не нужно.

Из чего состоит кластер

У узла есть роль: master (мастер) или replica (реплика). На одном экземпляре Firebird могут работать два узла: узел мастера и узел реплики. Тогда одни базы этого Firebird — мастера, другие — реплики.

Как это работает

1. На мастере Firebird пишет изменения базы в сегменты (файлы журнала репликации).
2. Узел мастера отправляет сегменты узлу реплики по защищённому каналу (mTLS).
3. Узел реплики кладёт сегменты в папку входящих сегментов. Firebird реплики применяет их к своей копии базы.
4. Первую копию базы на реплику узел мастера передаёт сам. Это называется инициализация (reinit). Она идёт через nbackup, мастер в это время работает.
5. Узлы отправляют статистику в RCM. RCM показывает состояние кластера и отправляет узлам команды оператора.

            сегменты (mTLS, :7051)
  [мастер] ───────────────────────────▶ [реплика]
     │                                       │
     └──── статистика (:7443) ──▶ [RCM] ◀────┘
                                    ▲
                     оператор (:7444, браузер)

Поддерживаемые версии

• Firebird / HQbird 5.0 и 4.0 — все функции.
• HQbird 3.0 и 2.5 — репликация через плагин replconf. Публикаций нет, набор таблиц задают фильтры. Отличия описаны во врезках «HQbird 2.5/3.0».

Главная версия Firebird на мастере и на реплике должна совпадать. Иначе узел реплики откажет в инициализации.

Порты

Если на одном хосте два узла (мастер и реплика), у второго узла другой порт, например 7052.

Порты 7444 и 13050 нельзя открывать в сеть. К веб-интерфейсу RCM подключайтесь через SSH-туннель (глава 1).

Главное правило: без fbagent нет изменений

Узел меняет конфигурацию репликации только через fbagent: ему нужно перезапускать Firebird. Если fbagent недоступен, узел отказывает в любом действии, которое меняет конфигурацию. Он не работает «частично».

Термины

Как читать руководство

Во всех главах один пример:

1. Установка узлов и hqbirdrcm

Есть три способа установки:

Через goafts и через RCM узлы и RCM вы не устанавливаете сами. Их ставит fbagent, когда вы добавляете его в кластер (глава 2). Сертификаты и конфигурация тоже создаются сами.

Linux и Windows описаны в одной главе. Отличия Windows — во врезках «На Windows».

1.1. Требования

На каждом сервере баз:

• Firebird / HQbird 5.0, 4.0, 3.0 или 2.5 (2.5 — только Linux).
• fbagent рядом с каждым экземпляром Firebird. Без fbagent узел не работает.
• Синхронизация времени (NTP, chrony, w32time) на всех серверах и на хосте RCM. От часов зависят окна перезапуска и передачи, оценка отставания и проверка «узел не отвечает».
• Свободное место для архива сегментов и для инициализации реплик (глава 4).
• Сеть по таблице портов (глава 0).

Linux: права root, x86_64, systemd, curl. Поддерживаются Ubuntu 20–26, Debian 11–13, Astra, CentOS 7–10, AlmaLinux, Rocky, Oracle Linux 8–10, РЕД ОС, openSUSE 15.6, Fedora 44+.

Windows: права администратора, x64, Windows 10 / Server 2016 или новее, 64-битный Windows PowerShell 5.1. На Windows 10 и Server 2016–2022 нужен 7-Zip.

Где будет RCM. RCM нужен один на кластер. Его можно поставить на любой сервер, который видит все узлы, в том числе на один из серверов баз.

1.2. Установка через goafts

Шаг 1. Запустите скрипт установки fbagent

Скрипт ставит Firebird (сборку HQbird), fbagent и регистрирует fbagent на сервере goafts. Скрипт выбирайте по версии Firebird: fb25, fb30, fb40, fb50.

Linux (от root):

sudo sh fbagent-fb50_known.sh --goafts <сервер-goafts> --enroll --cluster

На Windows (PowerShell от администратора):

powershell -NoProfile -ExecutionPolicy Bypass -File .\fbagent-fb50_known.ps1 -Enroll

Для Windows нет скрипта fb25 и нет параметра -Cluster: fbagent работает от LocalSystem и сам создаёт папки кластера.

Главные параметры:

Полный список параметров — в README скрипта установки fbagent.

Шаг 2. Одобрите запрос fbagent

С параметром --enroll fbagent отправляет на goafts запрос сертификата (CSR) и ждёт одобрения до 30 минут. Одобрить можно так:

• автоматически — если установка шла с лицензионным токеном (--token) и в лицензии есть свободное место;
• в панели администратора goafts — раздел запросов CSR, запрос этого хоста, кнопка одобрения и подписи;
• через API goafts — POST /v1/admin/csr-requests/{id}/approve.

Если регистрация не прошла (например, время ожидания кончилось), fbagent всё равно работает, а скрипт завершится с кодом 2. Запустите скрипт ещё раз с теми же параметрами: повторится только регистрация.

Через несколько минут после регистрации fbagent сам ставит HQ Monitor.

Шаг 3. Опишите кластер

Узлы и RCM появятся, когда вы добавите fbagent в кластер goafts. Как описать кластер — в главе 2.

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

1. В течение 10 минут fbagent получает кластер из goafts (потом проверяет изменения раз в 60 секунд).
2. fbagent хоста RCM создаёт центр сертификации (CA) кластера и подписывает сертификаты всех узлов.
3. Каждый fbagent пишет node.json или rcm.json для своих участников кластера.
4. При следующей проверке продуктов (раз в 3 минуты) fbagent ставит и запускает службы.

Что и куда ставится:

<порт> — порт Firebird, например 3050. На одном fbagent может быть не больше одного узла мастера, одного узла реплики и одного RCM.

На Windows. fbagent до версии 2.83.0 ставил узлы в C:\hqclusternode, а RCM в C:\hqbirdrcm. Если эти папки есть, fbagent продолжает их использовать.

Обновления

• fbagent проверяет новые версии узла и RCM раз в 3 минуты, канал по умолчанию — stable. Сначала обновляется узел реплики, потом узел мастера.
• Если после обновления служба не запустилась или сообщила не ту версию, fbagent возвращает прошлую версию и блокирует новую. Список блокировок: <папка продукта>/update/<продукт>/blocked-versions.json. Чтобы попробовать версию снова, удалите её строку из этого файла.
• Состояние продукта: fbagent --product-status hqclusternode (или hqbirdrcm).

1.3. Установка через RCM (без goafts)

Кластер ведёт RCM. fbagent каждого хоста получает описание кластера от RCM, fbagent хоста RCM подписывает сертификаты, а узел и RCM обновляются из выпусков, которые хранит RCM.

Ограничения:

• В RCM один кластер.
• Не больше 3 мест. Место — хост, на котором есть узел мастера или реплики. Мастер и реплика на одном хосте — одно место. Хост, где есть только RCM, места не берёт. Четвёртый хост — ошибка seats_exceeded.
• fbagent и Firebird RCM не обновляет. fbagent обновляет их сам и при этом не трогает replication.conf, node.json, rcm.json и сертификаты.

Есть два способа:

• Связать хосты в RCM — обычный способ. Три действия: установщик на каждом хосте, вход в RCM, форма Связать хосты.
• Вручную из командной строки — токены подключения и fbagent --cluster-join. Нужен, когда порт 7450 закрыт между хостами или окно связывания уже закрылось.

Лицензия. Пробная лицензия включает функцию cluster. После пробного периода fbagent не ставит узел и RCM, если в лицензии нет cluster. Обновления уже установленных узлов и RCM он не запрещает никогда. Без goafts плавающая лицензия перестаёт действовать через online_check_days плюс льготные дни. Поэтому на каждый fbagent установите привязанную лицензию:

fbagent --license-request --out license_request.json
# отправьте файл поставщику и получите license.json
fbagent --license-install license.json

Без лицензии мастер останавливает отправку сегментов (глава 2.8).

Порты:

Связать хосты в RCM

Шаг 1. Установите HQbird на каждый хост

Поставьте HQbird полным установщиком на каждый сервер баз. Регистрацию на goafts (--enroll) не делайте. По умолчанию установщик на каждом хосте:

1. кладёт программы узла и RCM в папку fbagent (update/<продукт>/staged/);
2. создаёт кластер этого хоста (fbagent --cluster-init), имя кластера — имя хоста;
3. ставит и запускает RCM, консоль RCM работает по HTTPS на порту 7444;
4. создаёт первого администратора RCM со случайным паролем;
5. открывает окно связывания fbagent на 24 часа: порт 7450.

В конце установщик печатает строки RCM: (адрес консоли, имя кластера, логин и где лежит пароль) и Pairing: (до какого времени открыт порт 7450 и отпечаток его сертификата). Запишите отпечаток каждого хоста.

Параметры установщика на Linux (hqbird2027-run.sh):

Окно связывания можно открыть снова или закрыть от пользователя fbagent:

cd <папка fbagent>
sudo -u firebird ./fbagent --cluster-pairing on      # ещё 24 часа
sudo -u firebird ./fbagent --cluster-pairing off
sudo -u firebird ./fbagent --cluster-pairing status

Шаг 2. Войдите в RCM

Выберите хост, на котором будет работать RCM кластера. Это может быть любой хост из шага 1. Откройте https://<хост>:7444 и войдите с логином и паролем из шага 1. RCM сразу просит новый пароль (1.5).

Шаг 3. Свяжите хосты

В RCM откройте Настройки → Связать хосты.

1. В поле Хосты впишите адреса или имена хостов, по одному в строке. Первая строка — хост RCM, он уже в кластере.
2. Нажмите Проверить хосты. RCM подключается к каждому хосту на порт 7450 и показывает платформу, версию Firebird, отпечаток и состояние. Сравните отпечатки с выводом установщика.
3. Выберите Мастер (по умолчанию первый хост) и нажмите Связать.

RCM спросит подтверждение и покажет ход в разделе Ход. Когда все узлы запущены, он пишет «Готово» и номер ревизии кластера:

Из командной строки то же самое:

cd /opt/hqbirdrcm
export RCM_USER=rcmadmin RCM_PASSWORD='<пароль>'
./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1

Что происходит дальше:

1. RCM отправляет каждому свободному хосту приглашение.
2. fbagent хоста вступает в кластер. Свой RCM он останавливает и отключает, а свой пустой кластер переносит в cluster/left/ в папке fbagent.
3. RCM сохраняет кластер: узел <хост>-master на мастере, <хост>-replica на других хостах, порт 7051, связи мастер → реплики.
4. fbagent каждого хоста ставит и запускает узел. RCM ждёт, пока все узлы работают, и показывает Работает у каждого хоста.

Состояния хоста после Проверить хосты:

Выпуски. Узел fbagent ставит только из RCM. RCM берёт подписанные выпуски из своей папки import/ (рядом с rcm.json) при старте и каждые 5 минут. Установщик кладёт туда выпуски хоста RCM, а fbagent других хостов загружают выпуск своей платформы сами. Список выпусков — внизу страницы Связать хосты. Выпуск можно импортировать и вручную (шаг 5 ниже).

Вручную из командной строки

Порядок: шаги 1–3 на хосте RCM, шаг 4 на каждом другом хосте, шаги 5–6 в RCM.

Шаг 1. Установите HQbird с fbagent

Поставьте HQbird на каждый сервер баз и на хост RCM полным установщиком, на Linux с --rcm off на всех хостах, кроме хоста RCM. Регистрацию на goafts (--enroll) не делайте.

На хосте RCM установщик оставляет программу RCM в папке fbagent (update/hqbirdrcm/staged/). Без неё шаг 3 завершится ошибкой no hqbirdrcm to install.

Шаг 2. Установите привязанную лицензию

Как в начале раздела, «Лицензия».

Шаг 3. Создайте кластер на хосте RCM

Если установщик уже создал кластер (строка RCM: в его выводе), этот шаг пропустите.

Выполните команду от пользователя fbagent (на Linux — firebird), не от root: иначе файлы CA и rcm.json будут принадлежать root.

cd <папка fbagent>
sudo -u firebird ./fbagent --cluster-init shop-prod --address 10.0.0.7

На Windows (PowerShell от администратора): .\fbagent.exe --cluster-init shop-prod --address 10.0.0.7

• shop-prod — имя кластера: строчные латинские буквы, цифры и -.
• --address — адрес хоста RCM, по которому к нему подключаются другие хосты. Можно повторить несколько раз. Без параметра берутся адреса и имя хоста.

Команда:

1. создаёт CA кластера и CA агентов (в папке fbagent, clusterca/<имя>/);
2. пишет сертификат RCM, rcm.json и cluster-init.json в папку RCM;
3. ставит RCM и регистрирует службу hqbirdrcm. На Linux служба работает от отдельного пользователя hqbirdrcm;
4. переключает fbagent на RCM (cluster.source = rcm) и перезапускает его;
5. печатает адрес RCM и отпечаток CA:

Cluster:    shop-prod
RCM URL:    https://10.0.0.7:7443
CA hash:    sha256:9f86d0...

Запишите RCM URL и CA hash: они нужны на других хостах. Повторный запуск для того же кластера безопасен: CA и ключи остаются прежними.

Сразу войдите в RCM и смените пароль rcmadmin (1.5).

На Linux. Пользователь hqbirdrcm входит в группу fbagent. RCM читает rcm.json через эту группу, но не может его записать. Поэтому Настройки → RCM не сохраняет изменения (ошибка rcm_config_read_only). Правьте rcm.json на хосте от пользователя fbagent и перезапускайте RCM.

Шаг 4. Подключите fbagent других хостов

1. На хосте RCM создайте токен подключения для каждого fbagent: в RCM Настройки → Кластер, кнопка Создать токен подключения. Или из командной строки:

   Command Copy

   cd /opt/hqbirdrcm
   export RCM_USER=rcmadmin RCM_PASSWORD='<пароль>'
   ./hqbirdrcm cluster join-token -note db2

   Токен действует 24 часа, только для одного fbagent и только один раз. RCM показывает его один раз, вместе с готовой командой.

2. На хосте узла выполните эту команду от пользователя fbagent:

   Command Copy

   cd <папка fbagent>
   sudo -u firebird ./fbagent --cluster-join https://10.0.0.7:7443 \
     --ca-hash sha256:9f86d0... --token-file token.txt

   Вместо --token-file можно --token <токен>. На Windows — то же с .\fbagent.exe в PowerShell от администратора.

fbagent проверяет CA RCM по отпечатку. Если отпечаток не совпал, он останавливается и ничего не пишет. Потом fbagent получает свой сертификат (90 дней, продлевается сам) и перезапускается. Подключённый fbagent виден в RCM в таблице Агенты. Пока у него нет участников, на хосте ничего не ставится.

Шаг 5. Импортируйте выпуски в RCM

Узел и RCM fbagent берёт только из RCM. Если нужного выпуска нет в списке Выпуски в зеркале (Настройки → Связать хосты), импортируйте каждый продукт (hqclusternode, hqbirdrcm) для каждой платформы ваших хостов (linux-amd64, windows-amd64). Файл выпуска и подпись .sig даёт поставщик.

cd /opt/hqbirdrcm
sudo -u hqbirdrcm ./hqbirdrcm release import -config rcm.json \
  -file hqclusternode-linux-amd64 -product hqclusternode \
  -platform linux-amd64 -version 2027.5.6
sudo -u hqbirdrcm ./hqbirdrcm release list -config rcm.json

• Подпись RCM ищет в <файл>.sig, или укажите её параметром -sig. Без верной подписи поставщика RCM файл не примет.
• Новый выпуск заменяет прошлый. Перезапуск RCM не нужен.
• fbagent проверяет новые версии раз в 3 минуты. Порядок обновления и блокировки — как через goafts (1.2, «Обновления»).

Шаг 6. Опишите кластер

Участников и связи задайте в RCM, Настройки → Кластер (глава 2.3). После сохранения fbagent ставит узлы так же, как через goafts (1.2, шаг 3): пишет сертификаты, node.json и rcm.json, ставит и запускает службы.

Порты — в начале раздела.

1.4. Установка вручную

Шаг 1. Установите HQbird с fbagent

Установите HQbird на каждый сервер баз (тем же скриптом, но без --enroll, или полным установщиком HQbird). Проверьте, что fbagent работает.

Запишите из agent_config.json fbagent три значения. Они нужны для node.json:

Проверка fbagent (ответ — JSON экземпляра Firebird):

curl -s -H "Authorization: Bearer <token>" http://127.0.0.1:13050/v1/instances/<instance_id>

Если на хосте несколько экземпляров HQbird, в firebird.update.services конфигурации fbagent оставьте только службу своего экземпляра (см. 3.5).

Шаг 2. Разложите файлы

Linux:

/opt/hqclusternode/
  hqclusternode        # программа
  node.json            # конфигурация узла (права 0600)
  certs/               # ca.crt, <node_id>.crt, <node_id>.key
  work/                # рабочая папка
/opt/hqbirdrcm/
  hqbirdrcm            # программа
  rcm.json             # конфигурация кластера
  certs/               # ca.crt, rcm.crt, rcm.key
  rcm-data/            # состояние, пользователи, журнал аудита

sudo mkdir -p /opt/hqclusternode/certs /opt/hqclusternode/work
sudo install -m 0755 hqclusternode-linux-amd64 /opt/hqclusternode/hqclusternode
# на хосте RCM:
sudo mkdir -p /opt/hqbirdrcm/certs /opt/hqbirdrcm/rcm-data
sudo install -m 0755 hqbirdrcm-linux-amd64 /opt/hqbirdrcm/hqbirdrcm

На Windows. Папка по умолчанию — C:\hqclusternode с тем же составом. Путь с пробелом допустим.

Если на одном хосте два узла (мастер и реплика), дайте каждому свою папку, например /opt/hqclusternode/master и /opt/hqclusternode/replica.

Шаг 3. Создайте сертификаты

Узлы и RCM общаются только по mTLS. Нужен один CA и сертификат для каждого участника. Выполните один раз на любой машине:

./hqclusternode gencerts -out certs \
  -nodes 'node-a:master,node-b:replica' \
  -hosts 'localhost,127.0.0.1,<ip-node-a>,<ip-node-b>,<ip-rcm>'

Команда создаёт ca.crt и ca.key, node-a.crt/.key, node-b.crt/.key и rcm.crt/.key. В -hosts перечислите все имена и адреса, по которым к участникам будут подключаться.

ca.key — ключ CA. На хосты его не копируйте, храните отдельно.

Новый узел позже добавляет -add: он подписывает пару тем же CA, остальные файлы не меняются:

./hqclusternode gencerts -out certs -add -nodes 'node-c:replica' -hosts '<ip-node-c>'

Сертификаты действуют 90 дней. gencerts -out certs -list показывает даты окончания, gencerts -out certs -renew продлевает их с тем же ключом. Новый .crt скопируйте на его хост: узел подхватит его без перезапуска.

Скопируйте на каждый хост ca.crt и только его сертификат и ключ.

Шаг 4. Напишите node.json

Один файл на каждый узел. Пример для мастера (node-a):

{
  "node_id": "node-a",
  "role": "master",
  "listen_addr": ":7051",
  "rcm": { "url": "https://<ip-rcm>:7443", "ca_cert": "certs/ca.crt",
           "client_cert": "certs/node-a.crt", "client_key": "certs/node-a.key" },
  "firebird": {
    "root": "/opt/firebird",
    "user": "SYSDBA",
    "password": "<пароль SYSDBA>",
    "port": 3050,
    "replication_conf": "/opt/firebird/replication.conf",
    "replication_log": "/opt/firebird/replication.log",
    "firebird_log": "/opt/firebird/firebird.log",
    "fbagent_url": "http://127.0.0.1:13050",
    "fbagent_token": "<local_api.token>",
    "instance_id": "<local_api.instance_id>",
    "service_name": "<имя службы Firebird>"
  },
  "windows": { "restart_window": "22:00-05:00", "transfer_window": "23:00-05:00" },
  "peers": [ { "node_id": "node-b", "url": "https://<ip-node-b>:7051", "compress": "zstd" } ]
}

Узел реплики (node-b) — такой же файл, но "role": "replica", свои сертификаты, а в peers — мастер node-a.

Главные поля:

Остальные поля имеют значения по умолчанию. Узел не запустится, если поля fbagent не заданы.

Закройте файл: в нём пароль и токен.

chmod 600 /opt/hqclusternode/node.json

На Windows. Пути пишите в формате JSON: "C:\\HQbird\\replication.conf". service_name — имя службы Windows для Firebird.

Шаг 5. Напишите rcm.json

{
  "ingest_addr": "0.0.0.0:7443",
  "operator_addr": "127.0.0.1:7444",
  "users_file": "rcm-data/users.json",
  "data_dir": "./rcm-data",
  "tls": { "ca_cert": "certs/ca.crt", "cert": "certs/rcm.crt", "key": "certs/rcm.key" },
  "nodes": [
    { "node_id": "node-a", "url": "https://<ip-node-a>:7051", "role": "master",  "host": "A" },
    { "node_id": "node-b", "url": "https://<ip-node-b>:7051", "role": "replica", "host": "B" }
  ]
}

• url — адрес узла, как его видит хост RCM. Только https.
• host — метка экземпляра Firebird. Узел мастера и узел реплики с одной меткой работают на одном Firebird (companion, нужен для повышения реплики до мастера, глава 8). На одну метку — не больше одного мастера и одной реплики.
• Относительные пути считаются от папки rcm.json.

Шаг 6. Зарегистрируйте службы

Порядок запуска: сначала RCM, потом реплики, потом мастера.

RCM (Linux):

cd /opt/hqbirdrcm
sudo ./hqbirdrcm svc install -config /opt/hqbirdrcm/rcm.json
sudo ./hqbirdrcm svc start

Узел (Linux):

cd /opt/hqclusternode
sudo ./hqclusternode svc install -config /opt/hqclusternode/node.json -certs /opt/hqclusternode/certs
sudo ./hqclusternode svc start -config /opt/hqclusternode/node.json
systemctl status hqclusternode-master-p3050

svc install создаёт службу hqclusternode-<роль>-p<порт> от пользователя firebird. Если папка Firebird принадлежит root, команда даёт группе firebird право записи в неё (с sticky bit) и печатает каждое изменение: узлу нужно заменять replication.conf.

Для svc start, svc stop и svc uninstall указывайте тот же node.json: имя службы считается из роли и порта Firebird.

На Windows (PowerShell от администратора):

Command Copy

cd C:\hqclusternode
.\hqclusternode.exe svc install -config C:\hqclusternode\node.json -certs C:\hqclusternode\certs

Служба HQClusterNode-<роль>-p<порт> работает от LocalSystem, стартует автоматически и перезапускается после сбоя. Служба узла не зависит от службы Firebird. Если узел ставили версией 2027.1.2–2027.1.9, уберите зависимость один раз: .\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.

Шаг 7. Откройте порты

На хосте узла разрешите входящие на 7051 (порт listen_addr) от других узлов и от RCM. На хосте RCM разрешите входящие на 7443 от всех узлов. Порты 7444 и 13050 наружу не открывайте.

Пример ufw на хосте узла:

sudo ufw allow from <ip-rcm> to any port 7051 proto tcp
sudo ufw allow from <ip-узла-партнёра> to any port 7051 proto tcp

Обновление вручную

Остановите службу, замените программу, запустите службу:

sudo systemctl stop hqclusternode-master-p3050
sudo install -m 0755 hqclusternode-linux-amd64 /opt/hqclusternode/hqclusternode
sudo systemctl start hqclusternode-master-p3050

Конфигурация и сертификаты при этом не меняются.

1.5. Первый вход в RCM

Адрес и пароль зависят от того, как поставлен RCM.

HTTPS (1.3). Сертификат RCM подписан CA кластера, браузер его не знает и предупреждает. На странице входа RCM показывает отпечаток CA. Сравните его с CA hash, который напечатал установщик, и импортируйте CA в браузер или в систему как доверенный корневой: ссылка Скачать сертификат CA на странице входа (https://<хост RCM>:7444/ca.crt, файл hqcluster-ca.crt). Чтобы RCM слушал только localhost, задайте в rcm.json "operator_addr": "127.0.0.1:7444" и перезапустите RCM.

HTTP (1.2, 1.4). С другого компьютера подключайтесь через SSH-туннель:

ssh -L 7444:127.0.0.1:7444 <хост-rcm>

Затем откройте в браузере http://127.0.0.1:7444.

Сгенерированный пароль RCM просит сменить при первом входе: пока вы его не смените, другие страницы не открываются. Пароль strong password смените сразу (ссылка Пароль в заголовке).

Язык. Выберите Русский в списке языков в заголовке страницы (есть и на странице входа). Без выбора язык берётся из браузера.

Смена пароля и новые пользователи

Свой пароль меняет каждый пользователь: ссылка Пароль в заголовке страницы. Нужен текущий пароль и новый, не короче 12 символов. После смены другие сеансы этого пользователя закрываются.

Если установщик сгенерировал пароль, удалите после первого входа файлы с ним: initial-admin.json в папке RCM и clusterca/<имя>/rcm-initial-password в папке fbagent.

Новые пользователи. В интерфейсе нет страницы пользователей. Пользователи хранятся в файле rcm-data/users.json. Пароль хранится как хеш HA1: MD5("<имя>:hqbirdrcm:<пароль>").

1. Посчитайте хеш:

   Command Copy

   printf '%s' 'rcmadmin:hqbirdrcm:<новый пароль>' | md5sum

2. Запишите его в поле ha1 пользователя в users.json. Чтобы добавить пользователя, добавьте ещё один элемент в users:

   json Copy

   { "username": "ivanov", "ha1": "<хеш>", "algo": "MD5", "created_at": "2026-11-03T00:00:00Z" }

3. Сразу перезапустите RCM: он читает файл только при запуске. При смене пароля в интерфейсе RCM записывает файл заново из памяти, и правки, которые он ещё не прочитал, пропадут.

chmod 600 /opt/hqbirdrcm/rcm-data/users.json
sudo systemctl restart hqbirdrcm

Ролей нет: у всех пользователей все права.

1.6. Как проверить установку

• Службы узлов и RCM работают и не перезапускаются по кругу: systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.

  

• RCM отвечает: curl http://127.0.0.1:7444/healthz (без пароля).

• В RCM на странице Обзор (Overview) видны все узлы, без пометки «не отвечает».

• Из командной строки на хосте RCM:

  Command Copy

  export RCM_USER=rcmadmin RCM_PASSWORD='<пароль>'
  ./hqbirdrcm nodes
  ./hqbirdrcm status

• Кластер через RCM: Настройки → Кластер, раздел Состояние — каждый участник применил последнюю ревизию и не сообщает об ошибке. Из командной строки: ./hqbirdrcm cluster status.

1.7. Журналы

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

2. Конфигурация кластера

В этой главе вы задаёте, какие узлы есть в кластере и какой мастер отправляет сегменты какой реплике. Потом настраиваете узлы и пользователей RCM.

Связи задаются одним из трёх способов:

На узлах, установленных через goafts или через RCM, меняйте связи только в описании кластера. fbagent перезаписывает node.json и rcm.json по описанию кластера, и правка в Настройки → RCM или Настройки → Узлы пропадёт.

2.1. Роли и схемы

У каждого узла одна роль: мастер или реплика. На одном экземпляре Firebird могут работать два узла — мастер и реплика.

Поддерживаемые схемы:

1 → 1        node-a (мастер) ──▶ node-b (реплика)

1 → N        node-a ──▶ node-b
                    └─▶ node-c

N → 1        node-a ──┐
                      ├─▶ node-b    (одна реплика для нескольких мастеров)
             node-x ──┘

Оба узла     host-1: node-1m (мастер) + node-1r (реплика)  ← один Firebird
на хосте     host-2: node-2m (мастер) + node-2r (реплика)  ← один Firebird
             node-1m ──▶ node-2r,  node-2m ──▶ node-1r

Связь всегда идёт от мастера к реплике. RCM связывает базу мастера с её репликой по GUID базы, а не по имени узла.

Companion. Узел мастера и узел реплики на одном экземпляре Firebird — компаньоны. Только для такой пары работает повышение реплики до мастера (глава 8). В rcm.json пара отмечается одинаковым значением host.

2.2. Связи через goafts

Где описать кластер

• HQ Monitor, страница Clusters (только для администраторов; нужна включённая доставка конфигурации). Обычный способ.
• API администратора goafts: POST /v1/admin/clusters и PUT /v1/admin/clusters/{id}. В панели администратора goafts страницы кластеров нет.

``

Шаги на странице Clusters

1. Введите New cluster id (строчные латинские буквы, цифры и -) и нажмите Create.
2. Добавьте участников (Members). Для каждого укажите:
   • fbagent хоста;
   • роль: master, replica или rcm;
   • адреса хоста;
   • порт: для узла — 7051 (второй узел на том же хосте — например 7052), для RCM — порт приёма статистики 7443.
3. Добавьте связи (Replication links) от мастера к реплике.
4. Нажмите Validate, затем Save.

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

Правила

• fbagent может быть только в одном кластере.
• На одном fbagent — не больше одного мастера, одной реплики и одного RCM.
• В кластере ровно один RCM. fbagent хоста RCM ведёт центр сертификации (CA) кластера.
• Имя участника (member_id) — латиница, цифры, -. Имя, fbagent и роль участника не меняются. Чтобы перенести участника на другой хост, создайте нового участника с новым именем. Старое имя больше не используйте.
• У каждой реплики должна быть связь с мастером.
• Адрес узла goafts строит сам: https://<первый адрес>:<порт>.
• HQbird 2.5/3.0: задайте для кластера дату replconf_valid_till (ГГГГ-ММ-ДД) — до этой даты действует конфигурация плагина replconf.

Пример через API

{"contract":1,"cluster_id":"shop-prod","name":"Shop","pki":"managed",
 "cert_validity_days":90,"renew_before_days":30,
 "members":[
  {"member_id":"db1-m","agent_id":"<fbagent хоста 1>","role":"master","addresses":["db1.lan"],"listen_port":7051},
  {"member_id":"db1-rcm","agent_id":"<fbagent хоста 1>","role":"rcm","addresses":["db1.lan"],"listen_port":7443},
  {"member_id":"db2-r","agent_id":"<fbagent хоста 2>","role":"replica","addresses":["db2.lan"],"listen_port":7052}],
 "links":[{"from":"db1-m","to":"db2-r"}]}

• Создание: POST /v1/admin/clusters (без участников), затем замена документа целиком: PUT /v1/admin/clusters/{id}.
• PUT требует заголовок If-Match: <revision> (ревизию дают GET и ETag). Без заголовка — 428, со старой ревизией — 409, с ошибкой в документе — 422 со списком ошибок.
• POST /v1/admin/clusters/{id}/validate проверяет документ без сохранения.
• GET /v1/admin/clusters/{id}/status показывает состояние участников и сроки сертификатов.

Что происходит после сохранения

1. fbagent каждого участника получает кластер. Не в кластере — проверка раз в 10 минут, в кластере — раз в 60 секунд.
2. Каждый fbagent создаёт ключ и отправляет запрос сертификата. fbagent хоста RCM подписывает его. Свой сертификат RCM подписывает без запроса.
3. fbagent пишет в node.json: имя, роль, адрес, peers (из связей), адрес RCM, пути сертификатов, данные Firebird и fbagent. В rcm.json: список узлов (nodes) и пути сертификатов. Остальные поля файлов fbagent не трогает.
4. fbagent ставит и запускает службы (глава 1).

Изменение кластера:

После удаления узла в общем replication.conf остаётся его область # BEGIN managed-by:<имя> … # END …. Удалите её вручную и перезапустите Firebird через RCM.

Одобрение сертификатов кластера

По умолчанию fbagent хоста RCM подписывает запросы сам (auto). Можно включить ручное одобрение. Команды на хосте RCM:

fbagent --cluster-ca-approval manual     # или auto
fbagent --cluster-status                 # участие этого fbagent в кластере (JSON)
fbagent --cluster-ca-approve <request_id>

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

2.3. Связи через RCM

Кластер RCM (без goafts)

Если кластер создан установщиком HQbird или командой fbagent --cluster-init (глава 1.3), описание кластера хранит RCM. Хосты проще всего добавить на странице Настройки → Связать хосты (глава 1.3, «Связать хосты в RCM»): RCM сам делает участников и связи. Правила те же, что в goafts (2.2, «Правила»), и ещё:

• в RCM один кластер; участник rcm есть всегда и не удаляется;
• не больше 3 мест (хостов с узлами мастера или реплики), иначе ошибка seats_exceeded;
• участника можно добавить только на fbagent, который подключился к RCM (глава 1.3: «Связать хосты» или «Вручную», шаг 4).

Шаги на странице Настройки → Кластер:

1. В таблице Агенты нажмите Добавить участника в строке fbagent.
2. Укажите роль (master или replica), member_id, адреса и порт. Страница предлагает имя <хост>-<роль> и свободный порт начиная с 7051. Адреса fbagent — кнопки: нажмите, чтобы добавить адрес.
3. В разделе Связи нажмите Добавить связь от мастера к реплике.
4. Нажмите Проверить: RCM покажет ошибки и предупреждения.
5. Нажмите Сохранить. Страница покажет список изменений и спросит подтверждение. Если участники удаляются, окно красное.

До сохранения изменения есть только на странице (метка «Не сохранено»). Если кто-то сохранил кластер в то же время, страница предложит перечитать его. Если изменились только поля RCM (ревизия, CA, поручения), страница сохранит ваше изменение сама.

Другие разделы страницы:

Из командной строки на хосте RCM:

export RCM_USER=rcmadmin RCM_PASSWORD='<пароль>'
./hqbirdrcm cluster show > c.json        # документ с ревизией
# измените c.json
./hqbirdrcm cluster validate -f c.json   # проверить, ничего не сохраняя
./hqbirdrcm cluster apply -f c.json      # сохранить (If-Match = ревизия из файла)
./hqbirdrcm cluster agents               # подключённые fbagent и их участники
./hqbirdrcm cluster status               # что сообщили fbagent

Формат документа — как в 2.2, «Пример через API». apply со старой ревизией получает 409: выполните show ещё раз. RCM хранит 20 последних ревизий в rcm-data/cluster/history/.

HQ Monitor. Страница Clusters работает и с RCM. В конфигурации HQ Monitor на хосте RCM задайте rcm_admin_url (http://127.0.0.1:7444), rcm_admin_user (пользователь RCM) и rcm_admin_password_file (файл с его паролем). В журнале аудита RCM видны оба пользователя: RCM и HQ Monitor.

После сохранения всё идёт как через goafts (2.2, «Что происходит после сохранения»). nodes в rcm.json RCM перечитывает сам, без перезапуска.

Убрать fbagent из кластера: удалите его участников и сохраните, затем нажмите Отозвать в таблице Агенты (или ./hqbirdrcm cluster revoke -agent <id>). Чтобы вернуть его, нужен новый токен.

Ручная установка: добавить узел в RCM

1. Настройки → RCM, таблица Подключённые узлы.
2. Нажмите Добавить узел. Заполните node_id, url (https://<адрес>:7051), роль, host (метка экземпляра Firebird), server (только для группировки на экране).
3. Нажмите Проверить в строке узла: RCM проверит связь и права.
4. Нажмите Сохранить. RCM запишет rcm.json и сохранит старый файл как rcm.json.<время UTC>.bak (последние 20).
5. Перезапустите RCM. До перезапуска работает старая конфигурация; страница показывает, какие поля ждут перезапуска.

sudo systemctl restart hqbirdrcm

Можно и без интерфейса: отредактируйте rcm.json и перезапустите RCM.

Ручная установка: связать мастер и реплику

Связь нужно записать на обеих сторонах:

1. Настройки → Узлы, выберите узел мастера.
2. В разделе Пиры нажмите Добавить пир: node_id реплики, её url, сжатие (zstd).
3. Нажмите Сохранить. RCM покажет список изменений и спросит подтверждение. Изменение peers действует сразу.
4. Повторите для узла реплики: её пир — мастер.

Если пир не записан на одной из сторон, RCM не предложит этот узел реплики при инициализации базы.

2.4. Настройки узла

Настройки → Узлы (Settings → Nodes) показывает настройки node.json, которые узел разрешает менять из RCM. Сохраняются только изменённые поля, после окна со списком изменений.

У каждой строки есть пометка, когда изменение начнёт действовать:

Только для чтения (меняются в node.json на хосте узла): firebird (в том числе пароль и auto_restart), rcm, tls, segments, адреса.

Главные настройки:

Подробно о скорости и хранении архива — в главах 5 и 7.

firebird.auto_restart (только в node.json) решает, может ли узел реплики перезапускать Firebird сам:

Через goafts. Окно windows.transfer_window узла fbagent использует и как окно для перезапуска самой службы узла при изменении кластера. Если окно в node.json не задано, fbagent перезапускает службу сразу.

2.5. Несколько HQbird на одном хосте

fbagent перезапускает службы из firebird.update.services своей конфигурации. Пустой список — все службы HQbird на хосте. Оставьте в списке только службу своего экземпляра. Узел не видит эту настройку и пишет в журнал предупреждение fbagent_shared, если fbagent знает больше одного экземпляра.

2.6. Пароль SYSDBA

Узел подключается к Firebird с пользователем и паролем из firebird.user и firebird.password в node.json. fbagent хранит свою копию пароля. Если вы сменили пароль SYSDBA:

1. Исправьте firebird.password в node.json каждого узла этого экземпляра (мастер и реплика).
2. Исправьте пароль в конфигурации fbagent и перечитайте её (см. документацию fbagent).
3. Перезапустите службы узлов.

Иначе страницы публикации и сверки в RCM покажут ошибку входа (SQLSTATE 28000).

2.7. Пользователи и аудит RCM

• Пользователи — в файле rcm-data/users.json (глава 1.5). Ролей нет.
• Сессия живёт 12 часов после последнего действия.
• После 10 неудачных входов за 5 минут вход для этого пользователя и адреса временно блокируется. Успешный вход сбрасывает счётчик.
• Журнал аудита — файл rcm-data/audit.jsonl: одна строка JSON на каждое изменение, вход и выход. В интерфейсе журнала нет.
• Страница Команды (Commands) показывает автора каждой команды.

2.8. Лицензия

Узел мастера раз в минуту читает лицензию fbagent своего хоста. Если лицензии нет (пробный период кончился, лицензия истекла или неверна), узел останавливает отправку сегментов всех баз мастера. Firebird и базы работают, реплики перестают получать изменения.

Что видно в RCM:

• мастер красный (NEEDS_ATTENTION), значок «no license: shipping stopped»;
• кнопки Возобновить (Resume) нет: паузу снимает только лицензия;
• у реплики: «not receiving since …: the master has no license»;
• в таблице Узлы значок «no license»; в Настройки → Узлы — блок лицензии fbagent;
• оповещения license_paused и license_pause_archive_released;
• инициализация запрещена (license_paused).

Установите лицензию в fbagent. Узел сам снимет паузу в течение минуты. Архив для реплик мастер хранит limits.retention_days (по умолчанию 2 дня) от начала паузы. Если лицензию установить позже, реплики придётся инициализировать заново.

Кластер через RCM, без goafts. Плавающая лицензия без goafts перестаёт действовать через online_check_days плюс льготные дни. На каждый fbagent кластера нужна привязанная лицензия (fbagent --license-request, затем fbagent --license-install, глава 1.3, «Лицензия»). После пробного периода fbagent не ставит новый узел и RCM без функции cluster в лицензии; обновления он не запрещает никогда. Для HQbird 2.5/3.0 дата replconf_valid_till в RCM не может быть позже конца лицензии плюс льготные дни у fbagent узлов (ошибка replconf_after_license).

2.9. Как проверить

• Обзор: все узлы на месте, сгруппированы по серверам.

  

• Настройки → Узлы: у мастера в Пиры есть реплика, у реплики — мастер.

• Настройки → RCM: кнопка Проверить в строке каждого узла проходит.

• Отчёт кластера одним файлом:

  Command Copy

  ./hqbirdrcm report -o report.json

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

3. Добавление базы в мастер

В этой главе база мастера попадает под управление узла. Узел записывает её в replication.conf и создаёт папки для сегментов. После перезапуска Firebird база готова к репликации.

Создание реплики — следующие шаги (публикация, инициализация). Они описаны в главах 4–6.

Названия кнопок даны по русскому интерфейсу RCM, в скобках — по английскому.

3.1. Как узел находит базы

Узел мастера ищет базы в одной папке — корне баз (databases.root). Что попадёт под управление, решают правила:

Путь root — это путь на хосте узла, а не на хосте RCM. Узел применяет сначала маску включения, затем маску исключения, затем размер.

Все правила хранятся в node.json узла. Узел применяет их при каждом сканировании.

Режим шаблона и режим списка:

• Режим шаблона (список включения пуст): узел берёт все файлы по маске, кроме исключённых. Новый файл в папке узел возьмёт сам при следующем сканировании.
• Режим списка (список включения не пуст): узел берёт только файлы из списка. Новый файл сам не попадёт под управление — его нужно добавить.

Выберите режим списка, если в папке лежат копии баз, тестовые базы или другие файлы, которые реплицировать не нужно.

3.2. Перед началом: проверьте права

Пользователь, от которого работают Firebird и узел (firebird в Linux, LocalSystem в Windows), должен иметь права на чтение и запись:

• папки корня баз и файлов баз;
• replication.conf и его папки (узел заменяет файл через временный файл);
• папок сегментов <база>.ReplLog и <база>.LogArch (узел создаёт их сам).

RCM проверяет права перед регистрацией (preflight). Если проверка не прошла, команда завершается с ошибкой preflight failed on <узел> и списком путей.

Проверка на хосте узла (Linux):

sudo -u firebird /opt/hqclusternode/hqclusternode checkpermissions -config /opt/hqclusternode/node.json

3.3. Страница регистрации баз

1. Откройте страницу регистрации узла мастера. Ссылка есть в двух местах:

   • Базы данных (Databases) → таблица Узлы → колонка действий → Зарегистрировать (Enroll);
   • Обзор (Overview) → карточка узла мастера → Зарегистрировать базы данных (Enroll databases).

   У узла реплики этой страницы нет.

2. Форма показывает текущие правила узла (узел прислал их сам). Если узел не отвечает, кнопки предпросмотра и регистрации выключены: без текущих правил они сбросили бы списки включения и исключения.

3. Заполните или исправьте поля: Путь к папке на этом сервере, рекурсивно, маски, Фильтр по размеру, Таблицы отслеживания синхронизации.

4. Нажмите Предпросмотр (Preview). Узел покажет все файлы по маске включения. Он ничего не меняет.

5. Проверьте список. У каждого файла есть флажок:

   • отмечен — файл будет под управлением;
   • отмечен, заблокирован, с пометкой уже под управлением — база уже зарегистрирована;
   • заблокирован с причиной — файл исключён маской, размером или списком исключения. Чтобы взять его, измените правило.

6. Отметьте нужные базы и нажмите Зарегистрировать выбранные (Enroll selected). RCM спросит подтверждение и покажет число файлов.

Что делает эта кнопка:

• в режиме шаблона — файлы без флажка попадают в список исключения, файлы с флажком убираются из него;
• в режиме списка — файлы с флажком добавляются в список включения.

Кнопка добавляет базы к тем, что уже под управлением. Заблокированные строки она не меняет. 7. Кнопка Зарегистрировать (Enroll) применяет форму без изменения списков. 8. Дождитесь сообщения о завершении и числа добавленных баз. Если ответа долго нет, смотрите результат на странице Команды (Commands).

Если после регистрации не нашлось ни одной базы, а у узла уже были базы, узел отказывает (409) и возвращает старые правила. Так ошибка в пути не выключает репликацию всех баз.

То же из командной строки

Command Copy

hqbirdrcm enroll-databases -node node-a -root /databases/master

Внимание: команда отправляет только поля из своих параметров. Остальные правила (маски, размеры, списки включения и исключения, sync_tables) узел сбросит. Перед командой прочитайте текущие правила (hqbirdrcm getconfig -node node-a) и передайте их в команде. Безопаснее пользоваться страницей регистрации.

3.4. Что происходит после регистрации

1. Узел записывает правила в node.json.
2. Узел сканирует папку (scansync).
3. Для каждой найденной базы узел пишет блок в свою область replication.conf (между строками # BEGIN managed-by:node-a role:master и # END …) и создаёт папки <база>.ReplLog и <база>.LogArch. Текст вне своей области узел не меняет.
4. Перед изменением узел сохраняет копию файла: replication_YYYYMMDD_hhmmss_NNN.conf.
5. Если replication.conf изменился, базы получают состояние PENDING_RESTART: Firebird прочитает новый файл только после перезапуска. В таблице Узлы это видно в колонке Ожидает перезапуска.

Состояния новой базы:

3.5. Перезапуск Firebird мастера

Узел мастера никогда не перезапускает Firebird сам. RCM тоже. Перезапуск мастера — решение оператора: при перезапуске разрываются все соединения со всеми базами этого Firebird.

Выберите время с малой нагрузкой и нажмите одну из кнопок:

• Перезапустить Firebird мастера — на странице Базы данных, в строке мастера базы, которая ждёт перезапуска;
• та же кнопка в окне Инициализировать (Initialize), глава 5;
• Перезапустить Firebird — на странице базы.

RCM спросит подтверждение. В нём имя узла и предупреждение: Firebird перезапустится сразу, без окна перезапуска, и все соединения будут разорваны.

То же из командной строки

Command Copy

hqbirdrcm restartfirebird -node node-a

Команда тоже перезапускает сразу, без окна перезапуска.

Как узел перезапускает Firebird:

1. Проверяет, что fbagent отвечает и управляет тем же экземпляром (идентификатор, порт, имя службы из node.json). Если хоть одно значение не совпадает, узел отказывает.
2. Просит fbagent перезапустить Firebird.
3. Ждёт, когда Firebird ответит на своём порту.
4. Переводит базы из PENDING_RESTART в CONFIGURED.

Несколько HQbird на одном хосте. fbagent перезапускает службы из firebird.update.services своей конфигурации. Пустой список — это все службы HQbird на хосте. Если на хосте два экземпляра HQbird, оставьте в списке только службу своего экземпляра. Иначе перезапуск одного узла остановит и другой экземпляр.

На Windows. Если replication.log вырос до log_portion_mb или больше, перезапуск идёт так: остановка Firebird → архивирование журнала → запуск.

3.6. База, которую уже реплицируют вручную

Если для базы репликация уже настроена вручную (свой блок в replication.conf, публикация включена, сегменты идут), её можно взять под управление без новой инициализации реплики. Для этого есть режим detect_existing (только для мастера).

1. Выполните предпросмотр:

   Command Copy

   hqbirdrcm enroll-databases -node node-a -root /databases/master -detect-existing -dry-run

   В ответе taken_over — базы, которые будут перенесены. Добавьте -verbose, чтобы увидеть пропущенные базы с причиной.

2. Если список правильный, выполните команду без -dry-run.

Узел переносит блок, только если:

• папки сегментов называются точно <база>.ReplLog и <база>.LogArch;
• в архиве уже есть сегменты;
• публикация в базе включена.

Блок с другими путями узел не переносит и показывает как «found but unsupported».

После переноса базы получают PENDING_RESTART, хотя настройки репликации не меняются: меняется только место блока в файле. Перезапустите Firebird в окно обслуживания.

3.7. Как проверить

• Базы данных: база видна в строке узла мастера, состояние CONFIGURED (после перезапуска).

• Рядом с базой может быть значок publication OFF: публикация ещё не включена. Это нормально, публикация — следующий шаг (глава 6).

  

• На хосте узла: блок базы есть в replication.conf внутри области managed-by:node-a, рядом с базой есть папки .ReplLog и .LogArch.

3.8. Убрать базу из управления

Обычный способ — кнопка. На странице Базы данных отметьте базы, выберите массовое действие Убрать из управления (Remove from management) и нажмите Применить к выбранным. RCM:

1. добавляет файлы в список исключения узла;
2. сканирует папку один раз: блоки баз уходят из replication.conf;
3. удаляет записи баз в узле.

Файлы баз и папки сегментов остаются на диске. Firebird не перезапускается. Firebird продолжает писать сегменты базы до своего следующего перезапуска; RCM скажет, если перезапуск нужен.

RCM откажет (has_replicas) для базы мастера, у которой есть живая реплика: иначе реплика тихо остановится. Сначала сделайте реплику обычной базой или уберите её (глава 8).

Не удаляйте блок базы из replication.conf вручную: при следующем сканировании узел запишет его снова.

Если файл базы пропал или его исключило правило. Тогда база получает состояние ORPHANED (группа Orphaned). Узел сохраняет её запись и архив сегментов: пропавшая база — чаще ошибка, чем решение. Если файл вернётся, база снова работает, оповещение снимается. Чтобы удалить такую базу окончательно, выполните два шага в этом порядке:

# 1. удалить архив сегментов (необязательно)
hqbirdrcm cleanuparchive -node node-a -db <db_id> -orphaned
# 2. удалить запись базы
hqbirdrcm forgetdatabase -node node-a -db <db_id>

После forgetdatabase команда cleanuparchive уже не найдёт базу. Обе команды работают только для базы в состоянии ORPHANED и не трогают файл базы.

Внимание. После перевода реплики в мастер (глава 8) не запускайте cleanuparchive -orphaned для старой записи: новый мастер использует ту же папку .LogArch, и команда удалит его рабочий архив.

3.9. Смена корня баз

Регистрация с другим путём разрешена. Узел:

• добавляет базы из новой папки;
• переводит базы старой папки, которых нет в новой, в ORPHANED (оповещение orphaned_database) и сохраняет их архивы.

Если вы ошиблись папкой, зарегистрируйте правильную папку ещё раз. База с тем же полным путём продолжит работу под тем же db_id. База по другому пути — новая база (новый db_id); её реплику нужно инициализировать заново.

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

4. Как сделать базу репликой: этапы и место на диске

В этой главе — весь путь базы от мастера до работающей реплики и расчёт места на диске. Сама инициализация подробно описана в главе 5.

4.1. Главное правило

База на реплике появляется только через инициализацию с мастера (reinit): узел мастера сам передаёт копию через nbackup.

Не делайте копию вручную:

• gbak создаёт новый GUID базы и сбрасывает номер сегмента. Связь мастер — реплика ломается.
• Копия файла работающей базы не согласована, а RCM увидит две базы с одним GUID (duplicate_guid) и запретит инициализацию.

Уже работающую реплику, настроенную вручную, можно взять под управление без новой копии — см. 4.6.

4.2. Этапы

Этап 3 обязателен для Firebird 4/5. Без публикации Firebird мастера не пишет изменения таблиц в сегменты, и реплика тихо отстаёт от мастера. На странице Базы данных такая база отмечена значком публикация ВЫКЛ.. Нажмите Синхронизировать публикацию (Sync publication) до инициализации.

HQbird 2.5/3.0. Публикаций нет, этап 3 пропускается. Набор таблиц задают фильтры плагина replconf (глава 6).

Состояния базы:

4.3. Подготовка реплики

Папка баз реплики

Узел реплики кладёт каждую базу в свою папку databases.root по пути:

<databases.root>/<имя узла мастера>/<путь базы относительно корня мастера>

Пример: мастер node-a с корнем /databases/master и базой /databases/master/sales/employee.fdb. На реплике node-b с корнем /databases/replica база будет здесь:

/databases/replica/node-a/sales/employee.fdb

Так базы с одинаковыми именами от разных мастеров не мешают друг другу.

Папку корня никто не создаёт сам — ни установщик, ни goafts, ни узел при запуске. Создайте её одним из способов:

• в окне Инициализировать (Initialize): поле Папка реплики, кнопка Создать папку. Если вы укажете другую папку, RCM перед инициализацией запишет её в databases.root узла реплики;

• вручную на хосте реплики (Linux):

  Command Copy

  sudo mkdir -p /databases/replica
  sudo chown firebird:firebird /databases/replica
  sudo chmod 2770 /databases/replica

  Бит setgid (2770) нужен, чтобы все файлы внутри получали группу Firebird.

Поменять корень реплики можно, только пока на ней нет баз: иначе старые базы окажутся вне сканирования. Чтобы положить одну базу в другое место, используйте Перенести (Move) на странице базы.

Права

Узел реплики и Firebird должны писать в корень баз. Узел проверяет, что размещённые файлы получат группу папки. Если не может — отказ ownership_unfixable с текстом, как исправить (обычно служба узла работает с Group=root).

Версия Firebird

Главная версия Firebird на реплике должна совпадать с мастером (5.0 → 5.0, 4.0 → 4.0). Иначе реплика откажет до передачи данных: incompatible_engine.

Связь

Узел реплики должен быть пиром мастера, а мастер — пиром реплики (глава 2). Иначе RCM не предложит этот узел в окне Инициализировать.

4.4. Сколько нужно места

Коротко

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

Инициализация проверяет место дважды и только до блокировки базы:

1. RCM — по последней статистике узлов, до отправки команды. Если места явно мало, RCM сразу отвечает ошибкой 507.
2. Узел мастера — живой замер на своём томе, затем запрос к реплике, чтобы она замерила свой. Не хватает хотя бы на одной стороне — инициализация завершается на шаге SPACE CHECK с ошибкой insufficient disk space on master или … on replica.

Требование на обеих сторонах — 105 % размера базы мастера.

force (принудительно) пропускает только проверку в RCM. Проверку узла обойти нельзя: она защищает узел от переполнения диска посреди копирования.

Почему столько

Мастер. Во время копирования база заблокирована nbackup -L. Все изменения пишутся в файл <база>.delta рядом с базой. Размер .delta зависит от нагрузки на запись за время копирования. При большой нагрузке и медленной передаче он может вырасти сильно — следите за местом во время первой инициализации.

Реплика. Копия пишется сразу в файл <база>.hqcluster-part рядом с местом базы. Узел заранее резервирует полный размер. Затем файл проверяется, исправляется (nbackup -FIXUP -SEQUENCE) и переименовывается на место. Второй копии не нужно — нужен размер базы один раз, на томе базы.

Если реплика уже была (повторная инициализация), старый файл лежит на диске до последнего шага. Значит, на томе одновременно нужны старый файл и новая копия. Свободное место считается без старого файла — поэтому требование то же: 105 % от размера базы свободно.

Архив мастера (.LogArch). Узел хранит отправленные сегменты retention_days дней, чтобы реплика могла их запросить повторно. Сегменты, которые реплика ещё не применила, хранятся дольше. Если места мало, узел чистит архив по ступеням:

1. сегменты, которые применили все реплики, старше retention_days;
2. применённые сегменты новее (при нехватке места);
3. неприменённые сегменты — только в последнюю очередь. Тогда реплика теряет нужные ей сегменты и получает NEEDS_REINIT.

Если реплика долго недоступна, архив растёт. Объём = изменения базы за время простоя.

Пример расчёта

База 100 ГБ. Нагрузка — 5 ГБ сегментов в сутки. Инициализация идёт ночью, копирование занимает 2 часа, за это время в .delta попадает около 2 ГБ.

Добавьте запас на рост базы и на простой реплики (архив мастера растёт на 5 ГБ в сутки простоя).

Сегменты на отдельном томе

Папки .ReplLog, .LogArch и .Incoming по умолчанию лежат рядом с базой. Их можно вынести на другой том: параметр segments.storage в node.json (с mirror_hierarchy: true узел повторяет структуру папок баз). Тогда архив не отнимает место у баз. Проверка 105 % при этом остаётся на томе базы.

Где смотреть место

• Базы данных → Узлы и Обзор: значок свободного места тома databases.root. Жёлтый — меньше 20 %, красный — меньше 10 %.

  

• Отчёт кластера: hqbirdrcm report.

4.5. Несколько реплик одной базы

Вторая и следующие реплики делаются так же: Инициализировать в строке мастера, выбор свободного узла реплики.

• Пока идёт инициализация новой реплики, мастер не передаёт эту базу и уже работающим репликам. Они догонят мастер после конца инициализации. Окно подтверждения говорит об этом.
• Одна база — одна инициализация за раз, даже на разные реплики.
• Место на мастере проверяется для каждой инициализации отдельно.

4.6. Реплика, настроенная вручную

Если реплика уже работает по replication.conf, написанному вручную, её можно взять под управление и не копировать базу заново:

1. Мастер: зарегистрируйте базы с detect_existing (глава 3.6).
2. Реплика: Базы данных → узел реплики → Подхватить (Take over), или hqbirdrcm takeover-replica. RCM найдёт блоки реплик, сопоставит файлы с базами мастера по GUID и покажет для каждой: in_sync, resumable или needs_reinit.
3. Подтвердите строки. Узел перенесёт блоки в свою область replication.conf.
4. Перезапустите Firebird реплики, чтобы он прочитал перенесённые блоки.
5. Инициализируйте только строки needs_reinit: архив мастера уже не содержит сегментов, нужных этим репликам.

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

5. Инициализация (reinit)

Инициализация — передача копии базы мастера на реплику. Первая передача называется инициализацией (кнопка Инициализировать), повторная — реинициализацией (кнопка Реинициализировать). Механизм один и тот же.

Перед началом выполните этапы 1–5 из главы 4: база зарегистрирована, Firebird мастера перезапущен, публикация включена, папка реплики есть, места хватает.

5.1. Как запустить

1. Откройте Базы данных (Databases).
2. В строке базы мастера нажмите Инициализировать (Initialize). Для уже существующей пары — Реинициализировать (Reinit) в раскрытой карточке мастера.
3. В окне:
   • выберите узел реплики (в списке только свободные узлы-пиры этого мастера);
   • проверьте Папку реплики; если папки нет — Создать папку;
   • выберите Способ реинита: Плавный (рекомендуется) или Обычный (5.4);
   • если база мастера ещё ждёт перезапуска Firebird, окно скажет об этом и покажет кнопку Перезапустить Firebird мастера. Без перезапуска база не реплицируется.
4. Подтвердите. RCM напишет, что база будет заблокирована на мастере и скопирована на реплику.

Ход инициализации виден в раскрытой карточке мастера на странице Базы данных: шаги и проценты.

Каждая команда RCM (инициализация, перезапуск Firebird, синхронизация публикации) записывается на странице Команды (Commands) с результатом.

То же из командной строки

Command Copy

# одна база
hqbirdrcm reinit -node node-a -db <db_id> -to node-b
# все базы мастера
hqbirdrcm reinit -node node-a -all -to node-b

Параметры: -mode smooth|standard (по умолчанию smooth), -hold=false (не удерживать архив при длинных транзакциях), -allow-restart (5.6), -force (5.9).

-all пробует все базы и собирает ошибки, а не останавливается на первой.

5.2. Шаги

После шага 6 база получает состояние IN_SYNC. Мастер продолжает отправку сегментов с того места, где заканчивается копия.

Что важно знать:

• Мастер работает всё время. Пользователи пишут в базу, изменения идут в .delta. Блокировка снимается сразу после передачи.
• Транзакции, которые совпали с блокировкой, не теряются. Узел находит транзакции, открытые в момент nbackup -L, и реплика повторяет их из сегментов.
• Передача продолжается после обрыва. Если связь или узел реплики перезапустились, мастер продолжит с последней полученной части. Недоделанная передача хранится на реплике 24 часа (reinit_partial_keep_hours).
• При ошибке узел снимает блокировку, удаляет недоделанный файл на реплике и ставит базе FAILED. Следующая попытка начинается с известного состояния.
• Только nbackup. gbak не используется: он меняет GUID базы.

5.3. Влияние на работу

На Windows. Файл, открытый Firebird, заменить нельзя. При повторной инициализации узел останавливает Firebird реплики через fbagent, ставит файл и запускает Firebird снова. На Linux Firebird тоже останавливается до замены: иначе он продолжит работать со старым удалённым файлом.

5.4. Плавный и обычный способ

Плавный (smooth, по умолчанию). Перед блокировкой узел ищет длинные транзакции: пишущие транзакции пользователей, которые начались раньше самого старого сегмента в архиве мастера. После инициализации реплика не сможет их повторить и остановится на первом их изменении («Transaction … is not found»). Транзакции без изменений не учитываются.

Если такие транзакции есть, инициализация не начинается: RCM пишет Плавный реинит ждёт длинные транзакции и даёт ссылку Открыть список.

На странице Длинные транзакции:

• сводка: сколько транзакций и соединений, самый старый сегмент;
• Топ-5 соединений с самыми старыми транзакциями: пользователь, клиент, начало, возраст, изменения, текущий запрос;
• Удерживать сегменты / Снять удержание — пока удержание включено, архив мастера не чистится и история не сокращается;
• Отключить выбранные и повторить реинит — отключает соединения (их транзакции откатываются) и сразу запускает плавный реинит;
• Повторить реинит, Проверить снова.

Удержание включается само при отказе из-за длинных транзакций. Оно снимается после успешной инициализации, вручную или когда архив дорастёт до reinit_hold_max_segments (по умолчанию 1000 сегментов, оповещение retention_hold_released).

Обычный (standard) блокирует базу сразу, без проверки. Используйте его, только если вы знаете, что длинных пишущих транзакций нет.

То же из командной строки

Command Copy

hqbirdrcm longtx -node node-a -db <db_id>                       # список
hqbirdrcm longtx -node node-a -db <db_id> -disconnect 12,34 -retry-to node-b
hqbirdrcm longtx -node node-a -db <db_id> -hold false           # снять удержание

Транзакции старше публикации. Firebird не пишет в сегменты транзакцию, которая началась до включения публикации. Если публикацию включил узел, инициализация ждёт (6 попыток через 10 секунд), пока такие транзакции не закончатся, иначе завершается ошибкой reinit_pre_publication_transactions с их списком. После синхронизации публикации, которая добавила таблицы, переподключите приложения, затем запускайте инициализацию.

5.5. Скорость

Узел пересчитывает режим каждые 30 секунд: инициализация, начатая днём, ускорится ночью сама.

Скорость диска узел измеряет тестом. Повторить тест на хосте мастера:

hqclusternode benchmark -config /opt/hqclusternode/master/node.json

Время инициализации ≈ размер базы ÷ скорость. Пример: 100 ГБ при 100 МБ/с — около 17 минут чистой передачи; на практике ограничивает сеть или диск.

5.6. Перезапуск Firebird реплики

Новая база на реплике. Файл ставится без остановки Firebird. Firebird прочитает новый блок replication.conf только после перезапуска. До него реплика ничего не применяет. Шаг RESTARTING REPLICA показывает ожидание:

Узел перезапускает Firebird один раз после серии инициализаций, а не после каждой базы.

Чтобы перезапустить вручную, нажмите Перезапустить Firebird реплики. Ожидание заканчивается после любого успешного перезапуска Firebird или когда реплика применила сегмент новее копии.

Повторная инициализация на Firebird, который обслуживает и базы мастера. Такой Firebird узел сам не останавливает и отказывает: restart_not_allowed. Запустите инициализацию снова и отметьте Разрешить <узел> остановить Firebird для этого reinit (-allow-restart в командной строке) — в то время, когда соединения этого Firebird можно разорвать, в том числе к его базам мастера. Запускайте такие инициализации по одной на хост.

5.7. Очередь и одновременные инициализации

• Одна база — одна инициализация за раз (даже на разные реплики). Кнопка Инициализировать выключена, пока идёт инициализация этой базы.
• Узел мастера ведёт limits.max_concurrent_reinits инициализаций разных баз одновременно (по умолчанию 1). Остальные ждут в очереди; ответ содержит номер в очереди.
• Не запускайте свой nbackup -L (или ALTER DATABASE BEGIN BACKUP) на базе во время её инициализации и не запускайте инициализацию во время такого бэкапа: у базы может быть только одна блокировка. Инициализация проверяет это и отказывает с nbackup backup lock already active.

Очередь и текущие передачи видны на странице Передача (Transfer).

5.8. Автоматическая реинициализация

RCM может сам реинициализировать базу в состоянии NEEDS_REINIT, только в заданное окно. По умолчанию выключено.

Когда база получает NEEDS_REINIT:

Включение — Настройки → RCM (или rcm.json, раздел auto_reinit):

"auto_reinit": {
  "enabled": true,
  "default_window": "22:30-04:00",
  "max_concurrent": 1,
  "nodes": {
    "node-a": { "window": "23:00-05:00",
                "databases": { "sales/employee.fdb": "01:00-03:00" } }
  }
}

• Окно: для базы → для узла → общее. "always" — в любое время.
• Окна считаются по часам хоста RCM.
• max_concurrent — сколько инициализаций (ручных и автоматических) может идти в кластере, чтобы RCM запустил ещё одну автоматическую.
• Автоматическая инициализация проходит те же проверки места и GUID, что и ручная. Автор команды — system:autoreinit.
• После изменения перезапустите RCM.

Отложить (Snooze) в карточке мастера отключает автоматическую инициализацию одной базы на 1 час, 4 часа, 24 часа или до отмены. Ручная инициализация остаётся доступной.

5.9. Ошибки

target_not_replica. На месте копии лежит рабочая база: её сделали обычной (есть файл <база>.hqcluster-normal.json) или она не в режиме реплики. Узел не перезаписывает рабочую базу. Если её нужно заменить, запрос к API узла с overwrite_non_replica: true (в RCM кнопки нет) заменит файл и сохранит старый как <база>.pre-reinit-<время UTC>.fdb.

5.10. Как проверить результат

1. Базы данных: пара мастер — реплика в группе Ok, состояние IN_SYNC.

2. Проверить (Verify) в карточке мастера: узлы считают строки таблиц из sync_tables (глава 3.1) на мастере и на реплике и сравнивают. Проверяйте в тихое время: при активной записи числа могут отличаться.

hqbirdrcm verifydata -master node-a -master-db <db_id> -replica node-b -replica-db <db_id>

3. Периодическая проверка (по желанию): страница Проверка данных (Data check), включить для всех узлов, затем перезапустить службы узлов. Узлы сами сравнивают число строк, когда мастер и реплика стоят на одном сегменте. Расхождение — оповещение data_mismatch; тогда запустите Проверить.

Таблица, которую оператор убрал из публикации, показывается как «not published», а не как расхождение.

6. Настройка публикации

Публикация говорит Firebird мастера, изменения каких таблиц писать в сегменты. Без неё реплика ничего не получает.

6.1. Что такое публикация

В Firebird 4 и 5 таблицы для репликации задаёт публикация RDB$DEFAULT:

• Публикация включена — в RDB$PUBLICATIONS у неё RDB$ACTIVE_FLAG = 1 (команда ALTER DATABASE ENABLE PUBLICATION).
• Опубликованные таблицы — список в RDB$PUBLICATION_TABLES.

Firebird пишет в сегменты изменения только опубликованных таблиц и только при включённой публикации. Регистрация базы (глава 3) публикацию не включает. Её включает Синхронизировать публикацию (6.2).

Узел мастера проверяет публикацию каждый час (limits.publication_check_interval_sec, по умолчанию 3600). Если она выключена, узел проверяет её каждые 2 минуты.

На странице Базы данных у базы мастера есть значок:

Фильтр Публикация выкл. показывает базы с выключенной или неизвестной публикацией.

Если у базы с выключенной публикацией уже есть реплика, мастер выдаёт оповещение master_publication_off.

6.2. Синхронизировать публикацию

Где нажать:

• в строке базы мастера на странице Базы данных. При выключенной публикации кнопка стоит рядом со значком;
• на странице базы;
• для нескольких баз: отметьте строки, в списке Действие выберите Синхронизировать публикацию. RCM отправит отдельную команду для каждой базы.

Что делает узел (одна транзакция):

1. Включает публикацию. Если оператор выключил её сам (6.4), не включает.
2. Добавляет в публикацию все таблицы с ключом, которых там ещё нет.
3. Убирает из публикации таблицы без ключа и таблицы, которые оператор исключил (6.3).
4. Выключает автоматическое добавление новых таблиц (EXCLUDE ALL FROM PUBLICATION, затем добавляет нужные таблицы). Состав публикации задаёт только узел.

Таблица с ключом — пользовательская постоянная таблица, у которой есть первичный ключ или активный уникальный индекс. Системные и временные таблицы не публикуются.

Синхронизация убирает из публикации и таблицы без ключа, которые DBA добавил вручную.

Если состав уже правильный, узел ничего не меняет.

Когда узел отказывает:

Все базы узла сразу — только из командной строки. На странице Команды результат показан по каждой базе: готово, пропущено или ошибка. Базы в состоянии FAILED или SEEDING и базы без файла пропускаются.

То же из командной строки

Command Copy

hqbirdrcm setpublication -node node-a -db <db_id>   # одна база
hqbirdrcm setpublication -node node-a               # все базы узла

Команда ждёт до 5 минут и печатает строку на каждую базу. При ошибке код выхода 1. -nowait — не ждать результата.

6.3. Таблицы публикации

Откройте Таблицы публикации в строке базы мастера.

Страница показывает:

• состояние публикации (вкл./выкл., выключена оператором) и счётчики;
• каждую таблицу: имя, ключ и состояние.

В колонке ключа — первичный ключ, а если его нет — уникальный индекс с наименьшим числом полей.

Почему таблицу без ключа нельзя опубликовать. Реплика ищет строку для UPDATE и DELETE по ключу. Без ключа она не найдёт строку. Добавьте первичный ключ или уникальный индекс, затем синхронизируйте публикацию.

Исключить из публикации / Вернуть в публикацию:

1. Отметьте таблицы.
2. Нажмите Исключить из публикации или Вернуть в публикацию.
3. Узел сохраняет список и сразу синхронизирует публикацию.

Список исключённых таблиц хранится на узле мастера. Синхронизация его не меняет. При повышении реплики до мастера (глава 8) список переходит на новый мастер.

Проверить (глава 5.10) показывает исключённую таблицу как «not published», а не как расхождение.

6.4. Включить и выключить публикацию

На странице Таблицы публикации: Выключить публикацию / Включить публикацию.

• Выключение — это выбор оператора. Синхронизация публикацию обратно не включает.
• Изменения, сделанные, пока публикация выключена (или пока таблица исключена), не отправляются на реплику и после включения тоже.
• После включения нажмите Проверить (глава 5.10). Если данные расходятся — реинициализируйте реплику (глава 5).

6.5. Новая таблица

Новая таблица не попадает в публикацию сама: узел выключает автоматическое добавление.

После DDL:

1. Создайте у таблицы первичный ключ или уникальный индекс.
2. Нажмите Синхронизировать публикацию.
3. Попросите приложения переподключиться, если нужна реинициализация. Firebird не пишет в сегменты транзакции, которые начались до включения публикации; COMMIT RETAINING держит такую транзакцию открытой. Инициализация ждёт такие транзакции и затем отказывает с reinit_pre_publication_transactions (глава 5.4).

Строки, записанные в новую таблицу до синхронизации, на реплику не попадут. Если они есть, проверьте данные и при необходимости реинициализируйте реплику.

6.6. HQbird 2.5 и 3.0

В HQbird 2.5 и 3.0 публикаций нет. Firebird пишет сегменты, если в файле плагина replconf есть блок мастера. Кнопки публикации на таких узлах скрыты, API отвечает no_publications.

Набор таблиц задают параметры движка:

Параметры меняются в Настройки → Параметры репликации (глава 7.1). Страница Таблицы публикации показывает их только для чтения, со ссылкой Изменить в настройках движка. Firebird читает новые значения после перезапуска.

Плагин replconf. Узел пишет свой файл replconf.hqcluster.hqbird в папке Firebird. Firebird читает его, только когда replconf.properties указывает на него. Плагин нужно активировать один раз:

1. Настройки → Узлы, блок Плагин репликации (HQbird 2.5 / 3.0). Блок показывает, куда указывает replconf.properties, и проблемы, которые нашёл узел.

2. Активировать… Окно перечисляет, что сделает узел: установит плагин, направит replconf.properties на файл узла, перенесёт записи старого файла. Выберите, когда: Только в окне перезапуска узла или Сейчас, не учитывая окно перезапуска.

3. После перезапуска Firebird поле Активировано показывает «да: движок читает файл узла».

Активация перезапускает Firebird и затрагивает все базы этого Firebird. Выполняйте её в тихое время.

7. Другие опции репликации

7.1. Параметры репликации

Страница Настройки → Параметры репликации меняет ключи replication.conf для выбранных баз или для узла в целом.

1. Добавить мастер и реплики — выберите базы. RCM группирует их по версии Firebird и роли: своя форма для мастеров и для реплик.

2. Для каждого параметра выберите действие:

   Действие	Что делает
   без изменений	значение не меняется
   задать значение	новое значение
   сбросить (к следующему уровню)	убрать своё значение, взять значение уровнем выше
   не записывать (значение Firebird)	ключ не пишется, работает значение Firebird

3. Выберите, куда применить: К выбранным базам или Как значение по умолчанию их узлов.

4. Предпросмотр — узлы проверяют значения, ничего не меняя.

5. Применить. RCM отправляет команду каждому узлу.

Откуда взято значение (колонка Сейчас):

Узел, который не отвечает, показывает свои базы как недоступные для выбора. Изменения требуют fbagent (иначе fbagent_required).

Кто перезапускает Firebird (Firebird читает replication.conf только при запуске):

Для ручного перезапуска на странице есть кнопка Перезапустить Firebird.

7.2. Главные параметры

Мастер, Firebird 4/5:

Узел также пишет log_errors = true (нельзя изменить) и disable_on_error = true.

Реплика, Firebird 4/5:

Только Firebird 5: include_filter, exclude_filter, cascade_replication.

HQbird 2.5/3.0 — ключи log_* с тем же смыслом: log_archive_timeout, log_segment_count, log_segment_size (не меньше 2 × buffer_size). Ключ alert_command задаётся только в node.json.

Подсказка к каждому параметру есть в форме RCM.

7.3. Хранение архива

Архив <база>.LogArch на мастере чистится по ступеням:

1. Сегменты, которые применили все реплики и которые старше retention_days.
2. Если свободного места меньше free_space_floor_gb — применённые сегменты моложе срока. Оповещение disk_serious_cleanup.
3. Если места всё ещё мало — неприменённые сегменты, начиная со старых. Реплика получает NEEDS_REINIT, оповещение replication_paused_reinit_scheduled.

Очистить архив вручную:

hqbirdrcm cleanuparchive -node node-a              # ступени для всех баз узла
hqbirdrcm cleanuparchive -node node-a -db <db_id>  # одна база

-orphaned (только вместе с -db) удаляет все сегменты базы в состоянии ORPHANED (глава 3.8). Для другой базы узел ответит not_orphaned. Никогда не запускайте -orphaned на доноре повышения (глава 8.5).

7.4. Передача: сжатие, скорость, окна

Сжатие задаётся для каждого пира: Настройки → Узлы → Пиры, колонка compress.

Изменение действует сразу. Сжатие полезно для медленной сети.

Скорость передачи сегментов (Настройки → Узлы, Передача и реинициализация):

Единица — мебибайты (MiB), хотя в имени стоит «mbps». Всплеск не может быть меньше скорости.

Окна времени (Окна времени):

Метка у каждого поля показывает, когда изменение действует: сразу или перезапуск узла.

7.5. Проверка данных

• Проверить (Verify) — разовая сверка числа строк на мастере и реплике (глава 5.10).
• Проверка данных — периодическая сверка (глава 5.10). Узел сверяет, когда мастер и реплика стоят на одном сегменте.
• Какие таблицы сверять, задаёт sync_tables при регистрации (глава 3).
• Исключённые из публикации таблицы показаны как «not published» (глава 6.3).

7.6. Оповещения

Страница Оповещения. Действия:

• Подтвердить — оповещение видно, но отмечено подтверждено;
• Заглушить на 60 мин — скрыть на час;
• Удалить / Удалить все с этим кодом — RCM передаёт удаление узлу, который выдал оповещение. Если причина осталась, оповещение появится снова.

hqbirdrcm clearalerts -code backlog_warn   # также -id, -acked, -all

Отправки оповещений по почте или в webhook нет: следите за страницей Оповещения или опрашивайте API RCM.

Главные коды:

7.7. Пауза отправки

На странице Базы данных, в строке мастера: Приостановить отправку / Возобновить отправку. Для нескольких баз — через список Действие.

hqbirdrcm pauseshipping  -node node-a -db <db_id>
hqbirdrcm resumeshipping -node node-a -db <db_id>

• Пауза действует до Возобновить отправку или до инициализации.
• Firebird мастера продолжает писать сегменты. Архив .LogArch растёт: пока реплика стоит, ступень 1 (7.3) не удаляет её сегменты.
• Долгая пауза может дойти до ступени 3 и NEEDS_REINIT. Следите за местом.
• Кнопки нет, если у базы нет реплики или публикация выключена. Значок Пауза: нет лицензии — это пауза по лицензии (глава 2.8), её снимает только лицензия.

7.8. Логи

Лог удалённого узла — страница Журналы: выберите узел и источник (replication.log, firebird.log, агент узла).

hqbirdrcm getlogs -node node-b -source replication -tail 200

8. Как перевести реплику в обычную базу

Есть два пути:

Оба пути нельзя отменить через интерфейс.

8.1. Сделать обычной

1. Базы данных, сторона реплики: отметьте строки реплик.

2. В списке Действие выберите Сделать обычной, подтвердите. Отдельной кнопки в строке нет. Команды в командной строке тоже нет.

После этого база открыта для записи.

Убрать блок реплики из replication.conf. Узел убирает его при следующем сканировании, а Firebird читает файл при запуске:

hqbirdrcm scansync -node node-b
hqbirdrcm restartfirebird -node node-b

До этого ошибки «база не в режиме реплики» для этой базы не выдаются как оповещения.

Файл-метка защищает базу. Инициализация не перезапишет такую базу: отказ target_not_replica (глава 5.9). Удалить только метку недостаточно: узел проверяет и режим реплики в заголовке базы.

Если базу нужно снова сделать репликой — только новая инициализация с перезаписью. Это делается через API узла (overwrite_non_replica: true), в RCM такой кнопки нет. Старый файл сохраняется как <база>.pre-reinit-<время UTC>.fdb, метка удаляется.

8.2. Что происходит с сегментами

• Пока узел не просканировал базы, мастер продолжает слать сегменты. Узел реплики каждые 30 секунд удаляет старые и хранит только последние 100 (keep_segments).
• После сканирования запись базы на реплике получает состояние ORPHANED. Узел реплики отвечает мастеру unknown_database. Мастер перестаёт слать сегменты на эту реплику, перестаёт держать для неё архив и раз в 10 минут проверяет её снова.
• Другие реплики этой базы не затронуты.
• Запись ORPHANED можно удалить (глава 3.8): hqbirdrcm forgetdatabase. Файл базы при этом не удаляется.

8.3. Повысить до мастера

Реплика становится новым мастером. Её файл остаётся на месте, а управление переходит к узлу-компаньону.

Условия:

RCM не создаёт узел-компаньон: установите его заранее (глава 1).

Как запустить:

• в строке реплики Повысить до мастера, или в списке Действие;

• из командной строки:

  Command Copy

  hqbirdrcm promotetomaster -node node-b -db <db_id>   # -timeout 10m

RCM спросит подтверждение и назовёт узел-компаньон.

Шаги (видны в строке реплики, названия на английском):

На HQbird 2.5 и 3.0 публикаций нет: шаг PUBLICATION SYNC проходит с текстом «this engine has no publication».

Если донор и компаньон работают с одним Firebird, этот Firebird перезапускается: соединения ко всем его базам разрываются.

Если шаг не удался, задание получает failed с текстом ошибки. Исправьте причину и снова нажмите Повысить до мастера: выполненные шаги не повторяются. Если RCM перезапустился во время повышения, задание тоже станет failed — проверьте состояние узлов и повторите.

Лицензия. Если у fbagent на хосте мастера нет лицензии, мастер приостановил отправку. Повышение всё равно возможно. RCM предупредит: изменения после начала паузы будут потеряны.

8.4. Новый GUID

После повышения база должна получить свой GUID. Иначе новый мастер пишет сегменты под GUID старого мастера, и его реплики получают отказ duplicate_guid.

Шаг NEW GUID на узле:

1. gfix -shut single -force 0 — все соединения к базе разрываются;
2. nbackup -L, затем nbackup -F без -SEQUENCE;
3. удаляет <база>.delta;
4. проверяет заголовок: новый GUID, REPLICATION_SEQUENCE = 0;
5. gfix -online normal.

Firebird не перезапускается. Способ работает на всех версиях (2.5, 3.0, 4.0, 5.0).

Если шаг прервался, узел выдаёт оповещение newguid_interrupted. База может остаться в single-shutdown. Повторите Повысить до мастера: шаг продолжится.

Шаг пропускается (текст начинается с skipped:), если узел донора старой версии или у файла уже свой GUID.

После нового GUID старая цепочка nbackup не подходит. Сделайте новую копию nbackup уровня 0.

Если база создавалась с ADD DIFFERENCE FILE, её .delta лежит в другом месте: удалите его вручную.

8.5. После повышения

Запись донора. На узле реплики база остаётся ORPHANED, путь — в exclude_paths, папка .Incoming и метка остаются. В RCM это строка Призрачная реплика с кнопками Открыть на новом мастере и Очистить.

• Чтобы убрать строку, нажмите Очистить. Это меняет только RCM.
• forgetdatabase для донора узел отклоняет (mailbox_active), пока есть файл и папка .Incoming.
• Никогда не запускайте cleanuparchive -orphaned на доноре. Донор и компаньон используют одну папку <база>.LogArch. Команда удалит живой архив нового мастера.

Старый мастер.

• Если донор был его последней работающей репликой, RCM ставит старому мастеру Мастер деградировал и приостанавливает отправку на донор («отправка приостановлена: … (повышение до мастера)»). Не возобновляйте отправку на донор: там уже рабочая база. Чтобы снять это состояние, инициализируйте базу на другую реплику.

  

• Инициализация со старого мастера на узел донора будет отклонена (target_not_replica): там уже рабочая база.
• Если шаг NEW GUID был пропущен, старый и новый мастер имеют один GUID. Тогда инициализация со старого мастера требует -force (глава 5.9).
• Сделать старый мастер репликой нового мастера автоматически нельзя. Остановите приложения на старом мастере и уберите его базу из управления (глава 3.8).

Новый мастер. Подключите для него реплику: узел реплики, пиры (глава 2), публикация (глава 6), инициализация (глава 5).

8.6. Плановое переключение: чек-лист

RCM не переключает мастер автоматически. Повышение не проверяет, пишут ли приложения в старый мастер. Порядок действий:

1. Заранее. На хосте реплики работает узел-компаньон с ролью мастера, у обоих узлов одна метка host (глава 2.1). Для нового мастера готов узел будущей реплики.
2. Остановите запись приложений в базу старого мастера.
3. Дождитесь, пока реплика получит и применит всё: Базы данных → IN_SYNC, нет очереди.
4. Проверить (глава 5.10): числа строк совпадают.
5. Повысить до мастера (8.3). Дождитесь шага FINALIZE.
6. Проверьте: база в списке мастеров компаньона, публикация вкл.
7. Переключите приложения на новый мастер.
8. Сделайте копию nbackup уровня 0 новой базы (8.4).
9. Очистить запись-призрак для строки донора (8.5).
10. Подключите реплику к новому мастеру и инициализируйте её (глава 5).
11. Старый мастер: уберите базу из управления или оставьте как архив (8.5).