Produção & deploy

O zapo foi feito para cargas de trabalho longevas e multi-sessão. Esta página reúne as decisões operacionais que importam quando você passa do protótipo local.

Persista as credenciais (não refaça o pareamento)

Sessões de produção precisam usar uma store durável para os domínios auth e Signal, além de um sessionId estável entre reinícios. A store em memória perde tudo ao sair, forçando um novo pareamento a cada boot.

const client = new WaClient({ store, sessionId: 'tenant-42' }, logger)

Trocar o sessionId deixa as credenciais anteriores órfãs — trate-o como a chave durável de um dispositivo/conta.

Escolha um backend de store

Backend	Melhor para
`@zapo-js/store-sqlite`	Processo único / host único — a opção local mais simples e rápida.
`@zapo-js/store-postgres` · `@zapo-js/store-mysql`	Múltiplos hosts, operações relacionais, backups gerenciados.
`@zapo-js/store-redis`	Cache de baixa latência + persistência.
`@zapo-js/store-mongo`	Deployments orientados a documentos.

Você pode misturar backends por domínio (ex.: auth/signal no Postgres, caches no Redis). Veja Instalação e a referência de stores.

Shutdown gracioso

Chame disconnect() (nunca logout()) no shutdown — ele descarrega os dados pendentes de write-behind e fecha o socket sem desvincular o dispositivo, então o próximo boot retoma a partir da store.

for (const signal of ['SIGINT', 'SIGTERM'] as const) {
  process.on(signal, async () => {
    await client.disconnect()
    process.exit(0)
  })
}

logout() desvincula o dispositivo no servidor e limpa o estado armazenado — força um novo pareamento completo. Use-o apenas para desconectar permanentemente, nunca como hook de shutdown.

Rode muitas sessões

Uma única store pode conter muitas contas independentes, cada uma indexada por sessionId. Crie um WaClient por conta:

const clients = tenants.map((id) => new WaClient({ store, sessionId: id }, logger))
await Promise.all(clients.map((c) => c.connect()))

Cada client pareia, reconecta e emite eventos de forma independente. Reserve memória/CPU por sessão (cada uma mantém estado Signal e caches em memória) e faça sharding entre processos/hosts conforme escala — um processo por sessão é o modelo de isolamento mais simples. Veja Deploys multi-sessão para o guia operacional completo.

Ajuste para throughput

Write-behind agrupa as escritas de mensagens/threads/contatos fora do hot path. Ajuste writeBehind.maxPendingKeys / maxWriteConcurrency / flushTimeoutMs ao seu banco. (config)
History sync (history.enabled) é ligado por padrão e adiciona um download inicial grande. Defina como false se você não persiste mailbox/threads/contacts; use requireFullSync deliberadamente.
Bots que não devem aparecer online: markOnlineOnConnect é false por padrão, então bots ficam invisíveis ao conectar. Passe true apenas quando quiser uma presença “online” visível.
Timeouts (iqTimeoutMs, keepAliveIntervalMs, deadSocketTimeoutMs, …) vêm com padrões de produção — sobrescreva só com motivo. (config)

Política de reconexão & erros

O zapo não reconecta sozinho — assuma a política. Ligue um loop de backoff (Reconexão) e classifique as falhas (Erros & desconexões) para parar em razões fatais (banned, not_authorized, logout) em vez de martelar o servidor.

Logging

Use um logger estruturado em produção:

const logger = await createPinoLogger({ level: 'info', pretty: false })

pretty: false emite linhas JSON adequadas a agregadores de log. Caia para debug / trace só ao investigar.

Segurança & versionamento

Credenciais são segredos. WaAuthCredentials contém as chaves do dispositivo — se você as persistir fora da store embutida, criptografe em repouso. (Autenticação)
Nunca habilite dangerous.* em produção — essas flags desabilitam verificações de segurança. (config)
Versionamento. O zapo é 1.0 e segue versionamento semântico — breaking changes só acontecem em um novo major. Use um range de versão ou lockfile como de costume, e revise o changelog antes de upgrades de major.

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Produção & deploy

Persista as credenciais (não refaça o pareamento)

Escolha um backend de store

Shutdown gracioso

Rode muitas sessões

Ajuste para throughput

Política de reconexão & erros

Logging

Segurança & versionamento

​Persista as credenciais (não refaça o pareamento)

​Escolha um backend de store

​Shutdown gracioso

​Rode muitas sessões

​Ajuste para throughput

​Política de reconexão & erros

​Logging

​Segurança & versionamento

Persista as credenciais (não refaça o pareamento)

Escolha um backend de store

Shutdown gracioso

Rode muitas sessões

Ajuste para throughput

Política de reconexão & erros

Logging

Segurança & versionamento