Escolha como você quer usar o projeto:
Ideal se você já tem um cluster MongoDB e quer apenas visualizar/controlar.
-
Instale a ferramenta globalmente:
npm install -g replica-failover-mongodb-ts
-
Rode o dashboard:
node-balancer-dashboard
-
Responda às perguntas de configuração: O sistema pedirá os dados do seu ambiente. Exemplo de preenchimento:
- API URL:
http://localhost:3000/api/users - MongoDB Nodes:
mongodb://localhost:27017,mongodb://localhost:27018 - Enable Docker Control?:
Yes(Se quiser parar/iniciar containers pelo painel) - Docker Container Names:
mongo1,mongo2,mongo3
- API URL:
Ideal para ver a mágica acontecer do zero (cria API + Banco + Réplicas).
-
Clone e Instale:
git clone https://github.com/JoaoIto/node-balancer.git cd node-balancer npm install -
Suba o Ambiente (Docker):
docker-compose up -d --build
Aguarde ~30s para o cluster configurar.
-
Rode o Dashboard:
npm run dashboard
Pronto! Selecione "RUN CHAOS DEMO" e divirta-se.
O Node Balancer é uma API escalável construída utilizando Node.js, MongoDB com replica set para alta disponibilidade, e Nginx como balanceador de carga. O sistema foi projetado para garantir resiliência, escalabilidade e alta disponibilidade. A arquitetura permite a adição manual de instâncias backend (Node.js) e garante que, em caso de falhas, o sistema continue operando sem interrupções, com a replicação automática dos dados e balanceamento de carga eficiente.
- Tecnologias
- Como Rodar o Projeto (Dev)
- Uso como Biblioteca (Library)
- Visual Dashboard (Painel de Controle)
- Uso Avançado do Dashboard (CLI)
- Testes e Automação (Chaos Testing)
- Observabilidade (v3.0)
- Documentação Detalhada
- Configuração Manual (Referência)
O Node Balancer utiliza as seguintes tecnologias:
- Node.js (com Express.js): Para a criação de APIs RESTful escaláveis e modularizadas.
- MongoDB Replica Set: Para garantir alta disponibilidade e redundância de dados, com failover automático.
- Nginx: Como balanceador de carga para distribuir as requisições entre as instâncias do backend.
- Docker: Para containerização das instâncias Node.js, permitindo fácil replicação e deploy.
- Monitoramento: O sistema está em processo de monitoramento para garantir a continuidade e performance da aplicação.
- Docker e Docker Compose instalados.
- Node.js (para rodar os scripts de teste localmente).
-
Clone o repositório e entre na pasta:
git clone https://github.com/JoaoIto/node-balancer.git cd NodeBalancer -
Suba o ambiente com Docker Compose:
docker-compose up -d --build
Isso iniciará:
- 3 nós MongoDB (
mongo1,mongo2,mongo3). - 1 container de inicialização (
replica-init) que configura o cluster. - 1 API Node.js (
node-api).
- 3 nós MongoDB (
-
Verifique se tudo está rodando:
docker-compose ps
Você pode usar o gerenciador de conexões resiliente deste projeto em sua própria aplicação Node.js ou NestJS.
Basta passar a string de conexão padrão do MongoDB. A lib detecta automaticamente os nós e o banco de dados.
-
Instale a lib:
npm install replica-failover-mongodb-ts
-
Importe e use:
import { ConnectionManager } from 'replica-failover-mongodb-ts'; // ✨ Plug & Play: Apenas a string de conexão! const db = new ConnectionManager({ connectionString: 'mongodb://mongo1:27017,mongo2:27017/mydb' }); await db.init(); // ✅ Failover automático para QUALQUER collection // Você NÃO precisa configurar as collections antes. Basta usar o nome. // Leitura na collection 'users' const users = await db.read('users', c => c.find().toArray()); // Escrita na collection 'logs' await db.write('logs', c => c.insertOne({ event: 'login' })); // Leitura na collection 'products' com preferência Secundária const products = await db.read('products', c => c.find().toArray(), {}, 'secondaryPreferred');
const products = await db.read('products', c => c.find().toArray(), {}, 'secondaryPreferred');
O Dashboard do NodeBalancer é inteligente:
- Auto-Detecção: Se você tiver um arquivo
.envcomMONGODB_URIouCONNECTION_STRING, ele conecta automaticamente! - Persistência: Se você configurar manualmente, ele pergunta se quer salvar (cria um
dashboard.json). Nas próximas vezes, abre direto!
Para rodar:
npm run dashboard
# ou
npx replica-failover-mongodb-ts-dashboardVocê pode verificar a saúde das conexões a qualquer momento ou ouvir eventos em tempo real.
Verificar Status:
const status = db.getStatus();
console.log(status);
/* Retorno:
{
isConnected: true,
dbName: 'mydb',
primary: 'mongodb://mongo1:27017/mydb',
secondaries: ['mongodb://mongo2:27017/mydb'],
totalNodes: 2
}
*/Ouvir Eventos (Real-time):
A classe ConnectionManager emite eventos que você pode escutar:
db.on('failover-start', (reason) => {
console.warn('⚠️ O banco principal caiu! Iniciando failover...', reason);
});
db.on('failover-complete', ({ newPrimary }) => {
console.info('✅ Novo banco principal eleito:', newPrimary);
});
db.on('node-lost', ({ count }) => {
console.error('❌ Um nó secundário caiu. Total restante:', count);
});const db = new ConnectionManager({
nodes: [
'mongodb://mongo1:27017/mydb',
'mongodb://mongo2:27017/mydb'
],
healthCheckIntervalMs: 5000,
minPoolSize: 5
});Se você usa NestJS, a integração é nativa:
// app.module.ts
import { Module } from '@nestjs/common';
import { NodeBalancerModule } from 'replica-failover-mongodb-ts/dist/nestjs';
@Module({
imports: [
NodeBalancerModule.forRoot({
connectionString: 'mongodb://localhost:27017,localhost:27018/mydb',
}),
],
})
export class AppModule {}E para usar nos seus services:
import { Injectable } from '@nestjs/common';
import { InjectConnectionManager } from 'replica-failover-mongodb-ts/dist/nestjs';
import { ConnectionManager } from 'replica-failover-mongodb-ts';
@Injectable()
export class UserService {
constructor(@InjectConnectionManager() private readonly db: ConnectionManager) {}
async getUsers() {
return this.db.read('users', (col) => col.find().toArray());
}
}Para uma experiência visual e interativa, utilize o nosso Dashboard via Terminal (TUI). Ele permite monitorar a topologia do cluster, gráficos de latência e controlar os nós (Stop/Start) manualmente.
npm run dashboard
O painel exibe:
- Topologia: Quem é o nó
PRIMARY(Verde) e quem são osSECONDARY(Azul). - Latência: Gráfico em tempo real do tempo de resposta da API.
- Logs: Histórico de ações e testes.
Ao realizar testes de carga ou criar usuários via dashboard, a API retornará respostas como:
Sucesso (201 Created):
{
"message": "Usuário criado com sucesso",
"data": {
"name": "User 1732500000000",
"email": "user1732500000000@test.com",
"_id": "6560f...",
"createdAt": "2025-11-24T23:00:00.000Z"
}
}Erro (Se o banco estiver caindo/failover - 500/Timeout):
{
"error": "Database connection failed"
}O dashboard pode ser configurado para monitorar qualquer API e qualquer cluster MongoDB, não apenas o deste projeto.
node-balancer-dashboard [opções]| Flag | Descrição | Padrão |
|---|---|---|
--api-url |
URL da API para testar latência/requests | http://localhost:3000/api/users |
--nodes |
Lista de URIs do MongoDB (separados por vírgula) | mongodb://localhost:27017... |
--no-docker |
Desabilita controles do Docker (para clusters remotos) | false |
Testando uma API de produção sem acesso ao Docker local:
node-balancer-dashboard \
--api-url https://api.minhaempresa.com/health \
--nodes mongodb://mongo-prod-1:27017,mongodb://mongo-prod-2:27017 \
--no-dockerSe preferir rodar apenas o script de teste sem o dashboard visual:
npm run ops:demo(Se estiver no Windows/PowerShell e tiver problemas, use: cmd /c "npm run ops:demo")
O que este script faz:
- Verifica a topologia do cluster.
- Envia requisições de teste (POST e GET).
- Derruba automaticamente o nó Primary.
- Prova que a API continua funcionando (Failover).
- Reinicia o nó e verifica a recuperação.
A versão 3.0 introduz recursos avançados de monitoramento para produção:
Receba alertas no seu Slack ou Discord. Basta passar a URL ao iniciar:
const db = new ConnectionManager({
nodes: [...],
webhookUrl: 'https://discord.com/api/webhooks/...' // Sua URL aqui
});O sistema fará um POST automático com JSON sempre que houver um failover.
- Prometheus: Acesse
http://localhost:3000/metricspara ver dados de latência e conexão. - WebSocket: Conecte via Socket.io para receber logs em tempo real.
👉 Leia o guia completo de Observabilidade (Português)
Para mais detalhes, consulte os guias na pasta docs/:
- 🖥️ Guia do Dashboard (Visual Runner): Manual completo do painel interativo.
- 📄 Guia de Testes e Execução (Demo Runner): Passo a passo detalhado de como rodar os testes manuais e automatizados.
- 🛠️ Documentação dos Scripts: Explicação técnica de como os scripts de automação funcionam.
- 📡 Observabilidade e Alertas: Guia de configuração de Webhooks, Métricas e WebSocket.
- As variáveis base estão no arquivo de
.env.local
Se você estiver usando o MongoDB replica set, a URL de conexão deve ser configurada corretamente para isso. Em um replica set, a URL de conexão precisa incluir todos os membros do replica set. A URL de conexão para um MongoDB replica set deve ser algo assim:
MONGODB_URI=mongodb://localhost:27017,localhost:27018,localhost:27019/node-balancer?replicaSet=rs0Se você está utilizando o MongoDB replica set, certifique-se de que o replica set está configurado corretamente no MongoDB:
-
Verifique se o MongoDB está rodando no modo replica set. Você pode iniciar o MongoDB com o seguinte comando:
mongod --replSet rs0
-
Configuração do Replica Set: Após iniciar o MongoDB, conecte-se a ele e configure o replica set:
mongo
Dentro do shell do MongoDB, inicialize o replica set:
rs.initiate({ _id: "rs0", members: [ { _id: 0, host: "localhost:27017" }, { _id: 1, host: "localhost:27018" }, { _id: 2, host: "localhost:27019" } ] });
-
Verifique o status do replica set:
rs.status();
 |
|---|
| João Ito |
| GitHub • Email |
Feito com ❤️ por João Ito. Entre em contato!
Este projeto está licenciado sob a licença ISC - veja o arquivo LICENSE para detalhes.