Цей посібник описує, як встановити й використовувати кластер реплікації HQbird:
вузли hqclusternode і менеджер кластера hqbirdrcm (RCM).
Це посібник для адміністратора Firebird. Ми припускаємо, що ви знаєте Firebird,
gfix і nbackup. Внутрішню будову вузла знати не потрібно.
З чого складається кластер
Компонент
Скільки
Де працює
Що робить
Firebird (HQbird)
один або кілька екземплярів
на кожному сервері баз даних
зберігає бази даних, записує сегменти реплікації
fbagent
один на екземпляр Firebird
поруч із Firebird
зупиняє і запускає Firebird на запит вузла
hqclusternode (вузол)
один на екземпляр і роль
поруч із Firebird
налаштовує реплікацію, передає сегменти, виконує ініціалізацію репліки
hqbirdrcm (RCM)
один на кластер
на будь-якому хості, який бачить усі вузли
вебінтерфейс, команди, сповіщення, статистика
Вузол має роль: master або replica. На одному екземплярі Firebird можуть працювати два вузли: вузол master і вузол replica.
У цьому випадку частина баз даних цього Firebird є master, а частина — репліками.
Як це працює
На master Firebird записує зміни бази даних у сегменти (файли журналу реплікації).
Вузол replica кладе сегменти в теку вхідних сегментів. Firebird репліки
застосовує їх до своєї копії бази даних.
Сам вузол master передає першу копію бази даних на репліку. Це називається
ініціалізацією (reinit). Вона проходить через nbackup, і master у цей час
продовжує працювати.
Вузли надсилають статистику до RCM. RCM показує стан кластера і
надсилає команди оператора вузлам.
Як працює кластер: сегменти, ініціалізація, статистика і команди оператора
Підтримувані версії
Firebird / HQbird 5.0 і 4.0 — усі можливості.
HQbird 3.0 і 2.5 — реплікація через плагін replconf. Публікацій немає;
набір таблиць задають фільтри. Відмінності описано в рамках «HQbird 2.5/3.0».
Старша версія Firebird на master і на репліці має збігатися. Інакше вузол replica
відмовиться від ініціалізації.
Порти
Порт
Хто слухає
Хто підключається
Для чого
7051
вузол
інші вузли і RCM
API вузла, передавання сегментів і копій баз даних
7443
RCM
усі вузли
отримання статистики від вузлів
7444
RCM
оператор
вебінтерфейс і API оператора. Встановлення через RCM (розділ 1.3): HTTPS на всіх адресах. Встановлення через HQCenter Admin або вручну: HTTP, лише 127.0.0.1
7450–7459
fbagent, поки вікно зв’язування відкрите
RCM
зв’язування хостів (розділ 1.3)
13050
fbagent, лише 127.0.0.1
вузол на тому самому хості
керування Firebird
3050
Firebird
застосунки
звичайна робота бази даних
Якщо на одному хості два вузли (master і replica), другий вузол має інший порт.
Під час встановлення через RCM другий вузол отримує порт 7061. В інших випадках
порт задаєте ви самі, наприклад 7052.
Порт 13050 не можна відкривати в мережу. Порт 7444 з HTTP (встановлення через
HQCenter Admin або вручну) теж не можна: підключайтеся до вебінтерфейсу RCM
через тунель SSH (розділ 1). Під час встановлення через RCM порт 7444 працює через
HTTPS, і інсталятор відкриває його в брандмауері.
Головне правило: немає fbagent — немає змін
Вузол змінює конфігурацію реплікації лише через fbagent: для цього потрібно
перезапустити Firebird. Якщо fbagent недоступний, вузол відмовляється від будь-якої дії,
що змінює конфігурацію. Він не працює «частково».
Терміни
Термін
Значення
Сегмент
файл журналу реплікації зі змінами бази даних
Публікація
список таблиць master, зміни яких потрапляють у сегменти (Firebird 4/5)
Ініціалізація (reinit)
передавання копії бази даних з master на репліку через nbackup
GUID бази даних
ідентифікатор бази даних Firebird; RCM використовує його, щоб зв’язати master і репліку
Peer
вузол-партнер: для master — його репліки
Companion
другий вузол на тому самому екземплярі Firebird (master і replica на одному хості)
ви запускаєте скрипт встановлення fbagent, схвалюєте запит, описуєте кластер
Через RCM, без HQCenter Admin (1.3)
HQCenter Admin немає, але потрібні сертифікати, конфігурація й оновлення без ручної роботи; до 3 серверів баз даних
ви встановлюєте HQbird на кожному хості, входите в RCM і в Параметри → Зв’язати хости вказуєте адреси хостів
Вручну (1.4)
немає доступу до HQCenter Admin, закрита мережа, особливі вимоги
ви встановлюєте файли, створюєте сертифікати, пишете node.json і rcm.json, реєструєте служби
Через HQCenter Admin і через 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, RED OS,
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. Встановлення через HQCenter Admin
Крок 1. Запустіть скрипт встановлення fbagent
Скрипт встановлює Firebird (збірку HQbird), fbagent і реєструє fbagent на
сервері HQCenter Admin. Оберіть скрипт відповідно до версії Firebird: fb25, fb30, fb40,
fb50.
Linux (від root):
Command
sudo sh fbagent-fb50_known.sh --goafts <HQCenter-Admin-server> --enroll --cluster
не ставити запитань (потрібно, коли немає термінала)
Повний список параметрів є в README скрипта встановлення fbagent.
Крок 2. Схваліть запит fbagent
З параметром --enroll fbagent надсилає запит сертифіката (CSR) до HQCenter Admin і
чекає схвалення до 30 хвилин. Схвалити можна так:
автоматично — якщо встановлення запущено з токеном ліцензії (--token) і
у ліцензії є вільне місце;
у панелі HQCenter Admin — розділ запитів CSR, запит
цього хоста, кнопка схвалити і підписати;
через API HQCenter Admin — POST /v1/admin/csr-requests/{id}/approve.
Якщо реєстрація не вдалася (наприклад, час очікування минув), fbagent усе одно
працює, але скрипт завершується з кодом 2. Запустіть скрипт знову з
тими самими параметрами: повториться лише реєстрація.
За кілька хвилин після реєстрації fbagent сам встановлює HQ Monitor.
Крок 3. Опишіть кластер
Вузли і RCM з’являються, щойно ви додаєте fbagent до кластера HQCenter Admin. Як описати
кластер, викладено в розділі 2.
Після збереження кластера:
Протягом 10 хвилин fbagent отримує кластер від HQCenter Admin (далі перевіряє
зміни кожні 60 секунд).
fbagent на хості RCM створює центр сертифікації (CA) кластера і підписує
сертифікати всіх вузлів.
Кожен fbagent записує node.json або rcm.json для своїх учасників кластера.
Під час наступної перевірки продукту (кожні 3 хвилини) fbagent встановлює служби і
запускає їх.
Що встановлюється і де:
Що
Linux
Windows
Вузол master
/opt/hqclusternode/master/, служба hqclusternode-master-p<port>
<HQbird>\hqclusternode\master\, служба HQClusterNode-master-p<port>
Вузол replica
/opt/hqclusternode/replica/, служба hqclusternode-replica-p<port>
<HQbird>\hqclusternode\replica\, служба HQClusterNode-replica-p<port>
RCM
/opt/hqbirdrcm/, служба hqbirdrcm
<HQbird>\hqbirdrcm\, служба hqbirdrcm
<port> — це порт Firebird, наприклад 3050. Один fbagent може розмістити не більше
одного вузла master, одного вузла replica, одного RCM і одного маршрутизатора
(hqclusternode router, від HQbird 2027.2.30, розділ 8.7).
У Windows. Версії fbagent до 2.83.0 встановлювали вузли в C:\hqclusternode і
RCM у C:\hqbirdrcm. Якщо ці теки існують, fbagent і далі
їх використовує.
Оновлення
fbagent перевіряє нові версії вузла і RCM кожні 3 хвилини; типовий
канал — stable. Спочатку оновлюється вузол replica, потім вузол master.
Якщо після оновлення служба не запускається або повідомляє неправильну версію,
fbagent повертається до попередньої версії і блокує нову. Список блокувань:
<тека fbagent>/update/<product>/blocked-versions.json. Щоб спробувати
версію знову, видаліть її рядок із цього файлу.
Стан продукту: fbagent --product-status hqclusternode (або
hqbirdrcm).
1.3. Встановлення через RCM (без HQCenter Admin)
Кластером керує RCM. fbagent кожного хоста отримує опис кластера від RCM,
fbagent на хості RCM підписує сертифікати, а вузол і RCM оновлюються з
випусків, які зберігає RCM.
Обмеження:
Один кластер на RCM.
Не більше 3 місць. Місце — це хост, на якому працює вузол master або replica.
Master і replica на тому самому хості рахуються як одне місце. Хост, на якому працює лише RCM,
місця не займає. Четвертий хост дає помилку seats_exceeded.
RCM не оновлює fbagent і Firebird. fbagent оновлює їх сам і не
чіпає replication.conf, node.json, rcm.json і сертифікати.
Є два способи:
Зв’язати хости в RCM — звичайний спосіб. Три дії: інсталятор на
кожному хості (RCM на одному хості, режим виявлення на інших), вхід у
RCM, форма Зв’язати хости.
Вручну з командного рядка — токени приєднання і
fbagent --cluster-join. Потрібно, коли порт 7450 між хостами закритий або
вікно спаровування вже закрилося.
Ліцензія. Пробна ліцензія містить функцію cluster. Після пробного
періоду fbagent не встановлює вузол або RCM, якщо в ліцензії немає cluster.
Він ніколи не блокує оновлення вже встановлених вузлів і RCM. Без
HQCenter Admin плаваюча ліцензія перестає працювати після online_check_days плюс
пільгові дні. Тому на кожному fbagent встановіть прив’язану ліцензію:
Command
fbagent --license-request --out license_request.json
# send the file to the vendor and receive license.jsonfbagent --license-install license.json
Без ліцензії master припиняє надсилати сегменти (розділ 2.8).
Порти:
Порт
Де
Хто підключається
7443
хост RCM
fbagent і вузли всіх хостів кластера
7444
хост RCM
браузер оператора (консоль RCM, HTTPS)
7450 (на другому і наступних хостах fbagent — 7451…7459)
хост у режимі виявлення, поки вікно спаровування відкрите
RCM на хості RCM
7051 (другий вузол того самого fbagent — 7061)
хости вузлів
інші вузли і RCM (1.4, крок 7)
Зв’язати хости в RCM
Приклад з нуля. Два сервери Linux, інсталятор .run, зв’язування,
реєстрація, публікація, ініціалізація і повторна ініціалізація під навантаженням — зі
знімками екрана і вимірюваннями: посібник hqbird2027-linux-cluster-guide.ru.md і
runbook hqbird2027-linux-cluster-runbook.ru.md (репозиторій goafts, тека
documentation).
Крок 1. Встановіть HQbird на кожному хості
Встановіть HQbird повним інсталятором на кожному сервері баз даних. Не реєструйтеся в
HQCenter Admin (--enroll).
Типово інсталятор не налаштовує кластер. Він кладе програми вузла
і RCM у теку fbagent (update/<product>/staged/), але не встановлює RCM, не відкриває вікно
спаровування і не відкриває порти кластера в брандмауері. Кластер
вмикається двома параметрами:
Command
sudo sh hqbird2027-fb50-linux-<version>.run --rcm on # RCM hostsudo sh hqbird2027-fb50-linux-<version>.run --cluster-pairing on # other hosts
--rcm on — на одному хості, де працюватиме RCM кластера. Інсталятор:
створює кластер цього хоста (fbagent --cluster-init); ім’я кластера — це
ім’я хоста;
встановлює і запускає RCM; консоль RCM працює через HTTPS на порту 7444;
створює першого адміністратора RCM rcmadmin з випадковим паролем;
відкриває в брандмауері порти 7443, 7444 і порт вузла 7051.
--cluster-pairing on (режим виявлення) — на кожному іншому хості.
Інсталятор відкриває вікно спаровування fbagent на 24 години: порт 7450 і
порт вузла 7051. Поки вікно відкрите, RCM з мережі може запросити цей хост до
свого кластера. fbagent починає слухати порт 7450 протягом хвилини.
Без цих параметрів інсталятор питає сам: у текстовому інтерфейсі
це сторінка Cluster, з --no-tui — два запитання.
Типова відповідь — «ні». --yes без параметрів кластера також відповідає
«ні» на обидва запитання.
Наприкінці інсталятор виводить рядки RCM: і Pairing:. На хості RCM:
text
RCM: https://10.0.0.7:7444 (cluster db1)
CA hash: sha256:7cfc1d4b…032d2582
Login: rcmadmin
Password: in /opt/hqbird/fbagent-fb50/clusterca/db1/rcm-initial-password (read it with sudo; RCM asks for a new one at the first login)
Pairing: not needed: this agent runs the RCM; other agents link through it
На іншому хості:
text
RCM: off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing: port 7450 open until 2026-11-17T17:49:18Z (fingerprint sha256:0439e44a…91a2f9b9); an RCM may invite this host
У виводі немає пароля: він у файлі з рядка Password:. Запишіть
fingerprint кожного хоста в режимі виявлення.
Параметри кластера в інсталяторі Linux:
Параметр
Що він робить
--rcm on|off
встановити RCM і створити кластер на цьому хості; типово off
--cluster-pairing on|off
режим виявлення: відкрити вікно спаровування на 24 години; типово off
--pairing-port N
порт спаровування нового fbagent, 7450–7459; типово перший вільний
--rcm-password-file F
пароль адміністратора RCM з першого рядка файлу F, замість випадкового
--cluster-id ID
ім’я кластера ID замість імені хоста (з --rcm on)
--cluster-node on|off
встановити програму вузла; типово on
--rcm-allow A,B
лише ці RCM можуть запросити цей хост: адреса, мережа CIDR або ім’я
Перший fbagent на хості отримує порт спаровування 7450 і порти вузла 7051 та
7061. Другий екземпляр на тому самому хості — 7451, 7052 і 7062.
RCM і вікно спаровування можна ввімкнути пізніше, без інсталятора: у HQ Monitor,
на сторінці Clusters, або командами від користувача fbagent:
Command
cd <fbagent folder> # /opt/hqbird/fbagent-fb50sudo -u firebird ./fbagent --cluster-init <name> # RCM host; open ports 7443 and 7444 yourselfsudo -u firebird ./fbagent --cluster-pairing on # window for 24 hourssudo -u firebird ./fbagent --cluster-pairing off
sudo -u firebird ./fbagent --cluster-pairing status
Старі інсталятори (fbagent до 3.1.0) не питають про кластер: вони
встановлюють RCM на кожному хості і всюди відкривають вікно спаровування. Потрібен RCM
одного хоста; RCM інших хостів самі зупиняються після зв’язування.
У Windows. Ті самі два варіанти є в інсталяторі Windows: параметри
/RCM і /DISCOVERY.
Крок 2. Увійдіть у RCM
Відкрийте адресу з рядка RCM: хоста RCM (https://<host>:7444). Увійдіть з
логіном rcmadmin і паролем із файлу в рядку Password:. RCM одразу просить
новий пароль (1.5).
Крок 3. Зв’яжіть хости
У RCM відкрийте Параметри → Зв’язати хости.
У полі Хости введіть адреси або імена хостів, по одному в рядку.
Перший рядок — хост RCM, він уже в кластері.
Натисніть Перевірити хости. RCM опитує порти спаровування
7450–7459 кожного хоста і показує платформу, версію Firebird,
відбиток і стан. Хосту RCM вікно спаровування не потрібне. Порівняйте
відбитки з виводом інсталятора (рядок Pairing:).
Виберіть Master (типово перший хост) і натисніть Зв’язати.
Зв'язати хости: результат перевірки
RCM просить підтвердження і показує перебіг у розділі Перебіг. Коли всі вузли
працюють, з’являється «Готово» і номер ревізії кластера:
Зв'язати хости: усі вузли працюють
Те саме з командного рядка:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1
Що відбувається далі:
RCM надсилає запрошення кожному вільному хосту.
fbagent хоста приєднується до кластера і закриває порт спаровування. Якщо
хост має власний RCM без вузлів, fbagent зупиняє його і вимикає, а
порожній кластер переносить у cluster/left/ у теці fbagent.
RCM зберігає кластер: вузол <host>-master на master, <host>-replica на
інших хостах, порт 7051, зв’язки master → replica.
fbagent кожного хоста встановлює і запускає вузол. RCM чекає, доки всі вузли
працюють, і показує Працює для кожного хоста.
Стани хоста після Перевірити хости:
Стан
Що робити
Готовий до зв’язування
нічого. Якщо нижче написано «Власний RCM цього хоста зупиниться після зв’язування» — це нормально
У кластері
хост уже в цьому кластері
Помилка unreachable
порт 7450 закритий: вікно спаровування вимкнене (як типово) або минуло 24 години. Одразу після встановлення зачекайте хвилину і натисніть Перевірити хости знову. Інакше відкрийте вікно (--cluster-pairing on) і перевірте брандмауер
Помилка in_other_cluster
хост в іншому кластері
Помилка claimed
інший RCM зв’язує цей хост просто зараз
Помилка seats_exceeded
більше ніж 3 місця
Випуски. fbagent встановлює вузол лише з RCM. RCM бере підписані
випуски зі своєї теки import/ (поруч із rcm.json) під час запуску і кожні
5 хвилин. Інсталятор кладе туди випуски хоста RCM, а fbagent інших хостів
самі завантажують випуск для своєї платформи. Список випусків унизу
сторінки Зв’язати хости. Випуск можна також імпортувати вручну (крок 5 нижче).
Вручну з командного рядка
Порядок: кроки 1–3 на хості RCM, крок 4 на кожному іншому хості, кроки 5–6 в RCM.
Крок 1. Встановіть HQbird з fbagent
Встановіть HQbird на кожному сервері баз даних і на хості RCM повним інсталятором.
На хості RCM можна одразу вказати --rcm on (тоді крок 3 не потрібен). На інших
хостах не вказуйте параметри кластера: типово немає ні RCM, ні вікна
спаровування. Не реєструйтеся в HQCenter Admin (--enroll).
На хості RCM інсталятор залишає програму RCM в теці fbagent
(update/hqbirdrcm/staged/). Без неї крок 3 завершується помилкою
no hqbirdrcm to install.
Крок 2. Встановіть прив’язану ліцензію
Як на початку розділу, «Ліцензія».
Крок 3. Створіть кластер на хості RCM
Якщо інсталятор уже створив кластер (--rcm on: рядок RCM: з адресою у
виводі), пропустіть цей крок.
Виконайте команду від користувача fbagent (у Linux — firebird), не від
root: інакше файли CA і rcm.json належатимуть root.
У Windows (PowerShell від адміністратора):
.\fbagent.exe --cluster-init shop-prod --address 10.0.0.7
shop-prod — ім’я кластера: малі латинські літери, цифри і -.
--address — адреса хоста RCM, за якою інші
хости до нього підключаються. Можна повторити кілька разів. Без параметра використовуються адреси й ім’я хоста.
Команда:
створює CA кластера і CA агента (у теці fbagent, clusterca/<name>/);
записує сертифікат RCM, rcm.json і cluster-init.json у теку RCM;
встановлює RCM і реєструє службу hqbirdrcm. У Linux служба працює як
окремий користувач hqbirdrcm;
перемикає fbagent на RCM (cluster.source = rcm) і перезапускає його;
виводить адресу RCM і відбиток CA:
Code
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 інших хостів
На хості RCM створіть токен приєднання для кожного fbagent: у RCM
Параметри → Кластер, кнопка Створити токен приєднання. Або з
командного рядка:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster join-token -note db2
Токен дійсний 24 години, лише для одного fbagent і лише один раз. RCM
показує його один раз, разом із готовою командою.
На хості вузла виконайте цю команду від користувача fbagent:
Замість --token-file можна використати --token <token>. У Windows — те саме з
.\fbagent.exe у PowerShell від адміністратора.
fbagent перевіряє CA RCM за відбитком. Якщо відбиток не збігається, він
зупиняється і нічого не записує. Потім fbagent отримує свій сертифікат
(90 днів, поновлюється автоматично) і перезапускається. Підключений fbagent видно в
RCM у таблиці Агенти. Поки в нього немає учасників, на хості нічого не встановлюється.
Крок 5. Імпортуйте випуски в RCM
fbagent бере вузол і RCM лише з RCM. Якщо потрібного випуску немає в
списку Випуски в дзеркалі (Параметри → Зв’язати хости), імпортуйте кожен продукт
(hqclusternode, hqbirdrcm) для кожної платформи ваших хостів
(linux-amd64, windows-amd64). Файл випуску і підпис .sig надає
постачальник.
RCM шукає підпис у <file>.sig, або вкажіть його через -sig. Без
дійсного підпису постачальника RCM не прийме файл.
Новий випуск замінює попередній. Перезапуск RCM не потрібен.
fbagent перевіряє нові версії кожні 3 хвилини. Порядок оновлення і
блокування такі самі, як через HQCenter Admin (1.2, «Оновлення»).
Крок 6. Опишіть кластер
Задайте учасників і зв’язки в RCM, Параметри → Кластер (розділ 2.3). Після
збереження fbagent встановлює вузли так само, як через HQCenter Admin (1.2, крок 3): записує
сертифікати, node.json і rcm.json, встановлює служби і запускає їх.
Порти — на початку розділу.
1.4. Встановлення вручну
Крок 1. Встановіть HQbird з fbagent
Встановіть HQbird на кожному сервері баз даних (тим самим скриптом, але без --enroll, або повним інсталятором HQbird). Перевірте, що fbagent працює.
Запишіть три значення з agent_config.json fbagent. Вони потрібні для node.json:
Поле fbagent
Поле node.json
Приклад
local_api.listen
firebird.fbagent_url
http://127.0.0.1:13050
local_api.token
firebird.fbagent_token
—
local_api.instance_id
firebird.instance_id
—
Перевірка fbagent (відповідь — це JSON екземпляра Firebird):
Команда створює ca.crt і ca.key, node-a.crt/.key, node-b.crt/.key і rcm.crt/.key. У -hosts перелічіть усі імена й адреси, за якими учасники будуть доступні.
gencerts і файли, які він створив
ca.key — це ключ CA. Не копіюйте його на хости; зберігайте окремо.
Новий вузол додається пізніше через -add: він підписує пару тією самою CA, а інші файли залишаються без змін:
Сертифікати дійсні 90 днів. gencerts -out certs -list показує дати закінчення, а gencerts -out certs -renew поновлює їх тим самим ключем. Скопіюйте новий .crt на його хост: вузол підхопить його без перезапуску.
Скопіюйте ca.crt і лише власний сертифікат і ключ на кожен хост.
Крок 4. Напишіть node.json
Один файл на вузол. Приклад для master (node-a):
json
{"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 password>","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 service name>"},"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"}]}
Вузол replica (node-b) має той самий файл, але з "role": "replica", власними сертифікатами і master node-a у peers.
Основні поля:
Поле
Значення
node_id
ім’я вузла; те саме в сертифікаті, у rcm.json і в peers інших вузлів
role
master або replica
listen_addr
адреса API вузла; другий вузол на тому самому хості використовує інший порт (:7052)
rcm.url
адреса для отримання статистики RCM; none — без RCM
firebird.*
Firebird і fbagent цього екземпляра; значення fbagent мають збігатися точно
firebird.auto_restart
чи може вузол replica сам перезапускати Firebird: auto (типово), never, always
windows.restart_window
вікно перезапуску Firebird; для master типове 22:00-05:00, для replica — завжди
windows.transfer_window
вікно, у якому ініціалізація йде на повній швидкості
peers
для master — його репліки, для replica — її master
databases
тека баз даних; краще не писати її вручну, а задати через RCM (розділ 3)
Решта полів має типові значення. Вузол не запуститься, якщо поля fbagent не задані.
Захистіть файл: у ньому пароль і токен.
Command
chmod 600 /opt/hqclusternode/node.json
У Windows. Пишіть шляхи у форматі JSON: "C:\\HQbird\\replication.conf".
service_name — це ім’я служби Windows для Firebird.
url — адреса вузла, як її бачить хост RCM. Лише https.
host — мітка екземпляра Firebird. Вузол master і вузол replica з тією самою міткою працюють на тому самому Firebird (companion, потрібний, щоб підвищити репліку до master, розділ 8). Одна мітка — не більше одного master і однієї replica.
Відносні шляхи розв’язуються від теки rcm.json.
Крок 6. Зареєструйте служби
Порядок запуску: спочатку RCM, потім репліки, потім master.
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-<role>-p<port>, що працює від користувача firebird. Якщо тека Firebird належить root, команда дає групі firebird право запису (зі sticky bit) і виводить кожну зміну: вузол має замінити replication.conf.
Для svc start, svc stop і svc uninstall вкажіть той самий node.json: ім’я служби виводиться з ролі і порту Firebird.
У Windows (PowerShell від адміністратора):
Command
cd C:\hqclusternode
.\hqclusternode.exe svc install -config C:\hqclusternode\node.json -certs C:\hqclusternode\certs
Служба HQClusterNode-<role>-p<port> працює як LocalSystem, запускається автоматично і перезапускається після збою. Служба вузла не залежить від служби Firebird. Якщо вузол установлено версією 2027.1.2–2027.1.9, приберіть залежність один раз:
.\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.
svc install і svc start у Windows
Крок 7. Відкрийте порти
На хості вузла дозвольте вхідні з’єднання на 7051 (порт listen_addr) від інших вузлів і від RCM. На хості RCM дозвольте вхідні з’єднання на 7443 від усіх вузлів. Не відкривайте порти 7444 і 13050 назовні.
Приклад ufw на хості вузла:
Command
sudo ufw allow from <ip-rcm> to any port 7051 proto tcp
sudo ufw allow from <ip-partner-node> to any port 7051 proto tcp
Конфігурація і сертифікати від цього не змінюються.
1.5. Перший вхід у RCM
Адреса і пароль залежать від того, як установлено RCM.
Як установлено RCM
Адреса
Логін і пароль
Інсталятором HQbird або fbagent --cluster-init (1.3)
https://<хост RCM>:7444 з будь-якого комп’ютера
rcmadmin і пароль, який вивів інсталятор (або власний з --rcm-password-file)
Через HQCenter Admin (1.2) або вручну (1.4)
http://127.0.0.1:7444, лише на хості RCM
rcmadmin, пароль strong password (з пробілом)
HTTPS (1.3). Сертифікат RCM підписаний CA кластера, якої браузер не знає, тому він попереджає. На сторінці входу RCM показує відбиток CA. Порівняйте його з CA hash, який вивів інсталятор, і імпортуйте CA в браузер або в систему як довірений корінь: посилання Завантажити сертифікат CA на сторінці входу (https://<хост RCM>:7444/ca.crt, файл hqcluster-ca.crt). Щоб RCM слухав лише localhost, задайте "operator_addr": "127.0.0.1:7444" у rcm.json і перезапустіть RCM.
HTTP (1.2, 1.4). З іншого комп’ютера підключіться через тунель SSH:
Command
ssh -L 7444:127.0.0.1:7444 <rcm-host>
Потім відкрийте http://127.0.0.1:7444 у браузері.
Сторінка входу RCM
Згенерований пароль. RCM просить змінити його під час першого входу: доки ви його не зміните, інші сторінки не відкриються. Змініть strong passwordодразу (посилання Пароль у заголовку).
Зміна пароля під час першого входу
Мова. Виберіть російську у списку мов у заголовку сторінки (він є і на сторінці входу). Якщо ви не виберете мову, її беруть із браузера.
Зміна паролів і нові користувачі
Кожен користувач змінює власний пароль: посилання Пароль у заголовку сторінки. Потрібні поточний пароль і новий щонайменше з 12 символів. Після зміни інші сеанси цього користувача закриваються.
Якщо інсталятор згенерував пароль, його записано у файл clusterca/<name>/rcm-initial-password у теці fbagent. Після зміни пароля fbagent сам видаляє цей файл. Не видаляйте файл initial-admin.json у теці RCM: у ньому лише хеш. Якщо файл користувачів втрачено і цього файлу немає, RCM створить користувача з типовим паролем.
Нові користувачі. У інтерфейсі немає сторінки користувачів. Користувачі зберігаються у файлі rcm-data/users.json. Пароль зберігається як хеш HA1: MD5("<name>:hqbirdrcm:<password>").
Перезапустіть RCM одразу: файл читається лише під час запуску. Коли пароль змінюють в інтерфейсі, RCM переписує файл із пам’яті, і правки, яких він ще не прочитав, буде втрачено.
Без поля role користувач має всі права. Від HQbird 2027.2.31 є роль "role": "viewer": лише перегляд, будь-який запит на зміну отримує 403.
1.6. Як перевірити встановлення
Служби вузла і RCM працюють і не перезапускаються в циклі:
systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.
systemctl status вузла
systemctl status RCM
RCM відповідає (без пароля): curl http://127.0.0.1:7444/healthz. Коли
встановлено через RCM (1.3), консоль працює через HTTPS:
curl -k https://127.0.0.1:7444/healthz.
У RCM сторінка Огляд показує всі вузли, без позначки «не
відповідає».
З командного рядка на хості RCM:
Command
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm nodes
./hqbirdrcm status
Кластер через RCM: Параметри → Кластер, розділ Стан — кожен
учасник застосував останню ревізію і не повідомляє про помилку. З командного
рядка: ./hqbirdrcm cluster status.
1.7. Журнали
Що
Де
Журнал вузла
<тека node.json>/logs/node-YYYYMMDD.jsonl
Вивід служби вузла (Linux)
journalctl -u hqclusternode-<role>-p<port>
Вивід служби RCM (Linux)
journalctl -u hqbirdrcm
Журнал реплікації Firebird
firebird.replication_log з node.json
Журнали будь-якого вузла без SSH
RCM, сторінка Журнали
1.8. Типові помилки
Що ви бачите
Причина
Що робити
Вузол не запускається: помилка про fbagent_url, fbagent_token або instance_id
fbagent не працює або значення не збігаються з agent_config.json
перевірте fbagent командою curl з 1.4, крок 1
Скрипт встановлення завершився з кодом 2
запит fbagent не було вчасно схвалено
схваліть запит і запустіть скрипт знову
Вузли не з’являються через HQCenter Admin
fbagent не в кластері, або кластер ще не отримано
перевірте кластер (розділ 2), зачекайте до 10 хвилин
Вузол у RCM «не відповідає»
порт 7051 закритий, url у rcm.json неправильний, адреси немає в сертифікаті
перевірте порти і -hosts сертифікатів
Немає входу в RCM: «Забагато невдалих спроб входу»
токен уже використано, йому більше ніж 24 години, або його відкликано
створіть новий токен (1.3, «Вручну», крок 4)
--cluster-join: hostname_conflict
у кластері є fbagent з тим самим іменем хоста й іншими адресами
дайте хостам різні імена
--cluster-join: this agent is in cluster … from goafts
fbagent уже в кластері HQCenter Admin
приберіть його з кластера HQCenter Admin
Вузол не встановлюється через RCM
у RCM немає випуску для цієї платформи
hqbirdrcm release list, імпортуйте випуск (1.3, «Вручну», крок 5)
2. Конфігурація кластера
У цьому розділі ви визначаєте, які вузли в кластері і який master надсилає
сегменти якій репліці. Потім налаштовуєте вузли RCM і користувачів.
Зв’язки задають одним із трьох способів:
Вузли встановлено
Де задають зв’язки
Розділ
через HQCenter Admin
у HQCenter Admin: сторінка Clusters HQ Monitor або API HQCenter Admin
2.2
через RCM, без HQCenter Admin
у RCM: Параметри → Кластер, hqbirdrcm cluster або сторінка Clusters HQ Monitor
2.3
вручну
у RCM: Параметри → RCM і Параметри → Вузли
2.3
На вузлах, установлених через HQCenter Admin або через RCM, змінюйте зв’язки лише в
описі кластера. fbagent перезаписує node.json і rcm.json згідно з
описом кластера. Редагування зв’язків у Параметри → RCM або Параметри → Вузли
RCM відхиляється (409 cluster_managed). Раніші версії RCM це приймали, але зміна
губилася.
2.1. Ролі і схеми
Кожен вузол має одну роль: master або replica. Два вузли — master і replica — можуть працювати на одному екземплярі Firebird.
Підтримувані схеми:
Code
1 → 1 node-a (master) ──▶ node-b (replica)
1 → N node-a ──▶ node-b
└─▶ node-c
N → 1 node-a ──┐
├─▶ node-b (one replica for several masters)
node-x ──┘
Both nodes host-1: node-1m (master) + node-1r (replica) ← one Firebird
on a host host-2: node-2m (master) + node-2r (replica) ← one Firebird
node-1m ──▶ node-2r, node-2m ──▶ node-1r
Зв’язок завжди йде від master до replica. RCM зв’язує базу даних master з її реплікою за GUID бази даних, а не за іменем вузла.
Companion. Вузол master і вузол replica на тому самому екземплярі Firebird є companion. Підвищення репліки до master (розділ 8) працює лише для такої пари. У rcm.json пару позначено однаковим значенням host.
2.2. Зв’язки через HQCenter Admin
Де описати кластер
HQ Monitor, сторінка Clusters (лише адміністратори; доставку конфігурації має бути ввімкнено). Звичайний спосіб.
API HQCenter Admin:POST /v1/admin/clusters і
PUT /v1/admin/clusters/{id}. Панель HQCenter Admin не має
сторінки кластерів.
``
Кроки на сторінці Clusters
Введіть Новий ідентифікатор кластера (малі латинські літери, цифри і -) і натисніть
Створити.
Додайте учасників (Учасники). Для кожного вкажіть:
fbagent хоста;
роль: master, replica або rcm;
адреси хоста;
порт: для вузла — 7051 (другий вузол на тому самому хості — напр. 7052),
для RCM — порт приймання статистики 7443.
Додайте зв’язки (Зв’язки реплікації) від master до replica.
Натисніть Перевірити, потім Зберегти.
Якщо інший адміністратор змінив кластер у той самий час, сторінка попросить
перезавантажити кластер і повторити зміну.
Правила
fbagent може належати лише до одного кластера.
На одному fbagent — не більше одного master, однієї replica, одного RCM і
одного маршрутизатора. Маршрутизатор (роль router, від HQbird 2027.2.30) не має зв’язків і
не займає ліцензійне місце (розділ 8.7).
Кластер має рівно один RCM. fbagent на хості RCM веде
центр сертифікації (CA) кластера.
Ім’я учасника (member_id) — латинські літери, цифри, -. Ім’я, fbagent і роль
учасника змінити не можна. Щоб перенести учасника на інший хост, створіть
нового учасника з новим іменем. Старе ім’я не використовуйте знову.
Кожна replica повинна мати зв’язок із master.
HQCenter Admin сам будує адресу вузла: https://<перша адреса>:<port>.
HQbird 2.5/3.0: задайте дату replconf_valid_till кластера
(YYYY-MM-DD) — конфігурація плагіна replconf дійсна до цієї дати.
Приклад через API
json
{"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 of host 1>","role":"master","addresses":["db1.lan"],"listen_port":7051},{"member_id":"db1-rcm","agent_id":"<fbagent of host 1>","role":"rcm","addresses":["db1.lan"],"listen_port":7443},{"member_id":"db2-r","agent_id":"<fbagent of host 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 показує стан учасників і дати
закінчення сертифікатів.
Що відбувається після збереження
fbagent кожного учасника отримує кластер. Усередині кластера — перевірка кожні
60 секунд (fbagent на хості RCM — кожні 30 секунд). Поза кластером fbagent
дізнається про кластер під час наступного опитування конфігурації. Якщо це опитування не
досягає сервера, перевірка йде кожні 10 хвилин.
Кожен fbagent створює ключ і надсилає запит сертифіката. fbagent на
хості RCM його підписує. RCM підписує власний сертифікат без запиту.
fbagent записує в node.json: ім’я, роль, адресу, peers (зі зв’язків),
адресу RCM, шляхи сертифікатів, дані Firebird і fbagent. У rcm.json: список
вузлів (nodes), список маршрутизаторів (routers), адресу приймання статистики і
шляхи сертифікатів. fbagent не чіпає інші поля файлів.
fbagent встановлює і запускає служби (розділ 1).
Зміна кластера:
Що змінилося
Що робить fbagent
лише peers працюючого вузла
передає їх вузлу без перезапуску
інші поля вузла
зупиняє вузол, записує файл, запускає вузол — у windows.transfer_window вузла (не задано — одразу)
rcm.json
перезапускає RCM одразу
сертифікати або CA
перезапускає службу
учасника видалено
зупиняє і видаляє службу; cluster-managed.json → cluster-removed.json, програма → *.removed; конфігурація, сертифікати і дані залишаються
Після видалення вузла його секція
# BEGIN managed-by:<name> … # END … лишається у спільному replication.conf. Видаліть її вручну і перезапустіть
Firebird через RCM.
Схвалення сертифікатів кластера
Типово fbagent на хості RCM сам підписує запити (auto). Можна ввімкнути ручне
схвалення. Команди на хості RCM:
Command
fbagent --cluster-ca-approval manual # or autofbagent --cluster-status # this fbagent's membership in the cluster (JSON)fbagent --cluster-ca-approve <request_id>
У режимі manual новий учасник або новий ключ чекає на схвалення. Поновлення
сертифіката з відомим ключем підписується автоматично.
2.3. Зв’язки через RCM
Кластер RCM (без HQCenter Admin)
Якщо кластер створив інсталятор HQbird або команда fbagent --cluster-init
(розділ 1.3), опис кластера зберігає RCM. Найпростіше додати хости на
сторінці Параметри → Зв’язати хости (розділ 1.3, «Зв’язати хости в RCM»):
RCM сам створює учасників і зв’язки. Правила ті самі, що в HQCenter Admin (2.2, «Правила»), плюс:
у RCM один кластер; учасник rcm завжди існує і його не можна видалити;
не більше 3 місць (хости з вузлами master або replica), інакше виникає помилка
seats_exceeded;
учасника можна додати лише на fbagent, який підключився до RCM
(розділ 1.3: «Зв’язати хости» або «Вручну», крок 4).
Кроки на сторінці Параметри → Кластер:
У таблиці Агенти натисніть Додати учасника в рядку fbagent.
Вкажіть роль (master, replica або router), member_id, адреси і порт.
Сторінка пропонує ім’я <host>-<role> і порт: 7051 для першого вузла fbagent,
7061 для другого. Порт, який уже зайнятий іншим учасником хоста, RCM відхиляє. Адреси
fbagent — це кнопки: натисніть, щоб додати адресу.
У розділі Зв’язки натисніть Додати зв’язок від master до replica.
Натисніть Перевірити: RCM покаже помилки і попередження.
Натисніть Зберегти. Сторінка покаже список змін і попросить
підтвердження. Якщо учасників видаляють, вікно червоне.
До збереження зміни існують лише на сторінці (мітка «Не збережено»). Якщо
хтось зберіг кластер у той самий час, сторінка запропонує перезавантажити його.
Якщо змінилися лише поля RCM (ревізія, CA, доручення), сторінка збереже
вашу зміну сама.
Інші розділи сторінки:
Розділ
Що там є
заголовок
ім’я кластера, ревізія, CA кластера і CA агента; кнопка Експортувати для старої CA
Токени з’єднання
створити токен для нового fbagent, відкликати невикористаний
Документ JSON
увесь документ у текстовому полі; Перевірити і Зберегти його використовують
Ключі і CA
доручення: новий ключ учасника (rekey), нова CA кластера (rotate_ca), нова CA агента (rotate_agent_ca); недоступні, коли є незбережені зміни
Стан
ревізія, яку застосував кожен учасник, закінчення сертифіката, служба, остання помилка
З командного рядка на хості RCM:
Command
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster show > c.json # document with revision# edit c.json./hqbirdrcm cluster validate -f c.json # validate without saving anything./hqbirdrcm cluster apply -f c.json # save (If-Match = revision from the file)./hqbirdrcm cluster agents # connected fbagents and their members./hqbirdrcm cluster status # what the fbagents reported
Формат документа такий, як у 2.2, «Приклад через API». apply зі старою ревізією
отримує 409: запустіть show знову. RCM зберігає останні 20 ревізій у
rcm-data/cluster/history/.
HQ Monitor. Сторінка Clusters працює і з RCM. На хості RCM
HQ Monitor звертається до RCM через fbagent цього хоста, сертифікатом fbagent:
користувач RCM і пароль не потрібні. У журналі аудиту RCM такі
дії записуються як agent:<id> (<user>). Інший спосіб, для раніших
версій RCM: у конфігурації HQ Monitor задайте rcm_admin_url
(http://127.0.0.1:7444), rcm_admin_user (користувач RCM) і
rcm_admin_password_file (файл з його паролем).
Після збереження все йде як через HQCenter Admin (2.2, «Що відбувається після
збереження»). RCM сам перечитує nodes у rcm.json, без перезапуску.
Прибрати fbagent з кластера: видаліть його учасників і збережіть, потім
натисніть Відкликати в таблиці Агенти (або
./hqbirdrcm cluster revoke -agent <id>). Щоб повернути його, потрібен новий
токен. Після відкликання fbagent (від версії 3.1.0) сам залишає кластер:
зупиняє свої вузли і видаляє дані кластера. Те саме на хості
вузла робить команда fbagent --cluster-leave. На хості RCM її відхиляють.
Встановлення вручну: додайте вузол до RCM
Параметри → RCM, таблиця Підключені вузли.
Натисніть Додати вузол. Заповніть node_id, url
(https://<адреса>:7051), роль, host (мітка екземпляра Firebird),
server (лише для групування на екрані).
Натисніть Перевірити в рядку вузла: RCM перевірить з’єднання і права.
Натисніть Зберегти. RCM запише rcm.json і збереже старий файл як
rcm.json.<час UTC>.bak (останні 20).
Перезапустіть RCM. До перезапуску діє стара конфігурація;
сторінка показує, які поля чекають на перезапуск.
Параметри → RCM
Command
sudo systemctl restart hqbirdrcm
Це можна зробити і без інтерфейсу: відредагуйте rcm.json і перезапустіть RCM.
Встановлення вручну: зв’яжіть master і replica
Зв’язок треба записати з обох боків:
Параметри → Вузли, виберіть вузол master.
У розділі Партнери натисніть Додати партнера: node_id репліки, її url,
стиснення (zstd).
Натисніть Зберегти. RCM покаже список змін і попросить
підтвердження. Зміна peers набуває чинності одразу.
Повторіть для вузла replica: його партнер — master.
Розділ Партнери вузла master
Якщо партнера не записано з одного з боків, RCM не запропонує цей вузол replica під час
ініціалізації бази даних.
2.4. Параметри вузла
Параметри → Вузли показує параметри node.json, які вузол дозволяє змінювати з RCM. Зберігаються лише змінені поля, після вікна зі списком змін.
Параметри → Вузли: вибір вузлаПараметри баз даних вузла з позначками «після сканування»
Кожен рядок позначено тим, коли зміна набуде чинності:
Коли
Які параметри
Одразу
channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; від HQbird 2027.2.24 — параметри перевірки даних (limits.data_check_*); від HQbird 2027.2.31 — advertise_addr
Після перезапуску вузла
решта лімітів, windows.transfer_window; сторінка показує їх окремим рядком, доки вузол не перезапущено
Після сканування
databases.*, exclude_filter; якщо replication.conf змінився, потрібен перезапуск Firebird (розділ 3.5)
Лише для читання (змінюються в node.json на хості вузла): firebird (включно з паролем і auto_restart), rcm, tls, segments, адреса listen_addr.
Основні параметри:
Параметр
Типово
Значення
windows.restart_window
master 22:00-05:00, replica — завжди
коли вузол може перезапускати Firebird; Firebird master ніколи не перезапускає себе сам
windows.transfer_window
23:00-05:00
вікно, у якому ініціалізація йде зі швидкістю reinit_window_mbps
limits.channel_a_mbps
50
швидкість передавання сегментів, МБ/с (channel_a_burst_mbps — короткочасний пік, 200)
limits.reinit_window_mbps
100
швидкість ініціалізації у вікні передавання, МБ/с
limits.reinit_day_disk_fraction
0.5
частка виміряної швидкості диска для ініціалізації поза вікном
limits.retention_days
2
скільки днів зберігати надіслані сегменти в архіві master
limits.free_space_floor_gb
1
мінімальне вільне місце, ГБ; нижче цього replica не приймає сегменти
limits.max_concurrent_reinits
1
скільки ініціалізацій вузол виконує одночасно
Подробиці швидкості і зберігання архіву — у розділах 5 і 7.
firebird.auto_restart (лише в node.json) визначає, чи може вузол replica сам перезапускати Firebird:
Значення
Поведінка
auto (типово)
може, якщо цей Firebird не обслуговує бази даних master
never
ніколи
always
завжди, навіть якщо цей Firebird має бази даних master
Через HQCenter Admin.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:
Виправте firebird.password у node.jsonкожного вузла цього
екземпляра (master і replica).
Виправте пароль у конфігурації fbagent і перезавантажте її (див.
документацію fbagent).
Перезапустіть служби вузлів.
Інакше сторінки публікації і перевірки в RCM покажуть помилку входу
(SQLSTATE 28000).
2.7. Користувачі RCM і аудит
Користувачі у файлі rcm-data/users.json (розділ 1.5). Без ролі
користувач має всі права; роль viewer (від HQbird 2027.2.31) — лише перегляд.
Сеанс триває 12 годин після останньої дії.
Після 10 невдалих входів за 5 хвилин вхід для цього користувача й адреси
тимчасово блокується. Успішний вхід скидає лічильник.
Журнал аудиту — це файл rcm-data/audit.jsonl: один рядок JSON на кожну
зміну, вхід і вихід. В інтерфейсі журналу аудиту немає.
Сторінка Команди показує автора кожної команди.
2.8. Ліцензія
Раз на хвилину вузол master читає ліцензію fbagent свого хоста. Якщо ліцензії немає (пробний період закінчився, ліцензія прострочена або недійсна), вузол припиняє надсилати сегменти для всіх баз даних master. Firebird і бази даних продовжують працювати, але репліки перестають отримувати зміни.
Що ви бачите в RCM:
master червоний (NEEDS_ATTENTION), зі значком «немає ліцензії: надсилання зупинено»;
немає кнопки Відновити: паузу знімає лише ліцензія;
на репліці: «не отримує від …: у master немає ліцензії»;
у таблиці Вузли значок «немає ліцензії»; у Параметри → Вузли блок ліцензії fbagent;
сповіщення license_paused і license_pause_archive_released;
ініціалізацію заборонено (license_paused).
Блок ліцензії fbagent у Параметри → Вузли
Встановіть ліцензію в fbagent. Вузол сам зніме паузу протягом хвилини. Master зберігає архів для реплік протягом limits.retention_days (типово 2 дні) від початку паузи. Якщо встановити ліцензію пізніше, репліки доведеться ініціалізувати знову.
Кластер через RCM, без HQCenter Admin. Плаваюча ліцензія без HQCenter Admin перестає працювати після 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. Як перевірити
Огляд: усі вузли присутні і згруповані за сервером.
Огляд кластера
Параметри → Вузли: master має репліку в Партнери, а replica має master.
Параметри → RCM: кнопка Перевірити в рядку кожного вузла проходить.
Звіт кластера одним файлом:
Command
./hqbirdrcm report -o report.json
2.10 Типові помилки
Що ви бачите
Причина
Що робити
Редагування партнерів у RCM відхилено (409 cluster_managed) або втрачено після перезапуску вузла
вузол установлено через HQCenter Admin або через RCM
змініть зв’язки в описі кластера (2.2, 2.3)
seats_exceeded під час збереження кластера в RCM
вузли на четвертому хості
не більше 3 хостів із вузлами
Параметри → RCM: rcm_config_read_only
кластер через RCM у Linux: rcm.json належить fbagent
відредагуйте rcm.json від користувача fbagent і перезапустіть RCM
Відкликати агента не працює (agent_has_members)
у fbagent є учасники
спочатку видаліть учасників і збережіть
Вузол replica не пропонується під час ініціалізації
партнера не записано з одного з боків
додайте партнера з обох боків (2.3)
Зміна в Параметри → RCM не набуває чинності
RCM не перезапущено
перезапустіть RCM
422 під час збереження кластера в HQCenter Admin
помилка в документі
виправте за списком errors, перевірте через validate
409 під час збереження кластера
кластер змінив хтось інший
перечитайте кластер і спробуйте знову
Новий учасник кластера HQCenter Admin не отримує сертифікат
ручне схвалення на хості RCM
fbagent --cluster-ca-approve <id>
Помилка SQLSTATE 28000 на сторінках публікації
пароль SYSDBA змінено
2.6
3. Додавання бази даних до master
У цьому розділі база даних master переходить під керування вузла. Вузол записує її в
replication.conf і створює теки для сегментів. Після перезапуску Firebird
база даних готова до реплікації.
Створення репліки — це наступні кроки (публікація, ініціалізація). Їх описано в
розділах 4–6.
Назви кнопок подано за російським інтерфейсом RCM, з англійськими в дужках.
3.1. Як вузол знаходить бази даних
Вузол master шукає бази даних в одній теці — корені баз даних (databases.root). Що переходить під керування, визначають правила:
Правило
Поле
Типово
Тека баз даних
root
не задано
Шукати підтеки
recursive
так
Маска включення
template
*.fdb
Маска виключення
exclude_mask
немає
Розмір файлу, МБ
min_size_mb, max_size_mb
без обмежень (0)
Таблиці для порівняння даних
sync_tables
з HQbird 2027.2.24 — таблиці з публікації бази даних, якщо їх немає — RDB$FIELDS; у 2027.5.7 — RDB$FIELDS
Список включення
include_paths
порожній (режим шаблону)
Список виключення
exclude_paths
порожній
Шлях root — це шлях на хості вузла, не на хості RCM. Вузол застосовує спочатку маску включення, потім маску виключення, потім розмір.
Правила однакові для всього вузла. Список sync_tables теж спільний: перевірка (розділ 5.10) шукає кожну таблицю зі списку в кожній базі даних вузла, яка не має власного списку.
Таблиці для порівняння, з HQbird 2027.2.24. Кожна база даних може мати власний список (Таблиці відстеження синхронізації). Вузол зберігає його в databases.sync_tables_by_db. Перевірка бере перший заданий список:
власний список бази даних;
спільний список sync_tables вузла;
таблиці з публікації бази даних;
RDB$FIELDS.
Спільний список, збережений раніше, має пріоритет над публікацією: база даних без власного списку використовує його. Сторінка бази даних master показує, який список зараз діє (3.3).
Таблиця, якої немає ні в основній базі даних, ні в репліці, отримує стан «немає в базі даних» (absent): її не порівнюють, і перевірка не покаже через неї «Не OK». Таблиця, якої бракує лише з одного боку, — це розбіжність.
RCM і вузол 2027.5.7. Є один список для всього вузла (sync_tables); без списку перевірка використовує RDB$FIELDS. Відсутня таблиця — це помилка, і перевірка бази даних покаже «Не OK».
Усі правила зберігаються в node.json вузла. Вузол застосовує їх під час кожного сканування.
Режим шаблону і режим списку:
Режим шаблону (список включення порожній): вузол бере всі файли, що відповідають масці, крім виключених. Новий файл у теці вузол підхопить автоматично під час наступного сканування.
Режим списку (список включення не порожній): вузол бере лише файли зі списку. Новий файл не перейде під керування автоматично — його треба додати.
Оберіть режим списку, якщо в теці є копії баз даних, тестові бази або інші файли, які не потрібно реплікувати.
3.2. Перш ніж почати: перевірте права
Користувач, від якого працюють Firebird і вузол (firebird у Linux,
LocalSystem у Windows), повинен мати права читання і запису на:
кореневу теку баз даних і файли баз даних;
replication.conf і його теку (вузол замінює файл через тимчасовий файл);
теки сегментів <database>.ReplLog і <database>.LogArch (вузол створює їх сам).
RCM перевіряє права перед реєстрацією (preflight). Якщо перевірка не вдається,
команда завершується помилкою preflight failed on <node> і списком шляхів.
Реєстрація бази даних: форма і попередній перегляд
Відкрийте сторінку реєстрації вузла master. Посилання є у двох місцях:
Бази даних → таблиця Вузли → стовпець дій →
Зареєструвати;
Огляд → картка вузла master → Зареєструвати бази даних.
Вузол replica цієї сторінки не має.
Форма показує поточні правила вузла (вузол надіслав їх сам). Якщо вузол
не відповідає, кнопки попереднього перегляду і реєстрації вимкнені: без поточних
правил вони скинули б списки включення і виключення.
Заповніть або виправте поля: Шлях до теки на цьому сервері,
recursive, маски, Фільтр розміру, Таблиці відстеження
синхронізації.
Поле Таблиці відстеження синхронізації:
з HQbird 2027.2.24 і пізніше — список на базу даних, яку ця дія
зареєструє. Порожнє поле: база даних використовує таблиці власної публікації. Реєстрація не змінює спільного
списку вузла (sync_tables). Якщо він є, форма про це каже: база даних без власного списку використовує його
замість публікації.
Список уже керованої бази даних задається на її сторінці: Бази даних →
база даних master → блок Таблиці відстеження синхронізації. Блок
показує, який список зараз діє. Порожнє поле прибирає власний
список бази даних;
у RCM і вузлі 2027.5.7 — один список для всіх баз даних вузла
(sync_tables).
Натисніть Попередній перегляд. Вузол покаже всі файли, що відповідають масці
включення. Він нічого не змінює.
Перевірте список. Кожен файл має прапорець:
позначено — файл буде під керуванням;
позначено, заблоковано, з міткою уже під керуванням — базу даних уже
зареєстровано;
заблоковано з причиною — файл виключено маскою, розміром або списком виключення.
Щоб його взяти, змініть правило.
Позначте потрібні бази даних і натисніть Зареєструвати
вибрані. RCM попросить підтвердження і покаже кількість файлів.
Підтвердження реєстрації
Що робить ця кнопка:
у режимі шаблону — файли без прапорця додаються до списку виключення, файли з
прапорцем з нього прибираються;
у режимі списку — файли з прапорцем додаються до списку включення.
Кнопка додає бази даних до тих, що вже під керуванням. Вона не змінює
заблоковані рядки.
7. Кнопка Зареєструвати застосовує форму без зміни
списків.
8. Дочекайтеся повідомлення про завершення і кількості доданих баз даних. Якщо довго
немає відповіді, перевірте результат на сторінці Команди.
З HQbird 2027.2.24 і пізніше повідомлення — «Зареєстровано: N». Якщо Firebird master
треба перезапустити, RCM каже, яку кнопку натиснути (зазвичай
Перезапустити Firebird master у рядку бази даних) і дає посилання на бази даних master.
RCM 2027.5.7 може сказати «Немає нових придатних баз даних», хоча бази даних
додано: перевірте сторінку Бази даних.
Результат реєстрації
Якщо після реєстрації баз даних не знайдено, а вузол уже їх мав, вузол
відмовляється (409) і повертає старі правила. Так помилка в шляху не вимикає
реплікацію всіх баз даних.
Примітка: команда надсилає лише поля зі своїх параметрів. Решту
правил (маски, розміри, списки включення і виключення, sync_tables) вузол
скине. Команда не має параметрів для цих правил. Перед
запуском перевірте поточні правила (hqbirdrcm getconfig -node node-a). Якщо
їх задано, використайте сторінку реєстрації.
3.4. Що відбувається після реєстрації
Вузол записує правила в node.json.
Вузол сканує теку (scansync).
Для кожної знайденої бази даних вузол пише блок у власну область
replication.conf (між рядками # BEGIN managed-by:node-a role:master і
# END …) і створює теки <database>.ReplLog та <database>.LogArch. Вузол не змінює текст поза власною областю.
Перед зміною вузол зберігає копію файлу:
replication_YYYYMMDD_hhmmss_NNN.conf.
Якщо replication.conf змінився, бази даних переходять у
стан PENDING_RESTART: Firebird прочитає новий файл лише після
перезапуску. У таблиці Вузли це показано в стовпці Очікує
перезапуску.
Firebird перезапущено, база даних готова до публікації й ініціалізації
3.5. Перезапуск Firebird master
Вузол master ніколи не перезапускає Firebird сам. RCM теж ні. Перезапуск
master — це рішення оператора: перезапуск розриває всі з’єднання з
усіма базами даних цього екземпляра Firebird.
Оберіть час малого навантаження і натисніть одну з кнопок:
Перезапустити Firebird master — на сторінці Бази даних, у рядку
master бази даних, яка чекає на перезапуск;
ту саму кнопку у вікні Ініціалізувати, розділ 5;
Перезапустити Firebird — на сторінці бази даних.
RCM попросить підтвердження. Він показує ім’я вузла і попередження: Firebird
перезапуститься одразу, без вікна перезапуску, і всі з’єднання буде розірвано.
Підтвердження перезапуску Firebird master
Те саме з командного рядка
Command
hqbirdrcm restartfirebird -node node-a
Ця команда теж перезапускає одразу, без вікна перезапуску.
Як вузол перезапускає Firebird:
Перевіряє, що fbagent відповідає і керує тим самим екземпляром
(ідентифікатор, порт, ім’я служби з node.json). Якщо якесь значення не
збігається, вузол відмовляється.
Просить fbagent перезапустити Firebird.
Чекає, доки Firebird відповість на своєму порті.
Переводить бази даних з PENDING_RESTART у CONFIGURED.
Кілька екземплярів HQbird на одному хості. fbagent перезапускає служби, перелічені в
firebird.update.services своєї конфігурації. Порожній список означає усі
служби HQbird на хості. Якщо на хості два екземпляри HQbird, залиште
в списку лише службу свого екземпляра. Інакше перезапуск одного вузла
зупинить і інший екземпляр.
У Windows. Якщо replication.log виріс до log_portion_mb або більше,
перезапуск іде так: зупинити Firebird → заархівувати журнал → запустити.
3.6. База даних, яку вже реплікують вручну
Якщо реплікацію бази даних уже налаштовано вручну (власний блок у
replication.conf, публікацію ввімкнено, сегменти йдуть), її можна взяти під
керування без повторної ініціалізації репліки. Для цього є режим
detect_existing (лише master).
У відповіді taken_over перелічує бази даних, які буде перенесено. Додайте -verbose,
щоб побачити пропущені бази даних із причиною.
Якщо список правильний, виконайте команду без -dry-run.
Вузол переносить блок лише якщо:
теки сегментів називаються точно <database>.ReplLog і <database>.LogArch;
в архіві вже є сегменти;
публікацію в базі даних увімкнено.
Вузол не переносить блок з іншими шляхами і повідомляє про нього як «знайдено, але
не підтримується».
Після перенесення бази даних отримують PENDING_RESTART, хоча параметри реплікації
не змінилися: змінюється лише положення блоку у файлі. Перезапустіть Firebird у
вікні обслуговування.
3.7. Як перевірити
Бази даних: базу даних видно в рядку вузла master, стан CONFIGURED
(після перезапуску).
Поруч із базою даних може бути значок публікація ВИМК: публікацію ще
не ввімкнено. Це нормально, публікація — наступний крок (розділ 6).
Нова база даних у рядку master
На хості вузла: блок бази даних є в replication.conf усередині області
managed-by:node-a, а поруч із базою даних є теки .ReplLog і .LogArch.
3.8. Прибрати базу даних з керування
Звичайний спосіб — кнопка. На сторінці Бази даних позначте бази даних,
виберіть масову дію Прибрати з керування і
натисніть Застосувати до вибраних. RCM:
додає файли до списку виключення вузла;
сканує теку один раз: блоки баз даних прибираються з replication.conf;
видаляє записи баз даних у вузлі.
Файли баз даних і теки сегментів залишаються на диску. Firebird не перезапускається.
Firebird продовжує писати сегменти бази даних до свого наступного перезапуску;
RCM скаже, чи потрібен перезапуск.
RCM відмовиться (has_replicas) для бази даних master, яка має живу репліку:
інакше репліка тихо зупинилася б. Спочатку зробіть репліку звичайною базою даних або
приберіть її (розділ 8).
Не видаляйте блок бази даних з replication.conf вручну: під час наступного
сканування вузол запише його знову.
Якщо файл бази даних зник або його виключено правилом. Тоді база даних отримує
стан ORPHANED (група Осиротілі). Вузол зберігає її запис і архів
сегментів: відсутня база даних частіше є помилкою, ніж рішенням. Якщо файл повернеться, база даних
знову працює, і сповіщення знімається. Щоб видалити таку базу даних назавжди,
виконайте два кроки в цьому порядку:
Після forgetdatabase команда cleanuparchive більше не знайде базу даних. Обидві
команди працюють лише для бази даних у стані ORPHANED і не чіпають файл
бази даних.
Обережно. Після підвищення репліки до master (розділ 8) не запускайте
cleanuparchive -orphaned для старого запису: новий master використовує ту саму
теку .LogArch, і команда видалить його робочий архів.
3.9. Зміна кореня баз даних
Реєстрація з іншим шляхом дозволена. Вузол:
додає бази даних з нової теки;
переводить бази даних зі старої теки, яких немає в новій, у ORPHANED (сповіщення
orphaned_database) і зберігає їхні архіви.
Якщо ви обрали неправильну теку, зареєструйте правильну теку знову. База даних з тим
самим повним шляхом продовжить працювати під тим самим db_id. База даних за іншим шляхом
— це нова база даних (новий db_id); її репліку треба ініціалізувати знову.
3.10. Типові помилки
Що ви бачите
Причина
Що робити
preflight failed on node-a
немає прав на теки
виправте права, спробуйте знову (3.2)
409 scan_would_empty_region
нова тека не містить баз даних, а вузол їх мав
перевірте шлях і маску
Попередній перегляд порожній
маска не збігається або тека неправильна
перевірте шлях, маску, «recursive»
Кнопки вимкнені, «Не вдалося прочитати конфігурацію вузла»
вузол не відповідає
перевірте службу вузла і мережу (розділ 1)
База даних довго лишається в PENDING_RESTART
master не перезапускає Firebird сам
перезапустіть Firebird (3.5)
Перезапуск відхилено через fbagent
fbagent не працює або його дані не збігаються з node.json
розділ 1, перевірка fbagent
Новий файл не з’явився
вузол у режимі списку
додайте файл через «Зареєструвати вибрані»
4. Як зробити базу даних реплікою: кроки і розташування на диску
Цей розділ охоплює весь шлях бази даних від основної до робочої репліки, а також розрахунок місця на диску. Саму ініціалізацію детально описано в розділі 5.
4.1. Головне правило
База даних з’являється на репліці лише через ініціалізацію з master (reinit):
сам вузол master передає копію через nbackup.
Не робіть копію вручну:
gbak створює новий GUID бази даних і скидає номер сегмента. Зв’язок master —
replica розривається.
Копія файлу працюючої бази даних не є узгодженою, і RCM побачить дві бази даних з тим самим
GUID (duplicate_guid) і заборонить ініціалізацію.
Уже працюючу репліку, налаштовану вручну, можна взяти під
керування без нової копії — див. 4.6.
4.2. Етапи
№
Етап
Де
Стан бази даних master після етапу
1
Реєстрація бази даних на master
розділ 3.3
PENDING_RESTART
2
Перезапуск Firebird master
розділ 3.5
CONFIGURED
3
Синхронізація публікації
розділ 6
CONFIGURED, публікація УВІМК
4
Підготовка репліки: тека, права, версія Firebird
4.3
—
5
Перевірка вільного місця на master і на репліці
4.4
—
6
Ініціалізація
розділ 5
SEEDING → IN_SYNC
7
Перезапуск Firebird репліки (якщо потрібно)
розділ 5.6
репліка починає застосовувати сегменти
8
Перевірка даних
розділ 5.10
—
Етап 3 обов’язковий для Firebird 4/5. Без публікації Firebird master не записує
зміни таблиць у сегменти, і репліка тихо відстає від master. На
сторінці Бази даних таку базу даних позначено значком публікація ВИМК. Натисніть
Синхронізувати публікацію перед ініціалізацією.
Від HQbird 2027.2.24 вікно Ініціалізувати про це попереджає і
пропонує кнопку Синхронізувати публікацію й ініціалізувати, а вузол master
відмовляє в ініціалізації з помилкою publication_off (розділ 5.1).
RCM і вузол 2027.5.7 публікацію не перевіряють.
HQbird 2.5/3.0. Публікацій немає, тому етап 3 пропускається. Набір таблиць задають
фільтри плагіна replconf (розділ 6).
Стани бази даних:
Стан
Група в RCM
Значення
CONFIGURED
Очікування
Firebird прочитав параметри, репліки ще немає
PUBLISHING
Очікування
триває синхронізація публікації
SEEDING
Очікування
триває ініціалізація
IN_SYNC
Ok
репліка отримала всі сегменти
LAGGING
Очікування
репліка відстає, сегменти в черзі
NEEDS_REINIT
Помилка
репліку треба ініціалізувати знову
FAILED
Помилка
остання ініціалізація не вдалася
4.3. Підготовка репліки
Тека бази даних репліки
Вузол replica кладе кожну базу даних у власну теку databases.root за шляхом:
Code
<databases.root>/<master node name>/<database path relative to the master root>
Приклад: master node-a з коренем /databases/master і базою даних
/databases/master/sales/employee.fdb. На репліці node-b з коренем
/databases/replica база даних буде тут:
Code
/databases/replica/node-a/sales/employee.fdb
Так бази даних з однаковими іменами від різних master не стикаються.
Ніхто не створює кореневу теку автоматично — ні інсталятор, ні HQCenter Admin, ні вузол під час
запуску. Створіть її одним із цих способів:
у вікні Ініціалізувати: поле Тека репліки, кнопка
Створити теку. Кнопка видима лише коли теки немає. З HQbird 2027.2.24,
якщо вузол replica ще не має databases.root, поле вже містить
/databases/replica/<ідентифікатор вузла replica>. Для репліки у Windows поле порожнє:
введіть теку з літерою диска. Кожному вузлу replica на тому самому хості потрібна власна
тека. Теку створює вузол
replica: власник — firebird (або користувач служби вузла), права
2770. Якщо вузол не може її створити, вікно покаже команду для хоста репліки.
Якщо ви вкажете іншу теку, RCM запише її в databases.root вузла replica перед ініціалізацією;
Біт setgid (2770) потрібен, щоб усі файли всередині отримали групу Firebird.
Корінь репліки можна змінити лише поки в ньому немає баз даних: інакше старі бази даних
опиняться поза скануванням. Щоб покласти одну базу даних в інше місце, використайте
Перемістити на сторінці бази даних.
Права
Вузол replica і Firebird повинні мати змогу писати в корінь баз даних. Вузол перевіряє, що
розміщені файли отримають групу теки. Якщо не може — відмовляється з
ownership_unfixable і текстом, як це виправити (зазвичай служба вузла працює з
Group=root).
З HQbird 2027.2.24 вікно Ініціалізувати показує також теку, яка
існує, але в яку служба вузла не може писати: текст вузла з командою виправлення
і кнопку Перевірити знову. RCM 2027.5.7 у цьому випадку каже
«Тека існує»: перевірте права самі (hqbirdrcm checkpermissions -node <replica> -root <folder>).
Версія Firebird
Старша версія Firebird на репліці має збігатися з master (5.0 → 5.0,
4.0 → 4.0). Інакше репліка відмовиться до будь-якого передавання даних:
incompatible_engine.
Зв’язок
Вузол replica має бути peer master, а master — peer репліки (розділ 2).
Інакше RCM не запропонує цей вузол у вікні Ініціалізувати.
4.4. Скільки місця потрібно
Коротко
Де
Що
Скільки
Master, том бази даних
вільно перед ініціалізацією
≥ 105 % розміру бази даних
Replica, том теки баз даних
вільно перед ініціалізацією
≥ 105 % розміру бази даних, з HQbird 2027.2.24 — плюс free_space_floor_gb (плюс старий файл, якщо репліка вже існувала; з прапорцем Видалити стару репліку — без нього)
Master, <database>.ReplLog
робочі сегменти Firebird
до 64 сегментів × розмір сегмента (типово 16 МБ) ≈ 1 ГБ на базу даних
Master, <database>.LogArch
архів сегментів для реплік
зміни за retention_days (типово 2 дні) + те, чого репліки ще не підтвердили
Replica, <database>.Incoming
черга сегментів до застосування
до 256 сегментів × 16 МБ ≈ 4 ГБ на базу даних у найгіршому випадку
Replica, увесь том
запас
щонайменше free_space_floor_gb (типово 1 ГБ)
Перевірка місця перед ініціалізацією
Ініціалізація перевіряє місце двічі і лише перед блокуванням бази даних:
RCM — з останньої статистики вузла, перед надсиланням команди. Якщо місця
явно недостатньо, RCM одразу повертає помилку 507.
Вузол master — живе вимірювання на власному томі, потім запит до репліки, щоб
вона виміряла свій. Якщо хоча б з одного боку замало, ініціалізація
закінчується на кроці ПЕРЕВІРКА МІСЦЯ помилкою
insufficient disk space on master або … on replica.
Вимога з обох боків — 105 % розміру бази даних master.
З HQbird 2027.2.24 вузол replica рахує так:
йому потрібно 105 % розміру бази даних плюсfree_space_floor_gb репліки (7.3):
після ініціалізації на томі лишається запас для сегментів;
залишки попередніх ініціалізацій (<database>.hqcluster-part, <database>.new)
рахуються як вільне місце: вузол видаляє їх перед новою копією;
текст помилки називає всі числа. Він також називає файли
<database>.pre-reinit-*.fdb і <database>.failed-seed-*.fdb з їхнім розміром. Вузол
ніколи їх не видаляє: видаліть їх самі, якщо вони не потрібні.
force (примусово) пропускає лише перевірку в RCM. Перевірку вузла
обійти не можна: вона захищає вузол від нестачі диска посеред копіювання.
Якщо місця не вистачає лише через стару копію репліки, RCM 2027.2.24 у
помилці 507 називає прапорець Видалити стару репліку, а не force. Для цього
обидва вузли мають бути HQbird 2027.2.24 або новіші. Інакше помилка називає
вузол, який треба оновити, і force.
Чому так багато
Master. Під час копіювання база даних заблокована через nbackup -L. Усі
зміни записуються у файл <database>.delta поруч із базою даних. Розмір .delta залежить
від навантаження записом під час копіювання. За великого навантаження і повільного
передавання він може сильно зрости — стежте за місцем під час першої
ініціалізації.
Replica. Копія пишеться прямо у файл <database>.hqcluster-part поруч із
місцем бази даних. Вузол заздалегідь резервує повний розмір. Потім файл перевіряється,
ремонтується (nbackup -FIXUP -SEQUENCE) і перейменовується на місце. Друга
копія не потрібна — розмір бази даних потрібен один раз, на томі бази даних.
Якщо репліка вже існувала (повторна ініціалізація), старий файл лежить на
диску до останнього кроку. Це означає, що старий файл і нова копія потрібні на томі
одночасно. Вільне місце рахується без старого файлу — тому вимога
та сама: вільно 105 % розміру бази даних.
Видалити стару репліку (з HQbird 2027.2.24). Якщо на томі репліки немає місця
для нової копії поруч зі старою, позначте цей прапорець у вікні ініціалізації
(розділ 5.1). Тоді вузол replica видаляє стару копію і її
вхідні сегменти (.Incoming) перед передаванням, і тому вистачає на 105 %
розміру бази даних плюс free_space_floor_gb. Вузол видаляє копію лише якщо всі умови
істинні:
без видалення місця не вистачає, а з видаленням вистачає;
це копія, встановлена ініціалізацією цього вузла: заголовок
читається, режим — репліка лише для читання;
базу даних не зроблено звичайною (немає файлу <database>.hqcluster-normal.json, розділ 8);
overwrite_non_replica не задано (5.9).
Інакше вузол нічого не видаляє і відмовляється з причиною в тексті. Щоб видалити,
вузол зупиняє Firebird репліки на час видалення (5.6).
Прапорець типово вимкнений. Ризик: поки триває передавання, на репліці немає
копії бази даних. Якщо в бази даних лише одна репліка, master увесь час
без захисту. Поки немає нової копії, база даних на репліці в стані NEEDS_REINIT (не FAILED і
не ORPHANED), і репліка видає сповіщення replica_removed_for_reinit
(warn). Щойно нова копія на місці, сповіщення знімається. Якщо ініціалізація
після видалення не вдається, пара лишається NEEDS_REINIT: запустіть
ініціалізацію знову (або її запустить автоматична повторна ініціалізація, 5.8).
Нова ініціалізація передає базу даних з початку.
Архів master (.LogArch). Вузол зберігає надіслані сегменти
retention_days днів, щоб репліка могла запросити їх знову. Сегменти,
які репліка ще не застосувала, зберігаються довше. Якщо місця мало, вузол
чистить архів етапами:
сегменти, застосовані всіма репліками і старші за retention_days;
застосовані сегменти, які новіші (коли місця мало);
незастосовані сегменти — лише як останній засіб. Тоді репліка
втрачає потрібні сегменти і отримує NEEDS_REINIT.
Якщо репліка довго недоступна, архів росте. Його обсяг = зміни бази даних за
період простою.
Приклад розрахунку
База даних 100 ГБ. Навантаження — 5 ГБ сегментів на день. Ініціалізація йде
вночі, копіювання триває 2 години, за які близько
2 ГБ потрапляє в .delta.
Де
Розрахунок
Усього вільно
Master, том бази даних
105 ГБ на перевірки (включно зі зростанням .delta) + .ReplLog 1 ГБ + .LogArch 2 дні × 5 ГБ = 10 ГБ
≥ 116 ГБ
Replica, нова база даних
105 ГБ + .Incoming до 4 ГБ + 1 ГБ запасу
≥ 110 ГБ
Replica, повторна ініціалізація
старий файл 100 ГБ уже на диску + 110 ГБ вільно
том ≥ 210 ГБ
Replica, повторна ініціалізація з прапорцем Видалити стару репліку (з HQbird 2027.2.24)
старий файл видалено перед передаванням: 105 ГБ + .Incoming до 4 ГБ + 1 ГБ запасу
том ≥ 110 ГБ
Додайте запас на зростання бази даних і на простій репліки (архів master росте на
5 ГБ за день простою).
Сегменти на окремому томі
Теки .ReplLog, .LogArch і .Incoming типово лежать поруч із базою даних.
Їх можна перенести на інший том: параметр segments.storage у node.json
(з mirror_hierarchy: true вузол відтворює структуру тек баз даних). Тоді
архів не забирає місце в баз даних. Перевірка 105 % як і раніше стосується тому бази даних.
Де дивитися місце
Бази даних → Вузли і Огляд: значок вільного місця для
тому databases.root. Жовтий — менше ніж 20 %, червоний — менше ніж 10 %.
Сторінка Бази даних: стовпець Диск у таблиці Вузли
Звіт кластера: hqbirdrcm report.
4.5. Кілька реплік однієї бази даних
Друга і наступні репліки створюються так само: Ініціалізувати в рядку master, з вибором вільного вузла replica.
Поки нова репліка ініціалізується, master не передає цю базу даних і вже працюючим реплікам. Вони наздоженуть master після завершення ініціалізації. Вікно підтвердження про це каже.
Одна база даних — одна ініціалізація за раз, навіть для різних реплік.
Місце на master перевіряється окремо для кожної ініціалізації.
База даних master з двома репліками
4.6. Репліка, налаштована вручну
Якщо репліка вже працює з написаного вручну replication.conf, її можна взяти під керування і не копіювати базу даних знову:
Master: зареєструйте бази даних з detect_existing (розділ 3.6).
Replica:Бази даних → вузол replica → Перейняти, або hqbirdrcm takeover-replica. RCM знайде блоки репліки, зіставить файли з базами даних master за GUID і покаже для кожної: in_sync, resumable або needs_reinit.
Підтвердьте рядки. Вузол перенесе блоки у власну область replication.conf.
Перезапустіть Firebird репліки, щоб він прочитав перенесені блоки.
Ініціалізуйте лише рядки needs_reinit: архів master більше не містить сегментів, потрібних цим реплікам.
4.7. Типові помилки
Що ви бачите
Причина
Що робити
insufficient disk space on master / on replica
замало місця (4.4). Під час повторної ініціалізації стара копія займає місце до кінця (4.4)
звільніть місце, спробуйте знову. Другий вихід на репліці (від HQbird 2027.2.24) — прапорець Видалити стару репліку (4.4, 5.1)
507 від RCM одразу
за статистикою місця його явно бракує
те саме. Якщо місце є без старої копії, RCM 2027.2.24 називає прапорець Видалити стару репліку
incompatible_engine
різні старші версії Firebird
оновіть Firebird репліки
Немає теки на вузлі replica
корінь не створено
Створити теку у вікні ініціалізації (4.3)
Тека існує, але служба вузла не може в неї писати (від HQbird 2027.2.24)
немає права запису
виконайте команду з вікна, натисніть Перевірити знову (4.3)
publication_off (від HQbird 2027.2.24)
публікацію master вимкнено або в ній немає таблиць
Синхронізувати публікацію й ініціалізувати (5.1)
ownership_unfixable
служба вузла має чужу групу
виправте групу служби, як сказано в тексті помилки
duplicate_guid
дві бази даних з тим самим GUID (копія файлу)
приберіть копію або дайте їй новий GUID (nbackup -F)
Вузла replica немає в списку Ініціалізувати
немає зв’язку в peers
розділ 2
Replica IN_SYNC, але дані розходяться
публікацію було вимкнено
синхронізуйте публікацію, потім повторіть ініціалізацію
5. Ініціалізація (reinit)
Ініціалізація — це передавання копії бази даних master на репліку. Перше передавання
називається ініціалізацією (кнопка Ініціалізувати), повторне передавання —
повторною ініціалізацією (кнопка Ініціалізувати знову). Механізм той самий.
Перед початком виконайте кроки 1–5 з розділу 4:
базу даних зареєстровано, Firebird master перезапущено, публікацію ввімкнено,
тека репліки існує, і місця достатньо. Скільки місця потрібно на master і на
репліці, описано в розділі 4.4.
5.1. Як почати
Спочатку публікація. Реєстрація бази даних не включає публікацію. Без
публікації репліка не отримує змін. Перед ініціалізацією виконайте
Синхронізувати публікацію (розділ 6) або
hqbirdrcm setpublication -node <master>.
З HQbird 2027.2.24 вікно ініціалізації перевіряє публікацію. Якщо
її вимкнено або в ній немає таблиць із ключем, вікно показує
попередження і кнопку Синхронізувати публікацію й
ініціалізувати. RCM синхронізує публікацію, чекає завершення команди і
починає ініціалізацію з вибором із вікна.
Вузол master 2027.2.24 сам відмовляється від такої ініціалізації (і від першої
теж) з помилкою publication_off і видає сповіщення
master_publication_off (розділ 6.1). Після відмови комірка бази даних знову
має кнопку Синхронізувати публікацію й ініціалізувати.
Якщо оператор вимкнув публікацію (6.4) або прибрав з неї всі таблиці з
ключем (6.3), синхронізація це зберігає. RCM не починає
ініціалізацію і дає посилання на сторінку Таблиці публікації.
RCM і вузол 2027.5.7 публікацію не перевіряють: ініціалізація
вдається, база даних показує «OK» у RCM, але репліка не отримує змін. Якщо
публікацію ввімкнули після ініціалізації — ініціалізуйте базу даних знову.
Вікно «Ініціалізувати базу даних знову?»
Відкрийте Бази даних.
У рядку бази даних master, у стовпці вузла replica, натисніть Ініціалізувати.
Вузол replica задається стовпцем: у вікні його не вибирають. Для
наявної пари — Reinit у розгорнутій картці master.
У вікні (з HQbird 2027.2.24 заголовок для нової пари — «Ініціалізувати
базу даних?»; у RCM 2027.5.7 — «Ініціалізувати базу даних знову?» також під час
першої ініціалізації):
перевірте Теку репліки. Вікно показує, чи тека існує. Якщо
ні, натисніть Створити теку: вузол replica її створить (4.3). Якщо вузол
не може її створити, вікно показує команду для хоста репліки. З HQbird
2027.2.24 вікно також показує теку, в яку служба вузла не може
писати: команду виправлення і кнопку Перевірити знову;
виберіть Метод reinit: Плавний (рекомендовано) або Стандартний
(5.4). З HQbird 2027.2.24, якщо в архіві master ще немає сегментів
(зазвичай перед першою ініціалізацією), вікно показує підказку: на
завантаженій базі даних Стандартний швидший;
якщо база даних master ще чекає на перезапуск Firebird, вікно про це скаже і
покаже кнопку Перезапустити Firebird master. Без перезапуску база даних
не реплікується;
Видалити стару репліку (з HQbird 2027.2.24, типово вимкнено)
потрібен лише для повторної ініціалізації, коли на томі репліки немає
місця для нової копії поруч зі старою (4.4). Вікно показує
числа наперед: скільки потрібно, скільки вільно, скільки займає стара копія.
Якщо місце є без старої копії, вікно просить позначити прапорець. Прапорець
неактивний, якщо вузол master або replica старої версії: вікно каже,
який вузол оновити. Доки нова копія не готова, у репліки немає копії
цієї бази даних (4.4).
Підтвердьте. RCM повідомить, що базу даних буде заблоковано на master і
скопійовано на репліку.
Перебіг ініціалізації видно в розгорнутій картці master на сторінці Бази даних:
кроки і відсотки. З HQbird 2027.2.24 перебіг видно і після оновлення
сторінки: під час першої ініціалізації — у комірці вузла replica, а також у
рядку Перебіг повторної ініціалізації на сторінці бази даних master. Кнопка
Ініціалізувати неактивна, поки вузол master копіює базу даних. Якщо RCM не
відстежує цю ініціалізацію (наприклад, її запущено з командного рядка вузла),
кроки беруться зі стану вузла, без відсотків. У RCM 2027.5.7 після
оновлення сторінки перебіг першої ініціалізації не видно: зачекайте, доки база даних master
залишить SEEDING.
Кроки ініціалізації в рядку master
Кожна команда RCM (ініціалізація, перезапуск Firebird, синхронізація
публікації) записується на сторінці Команди з результатом.
Сторінка «Команди»
Те саме з командного рядка
Command
# one databasehqbirdrcm reinit -node node-a -db <db_id> -to node-b
# all master databaseshqbirdrcm reinit -node node-a -all -to node-b
Параметри: -mode smooth|standard (типово smooth), -hold=false
(не утримувати архів під час довгих транзакцій), -allow-restart (5.6),
-force (5.9).
-remove-old-replica (з HQbird 2027.2.24) — те саме, що прапорець Видалити стару
репліку. Лише для однієї бази даних: -db і -to обов’язкові; з
-all команда відмовляється. Якщо вузол master або replica старої версії, RCM
відмовляється з node_too_old і нічого не надсилає.
nbackup -N одразу після передавання: зміни з .delta повертаються в базу даних
5
SEEDING
на репліці: перевірка контрольної суми файлу, nbackup -FIXUP -SEQUENCE, встановлення файлу, gfix -replica, запис блоку в replication.conf
6
RESTARTING REPLICA
перезапуск Firebird репліки, якщо він потрібен (5.6)
Після кроку 6 база даних отримує стан IN_SYNC. Master продовжує надсилати
сегменти від точки, де закінчується копія.
Що важливо знати:
Master працює весь час. Користувачі пишуть у базу даних, зміни йдуть у
.delta. Блокування знімається одразу після передавання.
Транзакції, що збіглися з блокуванням, не губляться. Вузол знаходить
транзакції, відкриті в момент nbackup -L, і репліка відтворює їх із
сегментів.
Передавання триває після переривання. Якщо з’єднання або вузол replica
перезапустився, master продовжить з останньої отриманої частини. Незавершене
передавання зберігається на репліці 24 години (reinit_partial_keep_hours).
У разі помилки вузол знімає блокування, видаляє незавершений файл на
репліці і ставить базу даних у FAILED. Наступна спроба починається з відомого
стану.
З прапорцем «Видалити стару репліку» (від HQbird 2027.2.24) репліка
видаляє стару копію після кроку LOCKING, перед передаванням. Крок COPYING TO
NODE у цей час показує «видалення старої копії репліки, щоб звільнити місце». Помилка після видалення дає парі NEEDS_REINIT, а не FAILED
(розділ 4.4).
Лише nbackup. gbak не використовується: він змінює GUID бази даних.
5.3. Вплив на роботу
Що
Вплив
Користувачі master
продовжують працювати; під час копіювання .delta росте, після -N зміни переносяться в базу даних
Інші репліки цієї бази даних
не отримують сегменти цієї бази даних, поки триває ініціалізація; потім наздоганяють
Інші бази даних master
не зачіпаються
Firebird репліки, нова база даних
не зупиняється; перезапуск за 5.6
Firebird репліки, повторна ініціалізація
зупиняється, поки файл замінюється: усі бази даних цього Firebird недоступні кілька секунд
зупиняється раніше, поки триває видалення, перед передаванням. Вузол установлює нову копію без другої зупинки, якщо блок бази даних у replication.conf не змінився. Якщо місця достатньо і видалення не потрібне, вузол нічого не видаляє, і все йде як при звичайній повторній ініціалізації
Мережа і диск
навантаження за лімітами швидкості (5.5)
У Windows. Файл, відкритий Firebird, не можна замінити. Під час повторної
ініціалізації вузол зупиняє Firebird репліки через fbagent, установлює
файл і знову запускає Firebird. У Linux Firebird також зупиняється перед
заміною: інакше він продовжив би працювати зі старим видаленим файлом.
5.4. Плавний і стандартний методи
Плавний (типово). Перед блокуванням вузол шукає довгі транзакції: транзакції запису користувача, що почалися до найстарішого сегмента в архіві master. Після ініціалізації репліка не зможе їх відтворити і зупиниться на їхній першій зміні («Транзакцію … не знайдено»). Транзакції без змін не рахуються.
Якщо такі транзакції є, ініціалізація не починається: RCM показує Плавна повторна ініціалізація чекає на довгі транзакції і дає посилання Відкрити список.
Сторінка Довгі транзакції: довгих транзакцій немає
На сторінці Довгі транзакції:
підсумок: скільки транзакцій і з’єднань, найстаріший сегмент;
Утримувати сегменти / Зняти утримання — поки утримання ввімкнене, архів master не чиститься і історія не обрізається;
Від’єднати вибрані і повторити reinit — від’єднує з’єднання (їхні транзакції відкочуються) і одразу починає плавний reinit;
Повторити reinit, Перевірити знову.
Утримання вмикається автоматично, коли reinit відхилено через довгі транзакції. Воно знімається після успішної ініціалізації, вручну або коли архів зростає до reinit_hold_max_segments (типово 1000 сегментів, сповіщення retention_hold_released).
Стандартний блокує базу даних одразу, без перевірки. Використовуйте його лише якщо знаєте, що довгих транзакцій запису немає.
Перша ініціалізація під навантаженням. Поки архів master порожній, немає сегмента для порівняння.
З вузлом master HQbird 2027.2.24: якщо вузол сам увімкнув публікацію і архів відтоді не змінився, історія починається в момент увімкнення публікації. Транзакція, що почалася пізніше, входить у журнал зі своєї першої зміни і не заважає плавному методу. Транзакція, що почалася раніше, у журнал не ввійшла: reinit чекає на неї перед блокуванням (6 спроб кожні 10 с), і крок locking показує її номер, з’єднання і користувача. Якщо вона не завершилася, reinit закінчується помилкою reinit_pre_publication_transactions: завершіть її і спробуйте знову. Сторінка Довгі транзакції показує такі транзакції в таблиці Транзакції, початі до ввімкнення публікації.
Якщо публікацію ввімкнули вручну, не через вузол, або архів уже змінився, початок історії невідомий. Тоді плавний метод відмовляється, якщо відкрита будь-яка транзакція запису, і повідомлення каже, що архів ще не містить сегмента. У цьому випадку RCM 2027.2.24 не відкриває список, а пише, що робити, у комірці бази даних. Оберіть Стандартний або спробуйте знову, щойно Firebird заархівує перший сегмент.
З вузлом master 2027.5.7 плавний метод відмовляється одразу під час першої ініціалізації бази даних, у яку зараз пишуть: long_transactions … segment 0 (0001-01-01T00:00:00Z). Для першої ініціалізації такої бази даних оберіть Стандартний.
Для наступних повторних ініціалізацій плавний метод працює як звичайно (архів уже існує).
Транзакції, старші за публікацію. Firebird не записує в сегменти транзакцію, що почалася до ввімкнення публікації. Якщо вузол увімкнув публікацію, ініціалізація чекає (6 спроб кожні 10 секунд), доки такі транзакції завершаться; інакше вона закінчується помилкою reinit_pre_publication_transactions з їхнім переліком. Після синхронізації публікації, що додала таблиці, перепідключіть застосунки, а потім почніть ініціалізацію.
5.5. Швидкість
Коли
Швидкість
Параметр
У вікні передавання windows.transfer_window (типово 23:00-05:00)
стала
limits.reinit_window_mbps, типово 100 МБ/с
Поза вікном
частка виміряної швидкості диска
limits.reinit_day_disk_fraction, типово 0.5
Вузол перераховує режим кожні 30 секунд: ініціалізація, почата вдень, сама прискориться вночі.
Вузол вимірює швидкість диска тестом. Щоб повторити тест на хості master:
Час ініціалізації ≈ розмір бази даних ÷ швидкість. Приклад: 100 ГБ при 100 МБ/с — близько 17 хвилин чистого передавання; на практиці це обмежує мережа або диск.
5.6. Перезапуск Firebird репліки
Нова база даних на репліці. Файл кладеться без зупинки Firebird. Firebird
прочитає новий блок replication.conf лише після перезапуску. Доти
репліка нічого не застосовує. Крок RESTARTING REPLICA показує очікування:
Мітка
Що вона означає
очікування перезапуску Firebird на репліці, його заплановано на …
вузол сам перезапустить Firebird після останньої ініціалізації (reinit_restart_delay_sec), щойно інші ініціалізації завершаться
… вікно перезапуску закрите, наступне відкриється о …
очікування restart_window репліки
… остання спроба не вдалася, наступна о …
спробує пізніше
репліка не може сама перезапустити Firebird: перезапустіть вручну
auto_restart: never, або цей Firebird також обслуговує бази даних master
Вузол перезапускає Firebird один раз після серії ініціалізацій, а не після
кожної бази даних.
Щоб перезапустити вручну, натисніть Перезапустити Firebird репліки.
Очікування закінчується після будь-якого успішного перезапуску Firebird або коли
репліка застосувала сегмент, новіший за копію.
Повторна ініціалізація на Firebird, який також обслуговує бази даних master.
Вузол не зупиняє такий Firebird сам і відмовляється з
restart_not_allowed. Почніть ініціалізацію знову і позначте Дозволити
зупинити Firebird для цього reinit (-allow-restart у командному рядку)
— у час, коли з’єднання цього Firebird можна розірвати, зокрема
з його базами даних master. Такі ініціалізації запускайте по одній на хост.
Видалення старої копії (прапорець Видалити стару репліку, з HQbird
2027.2.24) також зупиняє Firebird репліки, за тими самими правилами. Якщо
вузол не може сам зупинити цей Firebird, він нічого не видаляє і
відмовляється з restart_not_allowed: позначте також Дозволити
зупинити Firebird для цього reinit. Якщо в цей час інша ініціалізація
завершується на репліці або Firebird перезапускається, вузол нічого
не видаляє і відмовляється з engine_busy: master знімає блокування,
спробуйте пізніше.
5.7. Черга і одночасні ініціалізації
Одна база даних — одна ініціалізація за раз (навіть для різних реплік). Кнопка Ініціалізувати вимкнена, поки триває ініціалізація цієї бази даних.
Вузол master дотримується limits.max_concurrent_reinits одночасних ініціалізацій різних баз даних (типово 1). Решта чекає в черзі; відповідь містить позицію в черзі.
Не запускайте власний nbackup -L (або ALTER DATABASE BEGIN BACKUP) на базі даних під час її ініціалізації і не починайте ініціалізацію під час такого резервного копіювання: база даних може мати лише одне блокування. Ініціалізація це перевіряє і відмовляється з nbackup backup lock already active.
Черга і поточні передавання видно на сторінці Передавання.
Сторінка Передавання / черги
- Якщо після збою лишається файл `.delta`, переконайтеся, що резервне копіювання не триває, і виконайте `nbackup -N `. Не видаляйте `.delta` вручну.
5.8. Автоматична повторна ініціалізація
RCM може сам повторно ініціалізувати базу даних у стані NEEDS_REINIT, лише в
налаштованому вікні. Типово вимкнено.
Коли база даних входить у NEEDS_REINIT:
Причина
Де це видно
повторювана невиправна помилка застосування (порушення PK, UNIQUE, FK) — 3 рази поспіль
Вікно: на базу даних → на вузол → глобально. "always" — у будь-який час.
Вікна обчислюються за годинником хоста RCM.
max_concurrent — скільки ініціалізацій (ручних і автоматичних) може
тривати в кластері, перш ніж RCM запустить ще одну автоматичну.
Автоматична ініціалізація проходить ті самі перевірки місця і GUID, що й
ручна ініціалізація. Автор команди — system:autoreinit.
remove_old_replica_when_short (від HQbird 2027.2.24, рядок Видалити
стару репліку, коли бракує місця) — типово вимкнено. Якщо
увімкнено, автоматична ініціалізація надсилає прапорець Видалити стару
репліку (4.4). RCM надсилає його лише якщо сама репліка в
NEEDS_REINIT або причина NEEDS_REINIT master її називає. Для
репліки в стані IN_SYNC або LAGGING прапорець ніколи не надсилається. Якщо вузол
старішої версії, RCM запускає ту саму ініціалізацію без прапорця.
Після зміни перезапустіть RCM.
Відкласти в картці master вимикає автоматичну
ініціалізацію однієї бази даних на 1 годину, 4 години, 24 години або до скасування. Ручна
ініціалізація лишається доступною.
5.9. Помилки
Помилка
Причина
Що робити
insufficient disk space on master / on replica, 507
замало місця. Під час повторної ініціалізації стара копія займає місце до кінця
розділ 4.4; на репліці (від HQbird 2027.2.24) — прапорець Видалити стару репліку (5.1)
node_too_old (від HQbird 2027.2.24)
прапорець Видалити стару репліку позначено, але вузол master або replica старої версії
оновіть вузол так, як сказано в тексті помилки, або запустіть без прапорця
engine_busy, reclaim_in_progress (від HQbird 2027.2.24)
репліка не може зараз видалити стару копію: Firebird або ця база даних зайняті
спробуйте пізніше (5.6)
replica_removed_for_reinit, пара NEEDS_REINIT (від HQbird 2027.2.24)
репліка видалила стару копію, але ініціалізація не завершилася
почніть ініціалізацію знову (4.4)
publication_off (від HQbird 2027.2.24)
публікацію master вимкнено або вона не містить таблиць із ключем
Синхронізувати публікацію й ініціалізувати (5.1)
long_transactions, «Плавний reinit чекає на довгі транзакції»
відкриті довгі транзакції запису
5.4
long_transactions, «архів master ще не містить жодного сегмента»
перша ініціалізація під навантаженням
Стандартний (5.4)
reinit_pre_publication_transactions
транзакції, початі до ввімкнення публікації
перепідключіть застосунки, спробуйте знову
duplicate_guid
дві бази даних master з однаковим GUID
видаліть копію; якщо під час підвищення до master пропущено крок NEW GUID — -force (розділ 8.4)
license_paused
у fbagent master немає ліцензії
розділ 2.8
409 orphaned
база даних поза скануванням master
розділ 3.8
incompatible_engine
різні основні версії Firebird
розділ 4.3
target_not_replica
на місці репліки стоїть робоча база даних (її зроблено звичайною)
див. нижче
target_other_replica (від HQbird 2027.2.24)
на місці репліки стоїть копія іншої бази даних цього вузла
див. нижче
restart_not_allowed
Firebird репліки також обслуговує бази даних master
5.6, прапорець «Дозволити … зупинити Firebird»
fbagent_required
fbagent не встановлено на репліці
розділ 1
nbackup backup lock already active
триває резервне копіювання nbackup
5.7
… -L did not finish in 2m0s and was stopped
nbackup -L на master не завершився за 2 хвилини, тому вузол його зупинив
спробуйте знову; якщо помилка повторюється, перевірте Firebird master (firebird.log)
reinit already in progress for this database
ініціалізація цієї бази даних уже триває
зачекайте, доки вона завершиться
target_not_replica. На місці копії стоїть робоча база даних: її зроблено
звичайною (існує файл <database>.hqcluster-normal.json) або вона не в
режимі replica. Вузол не перезаписує робочу базу даних. Якщо її треба замінити, запит до API вузла з
overwrite_non_replica: true (кнопки для цього в RCM немає) замінить файл і збереже старий як
<database>.pre-reinit-<час UTC>.fdb.
target_other_replica (від HQbird 2027.2.24). Репліка кладе копію в
<databases.root>/<id master>/<шлях бази даних>. Id master унікальний лише в
його власному кластері, тож дві бази даних можуть опинитися на одному шляху. Вузол replica
не перезаписує копію, що належить іншій з його баз даних: помилка називає ту базу даних і її
master. Вузол також розпізнає копію, шлях якої записано інакше (символічне посилання або
junction у шляху, коротке ім’я теки Windows). overwrite_non_replica не знімає цю помилку. Перемістіть одну з
копій в іншу теку або видаліть ту базу даних з репліки, а потім почніть
ініціалізацію знову. Вузол бачить лише власні бази даних: два вузли replica на
одному хості повинні мати різні теки репліки (databases.root).
5.10. Як перевірити результат
Бази даних: пара master — replica в групі є Ok, стан
IN_SYNC.
Перевірити в картці master: вузли рахують рядки таблиць зі
списку таблиць бази даних (розділ 3.1) на master і на репліці та порівнюють їх.
Перевіряйте в спокійний час: за активного запису числа можуть відрізнятися.
У HQbird 2027.2.24 сторінка результату називає список кожного боку
(наприклад, «власний список цієї бази даних» або «таблиці публікації
(список не задано)»). RCM рахує репліку за списком master. Таблиця,
якої немає в обох базах даних, показана як «немає в базі даних» і не рахується як
помилка. Якщо не порівняно жодної таблиці, результат — «Немає таблиць для
порівняння», а не розбіжність. Якщо порівняння не завершилося у відведений час,
результат — «Не порівняно (ліміт часу)», і це теж не розбіжність.
Періодична перевірка (необов’язково): сторінка Перевірка даних,
Увімкнути для всіх вузлів. У HQbird 2027.2.24 вузол застосовує
параметри одразу, перезапуск служби вузла не потрібен: після Зберегти RCM
пише «Збережено і вже діє». Вузлу 2027.5.7 потрібен перезапуск
служби hqclusternode, і RCM 2027.2.24 про це каже.
Вузли самі порівнюють кількість рядків, коли master і репліка на одному
сегменті. Розбіжність піднімає сповіщення data_mismatch; потім виконайте
Перевірити.
Таблиця, яку оператор видалив із публікації, показана як «не
опублікована», а не як розбіжність.
6. Налаштування публікації
Публікація каже Firebird master, зміни яких таблиць записувати в сегменти.
Без неї репліка нічого не отримує.
6.1. Що таке публікація
У Firebird 4 і 5 таблиці для реплікації визначає публікація RDB$DEFAULT:
Публікацію ввімкнено — у RDB$PUBLICATIONS вона має RDB$ACTIVE_FLAG = 1
(команда ALTER DATABASE ENABLE PUBLICATION).
Опубліковані таблиці — список у RDB$PUBLICATION_TABLES.
Firebird записує зміни в сегменти лише для опублікованих таблиць і лише
коли публікацію ввімкнено. Реєстрація бази даних (розділ 3) не
вмикає публікацію. Її вмикає Синхронізувати публікацію (6.2).
Вузол master перевіряє публікацію щогодини
(limits.publication_check_interval_sec, типово 3600). Якщо її
вимкнено, вузол перевіряє її кожні 2 хвилини.
На сторінці Бази даних база даних master має значок:
Значок
Значення
публікація УВІМК
публікацію ввімкнено
публікація ВИМК
Firebird нічого не записує в сегменти, репліки не отримують змін
публікація невідома
вузол не зміг прочитати стан
Фільтр Публікацію вимкнено показує бази даних із вимкненою або невідомою
публікацією.
Якщо база даних із вимкненою публікацією вже має репліку, master піднімає
сповіщення master_publication_off.
У HQbird 2027.2.24 master піднімає це сповіщення також тоді, коли відмовився
ініціалізувати базу даних з помилкою publication_off (розділ 5.1): публікацію
вимкнено або вона не містить таблиці з ключем. Рівень сповіщення:
попередження — база даних ще не має репліки: ініціалізація чекає на публікацію;
серйозно — база даних уже має репліку;
info — оператор вимкнув публікацію.
Сповіщення зникає, коли публікацію виправлено або почалася інша
ініціалізація.
6.2. Синхронізувати публікацію
Рядок master: публікацію вимкнено
Де натискати:
у рядку бази даних master на сторінці Бази даних. Коли публікацію
вимкнено, кнопка стоїть біля значка;
на сторінці бази даних;
для кількох баз даних: позначте рядки, у списку Дія оберіть
Синхронізувати публікацію. RCM надішле окрему команду для кожної
бази даних.
Підтвердження синхронізації публікації
Що робить вузол (одна транзакція):
Вмикає публікацію. Якщо оператор сам її вимкнув (6.4), він її не вмикає.
Додає до публікації всі таблиці з ключем, яких ще немає.
Видаляє з публікації таблиці без ключа і таблиці, які оператор
виключив (6.3).
Вимикає автоматичне додавання нових таблиць (EXCLUDE ALL FROM PUBLICATION, потім додає потрібні таблиці). Склад публікації визначає лише вузол.
Рядок master після синхронізації: публікацію ввімкнено
Таблиця з ключем — постійна таблиця користувача, що має
первинний ключ або активний унікальний індекс. Системні і тимчасові
таблиці не публікуються.
Синхронізація також видаляє з публікації таблиці без ключа, які DBA додав
вручну.
Якщо склад уже правильний, вузол нічого не змінює.
Коли вузол відмовляється:
Код
Причина
no_publications
HQbird 2.5/3.0 (6.6)
not_master
вузол не є master
reinit_in_progress
триває ініціалізація цієї бази даних
orphaned, database_failed, file_missing
база даних поза скануванням, у помилці або без файлу
Усі бази даних вузла одразу — лише з командного рядка. На сторінці Команди
результат показано для кожної бази даних: готово, пропущено або помилка.
Бази даних у стані FAILED або SEEDING і бази даних без файлу пропускаються.
Те саме з командного рядка
Command
hqbirdrcm setpublication -node node-a -db <db_id> # one databasehqbirdrcm setpublication -node node-a # all node databases
Команда чекає до 5 хвилин і друкує рядок для кожної бази даних. У разі помилки код
виходу — 1. -nowait — не чекати на результат.
6.3. Таблиці публікації
Сторінка «Таблиці публікації»
Відкрийте Таблиці публікації в рядку бази даних master.
Сторінка показує:
стан публікації (увімк/вимк, вимкнено оператором) і лічильники;
кожну таблицю: ім’я, ключ і стан.
Стан
Значення
опублікована
зміни йдуть у сегменти
ще не опублікована
таблиця з ключем, буде додана під час синхронізації
виключена
оператор прибрав її з публікації
немає ключа
не можна опублікувати
У стовпці ключа — первинний ключ або, якщо його немає, унікальний індекс із
найменшою кількістю полів.
Чому таблицю без ключа не можна опублікувати. Репліка шукає рядок для
UPDATE і DELETE за ключем. Без ключа вона рядок не знайде. Додайте
первинний ключ або унікальний індекс, а потім синхронізуйте публікацію.
Виключити з публікації / Повернути до публікації:
Позначте таблиці.
Натисніть Виключити з публікації або Повернути до публікації.
Вузол зберігає список і одразу синхронізує публікацію.
Підтвердження «Виключити з публікації»
Список виключених таблиць зберігається на вузлі master. Синхронізація його
не змінює. Коли репліку підвищують до master (розділ 8), список переходить до
нового master.
Перевірити (розділ 5.10) показує виключену таблицю як «не опублікована»,
а не як розбіжність.
6.4. Вмикання і вимикання публікації
На сторінці Таблиці публікації: Вимкнути публікацію /
Увімкнути публікацію.
Вимикання — вибір оператора. Синхронізація не
вмикає публікацію знову.
Зміни, зроблені, поки публікацію було вимкнено (або поки таблицю було
виключено) не надсилаються на репліку, навіть після повторного ввімкнення.
Після ввімкнення натисніть Перевірити (розділ 5.10). Якщо дані
розійшлися — повторно ініціалізуйте репліку (розділ 5).
6.5. Нова таблиця
Нова таблиця не потрапляє сама до публікації: вузол вимикає
автоматичне додавання.
Після DDL:
Створіть на таблиці первинний ключ або унікальний індекс.
Натисніть Синхронізувати публікацію.
Попросіть застосунки перепідключитися, якщо потрібна повторна ініціалізація. Firebird
не записує в сегменти транзакції, що почалися до ввімкнення публікації;
COMMIT RETAINING тримає таку транзакцію відкритою. Ініціалізація чекає на
такі транзакції, а потім завершується помилкою reinit_pre_publication_transactions
(розділ 5.4).
Нова таблиця в стані «ще не опублікована»
Рядки, записані в нову таблицю до синхронізації, до репліки не дійдуть.
Якщо такі є, перевірте дані і за потреби повторно ініціалізуйте репліку.
6.6. HQbird 2.5 і 3.0
HQbird 2.5 і 3.0 не мають публікацій. Firebird записує сегменти, якщо файл
плагіна replconf містить блок master. Кнопки публікації на таких вузлах приховані,
і API відповідає no_publications.
Набір таблиць визначають параметри рушія:
Параметр
Значення
include_filter
які таблиці реплікувати: імена або шаблони через кому; порожньо — усі
exclude_filter
які таблиці не реплікувати
Параметри змінюють у Параметри → Параметри реплікації (розділ 7.1). Сторінка
Таблиці публікації показує їх лише для читання, з посиланням Змінити
в параметрах рушія. Firebird читає нові значення після перезапуску.
Таблиці публікації в HQbird 3.0: фільтри рушія
Плагін replconf. Вузол записує власний файл replconf.hqcluster.hqbird у теці
Firebird. Firebird читає його лише коли replconf.properties на нього
вказує. Плагін треба активувати один раз:
Параметри → Вузли, блок Плагін реплікації (HQbird 2.5 / 3.0). Блок
показує, куди вказує replconf.properties, і проблеми, які вузол
знайшов.
Плагін не активовано: replconf.properties вказує на файл HQbird DataGuard
Активувати… Вікно перелічує, що зробить вузол: установить плагін,
спрямує replconf.properties на файл вузла, перенесе записи старого файлу.
Оберіть коли: Лише у вікні перезапуску вузла або Зараз, ігноруючи
вікно перезапуску.
Вікно активації плагіна
Після перезапуску Firebird поле Активовано показує «так: рушій
читає файл вузла».
Плагін активовано
Активація перезапускає Firebird і стосується усіх баз даних цього Firebird.
Виконайте її в спокійний період.
7. Інші параметри реплікації
7.1. Параметри реплікації
Параметри → Параметри реплікації, форма майстра
Сторінка Параметри → Параметри реплікації змінює ключі в
replication.conf для вибраних баз даних або для вузла в цілому.
Додати master і репліки — виберіть бази даних. RCM групує їх за
версією Firebird і роллю: окрема форма для master і для реплік.
Для кожного параметра оберіть дію:
Дія
Що вона робить
без змін
значення не змінюється
задати значення
нове значення
скинути (на наступний рівень)
прибрати власне значення, взяти значення з рівня вище
не записувати (значення Firebird)
ключ не записується, діє значення Firebird
Оберіть, куди застосувати: До вибраних баз даних або Як типове
для їхніх вузлів.
Попередній перегляд — вузли перевіряють значення, нічого не змінюючи.
Попередній перегляд змін
Застосувати. RCM надсилає команду кожному вузлу.
Звідки береться значення (стовпець Поточне):
Джерело
Значення
ця база даних
задано для бази даних
значення вузла
задано як типове для вузла
вбудоване значення вузла
значення вузла з коду
значення Firebird
ключ не записано
з файлу (тут ще не задано)
значення з replication.conf, RCM його ще не змінював
задано вузлом
лише для читання (шляхи, префікси)
Вузол, який не відповідає, показує свої бази даних як недоступні для вибору.
Зміни потребують fbagent (інакше fbagent_required).
Хто перезапускає Firebird (Firebird читає replication.conf лише під час
запуску):
Вузол
Хто
master
перезапускаєте ви: master ніколи не перезапускає Firebird сам
replica з firebird.auto_restart: never
ви
replica, чий Firebird також обслуговує бази даних master
ви
інші репліки
вузол перезапускає його у власному вікні перезапуску
Для ручного перезапуску на сторінці є кнопка Перезапустити Firebird.
7.2. Основні параметри
Master, Firebird 4/5:
Параметр
Підпис у RCM
Значення вузла
Firebird
Підказка
journal_archive_timeout
Час очікування архіву
10 с
60 с
скільки секунд Firebird чекає, перш ніж закрити незавершений сегмент. Менше — репліка ближче до master. Має бути менше за limits.data_check_quiet_sec (90)
journal_segment_count
Кількість сегментів
64
8
скільки сегментів може лежати в .ReplLog. Має бути більше за limits.backlog_critical (48)
journal_segment_size
Розмір сегмента
—
16 МБ
від 1 МБ до 512 МБ; приймач не візьме більше ніж 512 МБ
buffer_size
—
1 МБ
Вузол також записує log_errors = true (змінити не можна) і
disable_on_error = true.
Replica, Firebird 4/5:
Параметр
Підпис у RCM
Firebird
Значення
apply_idle_timeout
Пауза бездіяльності
10 с
пауза, коли немає нових сегментів
apply_error_timeout
Пауза після помилки застосування
60 с
пауза перед повтором після помилки
verbose_logging
node: true
докладний replication.log; вимикати не рекомендовано
skip_upddel_without_pk
node: true
пропускати UPDATE/DELETE на таблицях без ключа
Лише 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. Зберігання архіву
Архів <database>.LogArch на master чиститься поетапно:
Сегменти, застосовані всіма репліками і старші за
retention_days.
Якщо вільного місця менше за free_space_floor_gb — застосовані сегменти,
молодші за термін зберігання. Сповіщення disk_serious_cleanup.
Якщо місця все ще бракує — незастосовані сегменти, починаючи з найстаріших.
Репліка отримує NEEDS_REINIT, сповіщення
replication_paused_reinit_scheduled.
Параметр (Параметри → Вузли, Сховище і файли)
Типово
limits.retention_days — Зберігання архіву, дні
2
limits.retention_min_kept_segments — Завжди залишати останні сегменти
0 (вимкнено)
limits.free_space_floor_gb — Мінімальне вільне місце
1 ГБ
Параметри → Вузли, «Сховище і файли»
Очистити архів вручну:
Command
hqbirdrcm cleanuparchive -node node-a # stages for all databases on the nodehqbirdrcm cleanuparchive -node node-a -db <db_id> # a single database
-orphaned (лише разом із -db) видаляє усі сегменти бази даних у стані
ORPHANED (розділ 3.8). Для будь-якої іншої бази даних вузол відповість not_orphaned.
Ніколи не запускайте -orphaned на донорі підвищення (розділ 8.5).
7.4. Передавання: стиснення, швидкість, вікна
Стиснення задається для кожного партнера: Параметри → Вузли → Партнери, стовпець
compress.
Значення
Що означає
порожньо або none
без стиснення (типово)
zstd
стиснення zstd
Зміна діє одразу. Стиснення корисне в повільній мережі.
Швидкість передавання сегментів (Параметри → Вузли, Передавання і
повторна ініціалізація):
Параметр
Типово
Коли набуває чинності
limits.channel_a_mbps — Швидкість передавання сегментів
Підпис біля кожного поля показує, коли зміна набуває чинності: одразу або
перезапуск вузла.
Параметри → Вузли, «Часові вікна»
7.5. Перевірка даних
Перевірити — разове порівняння кількості рядків на master і на репліці
(розділ 5.10).
Перевірка даних — періодичне порівняння (розділ 5.10). Вузол виконує порівняння,
коли master і репліка на одному сегменті.
У HQbird 2027.2.24 параметри перевірки діють одразу після
Зберегти; перезапуск служби вузла не потрібен. RCM показує «Збережено і вже
діє». Після ввімкнення перша перевірка йде після одного інтервалу. Після
вимкнення перевірка, що триває, переривається і нічого не записує. Новий
інтервал рахується від кінця останньої перевірки. Зберігати, дні, Ліміт
запиту, Тиша і Генератор прогресу діють із наступної
перевірки.
Вузол 2027.5.7 читає ці параметри лише під час запуску: після
Зберегти перезапустіть службу hqclusternode на цьому вузлі. RCM
2027.2.24 показує «Збережено, але ще не діє» і називає причину.
Які таблиці порівнювати, визначає список таблиць бази даних (розділ 3.1). У HQbird
2027.2.24 кожна база даних може мати власний список: поле під час реєстрації або блок
Таблиці відстеження синхронізації на сторінці бази даних master
(розділ 3.3). Сторінка Перевірка даних показує, який список
використано, і кількість таблиць «немає в базі даних». У 2027.5.7 список на вузол
(sync_tables).
Таблиці, виключені з публікації, показані як «не опублікована»
(розділ 6.3).
Сторінка перевірки даних
7.6. Сповіщення
Сторінка сповіщень
Сторінка Сповіщення. Дії:
Підтвердити — сповіщення лишається видимим, але позначене як підтверджене;
Вимкнути звук на 60 хв — сховати на годину;
Видалити / Видалити всі з цим кодом — RCM передає видалення вузлу,
який підняв сповіщення. Якщо причина лишається, сповіщення з’явиться знову.
Command
hqbirdrcm clearalerts -code backlog_warn # also -id, -acked, -all
Від HQbird 2027.2.33 RCM надсилає сповіщення в Telegram, на webhook (Slack,
Teams, JSON) і електронною поштою. Канали налаштовують у секції notify.channels
файлу rcm.json. Блок Канали сповіщень на сторінці
Сповіщення показує канали і надсилає тестове повідомлення. RCM повідомляє
про проблеми рівня warn і вище: проблема з’явилася, стала серйознішою
або зникла. Без каналів RCM нічого не надсилає. Раніші
версії не надсилають: стежте за сторінкою Сповіщення або опитуйте API RCM.
від HQbird 2027.2.30: Firebird хвилину не відповідав на з’єднання з базою даних (зависання). Сюди входить і з’єднання, яке не встановилося через тайм-аут; firebird_down — лише відмова в з’єднанні
master_publication_off
публікацію вимкнено (розділ 6); від HQbird 2027.2.24 і після помилки publication_off (розділ 6.1)
replica_removed_for_reinit
від HQbird 2027.2.24: репліка видалила стару копію для ініціалізації, і нової копії ще немає (розділ 4.4)
orphaned_database
база даних поза скануванням (розділ 3.8)
restart_required_after_reinit
Firebird репліки потребує перезапуску (розділ 5.6)
data_mismatch
періодична перевірка знайшла розбіжність
license_paused
у fbagent немає ліцензії (розділ 2.8)
7.7. Призупинення надсилання
На сторінці Бази даних, у рядку master: Призупинити надсилання /
Відновити надсилання. Для кількох баз даних — через список Дія.
Підтвердження призупинення надсиланняРядок master під час паузи
Пауза діє до Відновити надсилання або до ініціалізації.
Firebird master продовжує писати сегменти. Архів .LogArch росте: поки
репліку зупинено, етап 1 (7.3) не видаляє її сегменти.
Довга пауза може дійти до етапу 3 і NEEDS_REINIT. Стежте за місцем.
Кнопки немає, якщо база даних не має репліки або публікацію вимкнено. Значок
Пауза: немає ліцензії означає паузу через ліцензію (розділ 2.8); вона зникає
лише завдяки ліцензії.
7.8. Журнали
Журнал
Де
Вузол
<тека встановлення>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode або C:\hqclusternode), по 32 МБ, 20 файлів
Firebird replication.log, firebird.log
шляхи в node.json: firebird.replication_log, firebird.firebird_log
RCM
Linux: journalctl -u hqbirdrcm
Аудит RCM
rcm-data/audit.jsonl
Віддалений журнал вузла — сторінка Журнали: виберіть вузол і джерело
(replication.log, firebird.log, агент вузла).
потрібна окрема робоча копія: звіти, тести, збій без нового master
звичайна база даних поза реплікацією
Підвищити до master, 8.3
репліка має стати новим master
база даних, якою керує супутній вузол із роллю master
Жоден шлях не можна скасувати через інтерфейс.
8.1. Зробити звичайною
Список «Дія» репліки: пункт «Зробити звичайною»
Бази даних, бік репліки: позначте рядки репліки.
У списку Дія оберіть Зробити звичайною і підтвердьте.
Окремої кнопки в рядку немає. Команди командного рядка теж немає.
Підтвердження «Зробити звичайною»
3. Вузол replica:
- виконує `gfix -replica none` (HQbird 2.5/3.0: `gfix -replica {}`). Якщо
база даних зайнята застосуванням сегментів, вузол на кілька секунд переводить її в
зупинку `single` (`gfix -shut single -force 0`), знімає режим replica і
повертає її через `gfix -online normal`. **Усі з'єднання з цією базою даних
розриваються**;
- записує файл-маркер `.hqcluster-normal.json` (час, автор, db_id,
GUID);
- починає очищати чергу `.Incoming` (8.2).
4. RCM показує базу даних у групі **Не репліка (звичайна)**.
Сторінка «Бази даних» після «Зробити звичайною»
Після цього база даних відкрита для запису.
Приберіть блок репліки з replication.conf. Вузол видаляє його під час наступного
сканування, а Firebird читає файл під час запуску:
Доти помилки «база даних не в режимі replica» для цієї бази даних не
піднімаються як сповіщення.
Файл-маркер захищає базу даних. Ініціалізація не перезапише таку базу даних:
її відхилять з target_not_replica (розділ 5.9). Видалити лише маркер недостатньо:
вузол також перевіряє режим replica в заголовку бази даних. Прапорець Видалити стару
репліку (розділ 4.4) таку базу даних теж не видаляє.
У HQbird 2027.2.24, поки репліка видаляє стару копію цієї бази даних для
ініціалізації, Зробити звичайною відхиляється з reclaim_in_progress:
спробуйте пізніше.
Якщо база даних знову має стати реплікою — вистачить лише нової ініціалізації з
перезаписом. Це робиться через API вузла (overwrite_non_replica: true); такої кнопки в
RCM немає. Старий файл зберігається як
<database>.pre-reinit-<час UTC>.fdb, а маркер видаляється.
8.2. Що відбувається із сегментами
Поки вузол не просканував бази даних, master продовжує надсилати сегменти. Кожні 30 секунд вузол replica видаляє старі сегменти і залишає лише останні 100 (keep_segments).
Після сканування запис бази даних на репліці отримує стан ORPHANED. Вузол replica відповідає master unknown_database. Master припиняє надсилати сегменти цій репліці, припиняє тримати для неї архів і перевіряє її знову кожні 10 хвилин.
Інші репліки цієї бази даних не зачіпаються.
Запис ORPHANED можна видалити (розділ 3.8): hqbirdrcm forgetdatabase. Сам файл бази даних не видаляється.
8.3. Підвищити до master
Репліка стає новим master. Її файл лишається на місці, а керування
переходить до супутнього вузла.
Умови:
Умова
Відмова
база даних є реплікою
bad_request
на тому самому хості працює вузол із роллю master — супутній — (та сама мітка host у rcm.json, розділ 2.1)
no_companion
підвищення цієї бази даних ще не триває
already_running
немає ініціалізації в цю базу даних або з її master
reinit_running
RCM не створює супутній вузол: установіть його наперед (розділ 1).
Як почати:
у рядку репліки, Підвищити до master, або в списку Дія;
RCM попросить підтвердження і назве супутній вузол.
Підтвердження «Підвищити до master?»
Кроки (видно в рядку репліки, назви англійською):
№
Крок
Що він робить
1
TURN TO NORMAL
як у 8.1; пропускається, якщо база даних уже звичайна
2
NEW GUID
новий GUID бази даних на місці (8.4)
3
EXCLUDE ON DONOR
вузол replica (донор) виключає файл зі свого сканування (exclude_paths)
4
ENROLL ON
супутній вузол реєструє файл як базу даних master
5
PUBLICATION SYNC
синхронізація публікації; список виключених таблиць переноситься зі старого master (розділ 6.3)
6
RESTART DONOR FIREBIRD
перезапуск Firebird донора, без очікування вікна
7
RESTART FIREBIRD
перезапуск Firebird супутнього вузла, без очікування вікна
8
FINALIZE
рядок донора стає Реплікою-привидом; старий master може стати Master деградованим (8.5)
Кроки підвищення в рядку репліки
У HQbird 2.5 і 3.0 публікацій немає: крок PUBLICATION SYNC
завершується текстом «цей рушій не має публікації».
Кроки підвищення в HQbird 3.0 (Windows)
Якщо донор і супутній вузол використовують той самий Firebird, цей Firebird
перезапускається: з’єднання з усіма його базами даних розриваються.
Якщо крок не вдається, завдання отримує failed з текстом помилки. Усуньте
причину і натисніть Підвищити до master знову: завершені кроки не
повторюються. Якщо RCM перезапуститься під час підвищення, завдання теж стане
failed — перевірте стан вузлів і спробуйте знову.
Ліцензія. Якщо у fbagent на хості master немає ліцензії, master
призупинив надсилання. Підвищення все одно можливе. RCM попередить:
зміни, зроблені після початку паузи, буде втрачено.
8.4. Новий GUID
Після підвищення база даних повинна отримати власний GUID. Інакше новий master пише
сегменти під GUID старого master, і його репліки відхиляються з
duplicate_guid.
Крок NEW GUID на вузлі:
gfix -shut single -force 0 — усі з’єднання з базою даних завершуються;
nbackup -L, потім nbackup -F без -SEQUENCE;
видаляє <database>.delta;
перевіряє заголовок: новий GUID, REPLICATION_SEQUENCE = 0;
gfix -online normal.
Firebird не перезапускається. Метод працює на всіх версіях (2.5, 3.0, 4.0,
5.0).
Якщо крок перервано, вузол піднімає сповіщення newguid_interrupted. База даних може
лишитися в зупинці single. Повторіть Підвищити до master: крок
продовжиться.
Крок пропускається (текст починається з skipped:), якщо вузол донора старої
версії або файл уже має власний GUID.
Після нового GUID старий ланцюг nbackup більше не годиться. Зробіть нову копію nbackup рівня 0.
Якщо базу даних створено з ADD DIFFERENCE FILE, її .delta лежить в іншому
місці: видаліть її вручну.
8.5. Після підвищення
Запис донора. На вузлі replica база даних лишається ORPHANED, шлях лишається в
exclude_paths, а тека .Incoming і мітка лишаються. У RCM це рядок
Репліка-привид із кнопками Відкрити на новому master і Очистити.
Рядок донора: «Репліка-привид»
Щоб прибрати рядок, натисніть Очистити. Це змінює лише RCM.
Щоб прибрати запис донора з вузла replica, виконайте forgetdatabase.
Файл і тека .Incoming лишаються. HQbird 2027.2.30 і новіший не
відхиляє команду (mailbox_active), бо шлях донора є в
exclude_paths. Вузли раніших версій відхиляють її, поки є файл і
тека .Incoming.
Ніколи не запускайте cleanuparchive -orphaned на донорі. Донор і
супутній вузол ділять ту саму теку <database>.LogArch. Команда видалить живий
архів нового master.
Старий master.
Якщо донор був його останньою робочою реплікою, RCM ставить старий
master у Master деградований і призупиняє надсилання донору
(«надсилання призупинено: … (підвищення до master)»). Не відновлюйте
надсилання донору: там уже є робоча база даних. Щоб зняти цей стан,
ініціалізуйте базу даних на іншу репліку.
Старий master: «Master деградований», надсилання призупинено
Ініціалізацію зі старого master на вузол донора буде відхилено
(target_not_replica): там уже є робоча база даних.
Якщо крок NEW GUID пропущено, старий і новий master мають той самий GUID.
Тоді ініціалізація зі старого master потребує -force (розділ 5.9).
Після ручного підвищення RCM не перетворює старий master на репліку нового
master. Зупиніть застосунки на старому master і приберіть його базу даних з
керування (розділ 3.8). Для бази даних, описаної як сервіс, це робить Повторне приєднання
(8.7).
Новий master. Підготуйте для нього репліку: вузол replica, партнери (розділ 2),
публікація (розділ 6), ініціалізація (розділ 5).
Новий master: база даних із новим GUID, репліки ще немає
8.6. Планове перемикання: перелік
Це процедура ручного перемикання. Для бази даних, описаної як сервіс, RCM сам перемикає master (8.7). Ручне підвищення не перевіряє, чи застосунки пишуть у старий master. Процедура:
Заздалегідь. На хості репліки працює супутній вузол із роллю master, і обидва вузли мають ту саму мітку host (розділ 2.1). Вузол майбутньої репліки готовий для нового master.
Зупиніть запис застосунків у базу даних старого master.
Зачекайте, доки репліка отримає і застосує все: Бази даних → IN_SYNC, без черги.
Перевірити (розділ 5.10): кількості рядків збігаються.
Підвищити до master (8.3). Зачекайте на крок FINALIZE.
Перевірте: база даних є в списку master супутнього вузла, публікацію ввімкнено.
Перемкніть застосунки на новий master.
Зробіть копію nbackup рівня 0 нової бази даних (8.4).
Очистіть запис привида для рядка донора (8.5).
Підключіть репліку до нового master і ініціалізуйте її (розділ 5).
Старий master: приберіть базу даних з керування або лишіть її як архів (8.5).
8.7. Сервіси: перемикання і аварійне перемикання в RCM
У HQbird 2027.2.30 RCM сам переносить master на інший хост. Для цього базу даних описують як сервіс: одна логічна база даних на кількох хостах. На кожному хості сервісу є вузол master і вузол replica, і шлях до файлу бази даних однаковий. Сервіс створюють на сторінці Сервіси (від HQbird 2027.2.31) або командою hqbirdrcm services put -id <id> -file <file>.json.
Дія
Що вона робить
Команди
Перемикання
планове перенесення master без втрати даних. Потім старий master автоматично стає реплікою нового master
після аварійного перемикання повертає старий хост як репліку нового master
hqbirdrcm rejoin -service <id>
Відновити
виводить сервіс зі стану failed
hqbirdrcm resume -service <id> -check, потім hqbirdrcm resume -service <id>
Ті самі дії є на сторінці сервісу: кнопки Перемикання…, Аварійне перемикання…, Повторне приєднання… і Відновити….
Автоматичне аварійне перемикання типово вимкнене. Його вмикають для кожного сервісу окремо:
hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30.
Потрібні маршрутизатори. RCM починає аварійне перемикання лише коли вузол master мовчить, більшість маршрутизаторів не бачить Firebird master, і відставання репліки не більше за max_data_loss_sec.
Маршрутизатор (hqclusternode router, Linux) тримає HAProxy на поточному master сервісу. Застосунки з’єднуються з <router host>:<router_port> і не змінюють рядок з’єднання під час перемикання.
Після аварійного перемикання RCM ставить старий master у роль fenced, щойно той знову відповідає. Поверніть його командою rejoin.
Цей сайт використовує файли cookie для покращення вашого досвіду та збереження вподобань.