Este guia descreve como instalar e usar o cluster de replicação HQbird:
os nós hqclusternode e o gerenciador de cluster hqbirdrcm (RCM).
Este é um guia para o administrador do Firebird. Partimos do princípio de que você conhece o Firebird,
o gfix e o nbackup. Você não precisa conhecer o funcionamento interno de um nó.
Do que o cluster é feito
Componente
Quantos
Onde executa
O que faz
Firebird (HQbird)
uma ou mais instâncias
em cada servidor de bancos
armazena os bancos, grava os segmentos de replicação
fbagent
um por instância do Firebird
ao lado do Firebird
para e inicia o Firebird a pedido de um nó
hqclusternode (nó)
um por instância e papel
ao lado do Firebird
configura a replicação, transfere segmentos, faz a inicialização da réplica
hqbirdrcm (RCM)
um por cluster
em qualquer host que enxergue todos os nós
interface web, comandos, alertas, estatísticas
Um nó tem um papel: master ou replica. Dois nós podem executar em uma única
instância do Firebird: um nó mestre e um nó réplica.
Nesse caso, alguns bancos desse Firebird são mestres e outros são réplicas.
Como funciona
No mestre, o Firebird grava as alterações do banco em segmentos (arquivos de
log de replicação).
O nó mestre envia os segmentos ao nó réplica por um canal protegido (mTLS).
O nó réplica coloca os segmentos na pasta de segmentos de entrada. O Firebird da réplica
os aplica à sua cópia do banco.
O próprio nó mestre transfere a primeira cópia do banco para a réplica. Isso se chama
inicialização (reinit). Ela passa pelo nbackup, e o mestre continua
em execução durante esse tempo.
Os nós enviam estatísticas ao RCM. O RCM mostra o estado do cluster e
envia comandos do operador aos nós.
Como o cluster funciona: segmentos, inicialização, estatísticas e comandos do operador
Versões compatíveis
Firebird / HQbird 5.0 e 4.0 — todos os recursos.
HQbird 3.0 e 2.5 — replicação pelo plugin replconf. Não há publicações;
o conjunto de tabelas é definido por filtros. As diferenças estão descritas nas caixas “HQbird 2.5/3.0”.
A versão principal do Firebird no mestre e na réplica precisa ser a mesma. Caso contrário, o nó
réplica recusa a inicialização.
Portas
Porta
Quem escuta
Quem se conecta
Para quê
7051
nó
outros nós e o RCM
API do nó, transferência de segmentos e de cópias de bancos
7443
RCM
todos os nós
recepção de estatísticas dos nós
7444
RCM
operador
interface web e API do operador. Instalação pelo RCM (capítulo 1.3): HTTPS em todos os endereços. Instalação pelo HQCenter Admin ou manual: HTTP, somente 127.0.0.1
7450–7459
fbagent, enquanto a janela de vinculação está aberta
RCM
vinculação de hosts (capítulo 1.3)
13050
fbagent, somente 127.0.0.1
nó no mesmo host
gestão do Firebird
3050
Firebird
aplicações
operação normal do banco
Se houver dois nós em um host (mestre e réplica), o segundo nó tem outra porta.
Na instalação pelo RCM, o segundo nó recebe a porta 7061. Nos outros casos
você define a porta, por exemplo 7052.
A porta 13050 não deve ficar exposta na rede. A porta 7444 com HTTP (instalação pelo
HQCenter Admin ou manual) também não: conecte-se à interface web do RCM
por um túnel SSH (capítulo 1). Na instalação pelo RCM, a porta 7444 funciona em
HTTPS, e o instalador a abre no firewall.
A regra principal: sem fbagent, sem alterações
Um nó altera a configuração de replicação somente pelo fbagent: ele precisa
reiniciar o Firebird. Se o fbagent não estiver disponível, o nó recusa qualquer ação
que altere a configuração. Ele não trabalha “pela metade”.
Termos
Termo
Significado
Segmento
um arquivo de log de replicação com as alterações do banco
Publicação
a lista de tabelas do mestre cujas alterações entram nos segmentos (Firebird 4/5)
Inicialização (reinit)
transferência de uma cópia do banco do mestre para a réplica pelo nbackup
GUID do banco
o identificador do banco no Firebird; o RCM o usa para ligar o mestre e a réplica
Par
nó parceiro: para um mestre, as suas réplicas
Companheiro
o segundo nó na mesma instância do Firebird (mestre e réplica em um host)
Tornar comum, Promover a mestre, novo GUID, serviços (comutação, failover), lista de verificação da comutação
Todos os capítulos usam um exemplo:
O quê
Valor
node-a
nó mestre, bancos em /databases/master
node-b
nó réplica, bancos em /databases/replica
RCM
um host separado (também pode ser um dos servidores de bancos)
banco
employee.fdb
1. Instalação dos nós e do hqbirdrcm
Há três métodos de instalação:
Método
Quando escolhê-lo
O que você faz
Pelo HQCenter Admin (1.2)
o caminho habitual: o servidor de atualização do HQCenter Admin está acessível, atualizações automáticas são necessárias
você executa o script de instalação do fbagent, aprova o pedido, descreve o cluster
Pelo RCM, sem o HQCenter Admin (1.3)
não há HQCenter Admin, mas você precisa de certificados, configuração e atualizações sem trabalho manual; até 3 servidores de bancos
você instala o HQbird em cada host, entra no RCM e, em Configurações → Vincular hosts, informa os endereços dos hosts
Manualmente (1.4)
sem acesso ao HQCenter Admin, rede fechada, requisitos especiais
você instala os arquivos, cria os certificados, escreve node.json e rcm.json, registra os serviços
Pelo HQCenter Admin e pelo RCM você não instala os nós e o RCM. Eles são instalados pelo
fbagent quando você o adiciona ao cluster (capítulo 2). Os certificados e a
configuração também são criados automaticamente.
Linux e Windows estão descritos em um único capítulo. As diferenças do Windows estão nas
caixas “No Windows”.
1.1. Requisitos
Em cada servidor de bancos:
Firebird / HQbird 5.0, 4.0, 3.0 ou 2.5 (2.5 — somente Linux).
fbagent ao lado de cada instância do Firebird. Sem o fbagent o nó não funciona.
Sincronização de hora (NTP, chrony, w32time) em todos os servidores e no
host do RCM. Janelas de reinício e de transferência, a estimativa de atraso e
a verificação “nó não responde” dependem dos relógios.
Espaço livre para o arquivo de segmentos e para a inicialização da réplica (capítulo 4).
Rede conforme a tabela de portas (capítulo 0).
Linux: privilégios de root, x86_64, systemd, curl. Compatíveis: Ubuntu 20–26,
Debian 11–13, Astra, CentOS 7–10, AlmaLinux, Rocky, Oracle Linux 8–10, RED OS,
openSUSE 15.6, Fedora 44+.
Windows: privilégios de administrador, x64, Windows 10 / Server 2016 ou mais novo,
Windows PowerShell de 64 bits 5.1. No Windows 10 e no Server 2016–2022, o 7-Zip é necessário.
Onde o RCM vai executar. É necessário um RCM por cluster. Ele pode ser instalado em qualquer
servidor que enxergue todos os nós, inclusive em um dos servidores de bancos.
1.2. Instalação pelo HQCenter Admin
Passo 1. Executar o script de instalação do fbagent
O script instala o Firebird (a compilação HQbird), o fbagent, e registra o fbagent no
servidor do HQCenter Admin. Escolha o script correspondente à sua versão do Firebird: fb25, fb30, fb40,
fb50.
Linux (como root):
Command
sudo sh fbagent-fb50_known.sh --goafts <HQCenter-Admin-server> --enroll --cluster
Não há parâmetro -Cluster no Windows: o fbagent executa como
LocalSystem e cria as pastas do cluster sozinho.
Principais parâmetros:
Linux
Windows
Significado
--goafts <name>
-Goafts
servidor do HQCenter Admin de onde baixar; o nome é fornecido pelo seu fornecedor
--enroll
-Enroll
registrar o fbagent no HQCenter Admin (pedido de certificado)
--cluster
—
criar as pastas /opt/hqclusternode e /opt/hqbirdrcm (necessário somente para o fbagent 2.55.2 e anteriores; inofensivo nas versões mais novas)
--channel
-Channel
canal de atualização do fbagent, stable por padrão
--token
-Token
token de licença: o HQCenter Admin aprova o pedido automaticamente
--port
-Port
porta do Firebird
--yes
-Yes
não fazer perguntas (necessário quando não há terminal)
A lista completa de parâmetros está no README do script de instalação do fbagent.
Passo 2. Aprovar o pedido do fbagent
Com o parâmetro --enroll, o fbagent envia um pedido de certificado (CSR) ao HQCenter Admin e
espera até 30 minutos pela aprovação. Você pode aprová-lo assim:
automaticamente — se a instalação foi executada com um token de licença (--token) e
a licença tem uma vaga livre;
no painel do HQCenter Admin — a seção de pedidos de CSR, o pedido
deste host, o botão de aprovar e assinar;
pela API do HQCenter Admin — POST /v1/admin/csr-requests/{id}/approve.
Se o registro não teve sucesso (por exemplo, o tempo de espera esgotou), o fbagent ainda
funciona, mas o script termina com o código 2. Execute o script de novo com
os mesmos parâmetros: somente o registro será repetido.
Alguns minutos depois do registro, o fbagent instala o HQ Monitor sozinho.
Passo 3. Descrever o cluster
Os nós e o RCM aparecem quando você adiciona o fbagent ao cluster do HQCenter Admin. Como descrever o
cluster está no capítulo 2.
Depois de salvar o cluster:
Em até 10 minutos o fbagent recebe o cluster do HQCenter Admin (depois disso ele verifica
alterações a cada 60 segundos).
O fbagent no host do RCM cria a autoridade certificadora do cluster (CA) e assina
os certificados de todos os nós.
Cada fbagent grava node.json ou rcm.json para os membros
do seu cluster.
Na próxima verificação de produto (a cada 3 minutos) o fbagent instala e
inicia os serviços.
<port> é a porta do Firebird, por exemplo 3050. Um único fbagent pode hospedar no máximo
um nó mestre, um nó réplica, um RCM e um roteador
(hqclusternode router, a partir do HQbird 2027.2.30, capítulo 8.7).
No Windows. Versões do fbagent anteriores à 2.83.0 instalavam os nós em C:\hqclusternode e
o RCM em C:\hqbirdrcm. Se essas pastas existirem, o fbagent continua a
usá-las.
Atualizações
O fbagent verifica novas versões do nó e do RCM a cada 3 minutos; o canal
padrão é stable. O nó réplica é atualizado primeiro, depois o nó mestre.
Se, depois de uma atualização, o serviço não iniciar ou informar a versão errada,
o fbagent volta à versão anterior e bloqueia a nova. A lista de bloqueios:
<pasta do fbagent>/update/<product>/blocked-versions.json. Para tentar a
versão de novo, apague a linha dela nesse arquivo.
Estado do produto: fbagent --product-status hqclusternode (ou
hqbirdrcm).
1.3. Instalação pelo RCM (sem o HQCenter Admin)
O cluster é gerido pelo RCM. O fbagent de cada host recebe a descrição do cluster do RCM,
o fbagent no host do RCM assina os certificados, e o nó e o RCM são atualizados a partir de
versões armazenadas pelo RCM.
Limitações:
Um cluster por RCM.
No máximo 3 postos. Um posto é um host que executa um nó mestre ou réplica.
Um mestre e uma réplica no mesmo host contam como um posto. Um host que executa somente o RCM
não ocupa um posto. Um quarto host produz o erro seats_exceeded.
O RCM não atualiza o fbagent nem o Firebird. O fbagent os atualiza sozinho e não
mexe em replication.conf, node.json, rcm.json nem nos certificados.
Há dois métodos:
Vincular hosts no RCM — o método habitual. Três ações: o instalador em
cada host (RCM em um host, modo de descoberta nos outros), entrar no
RCM, o formulário Vincular hosts.
Manualmente pela linha de comando — tokens de ingresso e
fbagent --cluster-join. Necessário quando a porta 7450 está fechada entre os hosts ou
a janela de pareamento já fechou.
Licença. A licença de avaliação inclui o recurso cluster. Depois do período de
avaliação, o fbagent não instala um nó nem o RCM se a licença não tiver cluster.
Ele nunca bloqueia atualizações de nós e do RCM já instalados. Sem o
HQCenter Admin, uma licença flutuante deixa de funcionar depois de online_check_days mais
os dias de tolerância. Por isso instale uma licença vinculada em cada fbagent:
Command
fbagent --license-request --out license_request.json
# send the file to the vendor and receive license.jsonfbagent --license-install license.json
Sem licença, o mestre deixa de enviar segmentos (capítulo 2.8).
Portas:
Porta
Onde
Quem se conecta
7443
host do RCM
fbagent e nós de todos os hosts do cluster
7444
host do RCM
navegador do operador (console do RCM, HTTPS)
7450 (no segundo fbagent e nos seguintes — 7451…7459)
host em modo de descoberta, enquanto a janela de pareamento está aberta
RCM no host do RCM
7051 (segundo nó do mesmo fbagent — 7061)
hosts dos nós
outros nós e o RCM (1.4, passo 7)
Vincular hosts no RCM
Exemplo do zero. Dois servidores Linux, o instalador .run, vinculação,
registro, publicação, inicialização e reinicialização sob carga — com
capturas de tela e medições: o guia hqbird2027-linux-cluster-guide.ru.md e
o runbook hqbird2027-linux-cluster-runbook.ru.md (repositório goafts, pasta
de documentação).
Passo 1. Instalar o HQbird em cada host
Instale o HQbird com o instalador completo em cada servidor de bancos. Não registre no
HQCenter Admin (--enroll).
Por padrão o instalador não configura um cluster. Ele coloca os programas do nó
e do RCM na pasta do fbagent (update/<product>/staged/), mas não instala o RCM, não abre a janela de pareamento
e não abre as portas do cluster no firewall. O cluster
é ativado por dois parâmetros:
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 — em um host, onde o RCM do cluster vai executar. O instalador:
cria o cluster deste host (fbagent --cluster-init); o nome do cluster é o
nome do host;
instala e inicia o RCM; o console do RCM funciona em HTTPS na porta 7444;
cria o primeiro administrador do RCM rcmadmin com uma senha aleatória;
abre as portas 7443, 7444 e a porta do nó 7051 no firewall.
--cluster-pairing on (modo de descoberta) — em cada outro host.
O instalador abre a janela de pareamento do fbagent por 24 horas: a porta 7450 e
a porta do nó 7051. Enquanto a janela está aberta, um RCM da rede pode convidar este host para
o seu cluster. O fbagent começa a escutar na porta 7450 em até um minuto.
Sem esses parâmetros o instalador pergunta sozinho: na interface de
texto esta é a página Cluster; com --no-tui — duas perguntas.
A resposta padrão é “não”. --yes sem parâmetros de cluster também responde
“não” às duas perguntas.
No fim o instalador imprime as linhas RCM: e Pairing:. No host do 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
Em outro host:
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
Não há senha na saída: ela está no arquivo da linha Password:. Anote
o fingerprint de cada host em modo de descoberta.
Parâmetros de cluster no instalador Linux:
Parâmetro
O que faz
--rcm on|off
instala o RCM e cria um cluster neste host; padrão off
--cluster-pairing on|off
modo de descoberta: abre a janela de pareamento por 24 horas; padrão off
--pairing-port N
porta de pareamento do novo fbagent, 7450–7459; padrão a primeira livre
--rcm-password-file F
senha do administrador do RCM a partir da primeira linha do arquivo F, em vez de aleatória
--cluster-id ID
nome do cluster ID em vez do nome do host (com --rcm on)
--cluster-node on|off
instala o programa do nó; padrão on
--rcm-allow A,B
somente estes RCMs podem convidar este host: endereço, rede CIDR ou nome
O primeiro fbagent de um host recebe a porta de pareamento 7450 e as portas de nó 7051 e
7061. A segunda instância no mesmo host — 7451, 7052 e 7062.
O RCM e a janela de pareamento podem ser ativados depois, sem o instalador: no HQ Monitor,
a página Clusters, ou com comandos como o usuário do 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
Instaladores antigos (fbagent anterior à 3.1.0) não perguntam sobre o cluster: eles
instalam o RCM em cada host e abrem a janela de pareamento em todos. Você precisa do RCM de
um host; os RCMs dos outros hosts param sozinhos depois da vinculação.
No Windows. As mesmas duas escolhas existem no instalador do Windows: os parâmetros
/RCM e /DISCOVERY.
Passo 2. Entrar no RCM
Abra o endereço da linha RCM: do host do RCM (https://<host>:7444). Entre com
o login rcmadmin e a senha do arquivo da linha Password:. O RCM pede imediatamente uma
senha nova (1.5).
Passo 3. Vincular os hosts
No RCM abra Configurações → Vincular hosts.
No campo Hosts informe os endereços ou nomes dos hosts, um por linha.
A primeira linha é o host do RCM; ele já está no cluster.
Clique em Verificar hosts. O RCM sonda as portas de pareamento
7450–7459 de cada host e mostra a plataforma, a versão do Firebird,
a impressão digital e o estado. O host do RCM não precisa de janela de pareamento. Compare
as impressões digitais com a saída do instalador (a linha Pairing:).
Selecione o Mestre (por padrão o primeiro host) e clique em Vincular.
Vincular hosts: resultado da verificação
O RCM pede confirmação e mostra o progresso na seção Progresso. Quando todos os nós
estão em execução, ele diz “Concluído” e mostra o número de revisão do cluster:
Vincular hosts: todos os nós em execução
O mesmo pela linha de comando:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster link -hosts db1,db2,db3 -master db1
O que acontece em seguida:
O RCM envia um convite a cada host livre.
O fbagent do host entra no cluster e fecha a porta de pareamento. Se o
host tem o seu próprio RCM sem nós, o fbagent o para e o desativa, e
move o cluster vazio para cluster/left/ na pasta do fbagent.
O RCM salva o cluster: nó <host>-master no mestre, <host>-replica nos
outros hosts, porta 7051, vínculos mestre → réplica.
O fbagent de cada host instala e inicia o nó. O RCM espera até que todos os nós
estejam em execução e mostra Em execução para cada host.
Estados do host depois de Verificar hosts:
Estado
O que fazer
Pronto para vincular
nada. Se abaixo disser “O RCM próprio deste host vai parar depois da vinculação” — isso é normal
No cluster
o host já está neste cluster
Erro unreachable
a porta 7450 está fechada: a janela de pareamento está desligada (como por padrão) ou as 24 horas passaram. Logo depois da instalação espere um minuto e clique em Verificar hosts de novo. Caso contrário abra a janela (--cluster-pairing on) e verifique o firewall
Erro in_other_cluster
o host está em outro cluster
Erro claimed
outro RCM está vinculando este host agora
Erro seats_exceeded
mais de 3 postos
Versões. O fbagent instala o nó somente a partir do RCM. O RCM pega versões
assinadas da sua pasta import/ (ao lado de rcm.json) na inicialização e a cada
5 minutos. O instalador coloca ali as versões do host do RCM, e os fbagents dos outros hosts
baixam sozinhos a versão da sua plataforma. A lista de versões está no final da
página Vincular hosts. Uma versão também pode ser importada manualmente (passo 5 abaixo).
Manualmente pela linha de comando
Ordem: passos 1–3 no host do RCM, passo 4 em cada outro host, passos 5–6 no RCM.
Passo 1. Instalar o HQbird com o fbagent
Instale o HQbird em cada servidor de bancos e no host do RCM com o instalador completo.
No host do RCM você pode informar --rcm on logo de início (então o passo 3 não é necessário). Nos outros
hosts não informe parâmetros de cluster: por padrão não há RCM nem janela de
pareamento. Não registre no HQCenter Admin (--enroll).
No host do RCM o instalador deixa o programa do RCM na pasta do fbagent
(update/hqbirdrcm/staged/). Sem ele o passo 3 falha com o erro
no hqbirdrcm to install.
Passo 2. Instalar a licença vinculada
Como no início da seção, “Licença”.
Passo 3. Criar o cluster no host do RCM
Se o instalador já criou o cluster (--rcm on: uma linha RCM: com um endereço na
saída), pule este passo.
Execute o comando como o usuário do fbagent (no Linux — firebird), não como
root: caso contrário os arquivos da CA e o rcm.json ficarão com o root.
No Windows (PowerShell como administrador):
.\fbagent.exe --cluster-init shop-prod --address 10.0.0.7
shop-prod — nome do cluster: letras latinas minúsculas, dígitos e -.
--address — o endereço do host do RCM pelo qual os outros
hosts se conectam a ele. Pode ser repetido várias vezes. Sem o parâmetro, usam-se os endereços e o nome do host.
O comando:
cria a CA do cluster e a CA do agente (na pasta do fbagent, clusterca/<name>/);
grava o certificado do RCM, rcm.json e cluster-init.json na pasta do RCM;
instala o RCM e registra o serviço hqbirdrcm. No Linux o serviço executa como
um usuário separado hqbirdrcm;
passa o fbagent para o RCM (cluster.source = rcm) e o reinicia;
imprime o endereço do RCM e a impressão digital da CA:
Code
Cluster: shop-prod
RCM URL: https://10.0.0.7:7443
CA hash: sha256:9f86d0...
Anote RCM URL e CA hash: eles são necessários nos outros hosts. Executar de novo
para o mesmo cluster é seguro: a CA e as chaves permanecem as mesmas.
Entre no RCM imediatamente e altere a senha do rcmadmin (1.5).
No Linux. O usuário hqbirdrcm está no grupo do fbagent. O RCM lê
rcm.json por esse grupo, mas não pode gravá-lo. Por isso Configurações → RCM não salva alterações (erro
rcm_config_read_only). Edite rcm.json no host como o usuário do fbagent
e reinicie o RCM.
Passo 4. Conectar os fbagents dos outros hosts
No host do RCM crie um token de ingresso para cada fbagent: no RCM
Configurações → Cluster, o botão Criar token de ingresso. Ou pela
linha de comando:
Command
cd /opt/hqbirdrcm
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm cluster join-token -note db2
O token vale 24 horas, para um único fbagent e somente uma vez. O RCM
o mostra uma vez, junto com um comando pronto.
No host do nó execute este comando como o usuário do fbagent:
Em vez de --token-file você pode usar --token <token>. No Windows — o mesmo com
.\fbagent.exe no PowerShell como administrador.
O fbagent verifica a CA do RCM pela impressão digital. Se a impressão digital não coincidir, ele
para e não grava nada. Depois o fbagent recebe o seu certificado
(90 dias, renovado automaticamente) e reinicia. Um fbagent conectado aparece no
RCM na tabela Agentes. Enquanto ele não tem membros, nada é instalado no host.
Passo 5. Importar versões para o RCM
O fbagent pega o nó e o RCM somente do RCM. Se a versão necessária não estiver na
lista Versões no espelho (Configurações → Vincular hosts), importe cada produto
(hqclusternode, hqbirdrcm) para cada plataforma dos seus hosts
(linux-amd64, windows-amd64). O arquivo da versão e a assinatura .sig são fornecidos
pelo fornecedor.
O RCM procura a assinatura em <file>.sig, ou você a indica com -sig. Sem
uma assinatura válida do fornecedor o RCM não aceita o arquivo.
Uma versão nova substitui a anterior. Não é necessário reiniciar o RCM.
O fbagent verifica novas versões a cada 3 minutos. A ordem de atualização e o
bloqueio são como pelo HQCenter Admin (1.2, “Atualizações”).
Passo 6. Descrever o cluster
Defina os membros e os vínculos no RCM, Configurações → Cluster (capítulo 2.3). Depois de
salvar, o fbagent instala os nós do mesmo modo que pelo HQCenter Admin (1.2, passo 3): grava
certificados, node.json e rcm.json, instala e inicia os serviços.
Portas — no início da seção.
1.4. Instalação manual
Passo 1. Instalar o HQbird com o fbagent
Instale o HQbird em cada servidor de bancos (com o mesmo script, mas sem --enroll, ou com o instalador completo do HQbird). Verifique se o fbagent está em execução.
Anote três valores do agent_config.json do fbagent. Eles são necessários para o node.json:
Campo do fbagent
Campo do node.json
Exemplo
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
—
Verificação do fbagent (a resposta é o JSON da instância do Firebird):
Se o host tiver várias instâncias do HQbird, deixe somente o serviço da sua instância em firebird.update.services da configuração do fbagent (veja 3.5).
O comando cria ca.crt e ca.key, node-a.crt/.key, node-b.crt/.key e rcm.crt/.key. Em -hosts, liste todos os nomes e endereços pelos quais os participantes serão acessados.
gencerts e os arquivos que ele criou
ca.key é a chave da CA. Não a copie para os hosts; guarde-a separadamente.
Um nó novo é adicionado depois com -add: ele assina o par com a mesma CA, e os outros arquivos ficam inalterados:
Os certificados valem 90 dias. gencerts -out certs -list mostra as datas de expiração, e gencerts -out certs -renew os renova com a mesma chave. Copie o novo .crt para o seu host: o nó o pega sem reinício.
Copie ca.crt e somente o próprio certificado e chave de cada host.
Passo 4. Escrever node.json
Um arquivo por nó. Exemplo para o mestre (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"}]}
O nó réplica (node-b) tem o mesmo arquivo, mas com "role": "replica", os seus próprios certificados, e o mestre node-a em peers.
Principais campos:
Campo
Valor
node_id
nome do nó; o mesmo no certificado, no rcm.json e nos peers dos outros nós
role
master ou replica
listen_addr
o endereço da API do nó; um segundo nó no mesmo host usa outra porta (:7052)
rcm.url
o endereço para receber estatísticas do RCM; none — sem RCM
firebird.*
o Firebird e o fbagent desta instância; os valores do fbagent precisam coincidir exatamente
firebird.auto_restart
se o nó réplica pode reiniciar o Firebird sozinho: auto (padrão), never, always
windows.restart_window
a janela de reinício do Firebird; para o mestre o padrão é 22:00-05:00, para a réplica é sempre
windows.transfer_window
a janela em que a inicialização corre na velocidade máxima
peers
para o mestre — as suas réplicas, para a réplica — o seu mestre
databases
a pasta dos bancos; é melhor não escrevê-la à mão e defini-la pelo RCM (capítulo 3)
Os demais campos têm valores padrão. O nó não inicia se os campos do fbagent não estiverem definidos.
Proteja o arquivo: ele contém a senha e o token.
Command
chmod 600 /opt/hqclusternode/node.json
No Windows. Escreva os caminhos no formato JSON: "C:\\HQbird\\replication.conf".
service_name é o nome do serviço do Windows para o Firebird.
url — o endereço do nó como visto pelo host do RCM. Somente https.
host — o rótulo da instância do Firebird. Um nó mestre e um nó réplica com o mesmo rótulo executam no mesmo Firebird (companheiro, necessário para promover uma réplica a mestre, capítulo 8). Um rótulo — no máximo um mestre e uma réplica.
Caminhos relativos são resolvidos a partir da pasta do rcm.json.
Passo 6. Registrar os serviços
Ordem de início: primeiro o RCM, depois as réplicas, depois o mestre.
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 cria o serviço hqclusternode-<role>-p<port> executando como o usuário firebird. Se a pasta do Firebird pertencer ao root, o comando concede ao grupo firebird acesso de escrita a ela (com o bit sticky) e imprime cada alteração: o nó precisa substituir replication.conf.
Para svc start, svc stop e svc uninstall, indique o mesmo node.json: o nome do serviço é derivado do papel e da porta do Firebird.
No Windows (PowerShell como administrador):
Command
cd C:\hqclusternode
.\hqclusternode.exe svc install -config C:\hqclusternode\node.json -certs C:\hqclusternode\certs
O serviço HQClusterNode-<role>-p<port> executa como LocalSystem, inicia automaticamente e reinicia depois de uma falha. O serviço do nó não depende do serviço do Firebird. Se o nó foi instalado com a versão 2027.1.2–2027.1.9, remova a dependência uma vez:
.\hqclusternode.exe svc fix-deps -config C:\hqclusternode\node.json.
svc install e svc start no Windows
Passo 7. Abrir as portas
No host do nó, permita conexões de entrada em 7051 (a porta de listen_addr) a partir dos outros nós e do RCM. No host do RCM, permita conexões de entrada em 7443 a partir de todos os nós. Não exponha as portas 7444 e 13050 externamente.
Exemplo de ufw no host do nó:
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
Atualização manual
Pare o serviço, substitua o programa, inicie o serviço:
A configuração e os certificados não são alterados por isso.
1.5. Primeiro login no RCM
O endereço e a senha dependem de como o RCM foi instalado.
Como o RCM foi instalado
Endereço
Login e senha
Pelo instalador do HQbird ou por fbagent --cluster-init (1.3)
https://<host do RCM>:7444 a partir de qualquer computador
rcmadmin e a senha impressa pelo instalador (ou a sua, de --rcm-password-file)
Pelo HQCenter Admin (1.2) ou manualmente (1.4)
http://127.0.0.1:7444, somente no host do RCM
rcmadmin, senha strong password (com um espaço)
HTTPS (1.3). O certificado do RCM é assinado pela CA do cluster, que o navegador não conhece, por isso ele avisa. Na página de login o RCM mostra a impressão digital da CA. Compare-a com o CA hash impresso pelo instalador, e importe a CA no navegador ou no sistema como raiz confiável: o link Baixar o certificado da CA na página de login (https://<host do RCM>:7444/ca.crt, arquivo hqcluster-ca.crt). Para o RCM escutar somente em localhost, defina "operator_addr": "127.0.0.1:7444" em rcm.json e reinicie o RCM.
HTTP (1.2, 1.4). De outro computador, conecte-se por um túnel SSH:
Command
ssh -L 7444:127.0.0.1:7444 <rcm-host>
Depois abra http://127.0.0.1:7444 no navegador.
Página de login do RCM
Senha gerada. O RCM pede que você a altere no primeiro login: até você alterá-la, as outras páginas não abrem. Altere a strong passwordimediatamente (o link Senha no cabeçalho).
Alteração da senha no primeiro login
Idioma. Selecione Russo na lista de idiomas no cabeçalho da página (também disponível na página de login). Se você não selecionar um, o idioma é tomado do navegador.
Alteração de senhas e usuários novos
Cada usuário altera a própria senha: o link Senha no cabeçalho da página. Você precisa da senha atual e de uma nova com pelo menos 12 caracteres. Depois da alteração, as outras sessões desse usuário são encerradas.
Se o instalador gerou uma senha, ela é gravada no arquivo clusterca/<name>/rcm-initial-password na pasta do fbagent. Depois que a senha é alterada, o fbagent apaga esse arquivo sozinho. Não apague o arquivo initial-admin.json na pasta do RCM: ele contém somente um hash. Se o arquivo de usuários se perder e esse arquivo estiver ausente, o RCM criará um usuário com a senha padrão.
Usuários novos. Não há página de usuários na interface. Os usuários ficam no arquivo rcm-data/users.json. A senha é armazenada como um hash HA1: MD5("<name>:hqbirdrcm:<password>").
Reinicie o RCM imediatamente: ele lê o arquivo somente na inicialização. Quando uma senha é alterada na interface, o RCM reescreve o arquivo a partir da memória, e quaisquer edições que ele ainda não leu serão perdidas.
Sem um campo role, um usuário tem todas as permissões. A partir do HQbird 2027.2.31 existe o papel "role": "viewer": somente visualização; qualquer pedido de alteração recebe 403.
1.6. Como verificar a instalação
Os serviços do nó e do RCM estão em execução e não reiniciam em loop:
systemctl status hqclusternode-master-p3050, systemctl status hqbirdrcm.
systemctl status do nó
systemctl status do RCM
O RCM responde (sem senha): curl http://127.0.0.1:7444/healthz. Quando
instalado pelo RCM (1.3), o console funciona em HTTPS:
curl -k https://127.0.0.1:7444/healthz.
No RCM, a página Visão geral mostra todos os nós, sem o marcador “não
responde”.
Pela linha de comando no host do RCM:
Command
exportRCM_USER=rcmadmin RCM_PASSWORD='<password>'./hqbirdrcm nodes
./hqbirdrcm status
O cluster pelo RCM: Configurações → Cluster, a seção Estado — cada
membro aplicou a revisão mais recente e não informa erro. Pela linha de
comando: ./hqbirdrcm cluster status.
1.7. Logs
O quê
Onde
Log do nó
<pasta do node.json>/logs/node-YYYYMMDD.jsonl
Saída do serviço do nó (Linux)
journalctl -u hqclusternode-<role>-p<port>
Saída do serviço do RCM (Linux)
journalctl -u hqbirdrcm
Log de replicação do Firebird
firebird.replication_log do node.json
Logs de qualquer nó sem SSH
RCM, página Logs
1.8. Erros comuns
O que você vê
Causa
O que fazer
O nó não inicia: um erro sobre fbagent_url, fbagent_token ou instance_id
o fbagent não está em execução ou os valores não coincidem com agent_config.json
verifique o fbagent com o comando curl de 1.4, passo 1
O script de instalação terminou com o código 2
o pedido do fbagent não foi aprovado a tempo
aprove o pedido e execute o script de novo
Os nós não aparecem pelo HQCenter Admin
o fbagent não está no cluster, ou o cluster ainda não foi obtido
verifique o cluster (capítulo 2), espere até 10 minutos
O nó no RCM está “não responde”
a porta 7051 está fechada, o url em rcm.json está incorreto, o endereço não está no certificado
verifique as portas e o -hosts dos certificados
Sem login no RCM: “Excesso de tentativas de login malsucedidas”
10 logins malsucedidos em 5 minutos
espere alguns minutos
A versão nova não se instala
a versão está em blocked-versions.json
remova a linha da versão do arquivo
--cluster-init: no hqbirdrcm to install
o instalador não deixou o programa do RCM
instale o HQbird com o instalador completo (1.3, “Manualmente”, passo 1)
o token já foi usado, tem mais de 24 horas ou foi revogado
crie um token novo (1.3, “Manualmente”, passo 4)
--cluster-join: hostname_conflict
o cluster tem um fbagent com o mesmo nome de host e endereços diferentes
dê nomes diferentes aos hosts
--cluster-join: this agent is in cluster … from goafts
o fbagent já está no cluster do HQCenter Admin
remova-o do cluster do HQCenter Admin
O nó não se instala pelo RCM
o RCM não tem versão para esta plataforma
hqbirdrcm release list, importe a versão (1.3, “Manualmente”, passo 5)
2. Configuração do cluster
Neste capítulo você define quais nós estão no cluster e qual mestre envia
segmentos para qual réplica. Depois você configura os nós do RCM e os usuários.
Os relacionamentos são definidos de uma de três formas:
Nós instalados
Onde os relacionamentos são definidos
Seção
pelo HQCenter Admin
no HQCenter Admin: a página Clusters do HQ Monitor ou a API do HQCenter Admin
2.2
pelo RCM, sem o HQCenter Admin
no RCM: Configurações → Cluster, hqbirdrcm cluster ou a página Clusters do HQ Monitor
2.3
manualmente
no RCM: Configurações → RCM e Configurações → Nós
2.3
Em nós instalados pelo HQCenter Admin ou pelo RCM, altere os relacionamentos somente na
descrição do cluster. O fbagent sobrescreve node.json e rcm.json de acordo com
a descrição do cluster. Editar relacionamentos em Configurações → RCM ou Configurações → Nós
do RCM é recusado (409 cluster_managed). Versões anteriores do RCM aceitavam, mas isso
se perdia.
2.1. Papéis e esquemas
Cada nó tem um papel: mestre ou réplica. Dois nós — um mestre e uma réplica — podem executar em uma única instância do Firebird.
Esquemas compatíveis:
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
O vínculo vai sempre do mestre para a réplica. O RCM liga o banco do mestre à sua réplica pelo GUID do banco, não pelo nome do nó.
Companheiro. Um nó mestre e um nó réplica na mesma instância do Firebird são companheiros. A promoção de uma réplica a mestre (capítulo 8) funciona somente para esse par. Em rcm.json o par é marcado por um valor idêntico de host.
2.2. Vínculos pelo HQCenter Admin
Onde descrever um cluster
HQ Monitor, página Clusters (somente administradores; a entrega de configuração precisa estar ativada). O modo habitual.
API do HQCenter Admin:POST /v1/admin/clusters e
PUT /v1/admin/clusters/{id}. O painel do HQCenter Admin não tem
página de clusters.
``
Passos na página Clusters
Informe um Novo id do cluster (letras latinas minúsculas, dígitos e -) e clique em
Criar.
Adicione membros (Membros). Para cada um informe:
o fbagent do host;
o papel: master, replica ou rcm;
os endereços do host;
a porta: para um nó — 7051 (um segundo nó no mesmo host — por exemplo 7052),
para o RCM — a porta de entrada de estatísticas 7443.
Adicione vínculos (Vínculos de replicação) do mestre para a réplica.
Clique em Validar e depois em Salvar.
Se outro administrador alterou o cluster ao mesmo tempo, a página pedirá
que você recarregue o cluster e repita a alteração.
Regras
Um fbagent pode pertencer a somente um cluster.
Em um único fbagent — no máximo um mestre, uma réplica, um RCM e
um roteador. O roteador (papel router, a partir do HQbird 2027.2.30) não tem vínculos e
não ocupa um posto de licença (capítulo 8.7).
Um cluster tem exatamente um RCM. O fbagent no host do RCM executa a autoridade
certificadora do cluster (CA).
O nome do membro (member_id) — letras latinas, dígitos, -. O nome, o fbagent e o papel
de um membro não podem ser alterados. Para mover um membro para outro host, crie um
membro novo com um nome novo. Não use o nome antigo de novo.
Toda réplica precisa ter um vínculo com o mestre.
O HQCenter Admin monta o endereço do nó sozinho: https://<primeiro endereço>:<porta>.
HQbird 2.5/3.0: defina a data replconf_valid_till do cluster
(YYYY-MM-DD) — a configuração do plugin replconf vale até essa data.
Exemplo pela 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"}]}
Criar: POST /v1/admin/clusters (o documento pode ser enviado junto com os
membros). Substituir o documento inteiro: PUT /v1/admin/clusters/{id}.
PUT exige o cabeçalho If-Match: <revision> (a revisão é fornecida por GET e ETag).
Sem o cabeçalho — 428, com uma revisão antiga — 409, com um erro no documento —
422 com uma lista de erros.
POST /v1/admin/clusters/{id}/validate valida o documento sem salvar.
GET /v1/admin/clusters/{id}/status mostra o estado dos membros e as datas de
expiração dos certificados.
O que acontece depois de salvar
O fbagent de cada membro recebe o cluster. Dentro do cluster — uma verificação a cada
60 segundos (o fbagent no host do RCM — a cada 30 segundos). Fora de um cluster, um fbagent
fica sabendo do cluster na próxima consulta de configuração. Se essa consulta não
alcançar o servidor, a verificação corre a cada 10 minutos.
Cada fbagent cria uma chave e envia um pedido de certificado. O fbagent no
host do RCM o assina. O RCM assina o próprio certificado sem pedido.
O fbagent grava em node.json: nome, papel, endereço, peers (a partir dos vínculos), o
endereço do RCM, os caminhos dos certificados, os dados do Firebird e do fbagent. Em rcm.json: a lista de
nós (nodes), a lista de roteadores (routers), o endereço de entrada de estatísticas e os
caminhos dos certificados. O fbagent não mexe nos outros campos dos arquivos.
O fbagent instala e inicia os serviços (capítulo 1).
Alteração de um cluster:
O que mudou
O que o fbagent faz
somente os peers de um nó em execução
passa-os ao nó sem reinício
outros campos de um nó
para o nó, grava o arquivo, inicia o nó — dentro da windows.transfer_window do nó (não definida — imediatamente)
rcm.json
reinicia o RCM imediatamente
certificados ou CA
reinicia o serviço
um membro é removido
para e remove o serviço; cluster-managed.json → cluster-removed.json, o programa → *.removed; a configuração, os certificados e os dados permanecem
Depois que um nó é removido, a seção dele
# BEGIN managed-by:<name> … # END … permanece no replication.conf compartilhado. Apague-a manualmente e reinicie
o Firebird pelo RCM.
Aprovação dos certificados do cluster
Por padrão o fbagent no host do RCM assina os pedidos sozinho (auto). A aprovação manual
pode ser ativada. Comandos no host do 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>
No modo manual, um membro novo ou uma chave nova espera aprovação. A renovação de um
certificado com uma chave conhecida é assinada automaticamente.
2.3. Vínculos pelo RCM
Cluster do RCM (sem o HQCenter Admin)
Se o cluster foi criado pelo instalador do HQbird ou pelo comando fbagent --cluster-init
(capítulo 1.3), a descrição do cluster é armazenada pelo RCM. A forma mais fácil de adicionar hosts é na página
Configurações → Vincular hosts (capítulo 1.3, “Vincular hosts no RCM”):
o RCM cria os membros e os vínculos sozinho. As regras são as mesmas do HQCenter Admin (2.2, “Regras”), mais:
no RCM há um cluster; o membro rcm sempre existe e não pode ser excluído;
no máximo 3 postos (hosts com nós mestre ou réplica); caso contrário ocorre o erro
seats_exceeded;
um membro só pode ser adicionado em um fbagent que se conectou ao RCM
(capítulo 1.3: “Vincular hosts” ou “Manualmente”, passo 4).
Passos na página Configurações → Cluster:
Na tabela Agentes, clique em Adicionar membro na linha do fbagent.
Informe o papel (master, replica ou router), member_id, endereços e porta.
A página sugere o nome <host>-<role> e a porta: 7051 para o primeiro nó do fbagent,
7061 para o segundo. Uma porta já ocupada por outro membro do host é recusada pelo RCM. Os
endereços do fbagent são botões: clique para adicionar um endereço.
Na seção Vínculos, clique em Adicionar vínculo do mestre para a réplica.
Clique em Validar: o RCM mostrará erros e avisos.
Clique em Salvar. A página mostrará a lista de alterações e pedirá
confirmação. Se membros estão sendo excluídos, a janela fica vermelha.
Antes de salvar, as alterações existem somente na página (o rótulo “Não salvo”). Se
alguém salvou o cluster ao mesmo tempo, a página oferecerá recarregá-lo.
Se somente campos do RCM mudaram (revisão, CA, comissões), a página salvará
a sua alteração sozinha.
Outras seções da página:
Seção
O que há
cabeçalho
nome do cluster, revisão, CA do cluster e CA do agente; o botão Exportar da CA antiga
Tokens de conexão
criar um token para um fbagent novo, revogar um não usado
Documento JSON
o documento inteiro em um campo de texto; Validar e Salvar o usam
Chaves e CAs
comissões: chave nova de membro (rekey), CA nova do cluster (rotate_ca), CA nova do agente (rotate_agent_ca); indisponíveis quando há alterações não salvas
Estado
a revisão que cada membro aplicou, expiração do certificado, serviço, último erro
Pela linha de comando no host do 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
O formato do documento é o de 2.2, “Exemplo pela API”. apply com uma revisão antiga
recebe 409: execute show de novo. O RCM guarda as últimas 20 revisões em
rcm-data/cluster/history/.
HQ Monitor. A página Clusters também funciona com o RCM. No host do RCM,
o HQ Monitor acessa o RCM pelo fbagent desse host, com o certificado do
fbagent: o usuário e a senha do RCM não são necessários. No log de auditoria do RCM essas
ações são registradas como agent:<id> (<user>). Outro modo, para versões
anteriores do RCM: na configuração do HQ Monitor defina rcm_admin_url
(http://127.0.0.1:7444), rcm_admin_user (o usuário do RCM) e
rcm_admin_password_file (um arquivo com a senha dele).
Depois de salvar, tudo segue como pelo HQCenter Admin (2.2, “O que acontece depois de
salvar”). O RCM relê nodes em rcm.json sozinho, sem reinício.
Remover um fbagent do cluster: exclua os membros dele e salve, depois
clique em Revogar na tabela Agentes (ou
./hqbirdrcm cluster revoke -agent <id>). Para trazê-lo de volta, é necessário um
token novo. Depois da revogação o fbagent (a partir da versão 3.1.0) sai do cluster
sozinho: ele para os seus nós e apaga os dados do cluster. O mesmo é feito em um
host de nó pelo comando fbagent --cluster-leave. No host do RCM isso é recusado.
Instalação manual: adicionar um nó ao RCM
Configurações → RCM, a tabela Nós conectados.
Clique em Adicionar nó. Preencha node_id, url
(https://<endereço>:7051), papel, host (rótulo da instância do Firebird),
server (somente para agrupamento na tela).
Clique em Validar na linha do nó: o RCM verificará a conexão e as permissões.
Clique em Salvar. O RCM gravará rcm.json e salvará o arquivo antigo como
rcm.json.<hora UTC>.bak (os últimos 20).
Reinicie o RCM. Até o reinício a configuração antiga está em vigor;
a página mostra quais campos estão esperando um reinício.
Configurações → RCM
Command
sudo systemctl restart hqbirdrcm
Você também pode fazer isso sem a interface: edite rcm.json e reinicie o RCM.
Instalação manual: vincular mestre e réplica
O vínculo precisa ser registrado dos dois lados:
Configurações → Nós, selecione o nó mestre.
Na seção Pares, clique em Adicionar par: o node_id da réplica, o url dela,
compressão (zstd).
Clique em Salvar. O RCM mostrará a lista de alterações e pedirá
confirmação. A alteração de peers entra em vigor imediatamente.
Repita para o nó réplica: o par dele é o mestre.
A seção Pares do nó mestre
Se o par não estiver registrado em um dos lados, o RCM não oferecerá esse nó réplica na
inicialização do banco.
2.4. Configurações do nó
Configurações → Nós mostra as configurações de node.json que o nó permite alterar a partir do RCM. Somente os campos alterados são salvos, depois de uma janela que lista as alterações.
Configurações → Nós: seleção de um nóConfigurações de bancos do nó com marcadores "depois da varredura"
Cada linha é marcada com o momento em que a alteração entra em vigor:
Quando
Quais configurações
Imediatamente
channel_a_mbps, channel_a_burst_mbps, windows.restart_window, peers; a partir do HQbird 2027.2.24 — configurações de verificação de dados (limits.data_check_*); a partir do HQbird 2027.2.31 — advertise_addr
Depois do reinício do nó
os demais limites, windows.transfer_window; a página os mostra em uma linha separada até o nó ser reiniciado
Depois da varredura
databases.*, exclude_filter; se replication.conf mudou, é necessário reiniciar o Firebird (capítulo 3.5)
Somente leitura (alterados em node.json no host do nó): firebird (incluindo a senha e auto_restart), rcm, tls, segments, o endereço listen_addr.
Principais configurações:
Configuração
Padrão
Significado
windows.restart_window
mestre 22:00-05:00, réplica — sempre
quando o nó pode reiniciar o Firebird; o Firebird mestre nunca se reinicia sozinho
windows.transfer_window
23:00-05:00
a janela em que a inicialização corre na taxa reinit_window_mbps
limits.channel_a_mbps
50
taxa de transferência de segmentos, MB/s (channel_a_burst_mbps — pico de curta duração, 200)
limits.reinit_window_mbps
100
taxa de inicialização dentro da janela de transferência, MB/s
limits.reinit_day_disk_fraction
0,5
fração da velocidade de disco medida para a inicialização fora da janela
limits.retention_days
2
quantos dias manter os segmentos enviados no arquivo do mestre
limits.free_space_floor_gb
1
espaço livre mínimo, GB; abaixo disso a réplica não aceita segmentos
limits.max_concurrent_reinits
1
quantas inicializações o nó executa ao mesmo tempo
Detalhes de velocidade e retenção do arquivo estão nos capítulos 5 e 7.
firebird.auto_restart (somente em node.json) determina se um nó réplica pode reiniciar o Firebird sozinho:
Valor
Comportamento
auto (padrão)
pode, se este Firebird não servir bancos mestres
never
nunca
always
sempre, mesmo se este Firebird hospedar bancos mestres
Pelo HQCenter Admin. A windows.transfer_window do nó do fbagent também é usada como a janela para reiniciar o próprio serviço do nó quando o cluster muda. Se a janela não estiver definida em node.json, o fbagent reinicia o serviço imediatamente.
2.5. Várias instâncias do HQbird em um host
O fbagent reinicia os serviços listados em firebird.update.services da sua
configuração. Uma lista vazia significa todos os serviços do HQbird no host. Deixe somente
o serviço da sua própria instância na lista. O nó não vê essa configuração e grava um
aviso fbagent_shared no log se o fbagent conhece mais de uma instância.
2.6. Senha do SYSDBA
O nó se conecta ao Firebird com o usuário e a senha de firebird.user e
firebird.password em node.json. O fbagent guarda a própria cópia da senha. Se você
alterou a senha do SYSDBA:
Corrija firebird.password no node.json de cada nó desta
instância (mestre e réplica).
Corrija a senha na configuração do fbagent e recarregue-a (veja a
documentação do fbagent).
Reinicie os serviços dos nós.
Caso contrário as páginas de publicação e de verificação no RCM mostrarão um erro de login
(SQLSTATE 28000).
2.7. Usuários do RCM e auditoria
Os usuários estão no arquivo rcm-data/users.json (capítulo 1.5). Sem um papel, um
usuário tem todos os direitos; o papel viewer (a partir do HQbird 2027.2.31) — somente visualização.
Uma sessão dura 12 horas depois da última ação.
Depois de 10 logins malsucedidos em 5 minutos, o login desse usuário e endereço fica
temporariamente bloqueado. Um login bem-sucedido zera o contador.
O log de auditoria é o arquivo rcm-data/audit.jsonl: uma linha JSON para cada
alteração, login e logout. Não há log de auditoria na interface.
A página Comandos mostra o autor de cada comando.
2.8. Licença
Uma vez por minuto, o nó mestre lê a licença do fbagent do seu host. Se não houver licença (o período de avaliação terminou, a licença expirou ou é inválida), o nó deixa de enviar segmentos de todos os bancos do mestre. O Firebird e os bancos continuam em execução, mas as réplicas deixam de receber alterações.
O que você vê no RCM:
o mestre fica vermelho (NEEDS_ATTENTION), com o distintivo “sem licença: envio interrompido”;
não há botão Retomar: somente a licença encerra a pausa;
na réplica: “não recebe desde …: o mestre não tem licença”;
na tabela Nós, um distintivo “sem licença”; em Configurações → Nós, o bloco da licença do fbagent;
os alertas license_paused e license_pause_archive_released;
a inicialização é proibida (license_paused).
Bloco da licença do fbagent em Configurações → Nós
Instale a licença no fbagent. O nó encerra a pausa sozinho em até um minuto. O mestre retém o arquivo para as réplicas por limits.retention_days (2 dias por padrão) a partir do início da pausa. Se você instalar a licença mais tarde, as réplicas terão de ser inicializadas de novo.
Cluster pelo RCM, sem o HQCenter Admin. Uma licença flutuante sem o HQCenter Admin deixa de funcionar depois de online_check_days mais os dias de tolerância. Cada fbagent do cluster precisa de uma licença vinculada (fbagent --license-request, depois fbagent --license-install, capítulo 1.3, “Licença”). Depois do período de avaliação, o fbagent não adicionará um nó novo nem o RCM sem o recurso cluster na licença; ele nunca proíbe atualizações. Para o HQbird 2.5/3.0, a data replconf_valid_till no RCM não pode ser posterior ao fim da licença mais os dias de tolerância nos nós do fbagent (erro replconf_after_license).
2.9. Como verificar
Visão geral: todos os nós estão presentes e agrupados por servidor.
Visão geral do cluster
Configurações → Nós: o mestre tem uma réplica em Pares, e a réplica tem o mestre.
Configurações → RCM: o botão Verificar na linha de cada nó passa.
Relatório do cluster como um único arquivo:
Command
./hqbirdrcm report -o report.json
2.10 Erros comuns
O que você vê
Causa
O que fazer
Edição de pares no RCM recusada (409 cluster_managed) ou perdida depois do reinício do nó
o nó foi instalado pelo HQCenter Admin ou pelo RCM
altere os vínculos na descrição do cluster (2.2, 2.3)
seats_exceeded ao salvar o cluster no RCM
nós em um quarto host
no máximo 3 hosts com nós
Configurações → RCM: rcm_config_read_only
cluster pelo RCM no Linux: rcm.json pertence ao fbagent
edite rcm.json como o usuário do fbagent e reinicie o RCM
Revogar agente não funciona (agent_has_members)
o fbagent tem membros
primeiro exclua os membros e salve
O nó réplica não é oferecido durante a inicialização
o par não está registrado em um dos lados
adicione o par dos dois lados (2.3)
Uma alteração em Configurações → RCM não entra em vigor
o RCM não foi reiniciado
reinicie o RCM
422 ao salvar o cluster no HQCenter Admin
um erro no documento
corrija de acordo com a lista errors, verifique por validate
409 ao salvar o cluster
o cluster foi alterado por outra pessoa
releia o cluster e tente de novo
Um membro novo do cluster do HQCenter Admin não recebe certificado
aprovação manual no host do RCM
fbagent --cluster-ca-approve <id>
Erro SQLSTATE 28000 nas páginas de publicação
a senha do SYSDBA foi alterada
2.6
3. Inclusão de um banco no mestre
Neste capítulo o banco mestre passa ao controle do nó. O nó o registra em
replication.conf e cria pastas para os segmentos. Depois de reiniciar o Firebird
o banco fica pronto para replicação.
A criação da réplica são os passos seguintes (publicação, inicialização). Eles estão descritos nos
capítulos 4–6.
Os nomes dos botões seguem a interface do RCM em russo, com os nomes em inglês entre parênteses.
3.1. Como um nó descobre os bancos
O nó mestre procura bancos em uma única pasta — a raiz dos bancos (databases.root). O que entra na gestão é decidido por regras:
Regra
Campo
Padrão
Pasta dos bancos
root
não definida
Pesquisar subpastas
recursive
sim
Máscara de inclusão
template
*.fdb
Máscara de exclusão
exclude_mask
nenhuma
Tamanho do arquivo, MB
min_size_mb, max_size_mb
sem limites (0)
Tabelas para comparação de dados
sync_tables
com o HQbird 2027.2.24 — tabelas da publicação do banco; se não houver — RDB$FIELDS; em 2027.5.7 — RDB$FIELDS
Lista de inclusão
include_paths
vazia (modo de máscara)
Lista de exclusão
exclude_paths
vazia
O caminho root é um caminho no host do nó, não no host do RCM. O nó aplica primeiro a máscara de inclusão, depois a de exclusão, depois o tamanho.
As regras são as mesmas para o nó inteiro. A lista sync_tables também é compartilhada: a verificação (capítulo 5.10) procura cada tabela da lista em cada banco do nó que não tem a própria lista.
Tabelas para comparação, com o HQbird 2027.2.24. Cada banco pode ter a própria lista (Tabelas de acompanhamento da sincronização). O nó a guarda em databases.sync_tables_by_db. A verificação usa a primeira lista que estiver definida:
a lista própria do banco;
a lista compartilhada sync_tables do nó;
tabelas da publicação do banco;
RDB$FIELDS.
Uma lista compartilhada salva antes tem precedência sobre a publicação: um banco sem a própria lista a usa. A página do banco do mestre mostra qual lista está em vigor (3.3).
Uma tabela ausente tanto no banco primário quanto na réplica recebe o estado “não está no banco” (absent): ela não é comparada, e a verificação não mostrará “Não ok” por causa dela. Uma tabela que falta em somente um lado é uma divergência.
RCM e nó 2027.5.7. Há uma única lista para o nó inteiro (sync_tables); sem lista a verificação usa RDB$FIELDS. Uma tabela ausente é um erro, e a verificação do banco mostrará “Não ok”.
Todas as regras ficam no node.json do nó. O nó as aplica em cada varredura.
Modo de máscara e modo de lista:
Modo de máscara (lista de inclusão vazia): o nó pega todos os arquivos que correspondem à máscara, exceto os excluídos. Um arquivo novo na pasta será pego pelo nó automaticamente na próxima varredura.
Modo de lista (lista de inclusão não vazia): o nó pega somente os arquivos da lista. Um arquivo novo não entra na gestão automaticamente — ele precisa ser adicionado.
Escolha o modo de lista se a pasta contém cópias de bancos, bancos de teste ou outros arquivos que não precisam ser replicados.
3.2. Antes de começar: verificar permissões
O usuário sob o qual o Firebird e o nó executam (firebird no Linux,
LocalSystem no Windows) precisa ter permissões de leitura e escrita em:
a pasta raiz dos bancos e os arquivos dos bancos;
replication.conf e a pasta dele (o nó substitui o arquivo por um arquivo temporário);
as pastas de segmentos <database>.ReplLog e <database>.LogArch (o nó as cria sozinho).
O RCM verifica as permissões antes do registro (preflight). Se a verificação falhar,
o comando termina com o erro preflight failed on <node> e uma lista de caminhos.
Abra a página de registro do nó mestre. O link está disponível em dois lugares:
Bancos de dados → tabela Nós → coluna de ações →
Registrar;
Visão geral → cartão do nó mestre → Registrar bancos.
Um nó réplica não tem esta página.
O formulário mostra as regras atuais do nó (o próprio nó as enviou). Se o nó
não responde, os botões de pré-visualização e de registro ficam desativados: sem as regras atuais
eles zerariam as listas de inclusão e exclusão.
Preencha ou corrija os campos: Caminho da pasta neste servidor,
recursivo, máscaras, Filtro de tamanho, Tabelas de acompanhamento da
sincronização.
O campo Tabelas de acompanhamento da sincronização:
com o HQbird 2027.2.24 e posteriores — a lista é por banco que esta ação
vai registrar. Campo vazio: o banco usa as tabelas da própria publicação. O registro não altera a lista compartilhada do nó
(sync_tables). Se ela existir, o formulário diz isso: um banco sem a própria lista a usa
em vez da publicação.
A lista de um banco já gerido é definida na página dele: Bancos de dados →
banco mestre → bloco Tabelas de acompanhamento da sincronização. O bloco
mostra qual lista está em vigor. Um campo vazio remove a lista própria do banco;
no RCM e no nó 2027.5.7 — uma única lista para todos os bancos do nó
(sync_tables).
Clique em Pré-visualizar. O nó mostrará todos os arquivos que correspondem à máscara de
inclusão. Ele não altera nada.
Confira a lista. Cada arquivo tem uma caixa de seleção:
marcada — o arquivo será gerido;
marcada, bloqueada, com a marca já gerido — o banco já está
registrado;
bloqueada com um motivo — o arquivo é excluído por máscara, tamanho ou pela lista de
exclusão. Para incluí-lo, altere a regra.
Marque os bancos necessários e clique em Registrar
os selecionados. O RCM pedirá confirmação e mostrará o número de arquivos.
Confirmação do registro
O que este botão faz:
no modo de máscara — arquivos sem caixa de seleção são adicionados à lista de exclusão, arquivos com
caixa de seleção são removidos dela;
no modo de lista — arquivos com caixa de seleção são adicionados à lista de inclusão.
O botão adiciona bancos aos que já estão na gestão. Ele não altera
linhas bloqueadas.
7. O botão Registrar aplica o formulário sem alterar
as listas.
8. Espere a mensagem de conclusão e o número de bancos adicionados. Se não houver
resposta por muito tempo, verifique o resultado na página Comandos.
Com o HQbird 2027.2.24 e posteriores a mensagem é “Registrados: N”. Se o Firebird do mestre
precisar ser reiniciado, o RCM diz qual botão pressionar (em geral
Reiniciar o Firebird do mestre na linha do banco) e fornece um link para os bancos
mestres.
O RCM 2027.5.7 pode dizer “Nenhum banco novo adequado”, mesmo que bancos
tenham sido adicionados: verifique a página Bancos de dados.
Resultado do registro
Se nenhum banco for encontrado depois do registro, mas o nó já tinha bancos, o nó
recusa (409) e devolve as regras antigas. Assim um erro no caminho não desativa
a replicação de todos os bancos.
Nota: o comando envia somente os campos dos seus parâmetros. As demais
regras (máscaras, tamanhos, listas de inclusão e exclusão, sync_tables) serão zeradas pelo
nó. O comando não tem parâmetros para essas regras. Antes de
executar o comando, verifique as regras atuais (hqbirdrcm getconfig -node node-a). Se
elas estiverem definidas, use a página de registro.
3.4. O que acontece depois do registro
O nó grava as regras em node.json.
O nó varre a pasta (scansync).
Para cada banco encontrado, o nó grava um bloco na própria área de
replication.conf (entre as linhas # BEGIN managed-by:node-a role:master e
# END …) e cria as pastas <database>.ReplLog e <database>.LogArch. O nó não modifica texto fora da própria área.
Antes de fazer uma alteração, o nó salva uma cópia do arquivo:
replication_YYYYMMDD_hhmmss_NNN.conf.
Se replication.conf mudou, os bancos entram no
estado PENDING_RESTART: o Firebird só lerá o arquivo novo depois de um
reinício. Na tabela Nós isso aparece na coluna Reinício
pendente.
A coluna “Reinício pendente” na tabela “Nós”
Estados de um banco novo:
Estado
Grupo no RCM
Significado
UNCONFIGURED
Pendente
banco encontrado, configuração ainda não gravada
PENDING_RESTART
Pendente
configuração gravada, reinício do Firebird necessário
CONFIGURED
Pendente
Firebird reiniciado, banco pronto para publicação e inicialização
3.5. Reinício do Firebird do mestre
O nó mestre nunca reinicia o Firebird sozinho. O RCM também não. Reiniciar
o mestre é decisão do operador: um reinício derruba todas as conexões de
todos os bancos dessa instância do Firebird.
Escolha um horário de baixa carga e clique em um dos botões:
Reiniciar o Firebird do mestre — na página Bancos de dados, na linha do
mestre do banco que aguarda um reinício;
o mesmo botão na janela Inicializar, capítulo 5;
Reiniciar o Firebird — na página do banco.
O RCM pedirá confirmação. Ele mostra o nome do nó e um aviso: o Firebird
reiniciará imediatamente, sem janela de reinício, e todas as conexões serão derrubadas.
Confirmação do reinício do Firebird do mestre
O mesmo pela linha de comando
Command
hqbirdrcm restartfirebird -node node-a
Este comando também reinicia imediatamente, sem janela de reinício.
Como o nó reinicia o Firebird:
Verifica se o fbagent responde e gere a mesma instância
(identificador, porta, nome do serviço de node.json). Se algum valor não
coincidir, o nó recusa.
Pede ao fbagent que reinicie o Firebird.
Espera o Firebird responder na porta dele.
Move os bancos de PENDING_RESTART para CONFIGURED.
Várias instâncias do HQbird em um host. O fbagent reinicia os serviços listados em
firebird.update.services da sua configuração. Uma lista vazia significa todos
os serviços do HQbird no host. Se houver duas instâncias do HQbird no host, deixe
somente o serviço da sua instância na lista. Caso contrário, reiniciar um nó
também parará a outra instância.
No Windows. Se replication.log cresceu até log_portion_mb ou mais,
o reinício segue assim: parar o Firebird → arquivar o log → iniciar.
3.6. Um banco que já é replicado manualmente
Se a replicação já está configurada manualmente para um banco (o próprio bloco em
replication.conf, publicação ativada, segmentos fluindo), ele pode entrar na
gestão sem reinicializar a réplica. Para isso existe o
modo detect_existing (somente mestre).
Na resposta, taken_over lista os bancos que serão migrados. Adicione -verbose
para ver os bancos ignorados com o motivo.
Se a lista estiver correta, execute o comando sem -dry-run.
O nó migra um bloco somente se:
as pastas de segmentos se chamam exatamente <database>.ReplLog e <database>.LogArch;
já existem segmentos no arquivo;
a publicação está ativada no banco.
O nó não migra um bloco com caminhos diferentes e o informa como “encontrado, mas
não suportado”.
Depois da migração os bancos ficam em PENDING_RESTART, mesmo que as configurações de replicação
não mudem: somente a posição do bloco no arquivo muda. Reinicie o Firebird em uma
janela de manutenção.
3.7. Como verificar
Bancos de dados: o banco aparece na linha do nó mestre, estado CONFIGURED
(depois do reinício).
Ao lado do banco pode haver um ícone publicação DESLIGADA: a publicação ainda
não está ativada. Isso é normal; a publicação é o passo seguinte (capítulo 6).
Banco novo na linha do mestre
No host do nó: o bloco do banco está presente em replication.conf dentro da
área managed-by:node-a, e ao lado do banco há as pastas .ReplLog e .LogArch.
3.8. Remover um banco da gestão
O modo habitual é o botão. Na página Bancos de dados, marque os bancos,
selecione a ação em massa Remover da gestão e
clique em Aplicar aos selecionados. O RCM:
adiciona os arquivos à lista de exclusão do nó;
varre a pasta uma vez: os blocos dos bancos são removidos de replication.conf;
apaga os registros dos bancos no nó.
Os arquivos dos bancos e as pastas de segmentos permanecem no disco. O Firebird não é reiniciado.
O Firebird continua a gravar os segmentos do banco até o próximo reinício;
o RCM dirá se um reinício é necessário.
O RCM recusará (has_replicas) um banco mestre que tenha uma réplica viva:
caso contrário a réplica pararia em silêncio. Primeiro transforme a réplica em um banco comum ou
remova-a (capítulo 8).
Não apague o bloco do banco de replication.conf manualmente: na próxima
varredura o nó o gravará de novo.
Se o arquivo do banco desapareceu ou foi excluído por uma regra. Então o banco fica
no estado ORPHANED (o grupo Órfão). O nó mantém o registro e o arquivo de
segmentos: um banco ausente é mais vezes um engano do que uma decisão. Se o arquivo voltar, o banco
volta a funcionar e o alerta é limpo. Para excluir esse banco de forma permanente,
faça dois passos nesta ordem:
Depois de forgetdatabase o comando cleanuparchive não encontrará mais o banco. Os dois
comandos funcionam somente para um banco no estado ORPHANED e não tocam no arquivo do
banco.
Cuidado. Depois de promover uma réplica a mestre (capítulo 8), não execute
cleanuparchive -orphaned para o registro antigo: o novo mestre usa a mesma
pasta .LogArch, e o comando apagará o arquivo de trabalho dele.
3.9. Alteração da raiz dos bancos
O registro com outro caminho é permitido. O nó:
adiciona bancos da pasta nova;
move para ORPHANED os bancos da pasta antiga que não estão na nova (notificação
orphaned_database) e mantém os arquivos deles.
Se você escolheu a pasta errada, registre a pasta correta de novo. Um banco com o
mesmo caminho completo continuará a operar sob o mesmo db_id. Um banco em um caminho diferente
é um banco novo (novo db_id); a réplica dele precisa ser inicializada de novo.
3.10. Erros comuns
O que você vê
Causa
O que fazer
preflight failed on node-a
sem permissões nas pastas
corrija as permissões, tente de novo (3.2)
409 scan_would_empty_region
a pasta nova não contém bancos, mas o nó tinha alguns
verifique o caminho e a máscara
A pré-visualização está vazia
a máscara não corresponde ou a pasta está errada
verifique o caminho, a máscara, “recursivo”
Os botões estão desativados, “Falha ao ler a configuração do nó”
o nó não responde
verifique o serviço do nó e a rede (capítulo 1)
O banco permanece em PENDING_RESTART por muito tempo
o mestre não reinicia o Firebird sozinho
reinicie o Firebird (3.5)
Reinício recusado por causa do fbagent
o fbagent não está em execução ou os dados dele não coincidem com node.json
capítulo 1, verificação do fbagent
O arquivo novo não apareceu
o nó está no modo de lista
adicione o arquivo por “Registrar os selecionados”
4. Como tornar um banco uma réplica: etapas e local no disco
Este capítulo cobre toda a jornada de um banco do primário até uma réplica em funcionamento, mais o cálculo de espaço em disco. A própria inicialização está descrita em detalhe no capítulo 5.
4.1. A regra principal
Um banco aparece em uma réplica somente pela inicialização a partir do mestre (reinit):
o próprio nó mestre transfere uma cópia pelo nbackup.
Não faça uma cópia manualmente:
gbak cria um GUID novo de banco e zera o número do segmento. O vínculo
mestre — réplica se quebra.
Uma cópia de arquivo de um banco em execução não é consistente, e o RCM verá dois bancos com o mesmo
GUID (duplicate_guid) e proibirá a inicialização.
Uma réplica já em execução configurada manualmente pode ser tomada sob
gestão sem uma cópia nova — veja 4.6.
4.2. Etapas
Nº
Etapa
Onde
Estado do banco mestre depois da etapa
1
Registro do banco no mestre
capítulo 3.3
PENDING_RESTART
2
Reinício do Firebird do mestre
capítulo 3.5
CONFIGURED
3
Sincronização da publicação
capítulo 6
CONFIGURED, publicação LIGADA
4
Preparação da réplica: pasta, permissões, versão do Firebird
4.3
—
5
Verificação do espaço livre no mestre e na réplica
4.4
—
6
Inicialização
capítulo 5
SEEDING → IN_SYNC
7
Reinício do Firebird da réplica (se necessário)
capítulo 5.6
a réplica começa a aplicar segmentos
8
Verificação dos dados
capítulo 5.10
—
A etapa 3 é obrigatória para o Firebird 4/5. Sem publicação, o Firebird do mestre não grava
alterações de tabelas nos segmentos, e a réplica fica silenciosamente atrás do mestre. Na
página Bancos de dados esse banco é marcado com o ícone publicação DESLIGADA. Clique em
Sincronizar publicação antes da inicialização.
A partir do HQbird 2027.2.24, a janela Inicializar avisa sobre isso e
oferece um botão Sincronizar publicação e inicializar, enquanto o nó
mestre recusa a inicialização com o erro publication_off (capítulo 5.1).
O RCM e o nó 2027.5.7 não verificam a publicação.
HQbird 2.5/3.0. Não há publicações, por isso a etapa 3 é pulada. O conjunto de tabelas é definido pelos
filtros do plugin replconf (capítulo 6).
Estados do banco:
Estado
Grupo no RCM
Significado
CONFIGURED
Pendente
o Firebird leu as configurações, ainda não há réplica
PUBLISHING
Pendente
a sincronização da publicação está em andamento
SEEDING
Pendente
a inicialização está em andamento
IN_SYNC
Ok
a réplica recebeu todos os segmentos
LAGGING
Pendente
a réplica está atrasada, os segmentos estão na fila
NEEDS_REINIT
Erro
a réplica precisa ser inicializada de novo
FAILED
Erro
a última inicialização falhou
4.3. Preparação da réplica
Pasta dos bancos da réplica
O nó réplica coloca cada banco na própria pasta databases.root no caminho:
Code
<databases.root>/<master node name>/<database path relative to the master root>
Exemplo: mestre node-a com raiz /databases/master e banco
/databases/master/sales/employee.fdb. Na réplica node-b com raiz
/databases/replica, o banco ficará aqui:
Code
/databases/replica/node-a/sales/employee.fdb
Assim, bancos com os mesmos nomes de mestres diferentes não colidem.
Ninguém cria a pasta raiz automaticamente — nem o instalador, nem o HQCenter Admin, nem o nó na
inicialização. Crie-a de uma das formas seguintes:
na janela Inicializar: o campo Pasta da réplica, o
botão Criar pasta. O botão só aparece quando a pasta não existe. Com o HQbird 2027.2.24,
se o nó réplica ainda não tem databases.root, o campo já contém
/databases/replica/<id do nó réplica>. Para uma réplica no Windows o campo fica vazio:
informe uma pasta com letra de unidade. Cada nó réplica no mesmo host precisa da própria
pasta. A pasta é criada pelo nó
réplica: dono — firebird (ou o usuário do serviço do nó), permissões
2770. Se o nó não conseguir criá-la, a janela mostrará o comando para o host da
réplica. Se você informar outra pasta, o RCM a gravará em databases.root do nó réplica
antes da inicialização;
O bit setgid (2770) é necessário para que todos os arquivos internos recebam o grupo do Firebird.
Você só pode alterar a raiz da réplica enquanto ela não tem bancos: caso contrário os bancos antigos
ficarão fora da varredura. Para colocar um único banco em outro local, use
Mover na página do banco.
Permissões
O nó réplica e o Firebird precisam poder gravar na raiz dos bancos. O nó verifica se
os arquivos colocados receberão o grupo da pasta. Se não puder — recusa com
ownership_unfixable e um texto de como corrigir (em geral o serviço do nó executa com
Group=root).
Com o HQbird 2027.2.24, a janela Inicializar também mostra uma pasta que
existe mas na qual o serviço do nó não pode gravar: o texto do nó com o comando de
correção e um botão Verificar de novo. O RCM 2027.5.7 nesse caso diz
“A pasta existe”: verifique as permissões você mesmo (hqbirdrcm checkpermissions -node <replica> -root <folder>).
Versão do Firebird
A versão principal do Firebird na réplica precisa coincidir com a do mestre (5.0 → 5.0,
4.0 → 4.0). Caso contrário a réplica recusará antes de qualquer transferência de dados:
incompatible_engine.
Conectividade
O nó réplica precisa ser um par do mestre, e o mestre precisa ser um par da réplica (capítulo 2).
Caso contrário o RCM não oferecerá este nó na janela Inicializar.
4.4. Quanto espaço é necessário
Em resumo
Onde
O quê
Quanto
Mestre, volume do banco
livre antes da inicialização
≥ 105 % do tamanho do banco
Réplica, volume da pasta do banco
livre antes da inicialização
≥ 105 % do tamanho do banco, com o HQbird 2027.2.24 — mais free_space_floor_gb (mais o arquivo antigo, se a réplica já existia; com a caixa Remover a réplica antiga — sem ele)
Mestre, <database>.ReplLog
segmentos de trabalho do Firebird
até 64 segmentos × tamanho do segmento (16 MB por padrão) ≈ 1 GB por banco
Mestre, <database>.LogArch
arquivo de segmentos para as réplicas
alterações ao longo de retention_days (padrão 2 dias) + o que as réplicas ainda não confirmaram
Réplica, <database>.Incoming
fila de segmentos a aplicar
até 256 segmentos × 16 MB ≈ 4 GB por banco no pior caso
Réplica, volume inteiro
margem
pelo menos free_space_floor_gb (padrão 1 GB)
Verificação de espaço antes da inicialização
A inicialização verifica o espaço duas vezes e somente antes de bloquear o banco:
RCM — a partir das estatísticas mais recentes do nó, antes de enviar o comando. Se o espaço
for claramente insuficiente, o RCM devolve imediatamente o erro 507.
Nó mestre — uma medição ao vivo no próprio volume, depois um pedido à réplica para que
ela meça o dela. Se faltar em pelo menos um lado, a inicialização
termina no passo VERIFICAÇÃO DE ESPAÇO com o erro
insufficient disk space on master ou … on replica.
A exigência dos dois lados é 105 % do tamanho do banco mestre.
Com o HQbird 2027.2.24 o nó réplica calcula assim:
ele precisa de 105 % do tamanho do banco mais o free_space_floor_gb da réplica (7.3):
depois da inicialização permanece no volume uma reserva para segmentos;
sobras de inicializações anteriores (<database>.hqcluster-part, <database>.new)
contam como espaço livre: o nó as apaga antes da cópia nova;
o texto do erro nomeia todos os números. Ele também nomeia os arquivos
<database>.pre-reinit-*.fdb e <database>.failed-seed-*.fdb com o tamanho deles. O nó
nunca os apaga: apague-os você mesmo se não forem necessários.
force (forçado) pula somente a verificação no RCM. A verificação do nó
não pode ser contornada: ela protege o nó de ficar sem disco no meio da cópia.
Se o espaço for insuficiente somente por causa da cópia antiga da réplica, o RCM 2027.2.24 no
erro 507 nomeia a caixa Remover a réplica antiga em vez de force. Para
isso, os dois nós precisam ser HQbird 2027.2.24 ou mais novos. Caso contrário o erro nomeia
o nó que precisa de atualização, e force.
Por que tanto
Mestre. Durante a cópia o banco é bloqueado por nbackup -L. Todas as
alterações são gravadas no arquivo <database>.delta ao lado do banco. O tamanho de .delta depende
da carga de escrita durante a cópia. Sob carga pesada e transferência lenta
ele pode crescer bastante — acompanhe o espaço durante a primeira
inicialização.
Réplica. A cópia é gravada direto no arquivo <database>.hqcluster-part ao lado
do local do banco. O nó reserva o tamanho completo de antemão. O arquivo é então verificado,
reparado (nbackup -FIXUP -SEQUENCE) e renomeado para o lugar. Uma segunda
cópia não é necessária — o tamanho do banco é necessário uma vez, no volume do banco.
Se a réplica já existia (inicialização repetida), o arquivo antigo fica no
disco até o último passo. Isso significa que o arquivo antigo e a cópia nova são necessários no volume
ao mesmo tempo. O espaço livre é calculado sem o arquivo antigo — portanto a exigência
é a mesma: 105 % do tamanho do banco livres.
Remover a réplica antiga (com o HQbird 2027.2.24). Se não houver espaço no volume da réplica
para a cópia nova ao lado da antiga, marque esta caixa na janela de inicialização
(capítulo 5.1). O nó réplica então apaga a cópia antiga e os
segmentos de entrada (.Incoming) antes da transferência, e o volume tem o bastante para 105 % do
tamanho do banco mais free_space_floor_gb. O nó apaga a cópia somente se todas as condições
forem verdadeiras:
sem a exclusão não há espaço bastante, e com a exclusão há;
é uma cópia instalada pela inicialização deste nó: o cabeçalho
é legível, o modo é réplica somente leitura;
o banco não foi tornado normal (não há arquivo <database>.hqcluster-normal.json, capítulo 8);
overwrite_non_replica não está definido (5.9).
Caso contrário o nó não apaga nada e recusa com o motivo no texto. Para apagar,
o nó para o Firebird da réplica durante a exclusão (5.6).
A caixa fica desligada por padrão. Risco: enquanto a transferência está em andamento, não há
cópia do banco na réplica. Se o banco tem somente uma réplica, o mestre fica desprotegido
o tempo todo. Enquanto não há cópia nova, o banco na réplica está no estado NEEDS_REINIT (não FAILED e
não ORPHANED), e a réplica emite o alerta replica_removed_for_reinit
(warn). Quando a cópia nova está no lugar, o alerta é limpo. Se a inicialização
falhar depois da exclusão, o par permanece em NEEDS_REINIT: inicie a
inicialização de novo (ou a reinicialização automática a iniciará, 5.8).
Uma inicialização nova transfere o banco desde o início.
Arquivo do mestre (.LogArch). O nó guarda os segmentos enviados por
retention_days dias para que a réplica possa pedi-los de novo. Segmentos
que a réplica ainda não aplicou são guardados por mais tempo. Se o espaço está baixo, o nó
limpa o arquivo em etapas:
segmentos aplicados por todas as réplicas mais antigos que retention_days;
segmentos aplicados que são mais novos (quando o espaço está curto);
segmentos não aplicados — somente como último recurso. Então a réplica
perde os segmentos de que precisa e fica em NEEDS_REINIT.
Se uma réplica fica indisponível por muito tempo, o arquivo cresce. O volume dele = as alterações do banco ao longo do
período de indisponibilidade.
Exemplo de cálculo
Banco de 100 GB. Carga — 5 GB de segmentos por dia. A inicialização corre
à noite, a cópia leva 2 horas, durante as quais cerca de
2 GB vão parar em .delta.
Onde
Cálculo
Total livre
Mestre, volume do banco
105 GB para as verificações (inclui o crescimento de .delta) + .ReplLog 1 GB + .LogArch 2 dias × 5 GB = 10 GB
≥ 116 GB
Réplica, banco novo
105 GB + .Incoming até 4 GB + 1 GB de reserva
≥ 110 GB
Réplica, inicialização repetida
arquivo antigo de 100 GB já no disco + 110 GB livres
volume ≥ 210 GB
Réplica, inicialização repetida com a caixa Remover a réplica antiga (com o HQbird 2027.2.24)
arquivo antigo apagado antes da transferência: 105 GB + .Incoming até 4 GB + 1 GB de reserva
volume ≥ 110 GB
Acrescente uma reserva para o crescimento do banco e para a indisponibilidade da réplica (o arquivo do mestre cresce
5 GB por dia de indisponibilidade).
Segmentos em um volume separado
As pastas .ReplLog, .LogArch e .Incoming ficam por padrão ao lado do banco.
Elas podem ser movidas para outro volume: o parâmetro segments.storage em node.json
(com mirror_hierarchy: true o nó replica a estrutura das pastas dos bancos). Então
o arquivo não tira espaço dos bancos. A verificação de 105 % continua a valer para o volume do banco.
Onde ver o espaço
Bancos de dados → Nós e Visão geral: o ícone de espaço livre do
volume de databases.root. Amarelo — menos de 20 %, vermelho — menos de 10 %.
Página Bancos de dados: a coluna Disco na tabela Nós
Relatório do cluster: hqbirdrcm report.
4.5. Várias réplicas de um banco
A segunda réplica e as seguintes são criadas do mesmo modo: Inicializar na linha do mestre, selecionando um nó réplica livre.
Enquanto uma réplica nova está sendo inicializada, o mestre não transmite este banco às réplicas já em execução. Elas alcançarão o mestre depois que a inicialização terminar. A janela de confirmação diz isso.
Um banco — uma inicialização de cada vez, mesmo para réplicas diferentes.
O espaço no mestre é verificado separadamente para cada inicialização.
Banco mestre com duas réplicas
4.6. Réplica configurada manualmente
Se uma réplica já está em execução a partir de um replication.conf escrito à mão, você pode tomá-la sob gestão e não copiar o banco de novo:
Mestre: registre os bancos com detect_existing (capítulo 3.6).
Réplica:Bancos de dados → nó réplica → Assumir, ou hqbirdrcm takeover-replica. O RCM encontrará os blocos da réplica, combinará os arquivos com os bancos mestres pelo GUID e mostrará para cada um: in_sync, resumable ou needs_reinit.
Confirme as linhas. O nó moverá os blocos para a própria área de replication.conf.
Reinicie o Firebird da réplica para que ele leia os blocos movidos.
Inicialize somente as linhas needs_reinit: o arquivo do mestre já não contém os segmentos exigidos por essas réplicas.
4.7. Erros comuns
O que você vê
Causa
O que fazer
insufficient disk space on master / on replica
espaço insuficiente (4.4). Na reinicialização a cópia antiga ocupa espaço até o fim (4.4)
libere espaço, tente de novo. A segunda saída na réplica (a partir do HQbird 2027.2.24) é a caixa Remover a réplica antiga (4.4, 5.1)
507 do RCM imediatamente
segundo as estatísticas de espaço claramente não há o bastante
o mesmo. Se há espaço sem a cópia antiga, o RCM 2027.2.24 nomeia a caixa Remover a réplica antiga
incompatible_engine
versões principais do Firebird diferentes
atualize o Firebird da réplica
Pasta ausente no nó réplica
raiz não criada
Criar pasta na janela de inicialização (4.3)
A pasta existe, mas o serviço do nó não pode gravar nela (a partir do HQbird 2027.2.24)
sem permissões de escrita
execute o comando da janela, clique em Verificar de novo (4.3)
publication_off (a partir do HQbird 2027.2.24)
a publicação do mestre está desativada ou não tem tabelas
Sincronizar publicação e inicializar (5.1)
ownership_unfixable
o serviço do nó tem um grupo estranho
corrija o grupo do serviço como descrito no texto do erro
duplicate_guid
dois bancos com o mesmo GUID (uma cópia de arquivo)
remova a cópia ou dê a ela um GUID novo (nbackup -F)
Nó réplica ausente da lista Inicializar
sem conexão nos pares
capítulo 2
Réplica IN_SYNC, mas os dados divergem
a publicação estava desativada
sincronize a publicação e depois repita a inicialização
5. Inicialização (reinit)
A inicialização é a transferência de uma cópia do banco mestre para a réplica. A primeira transferência
se chama inicialização (o botão Inicializar); uma transferência repetida é
reinicialização (o botão Reinicializar). O mecanismo é o mesmo.
Antes de começar, conclua os passos 1–5 do capítulo 4:
o banco está registrado, o Firebird do mestre foi reiniciado, a publicação está ativada,
a pasta da réplica existe e há espaço bastante. Quanto espaço é necessário no mestre e na
réplica está descrito no capítulo 4.4.
5.1. Como começar
Publicação primeiro. Registrar um banco não inclui a publicação. Sem
publicação, a réplica não recebe alterações. Antes da inicialização, execute
Sincronizar publicação (capítulo 6) ou
hqbirdrcm setpublication -node <master>.
Com o HQbird 2027.2.24, a janela de inicialização verifica a publicação. Se
ela está desligada ou não tem tabelas com chave, a janela mostra um
aviso e um botão Sincronizar publicação e
inicializar. O RCM sincroniza a publicação, espera o comando terminar e
inicia a inicialização com a seleção da janela.
Um nó mestre 2027.2.24 recusa sozinho essa inicialização (e a primeira
também) com o erro publication_off e emite a notificação
master_publication_off (capítulo 6.1). Depois da recusa, a célula do banco volta a
ter o botão Sincronizar publicação e inicializar.
Se o operador desligou a publicação (6.4) ou removeu dela todas as tabelas com
chave (6.3), a sincronização preserva isso. O RCM não inicia a
inicialização e fornece um link para a página Tabelas da publicação.
O RCM e o nó 2027.5.7 não verificam a publicação: a inicialização
tem sucesso, o banco mostra “OK” no RCM, mas a réplica não recebe alterações. Se
a publicação foi ligada depois da inicialização — reinicialize o banco.
A janela "Reinicializar o banco?"
Abra Bancos de dados.
Na linha do banco mestre, na coluna do nó réplica, clique em Inicializar.
O nó réplica é definido pela coluna: ele não é selecionado na janela. Para um
par existente — Reinit no cartão expandido do mestre.
Na janela (com o HQbird 2027.2.24 o título para um par novo é “Inicializar
o banco?”; no RCM 2027.5.7 — “Reinicializar o banco?” também na
primeira inicialização):
verifique a Pasta da réplica. A janela mostra se a pasta existe. Se não
existe, clique em Criar pasta: o nó réplica a criará (4.3). Se o nó
não puder criá-la, a janela mostra o comando para o host da réplica. Com o HQbird
2027.2.24 a janela também mostra uma pasta na qual o serviço do nó não pode
gravar: o comando de correção e um botão Verificar de novo;
selecione o Método de reinit: Suave (recomendado) ou Padrão
(5.4). Com o HQbird 2027.2.24, se o arquivo do mestre ainda não tem segmentos
(em geral antes da primeira inicialização), a janela mostra uma dica: em um
banco ocupado Padrão é mais rápido;
se o banco mestre ainda espera um reinício do Firebird, a janela dirá isso e
mostrará um botão Reiniciar o Firebird do mestre. Sem o reinício o banco
não é replicado;
Remover a réplica antiga (com o HQbird 2027.2.24, desligada por padrão)
só é necessária na reinicialização quando o volume da réplica não tem
espaço para uma cópia nova ao lado da antiga (4.4). A janela mostra os
números de antemão: quanto é necessário, quanto está livre, quanto a cópia antiga ocupa.
Se há espaço sem a cópia antiga, a janela pede que você marque a caixa. A caixa
fica inativa se o nó mestre ou réplica é uma versão antiga: a janela indica
qual nó atualizar. Até a cópia nova estar pronta, a réplica não tem cópia deste
banco (4.4).
Confirme. O RCM informará que o banco será bloqueado no mestre e
copiado para a réplica.
O progresso da inicialização é visível no cartão expandido do mestre na página Bancos de dados:
passos e porcentagens. Com o HQbird 2027.2.24 o progresso também fica visível depois de atualizar
a página: na primeira inicialização — na célula do nó réplica, e também na
linha Progresso da reinicialização na página do banco mestre. O
botão Inicializar fica inativo enquanto o nó mestre está copiando o banco. Se o RCM não está
acompanhando esta inicialização (por exemplo, ela foi iniciada pela linha de comando do nó),
os passos são tomados do estado do nó, sem porcentagens. No RCM 2027.5.7, depois de
atualizar a página o progresso da primeira inicialização não fica visível: espere até o banco
mestre sair de SEEDING.
Passos da inicialização na linha do mestre
Cada comando do RCM (inicialização, reinício do Firebird, sincronização da
publicação) é registrado na página Comandos com o resultado.
A página "Comandos"
O mesmo pela linha de comando
Command
# one databasehqbirdrcm reinit -node node-a -db <db_id> -to node-b
# all master databaseshqbirdrcm reinit -node node-a -all -to node-b
Parâmetros: -mode smooth|standard (padrão smooth), -hold=false
(não reter o arquivo durante transações longas), -allow-restart (5.6),
-force (5.9).
-remove-old-replica (com o HQbird 2027.2.24) — o mesmo que a caixa Excluir
a réplica antiga. Somente para um banco: -db e -to são obrigatórios; com
-all o comando recusa. Se o nó mestre ou réplica é uma versão antiga, o RCM
recusa com node_too_old e não envia nada.
-all tenta todos os bancos e coleta os erros em vez de parar no primeiro.
5.2. Passos
Nº
Passo (no RCM)
O que acontece
1
VERIFICAÇÃO DE ESPAÇO
verifica o espaço no mestre e na réplica (capítulo 4.4); a réplica verifica de antemão que pode aceitar o arquivo
2
BLOQUEIO
nbackup -L: o arquivo do banco mestre é congelado, as alterações vão para <database>.delta
3
CÓPIA PARA O NÓ
o arquivo é transferido em partes: leitura → soma de verificação → compressão → envio
4
DESBLOQUEIO
nbackup -N imediatamente depois da transferência: as alterações de .delta voltam ao banco
5
SEMEADURA
na réplica: verificação da soma de verificação do arquivo, nbackup -FIXUP -SEQUENCE, instalação do arquivo, gfix -replica, gravação do bloco em replication.conf
6
REINÍCIO DA RÉPLICA
reinício do Firebird da réplica, se for necessário (5.6)
Depois do passo 6 o banco fica no estado IN_SYNC. O mestre continua a enviar
segmentos a partir do ponto em que a cópia termina.
O que é importante saber:
O mestre executa o tempo todo. Os usuários gravam no banco, as alterações vão para
.delta. O bloqueio é liberado imediatamente depois da transferência.
As transações que coincidiram com o bloqueio não se perdem. O nó encontra
as transações abertas no momento de nbackup -L, e a réplica as reproduz a partir
dos segmentos.
A transferência continua depois de uma interrupção. Se a conexão ou o nó réplica
reiniciou, o mestre continuará a partir da última parte recebida. Uma transferência
inacabada é guardada na réplica por 24 horas (reinit_partial_keep_hours).
Em um erro o nó libera o bloqueio, apaga o arquivo inacabado na
réplica e coloca o banco em FAILED. A tentativa seguinte começa de um estado
conhecido.
Com a caixa “Excluir a réplica antiga” (a partir do HQbird 2027.2.24) a réplica
apaga a cópia antiga depois do passo BLOQUEIO, antes da transferência. O passo CÓPIA PARA O
NÓ nesse momento mostra “removendo a cópia antiga da réplica para liberar
espaço”. Um erro depois da exclusão dá ao par NEEDS_REINIT em vez de FAILED
(capítulo 4.4).
Somente nbackup. O gbak não é usado: ele altera o GUID do banco.
5.3. Impacto na operação
O quê
Impacto
Usuários do mestre
continuam a trabalhar; durante a cópia .delta cresce, depois de -N as alterações são transferidas para o banco
Outras réplicas deste banco
não recebem segmentos deste banco enquanto a inicialização está em andamento; elas alcançam depois
Outros bancos do mestre
não são afetados
Firebird da réplica, banco novo
não é parado; reinício conforme 5.6
Firebird da réplica, inicialização repetida
é parado enquanto o arquivo é substituído: todos os bancos deste Firebird ficam indisponíveis por segundos
Firebird da réplica, o nó apaga a cópia antiga (caixa “Excluir a réplica antiga”, a partir do HQbird 2027.2.24)
é parado mais cedo, enquanto a exclusão está em andamento, antes da transferência. O nó instala a cópia nova sem uma segunda parada se o bloco do banco em replication.conf não mudou. Se há espaço bastante e não é necessária exclusão, o nó não apaga nada, e tudo segue como em uma inicialização repetida normal
Rede e disco
carga conforme os limites de velocidade (5.5)
No Windows. Um arquivo aberto pelo Firebird não pode ser substituído. Durante a inicialização
repetida o nó para o Firebird da réplica pelo fbagent, instala o
arquivo e inicia o Firebird de novo. No Linux o Firebird também é parado antes da
substituição: caso contrário ele continuaria a trabalhar com o arquivo antigo excluído.
5.4. Métodos suave e padrão
Suave (padrão). Antes do bloqueio, o nó procura transações longas: transações de escrita do usuário que começaram antes do segmento mais antigo no arquivo do mestre. Depois da inicialização a réplica não poderá reproduzi-las e parará na primeira alteração delas (“A transação … não foi encontrada”). Transações sem alterações não são contadas.
Se essas transações existem, a inicialização não começa: o RCM mostra O reinit suave está aguardando transações longas e fornece um link Abrir a lista.
Página de transações longas: nenhuma transação longa
Na página Transações longas:
resumo: quantas transações e conexões, o segmento mais antigo;
5 principais conexões com as transações mais antigas: usuário, cliente, início, idade, alterações, consulta atual;
Reter segmentos / Liberar a retenção — enquanto a retenção está ativada, o arquivo do mestre não é purgado e o histórico não é truncado;
Desconectar os selecionados e repetir o reinit — desconecta as conexões (as transações delas são desfeitas) e inicia imediatamente um reinit suave;
Repetir o reinit, Verificar de novo.
A retenção é ativada automaticamente quando um reinit é recusado por causa de transações longas. Ela é liberada depois de uma inicialização bem-sucedida, manualmente, ou quando o arquivo cresce até reinit_hold_max_segments (1000 segmentos por padrão, notificação retention_hold_released).
Padrão bloqueia o banco imediatamente, sem verificação. Use-o somente se você sabe que não há transações de escrita longas.
Primeira inicialização sob carga. Enquanto o arquivo do mestre está vazio, não há segmento com o qual comparar.
Com um nó mestre HQbird 2027.2.24: se o nó ativou a publicação sozinho e o arquivo não mudou desde então, o histórico começa no momento em que a publicação foi ativada. Uma transação iniciada depois entra no journal a partir da primeira alteração e não interfere no método suave. Uma transação iniciada antes não entrou no journal: o reinit espera por ela antes do bloqueio (6 tentativas a cada 10 s), e o passo locking mostra o número, a conexão e o usuário dela. Se ela não terminou, o reinit termina com o erro reinit_pre_publication_transactions: termine-a e tente de novo. A página Transações longas mostra essas transações na tabela Transações iniciadas antes de a publicação ser ativada.
Se a publicação foi ativada manualmente, não pelo nó, ou o arquivo já mudou, o início do histórico é desconhecido. Nesse caso o método suave recusa se qualquer transação de escrita está aberta, e a mensagem diz que o arquivo ainda não contém um segmento. Nesse caso o RCM 2027.2.24 não abre a lista, mas escreve o que fazer na célula do banco. Escolha Padrão ou tente de novo quando o Firebird arquivar o primeiro segmento.
Com um nó mestre 2027.5.7, o método suave recusa imediatamente na primeira inicialização de um banco que está sendo gravado: long_transactions … segment 0 (0001-01-01T00:00:00Z). Para a primeira inicialização desse banco, escolha Padrão.
Para as reinicializações seguintes o método suave funciona como de costume (o arquivo já existe).
Transações mais antigas que a publicação. O Firebird não grava nos segmentos uma transação que começou antes de a publicação ser ativada. Se o nó ativou a publicação, a inicialização espera (6 tentativas a cada 10 segundos) até que essas transações terminem; caso contrário termina com o erro reinit_pre_publication_transactions listando-as. Depois de sincronizar uma publicação que adicionou tabelas, reconecte as aplicações e depois inicie a inicialização.
5.5. Velocidade
Quando
Velocidade
Configuração
Dentro da janela de transferência windows.transfer_window (padrão 23:00-05:00)
constante
limits.reinit_window_mbps, padrão 100 MB/s
Fora da janela
fração da velocidade de disco medida
limits.reinit_day_disk_fraction, padrão 0,5
O nó recalcula o modo a cada 30 segundos: uma inicialização iniciada de dia acelerará sozinha à noite.
O nó mede a velocidade do disco com um teste. Para repetir o teste no host do mestre:
Tempo de inicialização ≈ tamanho do banco ÷ velocidade. Exemplo: 100 GB a 100 MB/s — cerca de 17 minutos de transferência pura; na prática é limitado pela rede ou pelo disco.
5.6. Reinício do Firebird da réplica
Um banco novo na réplica. O arquivo é colocado sem parar o Firebird. O Firebird
só lerá o bloco novo de replication.conf depois de um reinício. Até lá a
réplica não aplica nada. O passo REINÍCIO DA RÉPLICA mostra a espera:
Rótulo
O que significa
aguardando um reinício do Firebird na réplica, ele está agendado para …
o nó reiniciará o Firebird sozinho depois da última inicialização (reinit_restart_delay_sec), quando as outras inicializações tiverem terminado
… a janela de reinício está fechada, a próxima abrirá em …
espera da restart_window da réplica
… a última tentativa falhou, a próxima em …
tentará de novo mais tarde
a réplica não pode reiniciar o Firebird sozinha: reinicie-o manualmente
auto_restart: never, ou este Firebird também serve os bancos do mestre
O nó reinicia o Firebird uma vez depois de uma série de inicializações, não depois de
cada banco.
Para reiniciar manualmente, clique em Reiniciar o Firebird da réplica.
A espera termina depois de qualquer reinício bem-sucedido do Firebird ou quando
a réplica aplicou um segmento mais novo que a cópia.
Reinicialização em um Firebird que também serve os bancos do mestre.
O nó não para esse Firebird sozinho e recusa com
restart_not_allowed. Inicie a inicialização de novo e marque Permitir que
pare o Firebird para este reinit (-allow-restart na linha de
comando) — em um momento em que as conexões deste Firebird possam ser derrubadas, inclusive
as dos bancos mestres dele. Execute essas inicializações uma de cada vez por host.
Exclusão da cópia antiga (a caixa Remover a réplica antiga, com o HQbird
2027.2.24) também para o Firebird da réplica, pelas mesmas regras. Se
o nó não puder parar este Firebird sozinho, ele não apaga nada e
recusa com restart_not_allowed: marque também Permitir que <nó>
pare o Firebird para este reinit. Se nesse momento outra inicialização está
terminando na réplica ou o Firebird está reiniciando, o nó não apaga
nada e recusa com engine_busy: o mestre libera o bloqueio,
tente mais tarde.
5.7. Fila e inicializações simultâneas
Um banco — uma inicialização de cada vez (mesmo para réplicas diferentes). O botão Inicializar fica desativado enquanto uma inicialização deste banco está em andamento.
O nó mestre impõe limits.max_concurrent_reinits inicializações de bancos diferentes ao mesmo tempo (padrão 1). O resto espera na fila; a resposta contém a posição na fila.
Não execute o seu próprio nbackup -L (ou ALTER DATABASE BEGIN BACKUP) em um banco durante a inicialização dele, e não inicie uma inicialização durante esse backup: um banco só pode ter um bloqueio. A inicialização verifica isso e recusa com nbackup backup lock already active.
A fila e as transferências atuais são visíveis na página Transferência.
Página Transferência / filas
- Se um arquivo `.delta` permanecer depois de uma falha, certifique-se de que nenhum backup está em execução e execute `nbackup -N `. Não apague o `.delta` manualmente.
5.8. Reinicialização automática
O RCM pode reinicializar um banco no estado NEEDS_REINIT sozinho, somente dentro
de uma janela configurada. Desativada por padrão.
Quando um banco entra em NEEDS_REINIT:
Causa
Onde é visível
erro de aplicação irrecuperável recorrente (violação de PK, UNIQUE, FK) — 3 vezes seguidas
réplica, alerta replication_unrecoverable_error
o GUID do banco mestre mudou (restauração, substituição de arquivo)
réplica, alerta replication_guid_mismatch
o arquivo do mestre já não contém os segmentos de que a réplica precisa
mestre
a réplica apagou a cópia antiga para a inicialização e ainda não há cópia nova (a partir do HQbird 2027.2.24)
Janela: por banco → por nó → global. "always" — a qualquer momento.
As janelas são calculadas pelo relógio do host do RCM.
max_concurrent — quantas inicializações (manuais e automáticas) podem estar
em execução no cluster para o RCM iniciar outra automática.
A inicialização automática passa pelas mesmas verificações de espaço e de GUID que a
inicialização manual. O autor do comando é system:autoreinit.
remove_old_replica_when_short (a partir do HQbird 2027.2.24, a linha Excluir a
réplica antiga quando faltar espaço) — desativada por padrão. Se
ativada, a inicialização automática envia a flag Excluir a réplica
antiga (4.4). O RCM a envia somente se a própria réplica está em
NEEDS_REINIT ou a causa NEEDS_REINIT do mestre a nomeia. Para
uma réplica que está IN_SYNC ou LAGGING a flag nunca é enviada. Se o nó
é uma versão mais antiga, o RCM inicia a mesma inicialização sem a flag.
Depois de alterar, reinicie o RCM.
Adiar no cartão do mestre desativa a inicialização automática
de um único banco por 1 hora, 4 horas, 24 horas ou até ser cancelado. A inicialização
manual permanece disponível.
5.9. Erros
Erro
Causa
O que fazer
insufficient disk space on master / on replica, 507
espaço insuficiente. Durante a reinicialização a cópia antiga ocupa espaço até o fim
capítulo 4.4; na réplica (a partir do HQbird 2027.2.24) — a caixa Remover a réplica antiga (5.1)
node_too_old (a partir do HQbird 2027.2.24)
a caixa Remover a réplica antiga está marcada, mas o nó mestre ou réplica é uma versão antiga
atualize o nó como indicado no texto do erro ou execute sem a caixa
engine_busy, reclaim_in_progress (a partir do HQbird 2027.2.24)
a réplica não pode apagar a cópia antiga agora: o Firebird ou este banco está ocupado
tente mais tarde (5.6)
replica_removed_for_reinit, par NEEDS_REINIT (a partir do HQbird 2027.2.24)
a réplica apagou a cópia antiga, mas a inicialização não terminou
inicie a inicialização de novo (4.4)
publication_off (a partir do HQbird 2027.2.24)
a publicação do mestre está desativada ou não contém tabelas com chave
Sincronizar publicação e inicializar (5.1)
long_transactions, “O reinit suave está aguardando transações longas”
transações de escrita longas estão abertas
5.4
long_transactions, “o arquivo do mestre ainda não contém nenhum segmento”
primeira inicialização sob carga
Padrão (5.4)
reinit_pre_publication_transactions
transações iniciadas antes de a publicação ser ativada
reconecte as aplicações, tente de novo
duplicate_guid
dois bancos mestres com o mesmo GUID
remova a cópia; se o passo NOVO GUID foi pulado na promoção a mestre — -force (capítulo 8.4)
license_paused
o fbagent do mestre não tem licença
capítulo 2.8
409 orphaned
o banco está fora da varredura do mestre
capítulo 3.8
incompatible_engine
versões principais do Firebird diferentes
capítulo 4.3
target_not_replica
um banco de trabalho está no lugar da réplica (ele foi tornado normal)
veja abaixo
target_other_replica (a partir do HQbird 2027.2.24)
uma cópia de outro banco deste nó está no lugar da réplica
veja abaixo
restart_not_allowed
o Firebird da réplica também serve bancos mestres
5.6, a caixa “Permitir … parar o Firebird”
fbagent_required
o fbagent não está instalado na réplica
capítulo 1
nbackup backup lock already active
um backup nbackup está em andamento
5.7
… -L did not finish in 2m0s and was stopped
nbackup -L no mestre não terminou em 2 minutos, por isso o nó o parou
tente de novo; se o erro se repetir, verifique o Firebird do mestre (firebird.log)
reinit already in progress for this database
a inicialização deste banco já está em execução
espere ela terminar
target_not_replica. Um banco de trabalho está no lugar da cópia: ele foi tornado
normal (o arquivo <database>.hqcluster-normal.json existe) ou não está em
modo réplica. O nó não sobrescreve um banco de trabalho. Se ele precisa ser substituído, um pedido à API do nó com
overwrite_non_replica: true (não há botão para isso no RCM) substituirá o arquivo e guardará o antigo como
<database>.pre-reinit-<hora UTC>.fdb.
target_other_replica (a partir do HQbird 2027.2.24). A réplica coloca a cópia em
<databases.root>/<id do mestre>/<caminho do banco>. O id do mestre é único somente dentro
do próprio cluster, por isso dois bancos podem acabar com o mesmo caminho. O nó réplica
não sobrescreve uma cópia que pertence a outro dos seus bancos: o erro nomeia esse banco e o
mestre dele. O nó também reconhece uma cópia cujo caminho está registrado de outro modo (um link simbólico ou
junção no caminho, um nome curto de pasta do Windows). overwrite_non_replica não limpa este erro. Mova uma das
cópias para outra pasta ou remova esse banco da réplica, depois inicie a
inicialização de novo. O nó vê somente os próprios bancos: dois nós réplica no
mesmo host precisam ter pastas de réplica diferentes (databases.root).
5.10. Como verificar o resultado
Bancos de dados: o par mestre — réplica no grupo está Ok, estado
IN_SYNC.
Verificar no cartão do mestre: os nós contam as linhas das tabelas da
lista de tabelas do banco (capítulo 3.1) no mestre e na réplica e as comparam.
Verifique em horário calmo: com escritas ativas os números podem diferir.
Com o HQbird 2027.2.24 a página de resultado nomeia a lista de cada lado
(por exemplo, “a lista própria deste banco” ou “tabelas da publicação
(lista não definida)”). O RCM conta a réplica usando a lista do mestre. Uma tabela
ausente dos dois bancos é mostrada como “não está no banco” e não é contada como
erro. Se nenhuma tabela foi comparada, o resultado é “Nenhuma tabela para
comparar”, não uma divergência. Se a comparação não terminou no tempo previsto,
o resultado é “Não comparado (limite de tempo)”, o que também não é uma divergência.
Verificação periódica (opcional): a página Verificação de dados,
Ativar em todos os nós. Com o HQbird 2027.2.24 o nó aplica
as configurações imediatamente, sem reinício do serviço do nó: depois de Salvar o RCM
escreve “Salvo e já em vigor”. O nó 2027.5.7 precisa que o
serviço hqclusternode seja reiniciado, e o RCM 2027.2.24 diz isso.
Os nós comparam as contagens de linhas sozinhos quando o mestre e a réplica estão no mesmo
segmento. Uma divergência levanta o alerta data_mismatch; então execute
Verificar.
Uma tabela que o operador removeu da publicação é mostrada como “não
publicada”, não como uma divergência.
6. Configuração da publicação
A publicação diz ao Firebird mestre de quais tabelas gravar as alterações nos segmentos.
Sem ela, a réplica não recebe nada.
6.1. O que é a publicação
No Firebird 4 e 5, as tabelas a replicar são definidas pela publicação RDB$DEFAULT:
Publicação ativada — em RDB$PUBLICATIONS ela tem RDB$ACTIVE_FLAG = 1
(o comando ALTER DATABASE ENABLE PUBLICATION).
Tabelas publicadas — a lista em RDB$PUBLICATION_TABLES.
O Firebird grava alterações nos segmentos somente para tabelas publicadas e somente
quando a publicação está ativada. Registrar o banco (capítulo 3) não
ativa a publicação. Ela é ativada por Sincronizar publicação (6.2).
O nó mestre verifica a publicação a cada hora
(limits.publication_check_interval_sec, 3600 por padrão). Se ela está
desativada, o nó a verifica a cada 2 minutos.
Na página Bancos de dados, o banco mestre tem um ícone:
Ícone
Significado
publicação LIGADA
publicação ativada
publicação DESLIGADA
o Firebird não grava nada nos segmentos, as réplicas não recebem alterações
publicação desconhecida
o nó não conseguiu ler o estado
O filtro Publicação desligada mostra bancos com publicação desativada ou desconhecida.
Se um banco com publicação desativada já tem uma réplica, o mestre levanta
o alerta master_publication_off.
Com o HQbird 2027.2.24, o mestre levanta este alerta também quando recusou
inicializar um banco com o erro publication_off (capítulo 5.1): a publicação
está desativada ou não contém tabela com chave. O nível do alerta:
warn — o banco ainda não tem réplica: a inicialização espera a publicação;
serious — o banco já tem uma réplica;
info — o operador desativou a publicação.
O alerta é limpo quando a publicação é corrigida ou outra
inicialização começou.
6.2. Sincronizar publicação
Linha do mestre: publicação desativada
Onde clicar:
na linha do banco mestre na página Bancos de dados. Quando a publicação
está desativada, o botão fica ao lado do ícone;
na página do banco;
para vários bancos: marque as linhas, na lista Ação selecione
Sincronizar publicação. O RCM enviará um comando separado para cada
banco.
Confirmação da sincronização da publicação
O que o nó faz (uma única transação):
Ativa a publicação. Se o operador a desativou (6.4), ele não a ativa.
Adiciona à publicação todas as tabelas com chave que ainda não estão lá.
Remove da publicação as tabelas sem chave e as tabelas que o operador
excluiu (6.3).
Desativa a adição automática de tabelas novas (EXCLUDE ALL FROM PUBLICATION, depois adiciona as tabelas necessárias). Somente o nó define a
composição da publicação.
Linha do mestre depois da sincronização: publicação ativada
Uma tabela com chave — uma tabela permanente de usuário que tem uma
chave primária ou um índice único ativo. Tabelas de sistema e temporárias
não são publicadas.
A sincronização também remove da publicação tabelas sem chave que o DBA adicionou
manualmente.
Se a composição já está correta, o nó não altera nada.
Quando o nó recusa:
Código
Motivo
no_publications
HQbird 2.5/3.0 (6.6)
not_master
o nó não é o mestre
reinit_in_progress
a inicialização deste banco está em andamento
orphaned, database_failed, file_missing
o banco está fora da varredura, em erro, ou não tem arquivo
Todos os bancos do nó de uma vez — somente pela linha de comando. Na página Comandos
o resultado é mostrado por banco: concluído, ignorado ou erro.
Bancos no estado FAILED ou SEEDING e bancos sem arquivo são ignorados.
O mesmo pela linha de comando
Command
hqbirdrcm setpublication -node node-a -db <db_id> # one databasehqbirdrcm setpublication -node node-a # all node databases
O comando espera até 5 minutos e imprime uma linha para cada banco. Em erro o código de
saída é 1. -nowait — não esperar o resultado.
6.3. Tabelas da publicação
A página “Tabelas da publicação”
Abra Tabelas da publicação na linha do banco mestre.
A página mostra:
o estado da publicação (ligada/desligada, desativada pelo operador) e os contadores;
cada tabela: nome, chave e estado.
Estado
Significado
publicada
as alterações vão para os segmentos
ainda não publicada
uma tabela com chave, será adicionada na sincronização
excluída
o operador a removeu da publicação
sem chave
não pode ser publicada
Na coluna da chave — a chave primária ou, se não houver, o índice único com
o menor número de campos.
Por que uma tabela sem chave não pode ser publicada. A réplica procura a linha para
UPDATE e DELETE pela chave. Sem chave ela não encontrará a linha. Adicione uma
chave primária ou um índice único, depois sincronize a publicação.
Excluir da publicação / Devolver à publicação:
Marque as tabelas.
Clique em Excluir da publicação ou Devolver à publicação.
O nó salva a lista e sincroniza a publicação imediatamente.
Confirmação de “Excluir da publicação”
A lista de tabelas excluídas é armazenada no nó mestre. A sincronização não
a altera. Quando uma réplica é promovida a mestre (capítulo 8), a lista passa para
o novo mestre.
Verificar (capítulo 5.10) mostra uma tabela excluída como “não publicada”,
não como uma divergência.
6.4. Ativação e desativação da publicação
Na página Tabelas da publicação: Desativar publicação /
Ativar publicação.
Desativar é escolha do operador. A sincronização não
reativa a publicação.
Alterações feitas enquanto a publicação está desativada (ou enquanto uma tabela está
excluída) não são enviadas à réplica, mesmo depois de ela ser ativada.
Depois de ativar, clique em Verificar (capítulo 5.10). Se os dados
divergirem — reinicialize a réplica (capítulo 5).
6.5. Uma tabela nova
Uma tabela nova não entra na publicação sozinha: o nó desativa
a adição automática.
Depois do DDL:
Crie uma chave primária ou um índice único na tabela.
Clique em Sincronizar publicação.
Peça às aplicações que se reconectem se a reinicialização for necessária. O Firebird
não grava nos segmentos transações que começaram antes de a publicação ser ativada;
COMMIT RETAINING mantém essa transação aberta. A inicialização espera por
essas transações e depois falha com reinit_pre_publication_transactions
(capítulo 5.4).
Uma tabela nova no estado “ainda não publicada”
Linhas gravadas na tabela nova antes da sincronização não chegarão à réplica.
Se houver alguma, verifique os dados e, se necessário, reinicialize a réplica.
6.6. HQbird 2.5 e 3.0
O HQbird 2.5 e 3.0 não têm publicações. O Firebird grava segmentos se o
arquivo do plugin replconf contém um bloco mestre. Os botões de publicação nesses nós ficam ocultos,
e a API responde com no_publications.
O conjunto de tabelas é definido pelos parâmetros do mecanismo:
Parâmetro
Significado
include_filter
quais tabelas replicar: nomes ou padrões separados por vírgulas; vazio — todas
exclude_filter
quais tabelas não replicar
Os parâmetros são alterados em Configurações → Parâmetros de replicação (capítulo 7.1). A
página Tabelas da publicação os mostra somente leitura, com um link Alterar
nas configurações do mecanismo. O Firebird lê os valores novos depois de um reinício.
Tabelas da publicação no HQbird 3.0: filtros do mecanismo
O plugin replconf. O nó grava o próprio arquivo replconf.hqcluster.hqbird na
pasta do Firebird. O Firebird o lê somente quando replconf.properties aponta para
ele. O plugin precisa ser ativado uma vez:
Configurações → Nós, o bloco Plugin de replicação (HQbird 2.5 / 3.0). O bloco
mostra para onde replconf.properties aponta e os problemas que o nó
encontrou.
Plugin não ativado: replconf.properties aponta para o arquivo do HQbird DataGuard
Ativar… A janela lista o que o nó fará: instalar o plugin,
apontar replconf.properties para o arquivo do nó, migrar as entradas do arquivo antigo.
Escolha quando: Somente dentro da janela de reinício do nó ou Agora, ignorando
a janela de reinício.
Janela de ativação do plugin
Depois do reinício do Firebird, o campo Ativado mostra “sim: o mecanismo
lê o arquivo do nó”.
Plugin ativado
A ativação reinicia o Firebird e afeta todos os bancos deste Firebird.
Faça-a em um período calmo.
7. Outras opções de replicação
7.1. Parâmetros de replicação
Configurações → Parâmetros de replicação, formulário do assistente
A página Configurações → Parâmetros de replicação altera as chaves em
replication.conf para os bancos selecionados ou para o nó como um todo.
Adicionar mestre e réplicas — selecione os bancos. O RCM os agrupa por
versão do Firebird e papel: um formulário separado para mestres e para réplicas.
Para cada parâmetro, escolha uma ação:
Ação
O que faz
sem alterações
o valor não é alterado
definir valor
um valor novo
redefinir (para o nível acima)
remover o próprio valor, tomar o valor do nível acima
não gravar (valor do Firebird)
a chave não é gravada, vale o valor do Firebird
Escolha onde aplicar: Nos bancos selecionados ou Como padrão
dos nós deles.
Pré-visualizar — os nós verificam os valores sem alterar nada.
Pré-visualização das alterações
Aplicar. O RCM envia o comando a cada nó.
De onde vem o valor (a coluna Atual):
Origem
Valor
este banco
definido para o banco
valor do nó
definido como padrão do nó
valor interno do nó
o valor do nó a partir do código
valor do Firebird
a chave não é gravada
do arquivo (ainda não definido aqui)
o valor de replication.conf, o RCM ainda não o alterou
definido pelo nó
somente leitura (caminhos, prefixos)
Um nó que não responde mostra os bancos dele como indisponíveis para seleção.
As alterações exigem o fbagent (caso contrário fbagent_required).
Quem reinicia o Firebird (o Firebird lê replication.conf somente na
inicialização):
Nó
Quem
mestre
você o reinicia: o mestre nunca reinicia o Firebird sozinho
réplica com firebird.auto_restart: never
você
réplica cujo Firebird também serve os bancos do mestre
você
outras réplicas
o nó o reinicia na própria janela de reinício
Para um reinício manual, a página tem um botão Reiniciar o Firebird.
7.2. Principais parâmetros
Mestre, Firebird 4/5:
Parâmetro
Rótulo no RCM
Valor do nó
Firebird
Dica
journal_archive_timeout
Tempo limite do arquivo
10 s
60 s
quantos segundos o Firebird espera antes de fechar um segmento incompleto. Mais baixo — a réplica fica mais perto do mestre. Precisa ser menor que limits.data_check_quiet_sec (90)
journal_segment_count
Número de segmentos
64
8
quantos segmentos podem residir em .ReplLog. Precisa ser maior que limits.backlog_critical (48)
journal_segment_size
Tamanho do segmento
—
16 MB
de 1 MB a 512 MB; o receptor não aceitará mais de 512 MB
buffer_size
—
1 MB
O nó também grava log_errors = true (não pode ser alterado) e
disable_on_error = true.
Réplica, Firebird 4/5:
Parâmetro
Rótulo no RCM
Firebird
Valor
apply_idle_timeout
Pausa ociosa
10 s
pausa quando não há segmentos novos
apply_error_timeout
Pausa após erro de aplicação
60 s
pausa antes de tentar de novo depois de um erro
verbose_logging
nó: true
replication.log detalhado; não é recomendado desativar
skip_upddel_without_pk
nó: true
pular UPDATE/DELETE em tabelas sem chave
Somente Firebird 5: include_filter, exclude_filter, cascade_replication.
HQbird 2.5/3.0 — chaves log_* com o mesmo significado: log_archive_timeout,
log_segment_count, log_segment_size (não menor que 2 × buffer_size). A
chave alert_command é definida somente em node.json.
Uma dica para cada parâmetro está disponível no formulário do RCM.
7.3. Armazenamento do arquivo
O arquivo <database>.LogArch no mestre é limpo em etapas:
Segmentos que foram aplicados por todas as réplicas e que são mais antigos que
retention_days.
Se o espaço livre é menor que free_space_floor_gb — segmentos aplicados
mais novos que o período de retenção. Alerta disk_serious_cleanup.
Se o espaço ainda está baixo — segmentos não aplicados, começando pelos mais antigos.
A réplica recebe NEEDS_REINIT, alerta
replication_paused_reinit_scheduled.
Parâmetro (Configurações → Nós, Armazenamento e arquivos)
Padrão
limits.retention_days — Retenção do arquivo, dias
2
limits.retention_min_kept_segments — Sempre manter os últimos segmentos
0 (desativado)
limits.free_space_floor_gb — Espaço livre mínimo
1 GB
Configurações → Nós, “Armazenamento e arquivos”
Limpar o arquivo manualmente:
Command
hqbirdrcm cleanuparchive -node node-a # stages for all databases on the nodehqbirdrcm cleanuparchive -node node-a -db <db_id> # a single database
-orphaned (somente junto com -db) apaga todos os segmentos do banco no
estado ORPHANED (capítulo 3.8). Para qualquer outro banco o nó responderá not_orphaned.
Nunca execute -orphaned no doador da promoção (capítulo 8.5).
A compressão é definida por par: Configurações → Nós → Pares, coluna
compress.
Valor
Significado
vazio ou none
sem compressão (padrão)
zstd
compressão zstd
A alteração entra em vigor imediatamente. A compressão é útil em uma rede lenta.
Velocidade de transferência de segmentos (Configurações → Nós, Transferência e
reinicialização):
Parâmetro
Padrão
Quando entra em vigor
limits.channel_a_mbps — Velocidade de transferência de segmentos
50 MB/s
imediatamente
limits.channel_a_burst_mbps — Pico de transferência de segmentos
200 MB
imediatamente
A unidade é mebibyte (MiB), embora o nome diga “mbps”. O pico não pode ser
menor que a velocidade.
Configurações → Nós, “Transferência e reinicialização”
Janelas de tempo (Janelas de tempo):
Parâmetro
Padrão
Quando entra em vigor
O que afeta
windows.restart_window — Janela de reinício do Firebird
mestre 22:00-05:00, réplica always
imediatamente
quando o nó réplica pode reiniciar o Firebird
windows.transfer_window — Janela de transferência
23:00-05:00
depois do reinício do nó
velocidade plena de inicialização (capítulo 5.5)
O rótulo ao lado de cada campo mostra quando a alteração entra em vigor: imediatamente ou
reinício do nó.
Configurações → Nós, “Janelas de tempo”
7.5. Verificação de dados
Verificar — uma comparação pontual da contagem de linhas no mestre e na réplica
(capítulo 5.10).
Verificação de dados — uma comparação periódica (capítulo 5.10). O nó faz a comparação
quando o mestre e a réplica estão no mesmo segmento.
Com o HQbird 2027.2.24, as configurações de verificação entram em vigor imediatamente depois de
Salvar; não é necessário reiniciar o serviço do nó. O RCM mostra “Salvo e já
em vigor”. Depois de ativar, a primeira verificação corre depois de um intervalo. Depois de
desativar, uma verificação em andamento é interrompida e não grava nada. O intervalo
novo é contado a partir do fim da última verificação. Manter, dias, Limite da
consulta, Quieto e Gerador de progresso entram em vigor a partir da próxima
verificação.
O nó 2027.5.7 lê essas configurações somente na inicialização: depois de
Salvar, reinicie o serviço hqclusternode nesse nó. O RCM
2027.2.24 mostra “Salvo, mas ainda não em vigor” e indica o motivo.
Quais tabelas comparar é definido pela lista de tabelas do banco (capítulo 3.1). Com o HQbird
2027.2.24, cada banco pode ter a própria lista: o campo no registro ou o
bloco Tabelas de acompanhamento da sincronização na página do banco do mestre
(capítulo 3.3). A página Verificação de dados mostra qual lista
foi usada, e o número de tabelas “não está no banco”. Em 2027.5.7 a lista é por nó
(sync_tables).
Tabelas excluídas da publicação são mostradas como “não publicada”
(capítulo 6.3).
Página de verificação de dados
7.6. Alertas
Página de alertas
A página Alertas. Ações:
Reconhecer — o alerta permanece visível mas é marcado reconhecido;
Silenciar por 60 min — ocultar por uma hora;
Excluir / Excluir todos com este código — o RCM passa a exclusão ao nó
que levantou o alerta. Se a causa permanece, o alerta aparecerá de novo.
Command
hqbirdrcm clearalerts -code backlog_warn # also -id, -acked, -all
A partir do HQbird 2027.2.33, o RCM envia alertas para o Telegram, para um webhook (Slack,
Teams, JSON) e por e-mail. Os canais são configurados na seção notify.channels
do arquivo rcm.json. O bloco Canais de notificação na
página Alertas mostra os canais e envia uma mensagem de teste. O RCM informa
problemas de nível warn e acima: um problema apareceu, ficou mais
grave, ou foi limpo. Sem canais, o RCM não envia nada. Versões
anteriores não têm envio: acompanhe a página Alertas ou consulte a API do RCM.
Principais códigos:
Código
Significado
backlog_warn / backlog_critical
32 / 48 segmentos não arquivados em .ReplLog
disk_serious_cleanup
o arquivo está sendo limpo na etapa 2 (7.3)
replication_paused_reinit_scheduled
segmentos não aplicados apagados, inicialização necessária
o Firebird não está em execução ou está registrando erros
firebird_not_answering
a partir do HQbird 2027.2.30: o Firebird não respondeu a uma conexão de banco por um minuto (travamento). Isso inclui também uma conexão que não se estabeleceu por tempo esgotado; firebird_down é somente uma recusa de conexão
master_publication_off
a publicação está desligada (capítulo 6); a partir do HQbird 2027.2.24 e depois de uma falha publication_off (capítulo 6.1)
replica_removed_for_reinit
a partir do HQbird 2027.2.24: a réplica apagou a cópia antiga para a inicialização, e ainda não há cópia nova (capítulo 4.4)
orphaned_database
banco fora da varredura (capítulo 3.8)
restart_required_after_reinit
o Firebird da réplica precisa de um reinício (capítulo 5.6)
data_mismatch
a verificação periódica encontrou uma divergência
license_paused
o fbagent não tem licença (capítulo 2.8)
7.7. Pausa do envio
Na página Bancos de dados, na linha do mestre: Pausar o envio /
Retomar o envio. Para vários bancos — pela lista Ação.
Confirmação de pausar o envioLinha do mestre durante uma pausa
A pausa permanece em vigor até Retomar o envio ou até a inicialização.
O Firebird mestre continua a gravar segmentos. O arquivo .LogArch cresce: enquanto
a réplica está parada, a etapa 1 (7.3) não apaga os segmentos dela.
Uma pausa longa pode chegar à etapa 3 e a NEEDS_REINIT. Fique de olho no espaço.
O botão está ausente se o banco não tem réplica ou a publicação está desativada. O
ícone Pausa: sem licença significa uma pausa relacionada à licença (capítulo 2.8); ela é encerrada
somente por uma licença.
7.8. Logs
Log
Onde
Nó
<pasta de instalação>/logs/node-YYYYMMDD.jsonl (/opt/hqclusternode ou C:\hqclusternode), 32 MB cada, 20 arquivos
replication.log e firebird.log do Firebird
caminhos em node.json: firebird.replication_log, firebird.firebird_log
RCM
Linux: journalctl -u hqbirdrcm
Auditoria do RCM
rcm-data/audit.jsonl
Log remoto do nó — a página Logs: selecione um nó e uma fonte
(replication.log, firebird.log, agente do nó).
você precisa de uma cópia de trabalho separada: relatórios, testes, uma falha sem um mestre novo
um banco comum fora da replicação
Promover a mestre, 8.3
a réplica deve se tornar o novo mestre
um banco gerido por um nó companheiro com o papel de mestre
Nenhum dos caminhos pode ser desfeito pela interface.
8.1. Tornar normal
Lista “Ação” da réplica: o item “Tornar normal”
Bancos de dados, lado da réplica: marque as linhas da réplica.
Na lista Ação, selecione Tornar normal e confirme.
Não há botão separado na linha. Também não há comando de linha de comando.
Confirmação de “Tornar normal”
3. O nó réplica:
- executa `gfix -replica none` (HQbird 2.5/3.0: `gfix -replica {}`). Se
o banco está ocupado aplicando segmentos, o nó o coloca em
desligamento `single` por alguns segundos (`gfix -shut single -force 0`), limpa o modo réplica e
o devolve com `gfix -online normal`. **Todas as conexões deste banco
são derrubadas**;
- grava o arquivo marcador `.hqcluster-normal.json` (hora, autor, db_id,
GUID);
- começa a limpar a fila `.Incoming` (8.2).
4. O RCM mostra o banco no grupo **Não é réplica (normal)**.
A página “Bancos de dados” depois de “Tornar normal”
Depois disso, o banco está aberto para escrita.
Remova o bloco da réplica de replication.conf. O nó o remove na próxima
varredura, e o Firebird lê o arquivo na inicialização:
Até lá, erros “o banco não está em modo réplica” para este banco não são
levantados como alertas.
O arquivo marcador protege o banco. A inicialização não sobrescreverá esse banco:
ela é recusada com target_not_replica (capítulo 5.9). Apagar somente o marcador não basta:
o nó também verifica o modo réplica no cabeçalho do banco. A caixa Excluir a réplica
antiga (capítulo 4.4) também não apaga esse banco.
Com o HQbird 2027.2.24, enquanto a réplica está apagando a cópia antiga deste banco para
a inicialização, Tornar normal é recusado com reclaim_in_progress:
tente mais tarde.
Se o banco precisa voltar a ser uma réplica — somente uma inicialização nova com
sobrescrita serve. Isso é feito pela API do nó (overwrite_non_replica: true); não há esse botão no
RCM. O arquivo antigo é salvo como
<database>.pre-reinit-<hora UTC>.fdb, e o marcador é apagado.
8.2. O que acontece com os segmentos
Até o nó ter varrido os bancos, o mestre continua a enviar segmentos. A cada 30 segundos o nó réplica apaga os segmentos antigos e mantém somente os últimos 100 (keep_segments).
Depois da varredura, o registro do banco na réplica fica no estado ORPHANED. O nó réplica responde ao mestre com unknown_database. O mestre para de enviar segmentos a esta réplica, para de manter um arquivo para ela e a verifica de novo a cada 10 minutos.
As outras réplicas deste banco não são afetadas.
O registro ORPHANED pode ser excluído (capítulo 3.8): hqbirdrcm forgetdatabase. O próprio arquivo do banco não é excluído.
8.3. Promover a mestre
A réplica se torna o novo mestre. O arquivo dela permanece no lugar, e o controle
passa ao nó companheiro.
Condições:
Condição
Recusa
o banco é uma réplica
bad_request
um nó com o papel de mestre — o companheiro — está em execução no mesmo host (o mesmo rótulo host em rcm.json, capítulo 2.1)
no_companion
a promoção deste banco ainda não está em andamento
already_running
não há inicialização para este banco nem a partir do mestre dele
reinit_running
O RCM não cria o nó companheiro: instale-o de antemão (capítulo 1).
Como começar:
na linha da réplica, Promover a mestre, ou na lista Ação;
O RCM pedirá confirmação e nomeará o nó companheiro.
Confirmação “Promover a mestre?”
Passos (visíveis na linha da réplica, nomes em inglês):
Nº
Passo
O que faz
1
TURN TO NORMAL
como em 8.1; pulado se o banco já é normal
2
NEW GUID
um GUID novo do banco no lugar (8.4)
3
EXCLUDE ON DONOR
o nó réplica (doador) exclui o arquivo da varredura dele (exclude_paths)
4
ENROLL ON
o nó companheiro registra o arquivo como banco mestre
5
PUBLICATION SYNC
sincronização da publicação; a lista de tabelas excluídas é trazida do mestre antigo (capítulo 6.3)
6
RESTART DONOR FIREBIRD
reinício do Firebird do doador, sem esperar uma janela
7
RESTART FIREBIRD
reinício do Firebird do companheiro, sem esperar uma janela
8
FINALIZE
a linha do doador se torna Réplica fantasma; o mestre antigo pode se tornar Mestre degradado (8.5)
Passos da promoção na linha da réplica
No HQbird 2.5 e 3.0 não há publicações: o passo PUBLICATION SYNC
termina com o texto “este mecanismo não tem publicação”.
Passos da promoção no HQbird 3.0 (Windows)
Se o doador e o companheiro usam o mesmo Firebird, esse Firebird é
reiniciado: as conexões de todos os bancos dele são derrubadas.
Se um passo falha, o trabalho fica failed com o texto do erro. Corrija a
causa e clique em Promover a mestre de novo: os passos concluídos não são
repetidos. Se o RCM reinicia durante a promoção, o trabalho também ficará
failed — verifique o estado dos nós e tente de novo.
Licença. Se o fbagent no host do mestre não tem licença, o mestre
pausou o envio. A promoção ainda é possível. O RCM avisará:
as alterações feitas depois do início da pausa serão perdidas.
8.4. GUID novo
Depois da promoção, o banco precisa receber o próprio GUID. Caso contrário o novo mestre grava
segmentos sob o GUID do mestre antigo, e as réplicas dele são recusadas com
duplicate_guid.
O passo NEW GUID no nó:
gfix -shut single -force 0 — todas as conexões do banco são encerradas;
nbackup -L, depois nbackup -F sem -SEQUENCE;
apaga <database>.delta;
verifica o cabeçalho: GUID novo, REPLICATION_SEQUENCE = 0;
gfix -online normal.
O Firebird não é reiniciado. O método funciona em todas as versões (2.5, 3.0, 4.0,
5.0).
Se o passo foi interrompido, o nó emite o alerta newguid_interrupted. O banco pode
permanecer em desligamento single. Repita Promover a mestre: o passo
continuará.
O passo é pulado (o texto começa com skipped:) se o nó doador é uma versão
antiga ou o arquivo já tem o próprio GUID.
Depois de um GUID novo, a cadeia antiga de nbackup deixa de servir. Faça uma cópia nbackup nova de nível 0.
Se o banco foi criado com ADD DIFFERENCE FILE, o .delta dele está em outro
lugar: apague-o manualmente.
8.5. Depois da promoção
Registro do doador. No nó réplica o banco permanece ORPHANED, o caminho permanece em
exclude_paths, e a pasta .Incoming e o rótulo permanecem. No RCM esta é a linha
Réplica fantasma com os botões Abrir no novo mestre e Limpar.
Linha do doador: «Réplica fantasma»
Para remover a linha, clique em Limpar. Isso altera somente o RCM.
Para remover o registro do doador do nó réplica, execute forgetdatabase.
O arquivo e a pasta .Incoming permanecem. O HQbird 2027.2.30 e mais novos não
recusam o comando (mailbox_active), porque o caminho do doador está em
exclude_paths. Nós de versões anteriores o recusam enquanto o arquivo e a
pasta .Incoming estão presentes.
Nunca execute cleanuparchive -orphaned no doador. O doador e o
companheiro compartilham a mesma pasta <database>.LogArch. O comando apagará o arquivo
vivo do novo mestre.
Mestre antigo.
Se o doador era a última réplica em funcionamento dele, o RCM coloca o mestre
antigo em Mestre degradado e pausa o envio ao doador
(“envio pausado: … (promoção a mestre)”). Não retome
o envio ao doador: ele já contém um banco de trabalho. Para limpar este estado,
inicialize o banco em outra réplica.
Mestre antigo: «Mestre degradado», envio pausado
A inicialização do mestre antigo para o nó doador será recusada
(target_not_replica): ele já contém um banco de trabalho.
Se o passo NEW GUID foi pulado, o mestre antigo e o novo têm o mesmo GUID.
Nesse caso a inicialização a partir do mestre antigo exige -force (capítulo 5.9).
Depois de uma promoção manual o RCM não transforma o mestre antigo em réplica do novo
mestre. Pare as aplicações no mestre antigo e remova o banco dele da
gestão (capítulo 3.8). Para um banco descrito como serviço, isso é feito pelo Reingresso
(8.7).
Mestre novo. Configure uma réplica para ele: nó réplica, pares (capítulo 2),
publicação (capítulo 6), inicialização (capítulo 5).
Mestre novo: banco com um GUID novo, ainda sem réplica
8.6. Comutação planejada: lista de verificação
Este é o procedimento de uma comutação manual. Para um banco descrito como serviço, o RCM troca o mestre sozinho (8.7). Uma promoção manual não verifica se as aplicações estão gravando no mestre antigo. Procedimento:
De antemão. No host da réplica, um nó companheiro com o papel de mestre está em execução, e os dois nós têm o mesmo rótulo host (capítulo 2.1). Um nó para a réplica futura está pronto para o novo mestre.
Pare as escritas das aplicações no banco do mestre antigo.
Espere até a réplica ter recebido e aplicado tudo: Bancos de dados → IN_SYNC, sem fila.
Verificar (capítulo 5.10): as contagens de linhas coincidem.
Promover a mestre (8.3). Espere o passo FINALIZE.
Verifique: o banco está na lista de mestres do companheiro, publicação ligada.
Passe as aplicações para o novo mestre.
Faça uma cópia nbackup de nível 0 do banco novo (8.4).
Limpe o registro fantasma da linha do doador (8.5).
Conecte a réplica ao novo mestre e inicialize-a (capítulo 5).
Mestre antigo: remova o banco da gestão ou deixe-o como arquivo (8.5).
8.7. Serviços: comutação e failover no RCM
Com o HQbird 2027.2.30, o RCM move o mestre para outro host sozinho. Para isso, o banco é descrito como um serviço: um banco lógico em vários hosts. Em cada host do serviço há um nó mestre e um nó réplica, e o caminho do arquivo do banco é o mesmo. O serviço é criado na página Serviços (a partir do HQbird 2027.2.31) ou com o comando hqbirdrcm services put -id <id> -file <file>.json.
Ação
O que faz
Comandos
Comutação
transferência planejada do mestre sem perda de dados. Depois o mestre antigo se torna automaticamente uma réplica do novo mestre
depois de um failover, devolve o host antigo como réplica do novo mestre
hqbirdrcm rejoin -service <id>
Retomar
tira o serviço do estado failed
hqbirdrcm resume -service <id> -check, depois hqbirdrcm resume -service <id>
As mesmas ações estão disponíveis na página do serviço: os botões Comutação…, Failover…, Reingresso… e Retomar….
O failover automático fica desligado por padrão. Ele é ativado para cada serviço separadamente:
hqbirdrcm policy -service <id> -auto-failover on -max-data-loss 30.
Ele exige roteadores. O RCM inicia um failover somente quando o nó mestre está em silêncio, a maioria dos roteadores não enxerga o Firebird do mestre, e o atraso da réplica não passa de max_data_loss_sec.
Um roteador (hqclusternode router, Linux) mantém o HAProxy no mestre atual do serviço. As aplicações se conectam a <host do roteador>:<router_port> e não alteram a cadeia de conexão quando ocorre uma troca.
Depois de um failover, o RCM isola o mestre antigo (papel fenced) quando ele volta a responder. Traga-o de volta com o comando rejoin.
Este site usa cookies para melhorar sua experiência e lembrar preferências.