Tutoriais de VPS
Kafka KRaft na VPS: TLS explícito, ACLs e recuperação dos dados
Implante Kafka de um nó com patch 4.3 suportado, armazenamentos TLS explícitos e autenticação controller. Configure rotas e ACLs de topics/grupos, teste acesso do aplicativo e planeje retenção, monitoramento e recuperação fria.

Quando vários serviços produzem e consomem pagamentos, logs e eventos de pedidos, chamadas diretas ao banco e HTTP podem acoplá-los. O Kafka mantém eventos em um log particionado e reproduzível, permitindo que produtores e grupos independentes de consumidores trabalhem no próprio ritmo.
O guia usa Ubuntu 24.04, Docker Compose, KRaft, imagens oficiais, SASL/PLAIN com TLS, ACLs e armazenamento persistente. O exemplo de 15 de setembro de 2026 usava Kafka 4.3.1. A página oficial consultada em 16 de novembro lista 4.4.0, 4.3.2 e 4.2.2 como versões suportadas e 4.3.1 como arquivada. O exemplo é preservado com um override obrigatório de TLS explícito. Em instalação nova, use o patch suportado 4.3.2 após ler suas notas.
- Separar pedidos, pagamentos e estoque com eventos.
- Enviar logs ou análises a vários sistemas independentes.
- Guardar offsets e retomar consumo dentro do histórico retido.
- Permitir grupos independentes no mesmo topic.
- Usar partições para paralelismo e retenção por período definido.
Para tarefas individuais, roteamento flexível e confirmação de mensagens, RabbitMQ costuma ser mais simples. Kafka atende reprodução de eventos, processamento de streams e histórico compartilhado.
| Arquitetura | Vantagem | Limitação | Uso |
|---|---|---|---|
| KRaft de um nó | Menor custo e operação simples | Falha do host, disco ou processo interrompe; réplica 1 | Desenvolvimento e cargas recuperáveis |
| Três contêineres na mesma VPS | Testa configuração | Compartilha falhas de host, disco e rede | Somente laboratório |
| Nós independentes | Três réplicas podem tolerar uma indisponível | Mais custo e operação | Serviços críticos |
Combined mode executa broker e controller juntos; a documentação não recomenda para implantações críticas. Planeje domínios de falha independentes para brokers e quorum de 3 ou 5 controllers, sem confundir contêineres copiados com HA.
Com três réplicas, replication.factor=3, min.insync.replicas=2 e acks=all exigem réplicas sincronizadas suficientes antes da confirmação. Isso depende do ISR atual e de seu mínimo; não significa confirmação de todas as réplicas configuradas em qualquer situação nem representa backup.
Kafka 4.x usa KRaft, sem ZooKeeper. Quorums dinâmicos são suportados, mas o exemplo usa controller.quorum.voters estático. Planeje migração suportada de papéis/quorum; não copie dados existentes para criar outro nó.
Planeje pico de gravação, mensagens, partições, retenção, réplicas, reprodução e desempenho de disco/rede.
| Carga | VPS sugerida | Premissa |
|---|---|---|
| Desenvolvimento | 2 vCPU, 4GB RAM, SSD de 50GB | Heap perto de 1GB e dados reconstruíveis |
| Nó pequeno | 4 vCPU, 8GB RAM, pelo menos 100GB NVMe | Heap de 2GB e folga para page cache |
| Cluster crítico | Pelo menos 3 domínios de broker, 4–8 vCPU/8–16GB por nó, NVMe independente | Controllers planejados e testes reais |
São estimativas. Não ocupe toda a RAM com heap: Kafka depende do cache do sistema. O exemplo limita contêiner a 4GB e heap a 2GB; no host de desenvolvimento de 4GB, reduza heap para perto de 1GB e ajuste o limite. Evite compartilhar disco com outro banco de alto I/O.
| Porta | Uso | Exposição |
|---|---|---|
9094/TCP | Cliente SASL_SSL | 127.0.0.1; IP WireGuard para remoto |
19094/TCP | Broker interno | Sem publicação |
29093/TCP | Controller KRaft | Sem publicação |
Restrinja origens mesmo com TLS/ACLs. Não exponha controllers nem 9092 sem criptografia. Confira Docker e regras do provedor com a lista de exposição de middleware.
Instale antes Docker Engine e Compose v2 pelas instruções oficiais para Ubuntu:
sudo apt update
sudo apt full-upgrade -y
sudo apt install -y ca-certificates curl openssl openjdk-21-jre-headless
docker --version
docker compose version
keytool -help >/dev/null
Java no host fornece keytool; a imagem inclui o runtime Kafka. Instale netcat-openbsd para usar nc. Confira reinicializações, logs, limites e recuperação com a lista de Compose para produção.
sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/kafka
cd /opt/kafka
install -d -m 0750 data backups
install -d -m 0700 secrets pki
umask 077
docker run --rm --entrypoint /opt/kafka/bin/kafka-storage.sh \
apache/kafka:4.3.1 random-uuid
Guarde o Cluster ID gerado. Crie .env com o ID, hostname e binding privado:
CLUSTER_ID=请替换为上一步输出
KAFKA_HOST=mq.example.com
KAFKA_BIND_IP=127.0.0.1
Substitua todo o marcador após CLUSTER_ID pelo valor gerado. Não gere outro ID ao reutilizar dados.
Com WireGuard em 10.66.0.1, configure KAFKA_BIND_IP e faça mq.example.com resolver para esse IP nos clientes. No teste do listener externo em loopback, o hostname precisa resolver para loopback na VPS.
Gere credenciais hexadecimais na mesma sessão:
ADMIN_PASSWORD="$(openssl rand -hex 32)"
APP_PASSWORD="$(openssl rand -hex 32)"
STORE_PASSWORD="$(openssl rand -hex 24)"
printf '%s\n' "$STORE_PASSWORD" > secrets/kafka_keystore_creds
printf '%s\n' "$STORE_PASSWORD" > secrets/kafka_ssl_key_creds
printf '%s\n' "$STORE_PASSWORD" > secrets/kafka_truststore_creds
printf 'KafkaServer {\n org.apache.kafka.common.security.plain.PlainLoginModule required\n username="admin"\n password="%s"\n user_admin="%s"\n user_app="%s";\n};\n' \
"$ADMIN_PASSWORD" "$ADMIN_PASSWORD" "$APP_PASSWORD" \
> secrets/broker_jaas.conf
Reserve admin para operação e app para aplicativos. PLAIN não criptografa senhas; exige TLS. Proteja JAAS, propriedades e .env. Guarde a senha do aplicativo antes de fechar a sessão.
Inclua o hostname do contêiner kafka e o dos clientes mq.example.com:
cd /opt/kafka/pki
openssl genrsa -out ca.key 4096
openssl req -x509 -new -sha256 -days 3650 \
-key ca.key \
-subj '/CN=Kafka Internal CA' \
-out ca.crt
openssl genrsa -out broker.key 4096
openssl req -new -sha256 \
-key broker.key \
-subj '/CN=mq.example.com' \
-out broker.csr
printf '%s\n' \
'subjectAltName=DNS:kafka,DNS:mq.example.com' \
'extendedKeyUsage=serverAuth' > broker.ext
openssl x509 -req -sha256 -days 825 \
-in broker.csr \
-CA ca.crt \
-CAkey ca.key \
-CAcreateserial \
-extfile broker.ext \
-out broker.crt
openssl pkcs12 -export \
-name kafka-broker \
-in broker.crt \
-inkey broker.key \
-certfile ca.crt \
-out /opt/kafka/secrets/kafka.keystore.p12 \
-passout "pass:$STORE_PASSWORD"
keytool -importcert -noprompt \
-alias kafka-ca \
-file ca.crt \
-keystore /opt/kafka/secrets/kafka.truststore.p12 \
-storetype PKCS12 \
-storepass "$STORE_PASSWORD"
O DNS real deve constar no SAN e em KAFKA_HOST. Não monte nem distribua ca.key; entregue CA ou truststore e acompanhe a validade.
Crie propriedades administrativas para o health check:
printf 'security.protocol=SASL_SSL\nsasl.mechanism=PLAIN\nsasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required username="admin" password="%s";\nssl.truststore.location=/etc/kafka/secrets/kafka.truststore.p12\nssl.truststore.type=PKCS12\nssl.truststore.password=%s\n' \
"$ADMIN_PASSWORD" "$STORE_PASSWORD" \
> /opt/kafka/secrets/client-admin.properties
chmod 600 /opt/kafka/.env /opt/kafka/secrets/*
sudo chown -R 1000:1000 /opt/kafka/data /opt/kafka/secrets
Confira UID/GID da imagem antes de aplicar 1000:1000. O processo sem privilégios precisa atravessar secrets e ler arquivos 600; não torne segredos públicos para resolver permissões.
Crie /opt/kafka/compose.yml:
services:
kafka:
image: apache/kafka:4.3.1
container_name: kafka
hostname: kafka
restart: unless-stopped
ports:
- "${KAFKA_BIND_IP:-127.0.0.1}:9094:9094"
volumes:
- ./data:/var/lib/kafka/data
- ./secrets:/etc/kafka/secrets:ro
environment:
CLUSTER_ID: ${CLUSTER_ID}
KAFKA_NODE_ID: 1
KAFKA_PROCESS_ROLES: broker,controller
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:PLAINTEXT,INTERNAL:SASL_SSL,EXTERNAL:SASL_SSL
KAFKA_LISTENERS: CONTROLLER://:29093,INTERNAL://:19094,EXTERNAL://:9094
KAFKA_ADVERTISED_LISTENERS: INTERNAL://kafka:19094,EXTERNAL://${KAFKA_HOST}:9094
KAFKA_CONTROLLER_QUORUM_VOTERS: 1@kafka:29093
KAFKA_CONTROLLER_LISTENER_NAMES: CONTROLLER
KAFKA_INTER_BROKER_LISTENER_NAME: INTERNAL
KAFKA_SASL_ENABLED_MECHANISMS: PLAIN
KAFKA_SASL_MECHANISM_INTER_BROKER_PROTOCOL: PLAIN
KAFKA_OPTS: -Djava.security.auth.login.config=/etc/kafka/secrets/broker_jaas.conf
KAFKA_SSL_KEYSTORE_FILENAME: kafka.keystore.p12
KAFKA_SSL_KEYSTORE_TYPE: PKCS12
KAFKA_SSL_KEYSTORE_CREDENTIALS: kafka_keystore_creds
KAFKA_SSL_KEY_CREDENTIALS: kafka_ssl_key_creds
KAFKA_SSL_TRUSTSTORE_FILENAME: kafka.truststore.p12
KAFKA_SSL_TRUSTSTORE_TYPE: PKCS12
KAFKA_SSL_TRUSTSTORE_CREDENTIALS: kafka_truststore_creds
KAFKA_SSL_CLIENT_AUTH: none
KAFKA_AUTHORIZER_CLASS_NAME: org.apache.kafka.metadata.authorizer.StandardAuthorizer
KAFKA_SUPER_USERS: User:admin
KAFKA_ALLOW_EVERYONE_IF_NO_ACL_FOUND: "false"
KAFKA_LOG_DIRS: /var/lib/kafka/data
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
KAFKA_SHARE_COORDINATOR_STATE_TOPIC_REPLICATION_FACTOR: 1
KAFKA_SHARE_COORDINATOR_STATE_TOPIC_MIN_ISR: 1
KAFKA_GROUP_INITIAL_REBALANCE_DELAY_MS: 0
KAFKA_HEAP_OPTS: -Xms2g -Xmx2g
KAFKA_LOG_RETENTION_HOURS: 168
healthcheck:
test:
- CMD-SHELL
- /opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server kafka:19094 --command-config /etc/kafka/secrets/client-admin.properties >/dev/null 2>&1
interval: 30s
timeout: 10s
retries: 10
start_period: 60s
mem_limit: 4g
cpus: 2.0
ulimits:
nofile:
soft: 100000
hard: 100000
logging:
driver: json-file
options:
max-size: 10m
max-file: "5"
O listener controller é interno. KAFKA_ADVERTISED_LISTENERS informa aos clientes onde reconectar depois do bootstrap; DNS, hostname ou porta errados explicam falhas após a primeira conexão.
Não inicie apenas essa definição. O script oficial detecta SSL em nomes anunciados que contêm SSL; INTERNAL/EXTERNAL não acionam o atalho. Variáveis de nomes de arquivos não bastam para fornecer caminhos e senhas dos armazenamentos. Além disso, controller sem criptografia usa um principal anônimo enquanto ACLs estão ativas.
Preserve uma vez a senha já gerada no arquivo restrito:
cd /opt/kafka
printf 'KAFKA_TLS_STORE_PASSWORD=%s\n' "$(sudo cat secrets/kafka_keystore_creds)" >> .env
chmod 600 .env
Crie compose.override.yml para uma instalação nova do patch suportado:
services:
kafka:
image: apache/kafka:4.3.2
environment:
KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: CONTROLLER:SASL_SSL,INTERNAL:SASL_SSL,EXTERNAL:SASL_SSL
KAFKA_SASL_MECHANISM_CONTROLLER_PROTOCOL: PLAIN
KAFKA_SSL_KEYSTORE_LOCATION: /etc/kafka/secrets/kafka.keystore.p12
KAFKA_SSL_KEYSTORE_PASSWORD: ${KAFKA_TLS_STORE_PASSWORD:?store password required}
KAFKA_SSL_KEY_PASSWORD: ${KAFKA_TLS_STORE_PASSWORD:?store password required}
KAFKA_SSL_TRUSTSTORE_LOCATION: /etc/kafka/secrets/kafka.truststore.p12
KAFKA_SSL_TRUSTSTORE_TYPE: PKCS12
KAFKA_SSL_TRUSTSTORE_PASSWORD: ${KAFKA_TLS_STORE_PASSWORD:?store password required}
O controller usa a identidade admin de KafkaServer JAAS e confia no certificado de kafka. Em clusters existentes, confira compatibilidade de versão e migração de listeners. Para desenvolvimento com 4GB, adicione heap -Xms1g -Xmx1g e reduza o limite do contêiner; o heap de 2GB atende ao host maior.
Valide sem mostrar segredos e inicie:
cd /opt/kafka
docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 kafka
Crie orders com três partições e uma réplica:
docker exec kafka /opt/kafka/bin/kafka-topics.sh \
--bootstrap-server kafka:19094 \
--command-config /etc/kafka/secrets/client-admin.properties \
--create \
--topic orders \
--partitions 3 \
--replication-factor 1
Conceda permissões de topic e grupo:
docker exec kafka /opt/kafka/bin/kafka-acls.sh \
--bootstrap-server kafka:19094 \
--command-config /etc/kafka/secrets/client-admin.properties \
--add --allow-principal User:app \
--operation Read --operation Write --operation Describe \
--topic orders
docker exec kafka /opt/kafka/bin/kafka-acls.sh \
--bootstrap-server kafka:19094 \
--command-config /etc/kafka/secrets/client-admin.properties \
--add --allow-principal User:app \
--operation Read \
--group orders-workers
Prepare propriedades do aplicativo a partir de client-admin.properties, com app e APP_PASSWORD. Preserve security.protocol=SASL_SSL, sasl.mechanism=PLAIN e CA confiável. Clientes fora do contêiner precisam do caminho local do truststore. Não use ssl.endpoint.identification.algorithm= para desligar validação do hostname.
O teste administrativo verifica entrega básica:
printf 'order.created id=1001\n' | docker exec -i kafka \
/opt/kafka/bin/kafka-console-producer.sh \
--bootstrap-server kafka:19094 \
--producer.config /etc/kafka/secrets/client-admin.properties \
--topic orders
docker exec kafka /opt/kafka/bin/kafka-console-consumer.sh \
--bootstrap-server kafka:19094 \
--consumer.config /etc/kafka/secrets/client-admin.properties \
--topic orders \
--from-beginning \
--max-messages 1
Repita com propriedades do aplicativo e grupo explícito orders-workers; um grupo aleatório não corresponde à ACL. Teste negação de topics alheios e operações administrativas. O teste com admin não comprova os privilégios do aplicativo.
Use acks=all nos produtores. Entenda idempotência, transações, permissões e ordem por chave; conceda só privilégios documentados. Envio bem-sucedido não significa conclusão do processo de negócio.
A retenção do exemplo é 168 horas. Ela apaga histórico, não faz arquivo permanente. Estime armazenamento como MB/s de pico × 86400 × dias retidos × réplicas:
峰值写入 MB/s × 86400 × 保留天数 × 副本数
Reserve espaço para índices, segmentos, reprodução e limpeza atrasada. Uso contínuo de 70%–80% reduz a margem para compactação ou consumidores lentos.
Ajuste partições a consumidores e vazão. Só podem ser aumentadas, não reduzidas diretamente; aumentar pode mudar distribuição de chaves e expectativas de ordem.
JMX remoto não é publicado por padrão. Use JMX Exporter como agente Java e Prometheus em endpoints privados:
UnderReplicatedPartitionseUnderMinIsrPartitionCount.- Controller ativo, filas de eventos e falhas de eleição.
- Latência, erros e BytesIn/BytesOut.
- Lag máximo e taxa de processamento por grupo.
- GC, heap, processo e descritores.
- Disco, inodes, latência I/O e perda de rede.
Com um broker, UnderReplicatedPartitions=0 não garante disponibilidade do host. Combine alertas de Kafka e VPS com Prometheus e Grafana.
Replicação melhora disponibilidade, mas propaga exclusões e erros. Pare produtores/consumidores e faça uma cópia com o nó parado:
cd /opt/kafka
docker compose stop kafka
sudo tar -C /opt/kafka -czf \
"backups/kafka-data-$(date +%F-%H%M%S).tar.gz" \
data
docker compose start kafka
Confira o tar, restrinja permissões, criptografe e copie para fora do host. Inclui logs e metadados KRaft somente se todos os diretórios estiverem no caminho copiado; confira montagens personalizadas.
Copie separadamente e com criptografia ambiente, Compose/override, JAAS, CA, armazenamentos e propriedades. Restaure uma instância isolada e parada com Cluster ID original, configuração, metadados e permissões. Não reformate dados existentes. Use versões compatíveis, confira topics, eventos e offsets e teste clientes antes de redirecionar tráfego.
Para RPO/RTO baixos, planeje outro cluster com MirrorMaker 2 e checkpoints de grupos. Confira filtros, sincronização de offsets e failover; não oferece perda zero automaticamente nem substitui arquivos independentes.
Leia notas e compatibilidade de clientes, plugins, Connect e protocolos. Um nó exige manutenção e backup frio:
cd /opt/kafka
docker compose config --quiet
docker compose exec kafka /opt/kafka/bin/kafka-topics.sh \
--bootstrap-server kafka:19094 \
--command-config /etc/kafka/secrets/client-admin.properties \
--list
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 kafka
Troque a imagem/override antes de baixar: a mesma tag não faz mudança de versão. Evite latest. Siga a sequência de metadados e feature versions KRaft; após mudanças irreversíveis, restaure uma cópia anterior compatível em vez de presumir downgrade.
Confira advertised.listeners:
getent hosts mq.example.com
nc -vz mq.example.com 9094
Teste DNS e rotas no cliente, regras do provedor e bindings Docker pelo guia de acesso às portas.
Veja SAN e cadeia:
openssl s_client -connect mq.example.com:9094 \
-servername mq.example.com \
-showcerts </dev/null
O comando mostra certificados; para validar, adicione CA, -verify_hostname real e -verify_return_error. Corrija certificado/DNS sem desligar a verificação.
Use PLAIN e SASL_SSL. A chave JAAS ilustrada em user_用户名 deve ser user_app ou user_admin real. Recarregue configuração após editar broker_jaas.conf. Prepare credenciais novas e clientes testados antes de retirar as antigas.
Não altere CLUSTER_ID em .env ao reutilizar dados. Pare e compare meta.properties, configuração e backups. Reformatar dados de negócio destrói informações de recuperação.
cd /opt/kafka
docker compose logs --tail=200 kafka
namei -l /opt/kafka/data /opt/kafka/secrets
sudo chown -R 1000:1000 /opt/kafka/data /opt/kafka/secrets
Confira UID/GID antes de chown, TLS explícito, permissões dos diretórios, espaço e logs.
Não: usa KRaft. Não misture configurações antigas ZooKeeper.
Para desenvolvimento leve, heap perto de 1GB e limites rigorosos de disco/retenção. Produção pequena costuma exigir 8GB/NVMe e carga medida.
Só se parada e recuperação forem aceitáveis. Serviços críticos precisam de domínios independentes e quorum planejado; combined mode não é recomendado.
Prefira VPN/rede privada, SASL_SSL, ACLs e restrições de origem. Separe controllers das redes de clientes.
Use somente com TLS; avalie SCRAM, OAuthBearer ou autenticação externa.
Não. Adicione backups, arquivos independentes ou replicação entre clusters e ensaie recuperação.