Outros idiomas: English, Русский.

Este guia vai de dois servidores limpos até uma réplica do Firebird 5.0 em funcionamento. Tudo é feito no navegador, no console do RCM, exceto a instalação e uma pasta. As capturas de tela são do teste de 2026-11-17: kit 2027.2.33, RCM e nós 2027.5.12, Ubuntu 24.04. Elas mostram a interface do RCM em inglês. O idioma muda no seletor do cabeçalho; neste guia, os nomes de botões e campos são os da interface em português. Relatório do teste anterior, de 2026-11-08 (em russo): hqbird2027-rcm-cluster-check-report.ru.md (seção “Прогон 2”). Somente os comandos, sem capturas de tela: hqbird2027-linux-cluster-runbook.pt.md. Cada página do RCM em detalhe: guia do usuário do RCM (repositório hqcluster-node, docs/user-guide/).

Este guia é para o kit 2027.2.24 e mais novos. Para o kit 2027.2.22, veja a versão deste arquivo de 2026-11-07 no histórico do git.

O kit para baixar é o 2027.2.33 (2026-11-16): agente 3.4.0, HQ Monitor 1.57.0, RCM e nós 2027.5.12, Firebird 5.0.5.1917. Este guia foi verificado com ele em 2026-11-17 (dois servidores, Ubuntu 24.04, bancos de 3 MB e 167 MB): todos os passos passaram. O texto chama os resultados dessa verificação de “teste de 2026-11-17”. As capturas são de uma segunda passagem do mesmo dia, com o mesmo kit (bancos de 3 MB e 2,88 GB). Os outros números são do teste de 2026-11-08. O que os kits depois do 2027.2.27 mudaram para um cluster:

Kit Mudança
2027.2.29 (agente 3.1.0, RCM 2027.5.9) Não há cluster por padrão (veja abaixo). Vários agentes de um host podem entrar num cluster: cada um tem a sua porta de pareamento (7450–7459) e a sua porta de nó. fbagent --cluster-leave. A página Clusters do HQ Monitor
2027.2.30 (RCM 2027.5.10) Switchover e failover de um serviço, roteadores
2027.2.31 (agente 3.3.0, RCM 2027.5.11) O instalador abre uma interface de texto no terminal (passo 1). As páginas Serviços do RCM. Um servidor que não está ligado a um HQCenter atualiza sozinho o agente, o HQ Monitor e o fbmcp
2027.2.33 (agente 3.4.0, RCM 2027.5.12) O RCM envia os seus alertas para o Telegram, um webhook ou e-mail (“O que acompanhar depois”). Um cluster de dois contêineres Docker: guia do Docker

Todas as mudanças: What’s New.

Os kits com o agente (fbagent) 3.1.0 e mais novos (a partir do 2027.2.29) não criam cluster por padrão: não há RCM, não há janela de pareamento, e as portas do cluster ficam fechadas no firewall. No passo 1 você liga o RCM no mestre e o modo de descoberta na réplica.

Tempo: ≈30 minutos, mais a cópia dos bancos (≈1 minuto para 3 GB em uma rede de 1 Gbit/s).

Resultado

