# 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.

> 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.

João Rizzon · 2026-10-12 · Painéis

---

## Í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](https://docs.cpanel.net/whm/scripts/the-remove_dovecot_index_files-script/)).

## 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](/blog/email-conecta-mas-a-caixa-fica-vazia-depois-da-migracao). Se o que dói é entrega e autenticação, veja [o guia de diagnóstico de entrega](/blog/por-que-meu-email-cai-no-spam).

## 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 -i` com inodes esgotados produz sintoma parecido e reindexação não resolve.

```bash
# 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:

```bash
doveadm force-resync -u contato@exemplo.com.br INBOX
doveadm force-resync -u contato@exemplo.com.br '*'   # 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 contato@exemplo.com.br`, `doveadm kick -u contato@exemplo.com.br`) 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

```bash
/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` (ou `deliver`) 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 ver `dovecot.index.log` renascer 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 conforme `retry` do Exim. Nada se perde, mas a entrega só acontece quando o serviço voltar.

Confirme qual é o seu caso antes de parar:

```bash
# 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:

```bash
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.

```bash
/usr/local/cpanel/scripts/remove_dovecot_index_files --help
```

### Subir o serviço e confirmar o status

```bash
/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:

```bash
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

```bash
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.

