Como resolver assinaturas de imagem quebradas no Roundcube com cPanel e CloudLinux

Recentemente, precisei investigar um comportamento curioso no webmail: qualquer assinatura com imagem configurada no Roundcube, fosse ela JPG, PNG ou WebP, enviada por upload ou colada diretamente pelo clipboard, resultava em um quadrado em branco com ícone de imagem quebrada após salvar.

Em servidores rodando cPanel sobre CloudLinux, esse sintoma raramente é um defeito visual da interface. Quase sempre a falha reside nas camadas intermediárias: dependências de processamento de imagem no PHP, restrições do CageFS, limites de memória do LVE ou problemas na persistência do banco SQLite do usuário.

Abaixo, compartilho a análise de causalidade, o roteiro de diagnóstico pelo terminal e as ações corretivas que utilizei para normalizar o serviço.

1. Por que o Roundcube gera o quadrado em branco?#

O ícone de imagem quebrada indica que o Roundcube capturou o payload (seja multipart ou Base64), mas falhou ao processar os bytes binários ou ao gerar o preview interno inline.

Os três principais pontos de quebra no pipeline são:

1. Extensões PHP ausentes ou bloqueadas no CageFS (gd, imagick, fileinfo): O Roundcube usa GD ou ImageMagick para sanitizar e redimensionar imagens. Se o CageFS estiver sem acesso às bibliotecas compartilhadas (libjpeg, libpng) ou se o fileinfo estiver desativado (impedindo a identificação do MIME type real), as funções de leitura falham silenciosamente, gerando um buffer vazio de 0 bytes.
2. Estouro de limites de memória no LVE / PHP: O re-encode de imagens consome picos de RAM. Se o memory_limit do PHP for muito baixo ou se o usuário bater no teto de PMEM no CloudLinux, o processo é encerrado pelo kernel antes de concluir a gravação.
3. Truncamento de payload no banco de dados: Strings em Base64 geram um overhead de aproximadamente 33%. Se as diretivas post_max_size ou upload_max_filesize estiverem restritas, ou se a base SQLite do usuário estiver bloqueada em modo read-only por quota cheia, os dados são truncados.

2. Roteiro de diagnóstico via terminal#

Para validar cada componente diretamente pela linha de comando:

Passo 1: Inspeção de erros no log do Roundcube#

O webmail no cPanel roda de forma centralizada e grava seus erros de execução em /usr/local/cpanel/base/roundcube/logs/errors.log (o diretório /home/USERNAME/logs/ contém apenas os logs de vhost e PHP de sites do usuário):

tail -f /usr/local/cpanel/base/roundcube/logs/errors.log

Procure por falhas de manipulação de imagem ou erros de integridade no banco de dados.

Passo 2: Verificação de faults de memória no CloudLinux#

Para checar se o LVE encerrou o processo do PHP durante o processamento do upload:

lveinfo --user USERNAME --period 10m

Se a coluna PMemF (Physical Memory Faults) apresentar contadores maiores que zero, o limite de RAM do usuário foi atingido.

Passo 3: Validação das extensões ativas no PHP do sistema#

O Roundcube do cPanel é executado pelo PHP interno do sistema (EasyApache 4 / System Default PHP), e não pelo PHP configurado para o domínio do usuário (CloudLinux alt-php / PHP Selector). Portanto, valide os módulos diretamente no binário padrão do sistema:

/usr/local/bin/php -m | grep -E "gd|imagick|fileinfo"

A presença simultânea de fileinfo e gd (ou imagick) no PHP do sistema é obrigatória para o processamento de assinaturas ricas.

Passo 4: Checagem de logs do cpsrvd e ModSecurity#

Como o webmail é servido pelo daemon cpsrvd (portas 2095/2096) e não passa pelo Apache, requisições de webmail com falhas, timeouts ou bloqueios são registradas diretamente no log do cpsrvd:

tail -f /usr/local/cpanel/logs/error_log | grep USERNAME

3. Ações corretivas aplicadas#

Após identificar os gargalos, apliquei os seguintes ajustes:

A. Ajuste de diretivas no PHP do sistema#

No MultiPHP INI Editor (selecionando System Default ou editando o php.ini do sistema), aumente os limites para acomodar o overhead de conversão — já que o webmail roda sob o PHP do sistema, e não sob o PHP do domínio do usuário:

• upload_max_filesize = 32M
• post_max_size = 32M
• memory_limit = 256M

B. Manutenção do CageFS e diretórios temporários#

Para garantir que o ambiente enjaulado do usuário enxergue as dependências atualizadas:

# Atualizar o esqueleto e remontar a jaula do usuário
cagefsctl --update && cagefsctl --remount USERNAME

Valide também se o diretório temporário do Roundcube (/var/cpanel/roundcube/temp) possui permissões adequadas de escrita.

C. Verificação de quota e reparo da base SQLite#

Em instalações modernas do cPanel, o Roundcube armazena o banco SQLite dentro do diretório /home da conta do usuário. Se a conta atinge 100% da quota de disco alocada, o SQLite entra em modo somente leitura (read-only), impedindo a gravação do payload da assinatura:

# Verificar quota de disco do usuário
quota -v USERNAME

# Atualizar e reparar a base SQLite do Roundcube
/usr/local/cpanel/bin/update-roundcube-db --user USERNAME

Dicas práticas de isolamento#

Uma regra simples para isolar o problema rapidamente: teste texto puro antes de testar imagens.

Ao salvar uma assinatura composta apenas de texto, se o Roundcube gravar sem erros, isso descarta problemas gerais no banco SQLite e permissões da conta. O problema fica delimitado exclusivamente ao pipeline de processamento binário de imagens (extensões GD/Fileinfo, limites de POST e montagem do CageFS).

Após ativar os módulos gd e fileinfo, remontar a jaula com cagefsctl e ajustar os limites do PHP, o salvamento de imagens nas assinaturas voltou a operar normalmente, gerando os previews sem erros.

Conclusão#

Neste artigo compartilhei o roteiro que usei para isolar o problema: testar texto puro antes de imagem, validar extensões do PHP do sistema, conferir faults no LVE e ajustar limites. Com gd e fileinfo ativos no PHP do sistema e a jaula remontada, as assinaturas com imagem voltaram a salvar normalmente.

Veja também

E-mail Roundcube no cPanel quebrando com DB error [14] unable to open database file

E-mail Diagnóstico profundo de request timeout no cPanel webmail com Roundcube, cpsrvd e SQLite

E-mail Anatomia de uma falha em cascata: do bloqueio de IP por spam à depuração do Roundcube no cPanel

Este post está licenciado sob CC BY-NC.