Servidor 1 Servidor 2
Função mestre + console do RCM réplica
Bancos /databases/master/*.fdb /databases/replica/<nó da réplica>/<nó do mestre>/*.fdb
Serviços firebird, hqbirdfbagent-fb50, hqbirdmonitor-fb50, fbmcp, hqbirdrcm, hqclusternode-master-p3050 os mesmos, mas hqclusternode-replica-p3050 e sem hqbirdrcm (um kit antigo deixa lá o RCM próprio, parado)

Requisitos

  • Dois servidores Linux x86-64 (testado no Ubuntu 24.04), 2 núcleos, 4 GB.
  • Espaço. Mestre: livre ≥ 105% do tamanho do banco (durante o bloqueio, o arquivo .delta cresce). Réplica: livre ≥ 105% do tamanho do banco mais o limite limits.free_space_floor_gb (padrão: 1 GB). Na reinicialização sobre uma réplica, o arquivo antigo fica até o fim; por isso, o volume da réplica precisa de cerca de 2 vezes o tamanho do banco. Com a caixa “Remover a réplica antiga se faltar espaço” (passo 8), bastam 105% mais o limite.
  • Rede entre os servidores: portas 3050, 7051, 7443, 7444, 7450. São as portas da primeira instância de um servidor (slot 0). Uma segunda instância do servidor usa a porta de pareamento 7451 e a porta de nó 7052.
  • O seu PC alcança a porta 7444 do mestre (console do RCM), direto ou por um túnel SSH.
  • Um usuário com sudo.

Firewall. O instalador abre portas no firewalld ou no ufw ativo (com qualquer idioma do sistema): 3050 e 23050 sempre, as portas do cluster somente para as opções do passo 1. Mestre: 7443, 7444, 7051. Réplica: 7450, 7051. O agente fecha a 7450 de novo quando a janela de pareamento termina ou o host é vinculado. No Ubuntu, o ufw em geral está desativado. Então o instalador escreve uma linha, por exemplo no mestre: no active firewall (firewalld or ufw): ports 3050, 23050, 7443, 7444, 7051/tcp are not opened by this install; they are reachable from every network; close them or enable a firewall. Na nuvem, feche as portas no firewall da nuvem: de fora, somente o seu endereço; entre os servidores, a rede interna.

Abaixo estão os endereços do teste: mestre 10.114.0.5, réplica 10.114.0.6 (rede privada). Use os seus.

Passo 1. Instalação nos dois servidores

Em cada servidor:

Command
V=2027.2.33
wget https://ib-aid.com/download/hqbird/v2027/hqbird2027-fb50-linux-$V.run
wget https://ib-aid.com/download/hqbird/v2027/hqbird2027-fb50-linux-$V.run.sha256
sha256sum -c hqbird2027-fb50-linux-$V.run.sha256
sudo sh hqbird2027-fb50-linux-$V.run

No terminal, o instalador abre a interface de texto (kits a partir do 2027.2.31). Ele usa o idioma do sistema. A primeira página tem a linha Cluster RCM off, modo de descoberta off (Cluster RCM off, discovery mode off). Abra Cluster e mude uma linha:

Linha da página Cluster Mestre Réplica
Gerenciador de cluster (RCM) (Cluster manager (RCM)) on off
Modo de descoberta (24 h) (Discovery mode (24 h)) off (este agente roda o RCM) on

As linhas Id do cluster (padrão: o nome do host), Senha do administrador do RCM (padrão: gerada) e a porta de pareamento (padrão: a primeira livre, 7450) podem ficar como estão. Volte (Esc) e escolha Instalar (Install). O instalador mostra o plano: pressione Enter. Depois ele pergunta se deve começar a instalação (Nothing on this host was changed yet. Start the install now?). O cursor está em “Não” (No): vá para “Sim” (Yes) e pressione Enter. O instalador instala sozinho as bibliotecas que faltam (por exemplo, libtommath1). A interface de texto completa: hqbird2027-linux-setup-guide.md.

Com --no-tui, e nos kits 2027.2.29–2027.2.30, o instalador faz perguntas. A primeira é Install as planned? Yes/No: responda y. Depois ele faz duas perguntas sobre o cluster. A resposta padrão é Não (Enter):

Pergunta Mestre Réplica
Install the cluster manager (RCM) on this host and make a new cluster? [y/N] y Enter (Não)
Turn on discovery mode for 24 hours (an RCM on the network may invite this agent into its cluster; port 7450)? [y/N] não é feita: este agente roda o RCM y

Ou passe as respostas como opções: no terminal, elas definem os valores da página Cluster antes de ela abrir. Use-as também numa execução sem terminal: --yes sozinho significa Não para as duas.

Command
sudo sh hqbird2027-fb50-linux-$V.run --rcm on               # mestre
sudo sh hqbird2027-fb50-linux-$V.run --cluster-pairing on   # réplica

A instalação leva cerca de um minuto (teste de 2026-11-17: 61 segundos no mestre, 43 segundos na réplica). Fim da saída no mestre com o kit 2027.2.33 (o hash está encurtado aqui; o id do cluster nos exemplos abaixo é hq27d-m, do teste de 2026-11-08):

text
Done: agent hqbirdfbagent-fb50 in /opt/hqbird/fbagent-fb50, Firebird 5.0.5.1917 in /opt/firebird (port 3050).
HQ Monitor: http://localhost:23050/ (login admin; password in /opt/hqbird/conf/access.properties)
RCM:        https://10.114.0.5:7444 (cluster hq27d-m)
CA hash:    sha256:9754e0be…087cb195
Login:      rcmadmin
Password:   in /opt/hqbird/fbagent-fb50/clusterca/hq27d-m/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
fbmcp:      2027.2.24, service running; local only (remote mode: sudo fbmcp ctl hqbird-install --allow-from CIDR)

Na réplica:

text
RCM:        off; turn it on in HQbird Monitor or with fbagent --cluster-init <id>
Pairing:    port 7450 open until 2026-11-09T16:25:27Z (fingerprint sha256:0d137a71…09fe44cf); an RCM may invite this host

Um kit antigo escreve no mestre Pairing: not opened (this agent runs the RCM).

Anote as linhas RCM: e CA hash: do mestre e a linha Pairing: da réplica. A impressão digital (fingerprint) é usada no passo 3.

Kits antigos (agente anterior ao 3.1.0, por exemplo o kit 2027.2.27) não fazem perguntas sobre o cluster. Eles instalam o RCM em todo servidor e abrem a janela de pareamento em todos. Você usa o RCM do mestre; o RCM do segundo servidor para sozinho depois da vinculação.

Depois, sem o instalador. No HQ Monitor do servidor, abra Clusters, seção Cluster neste servidor. No mestre: Ativar o console do cluster (RCM); o HQ Monitor abre 7443 e 7444 no firewall. Na réplica: Abrir a janela de pairing por 24 horas. O mesmo com comandos, como o usuário do agente:

Command
cd /opt/hqbird/fbagent-fb50
sudo -u firebird ./fbagent --cluster-init hq27d-m     # mestre; abra 7443 e 7444 você mesmo
sudo -u firebird ./fbagent --cluster-pairing on       # réplica

Enquanto a janela de pareamento está aberta, o agente abre a sua porta de pareamento no firewall. Ele fecha a porta quando a janela termina ou o host é vinculado.

A saída não tem senhas. A senha do RCM está no arquivo da linha Password:, a senha do SYSDBA está em /root/fbagent-install-sysdba.txt, e a senha do HQ Monitor está em /opt/hqbird/conf/access.properties.

Não é preciso instalar uma licença: o agente novo inicia sozinho um trial de 7 dias, e os nós do cluster funcionam.

Passo 2. Login no RCM

Abra o endereço da linha RCM: do mestre. Se a porta 7444 estiver fechada para o seu PC, use um túnel SSH e https://localhost:7444:

Command
ssh -L 7444:127.0.0.1:7444 <usuário>@<mestre>

Se a porta 7444 do seu PC estiver ocupada, use outra porta local, por exemplo -L 17444:127.0.0.1:7444 e https://localhost:17444.

O navegador avisa sobre o certificado: o RCM é assinado pela CA do cluster. A página de login mostra “Hash da CA do cluster”: compare-o com a linha CA hash: da saída do instalador. Se forem iguais, instale o certificado da CA (o link “Baixar o certificado da CA (hqcluster-ca.crt)” na mesma página) como confiável ou aceite o aviso. Se forem diferentes, não faça login e verifique o endereço.

Login no RCM
Login no RCM

Usuário rcmadmin. A senha está no arquivo da linha Password::

Command
# o caminho vem da linha Password: da sua saída
sudo cat /opt/hqbird/fbagent-fb50/clusterca/hq27d-m/rcm-initial-password

O RCM pede logo uma senha nova (pelo menos 12 caracteres):

Troca de senha no primeiro login
Troca de senha no primeiro login

Um RCM anterior ao 2027.5.12 podia carregar esta página de novo, sem parar. O RCM 2027.5.12 (kit 2027.2.33) tem a correção.

Depois da troca da senha, o agente do mestre apaga sozinho o arquivo rcm-initial-password em até um minuto. Com um kit antigo, o segundo servidor também tem um RCM próprio. Depois da vinculação, o agente move esse cluster anterior para a pasta cluster/left/. O agente 3.1.0 apaga lá o rcm-initial-password dele; um agente antigo não. Então apague o arquivo você mesmo:

Command
# no servidor 2, depois do passo 3
sudo find /opt/hqbird -name rcm-initial-password
sudo rm <caminho da saída do find>

Não apague o arquivo /opt/hqbirdrcm/initial-admin.json: ele tem só o hash da senha antiga, e sem ele um RCM que perdeu o arquivo de usuários inicia com a senha padrão.

Depois da troca da senha, o RCM abre logo Configurações → Vincular hosts: o cluster ainda não tem nós. A lista “Versões no espelho” mostra as versões de hqbirdrcm e hqclusternode que os agentes usam para instalar os nós.

Vincular hosts depois do login
Vincular hosts depois do login

Passo 3. Vincular hosts

A primeira linha da lista já está preenchida (o host do RCM). Adicione a segunda: o endereço da réplica que o mestre alcança. Digite o IP se os servidores não têm um DNS comum: o RCM guarda a linha como ela está, e os nós se encontram por ela.

Lista de hosts
Lista de hosts

Clique em Verificar hosts. Para um host sem porta, o RCM consulta as portas de pareamento 7450–7459 e mostra uma linha para cada agente que responde, como host:porta (aqui 10.114.0.6:7450). Escreva host:porta para consultar uma só porta. O host do RCM não precisa de janela de pareamento: o RCM encontra o agente dele no próprio registro. Compare a Impressão digital do certificado com a saída do instalador (a linha Pairing: da réplica): elas devem ser iguais. O estado do segundo host é “Pronto para vincular”. A coluna “ID do membro” mostra o nome que o host recebe no cluster: <nome do host>-<função>, por exemplo hq27d-m-master. O sufixo da instância (-fb50) é adicionado somente se o host tem vários agentes.

Verificação dos hosts
Verificação dos hosts

Cada linha tem uma caixa de seleção, a porta, a instância e a porta do nó. Vincular usa somente as linhas marcadas. Uma linha com erro não pode ser marcada e não para as outras. Abaixo da tabela, o RCM 2027.5.12 escreve linhas como 10.114.0.6, no agent: closed or no answer: 7451-7459: são as portas de pareamento do host em que nenhum outro agente responde. Não são erros.

Master é o host onde ficarão os bancos de trabalho. Clique em Vincular e confirme:

Confirmação
Confirmação

Andamento: “Entrando → Entrou → O nó está iniciando → Em execução”. No teste, a vinculação levou 56 segundos (teste de 2026-11-17: 47 segundos).

Andamento da vinculação
Andamento da vinculação
Concluído
Concluído

Agora a Visão Geral mostra dois nós: mestre e réplica. Logo depois da vinculação, a réplica pode ficar “inativo” por um minuto; depois, “online”.

Visão Geral: dois nós
Visão Geral: dois nós

Se você clicar de novo em “Verificar hosts” para um host já vinculado, o RCM mostra que nenhum agente responde nas portas de pareamento ou que o host está inacessível: a janela de pareamento desse host está fechada, e a porta de pareamento dele também está fechada no firewall. Isso não é um erro.

Um host num cluster que já tem um mestre. A vinculação de uma só linha é recusada com lone_master: diga o papel da linha. -replica-of <membro do mestre> faz uma réplica desse mestre; -new-master (a caixa de seleção na página Vincular hosts) faz um mestre próprio.

Passo 4. Pasta dos bancos no mestre

No mestre, o banco precisa ficar em uma pasta acessível ao usuário firebird:

Command
sudo install -d -o firebird -g firebird -m 0770 /databases/master
# exemplo: o banco de exemplo do pacote
sudo cp /opt/firebird/examples/empbuild/employee.fdb /databases/master/
sudo chown firebird:firebird /databases/master/employee.fdb

Na réplica, não é preciso preparar nada: o botão “Criar pasta” do diálogo de inicialização cria a pasta para as cópias (passo 6).

Passo 5. Registro dos bancos no mestre

Bancos de Dados → na tabela “Nós”, na linha do mestre → Registrar.

  • Caminho da pasta nesse servidor: /databases/master, recursivo.
  • Máscara de inclusão de arquivos: *.fdb.
  • Tabelas de rastreamento de sincronização: as tabelas cujo número de linhas o botão “Verificar” compara. A lista vale para cada banco registrado. Deixe o campo vazio: então o banco conta as tabelas da sua publicação. A lista de um banco já gerenciado é alterada na página do banco do mestre.
Formulário de registro
Formulário de registro

Pré-visualizar → marque os bancos → Registrar os selecionados e confirme.

Confirmação do registro
Confirmação do registro

O resultado é “Registrados: 2.” e uma dica: é preciso reiniciar o Firebird do mestre. O texto “Nenhum banco de dados novo correspondeu.” abaixo dele não é um erro: os bancos já foram registrados.

Resultado do registro
Resultado do registro

Os bancos ficam no estado “Reinício pendente”:

Reinício pendente
Reinício pendente

Clique em Reiniciar o Firebird do mestre na linha de qualquer banco do mestre (uma vez basta para todos) e confirme. Todas as conexões ao Firebird do mestre caem por alguns segundos (no teste, 4 segundos): escolha o horário.

Reinício do Firebird do mestre
Reinício do Firebird do mestre

Depois do reinício, o nó do mestre fica CONFIGURED. Cada banco tem o selo publicação DESATIVADA, e a réplica mostra “não pareado”.

Depois do reinício
Depois do reinício

Passo 6. Inicialização da réplica

Na linha do banco, na coluna da réplica → Inicializar. O diálogo se chama “Inicializar banco de dados?”.

Diálogo de inicialização
Diálogo de inicialização
  • Publicação. Enquanto a publicação do banco está desativada, o Firebird não grava as alterações no journal, e a réplica não recebe nada. O diálogo informa isso e mostra o botão Sincronizar publicação e inicializar. Clique nele: o RCM inclui na publicação todas as tabelas com chave primária ou única e inicia logo a inicialização. O botão Inicializar com a publicação desativada não resolve: o nó do mestre recusa (publication_off).
  • Pasta da réplica: o diálogo propõe /databases/replica/<nó da réplica>, no teste /databases/replica/hq27d-r-replica. Cada nó réplica de um host precisa da própria pasta. Mantenha-a. Se abaixo do campo aparece “✗ A pasta não existe”, clique em Criar pasta; então aparece “✓ A pasta foi criada.” A cópia fica em /databases/replica/hq27d-r-replica/hq27d-m-master/. Para os bancos seguintes, a pasta já está definida, e o diálogo não a altera.
  • Método de reinit: Suave (padrão). Ele verifica as transações de escrita antes do bloqueio. Padrão bloqueia o banco logo.
  • As caixas “Permitir que … pare o Firebird” e “Remover a réplica antiga se faltar espaço” não são necessárias para uma réplica nova.

Reconecte as aplicações depois da primeira sincronização da publicação. Uma conexão com o banco do mestre aberta antes de a publicação ser ativada não é gravada no journal até conectar de novo. No teste de 2026-11-17, uma conexão aberta antes da sincronização da publicação e da inicialização gravou cerca de 9.500 linhas depois da cópia, e a réplica não recebeu nenhuma. O RCM mostrava “Ok” nos dois lados; somente Verificar (passo 9) mostrou “Não ok (dessincronizado)”. As linhas de uma conexão nova foram replicadas logo. Por isso, depois da primeira sincronização da publicação de um banco: reconecte as aplicações (ou reinicie o Firebird do mestre) e depois rode Verificar sem escritas. Se faltarem linhas na réplica, faça um reinit (passo 7).

Primeira inicialização com carga. Enquanto o arquivo do mestre não tem nenhum segmento de journal, o método “Suave” pode recusar se o banco recebe escritas. A linha do banco mostra long_transactions: … the archive holds no segment yet e uma dica no idioma da interface:

Recusa do método suave
Recusa do método suave

No teste, isso aconteceu também depois de “Sincronizar publicação e inicializar” (achado G-04 no relatório). A publicação já fica ativada. Espere até o banco do mestre mostrar “arquivo: 1 seg.” ou mais (no teste, depois de 15 segundos) e clique de novo em Inicializar com o método “Suave”. Ou escolha “Padrão”. No teste de 2026-11-17 (≈49 transações/s de uma só conexão), “Suave” não foi recusado.

O andamento aparece na linha do banco: SPACE CHECK → LOCKING → COPYING TO NODE (%) → UNLOCKING → SEEDING → RESTARTING REPLICA. O andamento aparece também depois de recarregar a página. O botão “Inicializar” fica inativo durante esse tempo.

Andamento da inicialização
Andamento da inicialização

Depois da cópia, o nó da réplica reinicia sozinho o Firebird da réplica no minuto planejado. A linha diz quando; o botão Reiniciar o Firebird da réplica faz isso logo. Todas as conexões ao Firebird da réplica caem nesse momento.

Aguardando o reinício do Firebird da réplica
Aguardando o reinício do Firebird da réplica

Um banco grande segue os mesmos passos. No teste, bulk.fdb (3,13 GB) foi inicializado com o botão “Sincronizar publicação e inicializar”, sem carga nele:

Cópia de um banco grande
Cópia de um banco grande

Está pronto quando o mestre e a réplica mostram “Ok”, e o “último segmento aplicado” da réplica alcança o “último segmento” do mestre. Um banco sem escritas novas (aqui bulk.fdb) mostra na réplica “Pendente” com o segmento 0: isso é normal.

Os dois bancos prontos
Os dois bancos prontos

Medições do teste (employee.fdb com carga de ≈55 transações/s):

Banco Tamanho Mestre: do início ao fim Bloqueio no mestre Par “Ok”
employee.fdb 4 MB 0,7 s 0,35 s depois de ≈1 min (esperou o reinício da réplica)
bulk.fdb 3,13 GB 64 s (≈55 MB/s) 59 s depois de ≈2 min

Teste de 2026-11-17 (kit 2027.2.33): employee.fdb (3 MB) levou 3 segundos no mestre, e bulk.fdb (167 MB) levou 15 segundos. O lado da réplica ficou pareado ≈40 segundos depois do início (esperou o reinício do Firebird da réplica).

Durante o bloqueio, o banco do mestre continua funcionando: as alterações vão para o arquivo .delta.

Publicação depois. O botão Sincronizar publicação do banco do mestre é necessário quando o banco ganhou tabelas novas. Ele ajusta a publicação às tabelas em uma transação; o Firebird não reinicia.

Sincronizar publicação
Sincronizar publicação

Tabelas da publicação mostra quais tabelas são replicadas. Uma tabela sem chave não pode ser publicada: dê a ela uma chave primária.

Tabelas da publicação
Tabelas da publicação

Passo 7. Reinicialização

A reinicialização é necessária quando a réplica divergiu do mestre ou quando o próprio nó a pede (NEEDS_REINIT). Na linha da réplica → Reinicializar, método Suave. O arquivo de segmentos já existe, e o método suave passa com carga. Ele espera as transações de escrita mais antigas que o histórico do journal e as mostra.

Reinicialização, método suave
Reinicialização, método suave

O andamento é o mesmo da inicialização. Na reinicialização, em geral não é preciso reiniciar o Firebird da réplica. No teste de 2026-11-17, o reinit de employee.fdb reiniciou o Firebird da réplica: conte com a queda das conexões com a réplica. Esse reinit levou 4 segundos no mestre com ≈49 transações/s; depois de parar as escritas, os números de linhas coincidiram (14.418 linhas na tabela de carga nos dois lados).

Cópia na reinicialização
Cópia na reinicialização

Medições do teste:

Banco Carga Tempo Bloqueio Observação
employee.fdb ≈55 transações/s 1,7 s 0,32 s 417 transações repetidas a partir dos segmentos
bulk.fdb nenhuma 61 s 55 s sem reinício do Firebird da réplica

Depois de um reinit suave com carga, a réplica pode mostrar o alerta info replication_conflict_resolved (“Record being inserted … already exists, updating instead”): a réplica repetiu transações que já estavam na cópia. Os dados são iguais: no teste, o número de linhas de todas as tabelas coincidiu. O alerta pode ser reconhecido (achado G-07 no relatório).

Passo 8. Pouco espaço na réplica

O volume da réplica precisa de ≥ 105% do tamanho do banco livres mais 1 GB além da cópia antiga: a cópia antiga fica até o fim, e o arquivo novo ocupa logo o tamanho total. Se falta espaço, o diálogo mostra quanto espaço é necessário, quanto está livre e quanto ocupa a cópia antiga (estimativa do RCM; quem decide é o nó da réplica). Se o espaço basta sem a cópia antiga, o diálogo recomenda a caixa Remover a réplica antiga se faltar espaço.

Pouco espaço: caixa "Remover a réplica antiga se faltar espaço"
Pouco espaço: caixa "Remover a réplica antiga se faltar espaço"

Com a caixa marcada, o nó da réplica, depois do bloqueio do mestre, para o Firebird da réplica, apaga a cópia antiga e inicia o Firebird de novo. No teste (2,97 GB livres, a cópia nova precisava de 3,29 GB, a cópia antiga tinha 3,13 GB), a reinicialização de bulk.fdb com a caixa levou 65 segundos. Sem a caixa, o nó recusa com insufficient disk space on replica.

O diálogo pode não mostrar números quando falta somente a reserva de 1 GB. No teste de 2026-11-17 (1,1 GB livre, banco de 167 MB), o diálogo não mostrou a estimativa, e o reinit sem a caixa falhou em 3 segundos. A linha do banco e a página Comandos mostraram o motivo: insufficient disk space on replica: need 184125850 bytes (105% of the database) + 1073741824 bytes free_space_floor_gb; free 1152950272 … Removing the old replica copy would free 175357952 bytes: ask again with remove_old_replica. O mesmo reinit com a caixa levou 9 segundos.

Risco da caixa. Durante a cópia, não existe réplica deste banco. Se o reinit falhar, o par fica em NEEDS_REINIT, a réplica mostra o alerta replica_removed_for_reinit (warn), e repetir significa um novo reinit completo. O reinit automático apaga a cópia antiga somente se a chave do RCM auto_reinit.remove_old_replica_when_short está ativada (padrão: desativada).

Passo 9. Verificação

Verificar na linha da réplica compara o COUNT(*) das tabelas de rastreamento no mestre e na réplica. Não é uma comparação linha a linha. A linha “Origem da lista de tabelas” diz qual lista foi usada: a lista própria do banco, a lista do nó, as tabelas da publicação ou RDB$FIELDS. Os números têm separadores de milhar.

Com carga, a réplica fica alguns segundos atrás, e “Verificar” mostra “Não ok” nas tabelas que recebem escritas:

Verificação com carga
Verificação com carga

Sem escritas, os números coincidem:

Verificação sem carga
Verificação sem carga

Uma tabela que não existe em nenhum dos dois bancos aparece como “não está no banco de dados”: isso não é uma diferença. Uma tabela que existe somente de um lado aparece como “sem tabela”: isso é uma diferença.

Um método mais confiável: contar as linhas de todas as tabelas dos dois lados depois de parar as escritas (o script está no hqbird2027-linux-cluster-runbook.pt.md). No teste, as 11 tabelas coincidiram (employee.fdb: 10, bulk.fdb: 1, com 2.800.000 linhas).

A verificação periódica (Verificação de dados) vem desativada por padrão. Clique em Ativar em todos os nós e confirme: cada nó conta as suas linhas, e o mestre compara os números. Não é preciso reiniciar: o RCM mostra “Salvo e já em vigor: o nó não precisa reiniciar.” A primeira verificação acontece depois de um intervalo (padrão: 2 horas).

Verificação periódica
Verificação periódica

O que acompanhar depois

  • Visão Geral: os nós, o estado deles, a raiz dos bancos e o espaço em disco.

    Visão Geral
    Visão Geral
  • Alertas: problemas dos nós e dos bancos. No teste, houve dois alertas, e os dois podem ser reconhecidos (Reconhecer): replication_conflict_resolved depois do reinit suave (passo 7) e parse_no_observations no mestre (“no events parsed from /opt/firebird/replication.log”). O Firebird do mestre grava em replication.log somente erros; por isso, um log vazio é normal (achado G-06 no relatório).

    Alertas
    Alertas

    O RCM 2027.5.12 e mais novos (kit 2027.2.33) pode enviar os alertas de nível warn e acima para um bot seu do Telegram, um webhook ou e-mail. Os canais são definidos no arquivo /opt/hqbirdrcm/rcm.json, chave notify.channels; depois reinicie o RCM (sudo systemctl restart hqbirdrcm). O bloco Canais de notificação desta página mostra então os canais, cada um com um botão Enviar teste. Sem canais, o bloco diz que o RCM não envia os alertas para lugar nenhum. Um canal do Telegram:

    json
    "notify": { "channels": [ { "name": "ops", "type": "telegram",
        "token_file": "secrets/telegram-ops.token", "chat_id": "-1001234567890" } ] }

    O teste de 2026-11-17 verificou o bloco sem canais; nenhuma mensagem foi enviada.

  • Serviços (RCM 2027.5.11 e mais novos, kits a partir do 2027.2.31): o mestre, as réplicas e os roteadores de um serviço, e as operações switchover, failover e rejoin. Este guia não trata delas: veja o guia do usuário do RCM. Antes de usá-las, atualize o RCM e os nós para a mesma versão.

  • Comandos: cada operação do RCM com o resultado. A hora é a hora local do navegador com o fuso (por exemplo, 17:59:45 UTC+1), e a dica (tooltip) mostra a hora em UTC. Os logs dos nós estão em UTC.

    Comandos
    Comandos
  • HQ Monitor: http://<servidor>:23050/, usuário admin, senha em /opt/hqbird/conf/access.properties. Mostra o servidor e os bancos. Nos kits com o agente 3.1.0 e mais novos, o HQ Monitor tem a página Clusters. No mestre (o host do RCM), ela mostra o cluster por meio do agente, sem configurações do RCM no HQ Monitor. Na réplica, ela mostra o host do RCM e tem um link para o console dele. O HQ Monitor 1.49.0 não mostra o estado da replicação e não tem link para o RCM. A partir do kit 2027.2.33 (agente 3.4.0), o agente também envia os problemas do seu servidor para os seus canais: Servers → Notifications.

Atualizar o cluster

Atualize primeiro o HQbird RCM e depois os nós. A partir do kit 2027.2.31, um servidor que não está ligado a um HQCenter atualiza sozinho o agente, o HQ Monitor e o fbmcp (seção “Updates without HQCenter” em hqbird2027-linux-setup-guide.md). Um servidor ligado a um HQCenter recebe as atualizações desse HQCenter.

Tirar um host do cluster

Command
cd /opt/hqbird/fbagent-fb50
sudo ./fbagent --cluster-leave

O agente para e remove os serviços dos seus nós, fecha as portas deles, apaga os seus certificados do cluster e define cluster.source como none. A pasta do nó fica (--remove-data apaga a pasta). O agente que roda o RCM recebe uma recusa. O agente também sai sozinho quando o RCM o revoga ou retira o seu último membro. Uma desinstalação sempre tira o agente do cluster: uma nova instalação na mesma pasta começa com um agente livre. No teste de 2026-11-17, o comando escreveu Cluster: left <id do cluster>, os bancos da réplica ficaram na pasta deles, e o RCM ainda mostrava o nó desse host um minuto depois. A remoção do HQbird de um servidor do cluster, também do servidor que roda o RCM: hqbird2027-removal-guide.md, seção 4.

Erros comuns

O que aparece Causa O que fazer
publication_off na inicialização a publicação está desativada, ou não tem tabelas embora o banco tenha tabelas com chave botão “Sincronizar publicação e inicializar” (passo 6)
long_transactions … the archive holds no segment yet primeira inicialização com o método suave, o banco recebe escritas, o arquivo do mestre está vazio esperar “arquivo: 1 seg.” e repetir com “Suave” ou escolher “Padrão”
reinit_pre_publication_transactions uma transação de escrita começou antes da ativação da publicação e está aberta há mais de um minuto terminar a transação (COMMIT ou ROLLBACK) e repetir
“✗ A pasta não existe em …” no diálogo a pasta da réplica não foi criada botão “Criar pasta” no diálogo ou install -d -o firebird -g firebird -m 0770 <pasta> na réplica
“Não ok (dessincronizado)” em “Verificar” sem escritas; os dois lados mostram “Ok” uma conexão da aplicação foi aberta antes de a publicação ser ativada: ela não é gravada no journal reconectar a aplicação e depois Reinit (passo 6, a nota sobre a primeira sincronização da publicação)
“Não ok (dessincronizado)” em “Verificar” o banco recebe escritas, e a réplica fica alguns segundos atrás repetir sem carga; olhar a coluna “Corresponde”
Host “unreachable” ou “nenhum agente” em “Vincular hosts” a janela de pareamento do host está fechada (desligada por padrão, ou as 24 h terminaram), ou um firewall entre os servidores fecha 7450–7459 abrir a janela no host: HQ Monitor → Clusters → Abrir a janela de pairing por 24 horas, ou fbagent --cluster-pairing on; abrir a porta no firewall da nuvem
insufficient disk space on replica na reinicialização a réplica antiga fica até o fim, e o arquivo novo ocupa o tamanho total liberar no volume da réplica ≥ 105% do tamanho do banco + 1 GB além do arquivo antigo, ou usar a caixa “Remover a réplica antiga se faltar espaço” (passo 8)
O nó não apareceu depois de “Vincular hosts” o espelho do RCM não tem uma versão assinada de hqclusternode “Versões no espelho” na página “Vincular hosts” (passo 2)