Reconstruir índice do Dovecot sem perder mensagem
Como reconstruir o índice do Dovecot de uma conta específica no cPanel, com a ordem de parada do serviço, o que não tocar e como verificar a contagem no fim.

Resposta curta: apagar `dovecot.index`, `dovecot.index.log` e `dovecot.index.cache` da conta não apaga nenhuma mensagem: as mensagens ficam em `cur/`, `new/` e `tmp/`. O índice é reconstruído na primeira reabertura, que é a conexão mais lenta do ciclo.
Neste artigo
- Índice é metadado, mensagem é arquivo em cur/ e new/
- Três sintomas que terminam na mesma pasta do Maildir
- O que conferir antes de remover qualquer arquivo
- A ordem de execução, do menos invasivo ao mais
- Por que a primeira reabertura fica mais lenta, não mais rápida
- Como verificar que nenhuma mensagem se perdeu e como reverter
- Quatro casos em que reindexar não resolve nada
Índice é metadado, mensagem é arquivo em cur/ e new/
No Dovecot com Maildir, a mensagem é um arquivo dentro de cur/, new/ ou tmp/. Todo o resto que mora na raiz da pasta é metadado: cache, mapa de flags, mapa de UID. Apagar índice não apaga e-mail. Apagar cur/ apaga.
Essa separação é a razão pela qual reconstruir índice é uma operação relativamente segura, e também a razão pela qual ela é inútil quando o problema real é a quantidade de arquivos no diretório. Se a INBOX tem dezenas de milhares de mensagens em cur/, a reindexação vai refazer o mesmo trabalho caro de novo na primeira abertura.
| Arquivo | Função | Consequência de apagar |
|---|---|---|
dovecot.index |
Mapa binário de mensagens, flags e keywords | Reconstruído na próxima abertura, varrendo o Maildir |
dovecot.index.log |
Transaction log das mudanças recentes de índice | Reconstruído; mudanças ainda não aplicadas se perdem |
dovecot.index.cache |
Cache de headers e campos usados em listagens | Reconstruído sob demanda; primeira listagem fica mais cara |
dovecot-uidlist |
Associação entre nome do arquivo Maildir e UID IMAP, mais UIDVALIDITY |
UIDVALIDITY novo: o cliente trata a pasta como nova e baixa tudo de novo |
subscriptions |
Lista de pastas assinadas (LSUB) | Pastas somem do painel do cliente mesmo existindo no disco |
maildirsize, maildirfolder |
Cota e marcação de subpasta | Cota recalculada; não é índice IMAP |
A documentação oficial do cPanel descreve o script remove_dovecot_index_files exatamente como um utilitário para remover arquivos de índice do Dovecot quando eles estão corrompidos ou inconsistentes (docs.cpanel.net).
Três sintomas que terminam na mesma pasta do Maildir
Caixa que demora a abrir porque o Dovecot varre o Maildir inteiro
O cliente pede SELECT INBOX e o Dovecot precisa devolver contagem, flags e UIDs. Com índice saudável isso sai do dovecot.index. Com índice corrompido ou ausente, sai de uma varredura do Maildir inteiro: stat() em cada arquivo, parse do nome, reconstrução do mapa. Em caixas grandes, a diferença aparece como timeout no cliente e CPU de I/O no servidor.
Duplicata depois de backup restaurado vem do UIDVALIDITY, não do índice
Este é o caso mais comum e o mais mal diagnosticado. Quando um backup restaura cur/ sem restaurar dovecot-uidlist coerente, ou restaura um dovecot-uidlist mais antigo que o conteúdo, o Dovecot pode atribuir UIDs novos a arquivos que o cliente já conhecia, ou regravar UIDVALIDITY. O IMAP não tem como dizer ao cliente "é a mesma mensagem com outro UID". A especificação manda o cliente descartar o cache local quando UIDVALIDITY muda. Outlook e Thunderbird fazem isso baixando tudo de novo. Se a pasta local estava configurada em modo que acumula, o usuário vê duas cópias de cada mensagem.
Observe a direção da causa. A duplicata não vem do índice corrompido, vem do UID regravado. Reconstruir o índice depois do fato não desfaz as cópias já baixadas no cliente.
Pasta existe no disco e some do cliente por causa do arquivo subscriptions
LIST lê o diretório. LSUB lê o arquivo subscriptions. Cliente configurado para mostrar só pastas assinadas esconde tudo que sumiu do subscriptions. A pasta continua lá, com as mensagens intactas. O teste de trinta segundos é abrir o webmail e marcar a exibição de todas as pastas, ou inspecionar o arquivo direto no home da conta.
Se a caixa está vazia e não lenta, o problema é outro e está descrito em e-mail conecta mas a caixa fica vazia depois da migração. Se o que dói é entrega e autenticação, veja o guia de diagnóstico de entrega.
O que conferir antes de remover qualquer arquivo
- Acesso root ao servidor. A operação envolve parar serviço e mexer em arquivo de outro usuário.
- Saber o caminho exato da conta. Em cPanel, a conta padrão do domínio principal fica em
/home/usuario/mail/, e as contas adicionais em/home/usuario/mail/dominio.com.br/conta/. - Cópia do estado atual. Antes de remover, copie os arquivos de índice para fora do Maildir. Reversão é colar de volta.
- Confirmação de que é índice e não disco.
df -icom inodes esgotados produz sintoma parecido e reindexação não resolve.
# conferir o alvo antes de remover qualquer coisa
MB=/home/usuario/mail/exemplo.com.br/contato
ls -la "$MB" | head
find "$MB/cur" "$MB/new" -type f | wc -l # mensagens na pasta: lidas e não lidas
df -i /home
O valor que wc -l devolve é o número de mensagens que o cliente vai enxergar: o Dovecot soma cur/ (já vistas pelo servidor) e new/ (entregues e ainda não movidas, que aparecem como não lidas). Guarde esse número: ele é a sua verificação no fim.
A ordem de execução, do menos invasivo ao mais
Tentar force-resync antes de derrubar a sessão IMAP
Antes de parar nada, considere o caminho por conta. doveadm reconstrói o índice de uma mailbox com o serviço no ar, sem afetar as outras contas:
doveadm force-resync -u [email protected] INBOX
doveadm force-resync -u [email protected] '*' # todas as pastas da conta
Isso cobre a maioria dos casos de índice inconsistente e é o que você tenta primeiro. Parar o Dovecot só se justifica quando o force-resync falha porque o índice está travado por lock, quando sobra processo imap/pop3 preso na conta (doveadm who -u [email protected], doveadm kick -u [email protected]) ou quando você vai remover arquivos à mão e precisa garantir que ninguém regrave índice no meio da operação.
Um cliente conectado mantém a mailbox selecionada e pode regravar índice logo depois de você apagar. Peça ao usuário para fechar o cliente, ou derrube a sessão. Com o Dovecot parado, nenhuma sessão nova entra.
Parar o Dovecot: o que acontece com a entrega do Exim
/scripts/restartsrv_dovecot --stop
IMAP e POP3 ficam indisponíveis enquanto o serviço está parado. O que acontece com a entrega depende de como o Exim entrega no Maildir:
dovecot-lda(oudeliver) chamado como binário, que é o transporte padrão nas instalações cPanel: o processo é standalone, lê a configuração, abre o Maildir e grava a mensagem sem depender do master do Dovecot. A entrega continua ocorrendo com o serviço parado. O efeito colateral é que o LDA também escreve índice: se ele entregar no meio da remoção, você vai verdovecot.index.logrenascer antes de subir o serviço.- LMTP via socket (
/var/run/dovecot/lmtp) ou via TCP: com o master parado não há quem aceite a conexão, o Exim recebe falha de conexão e a mensagem fica na fila, com retry conformeretrydo Exim. Nada se perde, mas a entrega só acontece quando o serviço voltar.
Confirme qual é o seu caso antes de parar:
# o transporte usado pelo roteador de entrega local do Exim
grep -rniE 'dovecot|lmtp' /etc/exim.conf.local /etc/exim.conf | head -20
# LMTP habilitado no Dovecot?
doveadm config -n | grep -A3 'protocol lmtp\|service lmtp'
grep -E '^protocols' /etc/dovecot/dovecot.conf
Se aparecer lmtp no transporte do Exim, trate a janela como janela de fila: faça curta e fora de pico. Se for dovecot-lda/deliver, a entrega segue, e a janela curta serve para reduzir a chance de o LDA recriar índice enquanto você está removendo arquivo.
Remover só os arquivos de índice, sem tocar em cur, new e tmp
Para uma conta específica, remova os arquivos de índice da pasta afetada, recursivamente se o problema atinge subpastas:
MB=/home/usuario/mail/exemplo.com.br/contato
mkdir -p /root/backup-indice-contato
cd "$MB" && find . -maxdepth 2 \( -name 'dovecot.index*' -o -name 'dovecot-uidlist' -o -name 'subscriptions' \) -print | cpio -pdm /root/backup-indice-contato
find "$MB" -maxdepth 2 -name 'dovecot.index*' -delete
Não inclua cur, new nem tmp no padrão. Não remova subscriptions se a queixa é lentidão: você troca um problema por outro.
Sobre dovecot-uidlist: só remova se a evidência aponta para ele, porque a remoção força UIDVALIDITY novo e todos os clientes conectados vão baixar a pasta inteira de novo. Em caixa grande isso é pico de banda e de I/O, e é precisamente o mecanismo que gera duplicata em cliente configurado para acumular.
Quando o script remove_dovecot_index_files do cPanel resolve
O WHM traz remove_dovecot_index_files em /usr/local/cpanel/scripts/, documentado como o caminho suportado para limpar índices do Dovecot. Antes de passar qualquer argumento, consulte o --help da versão instalada no seu servidor, porque o conjunto de opções acompanha a versão do cPanel e a documentação é a referência válida para o comportamento do script.
/usr/local/cpanel/scripts/remove_dovecot_index_files --help
Subir o serviço e confirmar o status
/scripts/restartsrv_dovecot
/scripts/restartsrv_dovecot --status
Dono e modo dos índices recriados: o erro de deixar root no Maildir
Se você rodou qualquer comando como root dentro do Maildir, há risco de o índice novo nascer com dono errado e a conta passar a falhar na abertura. O Dovecot cria o índice com a identidade do processo que abriu a caixa, então um doveadm rodado como root sobre caminho explícito pode deixar lixo de root ali. Confira e corrija:
stat -c '%U:%G %a %n' "$MB"/dovecot.index* "$MB/dovecot-uidlist"
chown -R usuario:usuario "$MB" # usuário cPanel dono do /home, não a conta de e-mail
find "$MB" -type f -name 'dovecot*' -exec chmod 600 {} +
O mesmo vale na reversão. No cpio do GNU, o modo pass-through (cpio -p) preserva UID e GID de origem quando executado como root, e esse é o comportamento padrão: só o root tem privilégio de chown para outro dono, então, rodando como usuário comum, os arquivos restaurados nascem com o dono de quem executou. Se você rodou como root e mesmo assim quer forçar que tudo fique com a identidade de quem executa, é cpio -p --no-preserve-owner. Na prática: restaure como root para manter o dono original, e confira com stat -c '%U:%G %a %n' depois de restaurar, não antes.
Por que a primeira reabertura fica mais lenta, não mais rápida
A primeira conexão depois da remoção é a mais cara do ciclo. O Dovecot vai varrer o Maildir, reconstruir dovecot.index e começar a preencher dovecot.index.cache conforme o cliente pede headers. Enquanto isso, a conta pode parecer mais lenta do que estava, não mais rápida.
Isso é esperado e é a parte que costuma gerar o segundo chamado. Avise o usuário antes: abrir uma vez, esperar a sincronização terminar, só então julgar o resultado. Se a caixa tem muitas dezenas de milhares de mensagens, a reindexação sob carga concorre com todas as outras contas no mesmo disco. Faça fora do horário de pico.
Se a lentidão volta ao estado anterior depois da reindexação completa, o índice não era o problema. O problema é o tamanho da pasta. A correção estrutural é arquivar por ano em subpastas, não reindexar de novo.
Como verificar que nenhuma mensagem se perdeu e como reverter
Comparar a contagem do webmail com o número medido antes
Abra a conta no webmail e compare a contagem exibida na pasta com o número que find "$MB/cur" "$MB/new" -type f | wc -l devolveu antes da operação. O cliente soma as duas pastas, então comparar só com cur/ produz divergência legítima e leva a concluir perda que não houve. Divergência grande significa que algo além de índice foi tocado. Igualdade significa que nenhuma mensagem se perdeu, que é exatamente o que a operação promete.
Conferir contagem, data e dono dos arquivos no disco
find "$MB/cur" "$MB/new" -type f | wc -l # mesmo número de antes
ls -la "$MB" # dovecot.index* recriado com data de agora
stat -c '%U:%G %a %n' "$MB"/dovecot.index* # dono tem que ser o usuário cPanel, não root
Reverter a partir da cópia dos índices antigos
Enquanto o backup dos arquivos de índice existir, reversão é parar o Dovecot, remover os índices novos, restaurar os antigos e subir o serviço. Depois que o cliente já sincronizou com UIDVALIDITY novo, a reversão não desfaz o download duplicado no lado do usuário: ali a correção é no cliente, removendo a conta e adicionando de novo, ou limpando a cópia local da pasta.
Quatro casos em que reindexar não resolve nada
- Caixa vazia no cliente, cheia no disco: é caminho de Maildir, prefixo de namespace ou assinatura de pasta, não índice.
- Erro de autenticação ou SSL: nada a ver com índice.
- Disco ou inode cheio: reindexar com disco cheio tende a piorar, porque o Dovecot não consegue gravar o índice novo e repete a varredura a cada abertura.
- Duplicata que continua chegando: duplicata nova, depois da reindexação, é regra de encaminhamento ou duas contas entregando na mesma caixa, não índice.
A pergunta que separa os casos é simples: o conteúdo do cur/ está certo? Se está, o problema é de metadado e reconstruir índice é a ferramenta. Se não está, reindexar só vai registrar com fidelidade um estado errado.
Referências
- Documentação oficial (cpanel) — The remove_dovecot_index_files Script. Consultado em 2026-09-25.