Cluster e replicação HQbird Cluster
Cluster e replicação HQbird Cluster
O master grava as alterações em segmentos e os envia às réplicas por um canal seguro. O próprio nó faz a cópia do banco de dados para uma nova réplica, via nbackup, enquanto os usuários trabalham. O gerenciador do cluster (RCM) mostra o atraso, as filas e os erros de todos os nós. Ele também move o master para outro host: de forma planejada, sem perda de dados, ou de emergência, quando o host do master foi perdido.
- Firebird 2.5 · 3 · 4 · 5
- nbackup cópia sem parar o master
- switchover sem perda de dados
- failover manual ou por regra
- roteador a string de conexão não muda
- mTLS em todos os canais
Nós · RCM · topologias
Como o cluster funciona
Ao lado de cada Firebird roda um nó. O nó tem um papel: master ou réplica. O nó do master envia segmentos, o nó da réplica os recebe, e o Firebird da réplica os aplica à sua cópia do banco de dados.
Há um RCM por cluster. Ele roda em qualquer host que alcance todos os nós. Os nós enviam estatísticas a ele, e ele repassa aos nós os comandos do operador. O RCM liga master e réplica pelo GUID do banco de dados, não pelo nome do nó.
O RCM não se instala sozinho. Ele é ligado em um host quando é preciso um cluster. Na frente das aplicações é possível colocar um roteador: ele sempre leva as aplicações ao master atual.
| Componente | Quantidade | O que faz |
|---|---|---|
| Firebird (HQbird) | em cada servidor de banco de dados | Armazena os bancos de dados e grava os segmentos de replicação. |
| fbagent | um por instância do Firebird | Para e inicia o Firebird a pedido do nó. |
| hqclusternode | um por instância e papel | Configura a replicação, transfere segmentos, faz a cópia do banco de dados para a réplica. |
| hqbirdrcm (RCM) | um por cluster | Interface web, comandos, alertas, estatísticas. Conduz o switchover e o failover. |
| Roteador (hqclusternode router) | opcional, no host das aplicações, Linux | Mantém o HAProxy apontado para o master de cada serviço. As aplicações se conectam ao roteador. |
- Mesma versão principal5.0 no master, 5.0 na réplica. Caso contrário, a réplica recusa antes de transferir dados.
- HQbird 2.5 e 3.0Replicação via plugin replconf. Filtros definem o conjunto de tabelas.
- Pasta própria para cada masterA réplica coloca o banco de dados em uma pasta com o nome do nó master. Bancos com o mesmo nome de masters diferentes não entram em conflito.
- Sem fbagent, sem alteraçõesSe o fbagent não está disponível, o nó recusa qualquer ação que altere a configuração. Ele não funciona “pela metade”.
- Nó sem RCMO nó pode funcionar sozinho. O RCM é necessário para a visão geral e os comandos.
- Compressão do canalPara rede lenta: zstd por par, vale na hora.
- Até 3 hosts sem o HQCenterCada host com um master ou uma réplica ocupa um lugar no cluster. O RCM não aceita um quarto host.
RCM · janela de pareamento · Link hosts · slots
Como montar o cluster
A instalação do HQbird coloca os programas do cluster em cada servidor, mas não os liga. O RCM e a janela de pareamento vêm desligados por padrão. O cluster é montado em três passos: ligar o RCM em um host, abrir a janela de pareamento nos outros, vincular os hosts com um botão.
- 1Ligar o RCMem um host: no HQ Monitor ou com
fbagent --cluster-init - 2Abrir a janela de pareamentonos outros hosts, por 24 horas
- 3Link hostso RCM encontra os agentes, emite os certificados e inicia os nós
Passo 1. RCM em um host
No HQ Monitor, abra a seção “Cluster on this server” e ligue o RCM. Um comando no host faz o mesmo. O agente cria a CA do cluster, o certificado do RCM e o primeiro usuário. No firewall, as portas 7443 e 7444 são abertas.
fbagent --cluster-init <id>
Na instalação, a opção --rcm on (Linux) ou /RCM (Windows) faz o mesmo.
Passo 2. Janela de pareamento
Em cada host que vai entrar no cluster, o agente abre a porta de pareamento por 24 horas. A porta se fecha sozinha quando a janela termina ou quando o agente entrou no cluster.
fbagent --cluster-pairing on
Um botão no HQ Monitor faz o mesmo. Na instalação: --cluster-pairing on ou /DISCOVERY.
Passo 3. Link hosts
No RCM, abra Settings → Link hosts e digite os hosts, um por linha. O botão Check hosts lê as portas 7450–7459 de cada host. Cada agente que respondeu é uma linha da tabela.
- A linha mostra: porta, instância, versão e porta do Firebird, porta do nó, impressão digital do certificado.
- Marque as linhas e escolha o master. Uma linha com erro não atrapalha as outras.
- Link emite um certificado para cada agente, cria os participantes e os vínculos master → réplica.
- O RCM espera o certificado do agente por até 10 minutos e o início dos nós por até 20 minutos.
hqbirdrcm cluster link -hosts db1,db2,db3 -master db1
Compare a impressão digital na linha com a que o agente mostrou no seu host. Assim você sabe que vincula o servidor certo.
- Vários agentes em um hostCada agente tem seu slot, de 0 a 9. Porta de pareamento 7450 + slot, portas dos nós 7051 + slot e 7061 + slot. A instalação escolhe o slot; a opção
--pairing-porto define explicitamente. - Add memberA página Cluster sugere uma porta de nó livre e recusa uma porta ocupada por outro participante deste host.
- Nomes dos participantes
<nome do host>-mastere<nome do host>-replica. O RCM não renomeia um participante: um novo nome é um novo participante. - Sem janela de pareamentoO RCM emite um token para um agente, válido por 24 horas. No novo host:
fbagent --cluster-joincom esse token e o hash da CA.
- Dono do RCMO agente que ligou o RCM no host. Um segundo agente deste host recebe uma recusa. Se o dono foi removido,
fbagent --cluster-init --rcm-takeoverpassa o RCM para outro agente. O cluster recebe uma nova CA, e os participantes precisam ser vinculados de novo. - Saída do cluster
fbagent --cluster-leavepara os nós, fecha as portas deles e apaga os certificados do cluster. As pastas dos nós ficam;--remove-dataas apaga. O agente sai sozinho se o RCM o revogou ou removeu o último participante. - FirewallO agente abre e fecha sozinho as suas portas do cluster. Uma porta que já estava aberta antes dele, ele não fecha.
- Remoção do HQbirdO dono do RCM não é removido enquanto outros agentes usam o seu RCM. O assistente de instalação pergunta; o modo silencioso exige
--forceou/FORCE.
A página Clusters no HQ Monitor local funciona por meio do agente do host do RCM. Ela não precisa da senha do RCM. A seção “Cluster on this server” só aparece para o administrador.
Inicialização · reinit
Nova réplica sem parar o master
A réplica recebe o banco de dados só do master. O nó do master congela o arquivo com nbackup -L, envia-o em partes e remove o bloqueio logo em seguida. Os usuários do master continuam trabalhando o tempo todo: suas alterações vão para o .delta e depois voltam ao banco de dados.
gbak e cópia manual do arquivo não servem. O gbak altera o GUID do banco de dados e quebra o vínculo master–réplica. A cópia do arquivo de um banco em uso não é consistente.
Usuários do master
Arquivos
- Queda de conexãoA transferência continua a partir da última parte recebida. A cópia incompleta fica na réplica por 24 horas.
- ErroO nó remove o bloqueio, apaga o arquivo incompleto e marca o banco de dados como FAILED. A próxima tentativa começa de um estado conhecido.
- Transações durante o bloqueioNão se perdem. Firebird 4 e 5: o nó encontra as transações abertas no momento do
nbackup -L, e a réplica as repete a partir dos segmentos. HQbird 2.5 e 3.0: o nó espera essas transações terminarem (cerca de um minuto); caso contrário, a cópia não começa.
- Um banco de dados por vezPor padrão, o nó do master copia um banco de dados. Os outros esperam na fila.
- Outras réplicas deste bancoDurante a cópia, não recebem segmentos deste banco de dados. Depois se atualizam.
- Reinicialização automáticaO RCM pode copiar de novo, por conta própria, um banco de dados no estado NEEDS_REINIT, apenas em uma janela definida. Desligada por padrão.
O modo suave espera as transações longas
Antes do bloqueio, o nó procura transações de escrita que começaram antes do segmento mais antigo no arquivo de journals do master. Se o arquivo está vazio (primeira cópia), o limite é o momento em que o nó ligou a publicação. A réplica não consegue repetir essas transações e pararia. Por isso, a cópia não começa enquanto essas transações estiverem abertas.
O RCM mostra as cinco conexões com as transações mais antigas: usuário, cliente, idade, consulta atual. Você pode desconectá-las e repetir a cópia na hora. Enquanto a cópia espera, o arquivo de journals do master não é limpo, mas por no máximo 1000 segmentos. Depois a limpeza continua, e o RCM gera um alerta.
O modo normal bloqueia o banco de dados na hora, sem a verificação.
Espaço e velocidade
| Onde | O que é necessário |
|---|---|
| Master, volume do banco de dados | Livre pelo menos 105 % do tamanho do banco de dados. Durante a cópia, o .delta cresce. |
| Réplica, volume do banco de dados | 105 % mais a reserva do volume free_space_floor_gb (1 GB por padrão). O nó reserva o tamanho total com antecedência; uma segunda cópia não é necessária. Em uma nova cópia, o arquivo antigo fica até o fim. Se não há espaço para os dois arquivos, a opção “Remover a réplica antiga” apaga o arquivo antigo antes da transferência. |
| Velocidade à noite | Na janela de transferência (por padrão 23:00–05:00) é constante, por padrão 100 MB/s. |
| Velocidade de dia | Uma fração da velocidade medida do disco, por padrão a metade. Uma cópia iniciada de dia acelera sozinha à noite. |
O espaço é verificado duas vezes e só antes do bloqueio: primeiro pelo RCM com base nas estatísticas, depois pelos nós com medição ao vivo nos dois lados. A verificação do nó não pode ser ignorada: ela evita que o disco encha no meio da cópia.
Firebird 4 e 5 · HQbird 2.5 e 3.0
Publicação: quais tabelas vão para a réplica
O Firebird 4 e 5 grava nos segmentos apenas as alterações das tabelas publicadas, e só com a publicação ligada. Sem ela, as alterações não chegam à réplica. O nó percebe isso e gera um alerta. O botão “Sincronizar publicação” a liga e monta a lista correta de tabelas.
O que a sincronização faz
- liga a publicação, a menos que o operador a tenha desligado por conta própria;
- adiciona todas as tabelas com chave primária ou índice único;
- remove as tabelas sem chave e as tabelas que o operador excluiu;
- desliga a inclusão automática de novas tabelas.
Sem chave, a réplica não encontra a linha para UPDATE e DELETE. Por isso, essa tabela não pode ser publicada: adicione uma chave e sincronize de novo.
- Verificação a cada horaSe a publicação está desligada, o nó a verifica a cada 2 minutos. Para um banco de dados com réplica, isso é um alerta.
- Lista de exclusõesFica no nó do master. Quando a réplica é promovida a master, a lista passa para o novo master.
- Nova tabelaNão entra na publicação sozinha. Crie uma chave e clique em “Sincronizar publicação”.
- Cópia sem publicaçãoO nó do master recusa a cópia do banco de dados se a publicação está desligada ou não tem tabelas (
publication_off). A janela de inicialização oferece “Sincronizar publicação e inicializar”. - HQbird 2.5 e 3.0Não há publicações. Os filtros de inclusão e exclusão nas configurações de replicação definem o conjunto de tabelas.
Alterações feitas enquanto a publicação estava desligada ou a tabela excluída não chegam à réplica, mesmo depois de ligá-la. “Verificar” compara só o número de linhas; não encontra UPDATEs perdidos. Se o banco de dados recebeu gravações com a publicação desligada, copie o banco de dados de novo.
Atraso · arquivo · alertas · verificação de dados
Monitoramento: a réplica não fica para trás em silêncio
Os nós enviam estatísticas ao RCM a cada 30 segundos. Para cada par master–réplica você vê: o último segmento, quantos foram enviados, confirmados e aplicados, a fila e o atraso em segundos.
| Estado do banco de dados | Grupo no RCM | Significado |
|---|---|---|
IN_SYNC | Ok | A réplica recebeu todos os segmentos. |
LAGGING | Pending | A réplica está atrasada, há segmentos na fila. |
SEEDING | Pending | O banco de dados está sendo copiado para a réplica. |
NEEDS_REINIT | Error | A réplica precisa ser copiada de novo. |
FAILED | Error | A última cópia falhou. |
O arquivo de journals do master é limpo em etapas
O master guarda os segmentos enviados para que a réplica possa pedi-los de novo. Se falta espaço, ele apaga primeiro o que com certeza não é necessário.
- 1Aplicados por todas, mais antigos que o prazoprazo padrão de 2 dias
- 2Aplicados, mas mais novos que o prazose há menos de 1 GB livre; alerta
- 3Ainda não aplicadospor último; a réplica precisa de uma nova cópia
Alertas com instruções
O RCM conhece mais de 20 tipos de alerta, e cada um tem uma instrução do que fazer. Um alerta pode ser confirmado, silenciado por 60 minutos ou removido. Se a causa continuar, o alerta aparece de novo.
Não há e-mail nem webhook: acompanhe a página “Alertas” ou consulte a API do RCM.
| Código | O que aconteceu |
|---|---|
backlog_warn / backlog_critical | O master tem 32 / 48 segmentos não arquivados. |
apply_error, replication_stopped | A réplica não consegue aplicar um segmento. |
replication_guid_mismatch | O GUID do banco de dados do master mudou: restore ou troca do arquivo. |
segment_missing, sequence_gap | A sequência de segmentos está quebrada. |
firebird_down, firebird_log_error | O Firebird está parado ou registra erros. |
firebird_not_answering | A porta do Firebird está aberta, mas não é possível conectar ao banco de dados há um minuto. |
master_publication_off | A publicação está desligada em um banco de dados com réplica. |
data_mismatch | A verificação periódica encontrou uma diferença. A verificação é ligada à parte. |
Comparação entre master e réplica
Verificar conta as linhas das tabelas escolhidas no master e na réplica e as compara. Não compara o conteúdo das linhas: não encontra linhas alteradas. Execute em um horário calmo: com gravação ativa, os números podem diferir.
A verificação periódica vem desligada por padrão: COUNT(*) lê a tabela inteira. Ligue-a com o parâmetro do nó data_check_enabled; ela roda a cada 2 horas. Novas configurações da verificação valem na hora, sem reiniciar o nó. A verificação compara os dados quando master e réplica estão no mesmo segmento. Uma diferença gera um alerta. Uma tabela excluída da publicação aparece como “not published”, e não como erro.
- Pausa no envioPara um ou vários bancos de dados. Depois de “Retomar”, o envio continua a partir do último segmento, sem nova cópia. O arquivo de journals cresce nesse meio-tempo.
- Logs do nó remotoreplication.log, firebird.log e o log do nó direto no RCM, sem entrar no servidor.
- Sem licençaO master para o envio; o Firebird e os bancos de dados continuam funcionando. Depois de instalar a licença, o envio volta sozinho em até um minuto.
- Registro de comandosCada comando do RCM é registrado com o autor e o resultado. Relatório do cluster em um único arquivo JSON.
Serviço · época · onde está o master
Serviços: um banco de dados em vários hosts
Um serviço é um banco de dados lógico em vários hosts. O master pode passar de um host para outro, mas o nome do serviço e o alias do banco de dados não mudam. As aplicações e os roteadores perguntam ao RCM onde está o master do serviço agora.
Cada troca de master recebe o próximo número: a época. O RCM guarda o histórico das épocas: quando o master mudou e por quê. O serviço é encontrado pelo nó e pelo caminho do arquivo, não pelo GUID: no switchover o GUID do banco de dados muda, o caminho fica.
O que o serviço descreve
- alias — nome do banco de dados no
databases.conf. O novo master o grava sozinho. - members — um registro por host: nó master, nó de réplica, caminho do arquivo, prioridade.
- router_port — porta em que os roteadores recebem as aplicações deste serviço.
- policy — regras do failover automático e o modo de fechamento do master antigo.
Em cada host do serviço rodam dois nós no mesmo Firebird: o nó master e o nó de réplica. É a mesma topologia “Dois nós por host” do diagrama acima.
O nó master precisa do endereço do Firebird para os clientes: o parâmetro advertise_addr. Sem ele, o RCM não diz à aplicação onde se conectar.
Onde está o master agora
hqbirdrcm services put -id shop -file shop.json hqbirdrcm services hqbirdrcm where -service shop hqbirdrcm where -db shop
where responde: host e endereço do master, número da época, réplicas e problemas encontrados. Pela API, a aplicação pode esperar uma nova época sem consultar o RCM a cada segundo.
A página Services do RCM mostra o mesmo para cada serviço: estado, época, master, endereço do Firebird, réplicas e problemas. O campo Find encontra o banco de dados pelo alias, pelo nome do serviço, pelo GUID ou pelo caminho.
Serviços no navegador
Tudo o que os comandos hqbirdrcm fazem para os serviços existe na interface web do RCM. A linha de comando não é necessária para isso.
- Página do serviçoO estado e o seu motivo, o master, as réplicas com o atraso, os hosts e os seus papéis, os roteadores, os masters antigos na fila de fechamento, a regra do failover automático, a operação em andamento passo a passo e o histórico dos masters.
- Botões de açãoSwitchover, Failover, Rejoin, Resume. Cada um primeiro executa uma verificação e mostra os problemas. A ação só começa depois da confirmação. Um segundo clique não inicia uma segunda operação.
- Formulário do serviçoO botão New service cria um serviço: nome, alias, porta do roteador e uma linha para cada host. O formulário sugere os nós e os bancos de dados que eles veem. Check verifica, Save primeiro mostra a lista de alterações.
- OperationsUma página com todos os switchovers, failovers e rejoins, os mais novos no topo. Enquanto uma operação está em andamento, o cabeçalho de cada página mostra uma marca com um link para ela.
- Exclusão do serviçoSó o registro no RCM é excluído. A janela diz o que fica (bancos de dados, replicação, papéis dos nós, alias) e o que se perde (histórico, regra, porta nos roteadores), e pede para digitar o nome do serviço.
- Papel viewerUm usuário com esse papel vê todas as páginas e executa verificações, mas não tem botões de ação.
| Estado do serviço | Significado | O que fazer |
|---|---|---|
ok | O master funciona, a réplica em outro host o acompanha. | Nada. |
rejoining | O master antigo está voltando como réplica. | Esperar: o banco de dados está sendo copiado. |
degraded_no_replica | O master funciona, não há réplica. Acontece depois de um failover ou de um erro no retorno. | hqbirdrcm rejoin |
failed | O RCM não consegue determinar o estado, ou o Firebird do master não responde. | hqbirdrcm resume após verificar |
Um serviço no estado failed não inicia nem switchover, nem failover automático. Só o operador o tira desse estado: com o comando resume, com um rejoin ou com um failover manual.
Mudança planejada do master · sem perda de dados
Switchover: o master passa para outro host
O switchover move o master do serviço para outro host sem perda de dados. O RCM para as gravações no master antigo, espera a réplica aplicar o último segmento e a torna master. Depois, o master antigo volta ao cluster como réplica do novo, no mesmo caminho.
Ele serve para trabalhos planejados: atualização do sistema operacional, troca de discos, mudança da carga para outro servidor. Primeiro a verificação, depois a execução:
hqbirdrcm switchover -service shop -check # só verifica, não altera nada hqbirdrcm switchover -service shop -to db2 # move o master para db2
O comando conduz a operação até o fim e imprime cada passo. Código de saída 0 é sucesso. O botão Switchover na página do serviço no RCM faz o mesmo: primeiro a verificação, depois a confirmação, depois os passos da operação na tela.
Aplicações
Hosts e serviço
O que é verificado antes do início
- O serviço está no estado
ok, o master é conhecido. - A réplica de destino está no estado
IN_SYNC. - Os quatro nós dos dois hosts respondem.
- A réplica de destino não está em pausa por causa da licença.
- Nesses nós não há cópia do banco de dados ou promoção em andamento.
Se algo está errado, o RCM recusa e informa o motivo com um código. Até esse momento, nada mudou.
Se algo deu errado
- Antes do ponto sem retorno. Um erro, um timeout ou um cancelamento colocam o master antigo de volta online. O serviço continua
okno host antigo. Se o master antigo não voltar online, o serviço ficafailed: coloque o banco online comgfix -online normale executeresume. - Depois do ponto sem retorno. Não é possível cancelar. Um erro coloca o serviço em
failed. - Erro no retorno. O novo master funciona, não há réplica:
degraded_no_replica. Executehqbirdrcm rejoin -service shop.
hqbirdrcm operations show -id <id> hqbirdrcm operations cancel -id <id>
No navegador, é a página Operations e o botão Cancel na página do serviço.
- Parada das gravaçõesO master antigo entra em shutdown completo. O nó espera as conexões terminarem: por padrão 120 segundos, no máximo 900. A opção
-force Nderruba as conexões após N segundos. - Aplicação finalA cada segundo, o RCM pergunta à réplica se ela aplicou o último segmento. Limite padrão de 300 segundos.
- Um reinício do FirebirdNo novo master, sem esperar a janela. No retorno, o Firebird do host antigo é reiniciado só se o nó de réplica precisar.
- O retorno é uma cópia do banco de dadosO novo master copia o banco de dados para o host antigo via nbackup. Para um banco grande isso demora, por isso o comando espera a operação por até 2 horas.
- O RCM reiniciouCada passo é gravado em disco antes da chamada ao nó. Depois do reinício, o RCM continua a operação a partir do passo atual.
- Bloqueio do serviçoEnquanto o switchover ou o retorno estão em andamento, o RCM recusa outras alterações nesses nós: configurações, reinício do Firebird, cópia, pausa no envio.
As conexões com o master antigo são fechadas no passo de parada das gravações. A aplicação precisa se conectar de novo. Com roteador, a string de conexão continua a mesma. Sem roteador, a aplicação vai para o endereço do novo master: ele é informado por hqbirdrcm where -service shop.
HAProxy · Linux · uma única string de conexão
Roteadores: as aplicações não mudam o endereço
O roteador fica no host das aplicações e mantém o HAProxy apontado para o master de cada serviço. As aplicações se conectam a <host do roteador>:<porta do serviço>. Depois de um switchover ou failover, a string de conexão continua a mesma.
Como o roteador escolhe o host
- Recebe do RCM a tabela de serviços: época, host do master, endereços do Firebird.
- A cada 2 segundos, pergunta ao nó master: “você é o master desta época e o banco de dados está online?”
- Resposta “sim”: o host aceita conexões.
- Resposta “não”: não há novas conexões, as abertas continuam.
- Nova época: as sessões do master antigo são fechadas na hora.
Se o RCM não está disponível, o roteador trabalha com a última tabela. Ela fica guardada no disco do roteador.
Como adicionar um roteador
O roteador é um participante do cluster com o papel router. Adicione-o na página Cluster, como um master ou uma réplica. O fbagent desse host recebe um certificado, grava a configuração e registra o serviço do sistema. O HAProxy precisa estar instalado no host.
A porta do serviço é definida por router_port na descrição do serviço. Pode haver vários roteadores: um em cada host de aplicações.
A página Settings → Routers do RCM mostra os roteadores e os seus relatórios: qual época o roteador aplicou e para qual host ele aponta.
- As conexões caemNa troca de master, as conexões abertas são fechadas. A aplicação precisa se conectar de novo, no mesmo endereço.
- Endereço do clienteO Firebird vê o endereço do HAProxy, e não o da aplicação. Regras de acesso pelo IP do cliente não funcionam atrás do roteador.
- Só LinuxO roteador funciona no Linux. Os servidores de banco de dados podem ser Windows e Linux.
- TestemunhasOs roteadores informam ao RCM se veem a porta do Firebird do master. Sem eles, o failover automático não liga.
Host do master perdido · manual ou por regra
Failover: a réplica assume o papel de master
O failover é necessário quando o host do master não responde. A réplica vira master com os segmentos que conseguiu receber. O que o master não enviou se perde. Por isso, o operador precisa aceitar a perda de forma explícita.
hqbirdrcm failover -service shop -check # o que será perdido hqbirdrcm failover -service shop -to db2 -accept-data-loss # execução
Sem a opção -accept-data-loss, o comando só verifica e mostra a estimativa de perda: o último segmento do master, quantos a réplica recebeu e aplicou, quantos segmentos foram perdidos no mínimo.
No navegador, é o botão Failover na página do serviço. Ele só inicia a operação quando o operador marca a caixa de seleção sobre a perda de dados e digita o nome do serviço.
- 1Verificaçãoo master não responde, a réplica tem uma cópia válida
- 2Aplicação finala réplica aplica tudo o que recebeu; limite de 60 s
- 3Promoçãoponto sem retorno: novo GUID, reinício do Firebird
- 4Nova épocaa réplica é master; o master antigo espera o fechamento
- O master ainda respondeO RCM recusa:
master_reachable. Execute um switchover ou pare primeiro o nó master. - Réplica atrasadaO estado
LAGGINGé aceito. Uma réplica que precisa de uma nova cópia não serve. - Várias réplicasPor padrão, o RCM escolhe a que aplicou mais segmentos, depois a que tem prioridade maior.
- Depois do failoverO serviço fica no estado
degraded_no_replica: o master funciona, não há réplica. Não há retorno enquanto o host antigo não voltar. - Serviço no estado failedO failover manual funciona também nesse caso. É a saída quando o Firebird do master travou e não é possível reiniciá-lo rápido.
- Tabelas excluídasO RCM pega a lista delas da réplica ou das últimas estatísticas do master antigo. Se não há lista, defina as tabelas na página de publicação do novo master.
- Limite da aplicação finalOpção
-apply-timeout, por padrão 60 segundos, no máximo 3600.
Failover automático opcional
O RCM pode iniciar o failover sozinho. Por padrão isso está desligado. A regra é ligada para cada serviço separadamente: na página do serviço no navegador ou por comando.
hqbirdrcm policy -service shop # mostrar a regra
hqbirdrcm policy -service shop -auto-failover on -max-data-loss 30
O RCM verifica as condições a cada 10 segundos e só inicia o failover quando todas são atendidas.
| Condição | Para quê |
|---|---|
| O nó master está em silêncio há 90 segundos | O master não envia estatísticas. |
| A chamada direta do RCM ao nó master falha (5 segundos) | Não são apenas estatísticas atrasadas. |
| Mais da metade dos roteadores não vê a porta do Firebird do master | As aplicações também não conseguem se conectar. |
| O nó de réplica não vê o master há 90 segundos | Terceira testemunha. |
| O atraso da réplica não passa de 30 segundos | Limite de perda de dados. |
| Passou uma hora desde o último failover automático | O master não fica pulando entre hosts. |
| O RCM está rodando há mais de 90 segundos | Depois de um reinício, o RCM não tem dados recentes. |
Serviço ok, sem cópia ou promoção nos nós | Sem conflito com trabalho em andamento. |
- Roteadores são necessáriosA regra precisa de roteadores e da porta de serviço. Se faltar um deles, ela não liga:
no_witnesses. Coloque os roteadores de forma que a maioria não fique no host do master. - Uma vezDepois de um failover automático, a regra se desliga. Só o operador a liga de novo.
- Por que não começouO RCM guarda o motivo da espera junto com a regra do serviço e grava cada novo motivo no seu log uma única vez.
- LogA operação roda em nome de
system:autofailover. O primeiro registro diz o que as testemunhas viram.
O limite de 30 segundos restringe só a fila que a réplica recebeu e ainda não aplicou. Os segmentos que o master gravou, mas não enviou, não entram nela. O relatório da operação mostra quantos são.
Fence · rejoin · master travado · resume
Retorno e recuperação
Depois de um failover, o cluster tem dois arquivos que já foram master. O antigo precisa ser fechado, para não aceitar gravações, e voltar como réplica. O RCM faz o primeiro sozinho, e o segundo por comando do operador.
Fechamento do master antigo (fence)
O RCM tenta fechar o master antigo a cada 10 segundos. Quando o nó dele responde, recebe o papel “fechado” e para de enviar segmentos. Cada fechamento é gravado no log de auditoria.
- Modo
route(padrão). O banco de dados do master antigo continua online. Os roteadores já não o usam. - Modo
shutdown. O RCM primeiro para o banco de dados. As conexões são fechadas após 5 segundos.
hqbirdrcm policy -service shop -fence-mode shutdown
Retorno do master antigo (rejoin)
Quando o host antigo volta a funcionar, inicie o retorno. Primeiro o RCM fecha o master antigo, se isso ainda não foi feito. Depois o novo master copia o seu banco de dados para o host antigo, no mesmo caminho.
hqbirdrcm rejoin -service shop
O arquivo antigo não é apagado. Ele fica ao lado como <nome>.pre-reinit-<hora>.fdb. Nele e no arquivo de journals do master antigo estão as alterações que o novo master não tem.
No modo route, as aplicações que se conectam ao host antigo diretamente, e não pelo roteador, ainda podem gravar no banco de dados antigo. Essas alterações não chegam ao novo master. Se parte das aplicações funciona sem roteador, ligue o modo shutdown.
Master travado
O Firebird pode travar de forma que a porta fica aberta, mas não é possível conectar ao banco de dados. A verificação da porta não vê isso. Por isso, o nó se conecta ao banco de dados sozinho a cada minuto, com limite de 10 segundos.
- Um minuto sem resposta: alerta grave
firebird_not_answering. - O RCM coloca o serviço em
failede grava o motivo: nó, host, hora. - Nesse estado, o failover automático não começa.
O que fazer: salve as pilhas das threads do Firebird e o firebird.log, reinicie o Firebird no host do master e depois execute resume. Se não é possível reiniciar rápido, pare o nó master e inicie o failover.
Saída do estado failed
hqbirdrcm resume -service shop -check hqbirdrcm resume -service shop
O RCM pergunta diretamente ao nó master e verifica:
- não há operação em andamento no serviço;
- o nó master responde;
- o Firebird dele aceita conexões;
- o host é o master da época atual, e o banco de dados está online.
O serviço passa para ok se a réplica do outro host acompanha o master. Caso contrário, para degraded_no_replica: então execute rejoin.
Tornar normal · promover a master
Promoção manual da réplica: passo a passo
Para um banco de dados que faz parte de um serviço, use o switchover e o failover: eles mesmos fazem todos os passos abaixo. O caminho manual fica para bancos de dados sem serviço. “Tornar normal” transforma a réplica em um banco de dados independente, pronto para uso: para relatórios, testes ou uma falha. “Promover a master” torna a réplica o novo master.
A promoção funciona para um par de nós companheiros: um nó de réplica e um nó master na mesma instância do Firebird. O arquivo do banco de dados fica no lugar; o controle passa ao companheiro. Cada passo aparece na linha do banco de dados. Se um passo foi interrompido, clique no botão de novo: passos concluídos não se repetem.
Conexões
O que o RCM mostra
Por que um novo GUID
Sem ele, o novo master gravaria segmentos com o GUID do master antigo, e suas réplicas os recusariam. O nó dá ao banco de dados um novo GUID no lugar, via nbackup, sem reiniciar o Firebird. Funciona em 2.5, 3.0, 4.0 e 5.0.
Depois do novo GUID, a cadeia antiga do nbackup não serve mais. Faça uma nova cópia de nível 0.
Troca manual sem serviço
- Pare as gravações das aplicações no master antigo.
- Aguarde
IN_SYNCe a fila vazia. - Clique em “Verificar”: os números de linhas coincidem. Esta verificação é só do número de linhas.
- “Promover a master”, aguarde o passo FINALIZE.
- Aponte as aplicações para o novo master.
- Faça uma cópia nbackup de nível 0 e conecte uma nova réplica.
A promoção manual não verifica se as aplicações gravam no master antigo e não traz o master antigo de volta como réplica. Pare as gravações você mesmo primeiro. O switchover faz os dois passos por você: para as gravações e traz o master antigo de volta.
Reinicialização · parâmetros · certificados
Configurações e segurança
O Firebird lê as configurações de replicação só na inicialização. Por isso importa quem o reinicia e quando. A regra é simples: o Firebird do master nunca é reiniciado automaticamente. Há uma exceção: o switchover e o failover. Neles, o reinício faz parte de uma operação que o operador iniciou, ou de uma regra que ele ligou.
| Nó | Quem reinicia o Firebird |
|---|---|
| Master | Só você. O nó do master não reinicia o Firebird sozinho. |
| Réplica, o mesmo Firebird tem bancos master | Você. A permissão na janela de cópia deixa o nó apenas parar o Firebird para trocar ou apagar o arquivo antigo da réplica. |
| Réplica, reinício automático proibido | Você. |
| Demais réplicas | O nó, na sua janela de reinicialização. Uma vez após uma série de cópias, e não após cada banco de dados. |
Parâmetros de replicação para vários bancos de dados
Escolha os bancos de dados: o RCM os agrupa por versão do Firebird e papel. Para cada parâmetro, escolha uma ação: manter, definir, voltar ao nível acima ou não gravar. Você vê de onde vem o valor atual: do banco de dados, do nó ou do Firebird.
A pré-visualização verifica os valores nos nós e não altera nada. Ela também mostra quem vai reiniciar o Firebird e quantos bancos de dados isso afeta.
- Janelas de tempoReinicialização do master solicitada por você: 22:00–05:00. Réplica: a qualquer hora. A promoção manual a master reinicia os dois Firebird na hora, sem janela. O switchover reinicia um Firebird: no novo master. Velocidade total de cópia: 23:00–05:00.
- Velocidade dos segmentosPor padrão 50 MB/s, pico curto de 200 MB. Muda na hora, sem reiniciar.
- Mover o arquivo da réplicaPara outra subpasta sem nova cópia; reversão em caso de erro.
- Réplica configurada manualmentePode passar a ser gerenciada sem nova cópia. O RCM associa os arquivos pelo GUID.
- Linha de comandoCópia, verificação, pausa, promoção e outros comandos do RCM também estão no
hqbirdrcm. Switchover, failover e a regra do serviço estão disponíveis de três formas: no navegador, por comando e pela API. - Papel viewerUm usuário do RCM com o papel viewer vê tudo e executa verificações. Qualquer alteração é proibida para ele.
- 6 idiomasInterface do RCM. As instruções dos alertas são em inglês.
Um único documento descreve o cluster
Participantes, seus papéis e vínculos master → réplica são definidos na página Clusters do HQ Monitor ou no RCM. O fbagent de cada host recebe a descrição, instala e configura os nós sozinho. Sem o HQCenter, o RCM gerencia um cluster de até 3 hosts.
mTLS e certificados
Todos os canais do cluster são protegidos por mTLS com uma CA comum. A chave é criada no host do participante e não sai dele: só a solicitação de certificado é enviada. O certificado vale 90 dias e se renova sozinho 30 dias antes de vencer. Nova chave e nova CA são emitidas por comando do administrador.
A interface web do RCM funciona via HTTPS na porta 7444. O agente abre essa porta no firewall quando o RCM é ligado no host. O login é com usuário e senha; a primeira senha precisa ser trocada. Ela fica no arquivo rcm-initial-password no host do RCM e não aparece na tela. Depois da troca da senha, o agente apaga esse arquivo. A página de login mostra o hash da CA do cluster: compare-o com a linha “CA hash” no resumo da instalação no host do RCM. Cada alteração e cada login são gravados no log de auditoria.
Comandos · timeouts · portas · códigos de recusa
Referência
Comandos
| Tarefa | Comando |
|---|---|
| Ligar o RCM no host | fbagent --cluster-init <id> |
| Abrir ou fechar a janela de pareamento | fbagent --cluster-pairing on|off |
| Vincular os hosts | hqbirdrcm cluster link -hosts db1,db2 -master db1 |
| Token para um host sem janela de pareamento | hqbirdrcm cluster join-token -note db2 |
| Sair do cluster | fbagent --cluster-leave |
| Descrever um serviço | hqbirdrcm services put -id shop -file shop.json |
| Onde está o master | hqbirdrcm where -service shop |
| Mudança planejada do master | hqbirdrcm switchover -service shop [-to db2] [-check] |
| Mudança de emergência | hqbirdrcm failover -service shop -accept-data-loss |
| Trazer o master antigo de volta como réplica | hqbirdrcm rejoin -service shop |
| Sair do estado failed | hqbirdrcm resume -service shop [-check] |
| Regra do failover automático | hqbirdrcm policy -service shop -auto-failover on|off |
| Andamento e cancelamento de uma operação | hqbirdrcm operations show|cancel -id <id> |
Timeouts e intervalos
| O quê | Padrão | Como alterar |
|---|---|---|
| Switchover: espera do fim das conexões | 120 s, no máximo 900 s | -quiesce-timeout |
| Switchover: a réplica aplica o último segmento | 300 s | -apply-timeout |
| Switchover: o comando espera o fim da operação | 2 horas | -timeout |
| Failover: a réplica aplica o que recebeu | 60 s, no máximo 3600 s | -apply-timeout |
| Failover automático: o master está em silêncio | 90 s | -failover-delay |
| Failover automático: limite de atraso | 30 s | -max-data-loss |
| Failover automático: intervalo entre dois | 1 hora | -min-interval |
| Verificação das condições de failover e do fechamento do master antigo | a cada 10 s | não muda |
| Firebird travado: teste de conexão | uma vez por minuto, limite de 10 s | não muda |
| Roteador: consulta ao nó master | a cada 2 s | não muda |
| Janela de pareamento, token de entrada | 24 horas | janela: número de horas na solicitação |
| Link hosts: certificado do agente, início dos nós | até 10 minutos, até 20 minutos | não muda |
Portas
| Porta | Para quê |
|---|---|
7443 | RCM: nós, agentes e roteadores, mTLS. |
7444 | RCM: interface web e comandos do operador, HTTPS. |
7450–7459 | Janela de pareamento do agente: 7450 + slot. |
7051–7060 | Primeiro nó do agente: 7051 + slot. |
7061–7070 | Segundo nó do agente: 7061 + slot. |
router_port | Porta do serviço no roteador, por exemplo 3051. |
Códigos de recusa
| Código | Significado |
|---|---|
not_in_sync | A réplica de destino está atrasada: o switchover não começa. |
busy | Há cópia do banco de dados ou promoção em andamento nos nós. |
service_busy | Já há uma operação em andamento no serviço. |
master_reachable | O master responde: o failover não é necessário. |
replica_unusable | A réplica não tem uma cópia válida do banco de dados. |
data_loss_not_accepted | Failover sem a opção -accept-data-loss. |
past_no_return | Cancelamento depois do ponto sem retorno. |
no_witnesses | Failover automático sem roteadores. |
node_port_clash | A porta do nó está ocupada por outro participante do host. |
seats_exceeded | O cluster já tem 3 hosts. |
O principal em poucas palavras
Perguntas frequentes
Qual a diferença entre switchover e failover?
O switchover é planejado: os dois hosts funcionam, os dados não se perdem, o master antigo volta sozinho como réplica. O failover é de emergência: o host do master foi perdido, perde-se o que o master não conseguiu enviar, e o master antigo volta com um comando separado.
O que a aplicação vê durante o switchover?
As conexões com o master antigo são fechadas quando o RCM para as gravações. Enquanto a réplica não vira master, não há onde gravar. Depois da nova época, a aplicação se conecta de novo: no mesmo endereço do roteador ou no endereço do novo master.
Quanto tempo dura o switchover?
A pausa nas gravações tem três partes: espera do fim das conexões (até 120 segundos por padrão), aplicação final do último segmento e um reinício do Firebird no novo master. O retorno do master antigo vem depois disso, em segundo plano. O tempo dele é o tempo da cópia do banco de dados.
É possível trabalhar sem roteador?
Sim. O switchover e o failover manual funcionam sem roteadores. A aplicação então descobre sozinha o endereço do master no RCM. O failover automático não liga sem roteadores: os roteadores são as testemunhas dele.
Quantos dados podem ser perdidos no failover automático?
A regra não dispara se a réplica está mais de 30 segundos atrasada. Mas os segmentos que o master gravou e não conseguiu enviar se perdem. O relatório da operação mostra quantos são. O arquivo antigo do banco de dados é mantido: essas alterações ficam nele e no arquivo de journals do master antigo.
O serviço está no estado failed. O que fazer?
Veja o motivo na página Services. Se o Firebird do master travou, reinicie-o. Depois, hqbirdrcm resume -service <id> -check mostra o que impede, e resume sem a opção coloca o serviço de volta em funcionamento.
Quanto espaço é preciso para o retorno do master antigo?
O retorno é uma nova cópia do banco de dados. Valem as mesmas regras de qualquer cópia: 105 % do tamanho do banco de dados. Depois do failover, o arquivo antigo fica ao lado, por isso o host antigo precisa de espaço para os dois arquivos.
Funciona no Windows?
Os nós e o RCM funcionam no Windows e no Linux. O roteador funciona só no Linux.