Como corrigir o erro "Tempo limite do mecanismo de bloqueio" no ownCloud

Se o ownCloud reportar um erro de tempo limite de bloqueio de arquivo durante a sincronização, upload, movimentação, renomeação ou montagem de chunks, o primeiro passo é entender que o erro geralmente envolve o bloqueio transacional de arquivos , e não o recurso de Bloqueio Manual de Arquivos visível ao usuário. O bloqueio transacional é um mecanismo de segurança interno que impede que duas requisições salvem ou modifiquem o mesmo arquivo simultaneamente. Ele está habilitado por padrão no ownCloud e pode usar o banco de dados ou o Redis como backend de bloqueio.

A documentação atual do ownCloud 11 ainda recomenda o Redis para bloqueio de arquivos transacionais, pois os bloqueios baseados em banco de dados geram uma carga significativa no banco. Em instalações em cluster, cada nó de aplicação deve usar a mesma instância compartilhada do Redis para bloqueio. Essa é a solução definitiva que você precisa entender antes de alterar os valores de tempo limite ou excluir registros de bloqueio.

Este guia aborda o problema da perspectiva de um administrador iniciante: o que o bloqueio significa, o que fazer backup, como confirmar o componente com falha, como configurar o Redis, como os clusters alteram o cenário e quais atalhos podem piorar a situação.

O que significa o erro

Quando o ownCloud altera um arquivo, ele adquire um bloqueio para que outra solicitação não possa realizar uma alteração incompatível simultaneamente. O bloqueio também pode abranger um diretório pai, impedindo que ele seja renomeado enquanto houver alterações em andamento dentro dele. Se o bloqueio não puder ser adquirido a tempo, a operação pode falhar com um erro de recurso bloqueado ou de tempo limite excedido, em vez de correr o risco de corromper o arquivo.

De acordo com a documentação de bloqueio de arquivos transacionais do ownCloud 11 , esse mecanismo também lida com uploads interrompidos, arquivos compartilhados, armazenamento externo e arquivos criptografados.

Isso é diferente do Bloqueio Manual de Arquivos , o recurso opcional de check-in/check-out baseado em WebDAV que permite ao usuário bloquear deliberadamente um arquivo na interface web. Os bloqueios manuais possuem valores de expiração configuráveis ​​pelo usuário. Alterar esses valores não corrige um backend de bloqueio transacional sobrecarregado ou configurado incorretamente.

Antes de começar

• Faça backup do banco de dados do ownCloud e config/config.php.
• Registre sua versão do ownCloud e o tipo de implantação: pacote tradicional, Docker Compose ou cluster com vários nós.
• Identifique seu mecanismo de banco de dados e verifique se o Redis já está instalado.
• Registre a operação exata que falhou, como uma sincronização de área de trabalho, um upload via WebDAV, a renomeação de uma pasta ou um upload em partes.
• Observe se o problema afeta um arquivo, um usuário ou vários usuários simultaneamente.

Uma interrupção generalizada que afeta muitos usuários geralmente indica um componente compartilhado, como o mecanismo de bloqueio, o banco de dados, o Redis ou o armazenamento. Um erro repetível em um arquivo pode, por outro lado, envolver uma operação genuinamente ativa ou um bloqueio obsoleto que ainda não expirou.

Passo 1: Confirme qual mecanismo de travamento está com defeito.

Comece analisando os logs do ownCloud, do servidor web, do PHP-FPM e o status do serviço Redis. Procure por exceções repetidas de recursos bloqueados, erros de espera de bloqueio no banco de dados, falhas de conexão com o Redis ou um padrão em que o mesmo caminho permanece bloqueado muito tempo depois do término da operação original.

Algumas verificações úteis em um host Linux incluem:

systemctl status redis-server
redis-cli PING
ps -ef | grep php
tail -n 200 /path/to/owncloud/data/owncloud.log

Um comando Redis saudável deve retornar . Se o ownCloud estiver configurado para acessar o Redis por meio de um socket, nome de host do contêiner, senha ou host remoto, teste o mesmo caminho de conexão que o ownCloud realmente usa, em vez de presumir que um teste PONGlocal comprova a conectividade do aplicativo.redis-cli

Se o log contiver uma mensagem do banco de dados semelhante a “tempo limite de espera de bloqueio excedido”, investigue também a contenção do banco de dados. O antigo mecanismo de bloqueio do banco de dados ainda funciona, mas a documentação do ownCloud alerta explicitamente que ele impõe uma carga significativa ao banco de dados.

Etapa 2: Migrar o bloqueio de arquivos transacionais para o Redis.

Para uma instalação tradicional do ownCloud, configure o Redis como memcache.lockingbackend em config/config.php. A documentação atual do ownCloud sobre cache de memória fornece um exemplo de TCP com Redis semelhante a este:

'filelocking.enabled' => true,
'memcache.locking' => '\OC\Memcache\Redis',
'redis' => [
    'host' => 'localhost',
    'port' => 6379,
    'timeout' => 0,
    'password' => '',
],

Não copie a senha vazia literalmente para uma configuração do Redis exposta à internet. A documentação de cache de memória do ownCloud recomenda proteger o Redis adequadamente. Idealmente, o Redis deve ser acessível apenas a partir de hosts confiáveis ​​do ownCloud ou da rede interna do contêiner.

Na configuração oficial do Docker para ownCloud, o Redis é habilitado por meio de variáveis ​​de ambiente. A documentação atual do ownCloud 11 mostra:

OWNCLOUD_REDIS_ENABLED=true
OWNCLOUD_REDIS_HOST=redis
OWNCLOUD_REDIS_PORT=6379

Quando o Redis está habilitado nesse modelo de implantação, o ownCloud define automaticamente o cache distribuído e o cache de bloqueio para o Redis. Use a configuração específica da implantação documentada para sua instalação em vez de misturar variáveis ​​de ambiente do Docker com uma configuração mantida manualmente, config.phpa menos que você entenda qual camada prevalece.

Passo 3: Em um cluster, faça com que todos os nós usem o mesmo Redis.

Um cluster é uma implantação com vários servidores de aplicativos ownCloud atrás de um balanceador de carga. Nesse design, um bloqueio criado em um nó de aplicativo deve ser visível para todos os outros nós. Caches APCu por nó ou instâncias Redis separadas por nó não podem fornecer esse estado de bloqueio compartilhado.

O guia de armazenamento compartilhado em cluster do ownCloud é explícito: utilize uma instância Redis compartilhada acessível por todos os nós da aplicação. Ele alerta contra o uso de bloqueios de sistema de arquivos ou NFS para o bloqueio em nível de aplicação do ownCloud.

Verifique se todos os nós usam o mesmo endpoint e credenciais do Redis. Um padrão de falha comum é quando um nó ainda está usando o banco de dados ou um Redis local enquanto os outros usam o serviço compartilhado. Isso cria um comportamento de bloqueio inconsistente que pode parecer intermitente, pois o resultado depende de qual nó da aplicação processa cada requisição.

Etapa 4: Verifique a configuração e tente novamente a operação original.

Após configurar o Redis, verifique as configurações ativas do ownCloud com o comando ` occdocker-compose up`. Dependendo da sua instalação, o comando pode ser invocado como o usuário do servidor web ou através do Docker Compose.

sudo -u www-data php occ config:system:get memcache.locking
sudo -u www-data php occ config:system:get filelocking.enabled

O primeiro comando deve reportar o problema \OC\Memcache\Redise o bloqueio de arquivos transacionais deve permanecer ativado. Não "resolva" o problema desativando o bloqueio de arquivos. Isso remove uma salvaguarda de integridade de dados em vez de corrigir o problema no servidor.

Agora, tente novamente a mesma operação que falhou. Se o upload de um cliente desktop expirou, repita o upload. Se a movimentação de uma pasta falhou, repita a movimentação. Monitore os logs do ownCloud e do Redis durante o teste. Uma nova tentativa bem-sucedida, sem recorrência de timeouts de bloqueio, é uma evidência muito mais forte do que executar um comando de manutenção não relacionado.

E se o arquivo ainda aparecer bloqueado?

Primeiro, determine se outra operação ainda está realmente usando o arquivo. Uploads grandes, chamadas a armazenamento externo, movimentação de arquivos, criptografia ou armazenamento lento podem, legitimamente, manter bloqueios por mais tempo do que o esperado. Eliminar o bloqueio enquanto a operação ainda está ativa pode criar a condição de corrida que o bloqueio foi projetado para evitar.

Os bloqueios transacionais são projetados para serem liberados após transações interrompidas. Documentos de configuração mais antigos do ownCloud também incluem um mecanismo de tempo de vida (TTL) para que bloqueios antigos possam ser liberados automaticamente. Como os detalhes exatos da configuração podem variar de acordo com a versão do ownCloud, verifique a opção na documentação correspondente à sua versão instalada antes de alterá-la. Não defina um TTL extremamente curto apenas para mascarar um problema de lentidão no armazenamento ou no banco de dados.

Se os metadados estiverem inconsistentes, o ownCloud oferece comandos de verificação de arquivos com foco em reparo. A documentação oficial do comando `occ` recomenda fazer backup do banco de dados antes de executar uma verificação de reparo. Uma verificação de reparo é indicada para metadados de arquivos danificados ou inconsistentes; não é a solução de primeira linha para conflitos de bloqueio comuns.

Não confunda bloqueio transacional com bloqueio manual de arquivos.

A documentação atual do ownCloud 11 indica que o Bloqueio Manual de Arquivos está desativado por padrão na interface web. Quando ativado, o bloqueio na interface web tem duração padrão de 30 minutos, e o máximo padrão é de 24 horas. Esses valores estão documentados no guia de Bloqueio Manual de Arquivos .

Se o seu problema for especificamente um bloqueio manual criado pelo usuário, então comandos como estes são relevantes:

docker compose exec owncloud occ config:app:set files lock_timeout_default --value 1800
docker compose exec owncloud occ config:app:set files lock_timeout_max --value 86400

Se o seu problema for um tempo limite interno durante a sincronização ou o salvamento de um arquivo, alterar esses valores de bloqueio manual geralmente não é a solução adequada.

Erros comuns que pioram os tempos limite de bloqueio

Excluindo linhas de bloqueio do banco de dados enquanto o ownCloud está ativo

Isso pode competir com solicitações em tempo real e remover bloqueios válidos. Além disso, trata o sintoma sem corrigir a configuração do banco de dados ou do Redis que causou o tempo limite.

Desativar o bloqueio de arquivos transacionais

O bloqueio transacional existe para proteger as operações de arquivo contra modificações simultâneas. Mantenha-o ativado e repare o servidor.

Utilizando APCu para bloqueio compartilhado em um cluster

O APCu é um cache local por nó. É adequado para cache local, mas não fornece um estado de bloqueio compartilhado entre vários servidores de aplicativos. Use o Redis compartilhado para caches distribuídos e com bloqueio em implantações em cluster.

Executando uma instância do Redis por nó de aplicação.

Isso faz com que cada servidor tenha uma visão diferente dos bloqueios de arquivos. Todos os nós precisam do mesmo serviço Redis compartilhado para a coordenação dos bloqueios.

Aumentar o tempo de espera de bloqueio do banco de dados sem corrigir a contenção.

Um tempo limite de banco de dados mais longo pode apenas fazer com que os usuários esperem mais tempo. Mover o tráfego de bloqueio transacional para o Redis reduz a carga de trabalho de bloqueio do banco de dados e resolve o gargalo arquitetônico.

Tornar o prazo de validade do bloqueio irrealisticamente curto

Uma operação lenta de armazenamento externo ou um upload grande pode justificadamente exigir tempo. Expirar o bloqueio prematuramente pode permitir que outra solicitação modifique o mesmo recurso simultaneamente.

Lista de verificação rápida para solução de problemas

• Confirme se o erro envolve bloqueio transacional e não um bloqueio manual criado pelo usuário.
• Verifique os logs do ownCloud, PHP, banco de dados e Redis aproximadamente no mesmo horário.
• Verifique se o Redis está acessível a partir do ambiente de execução do ownCloud, e não apenas a partir do seu terminal.
• Defina memcache.lockingcomo \OC\Memcache\Redis.
• Manter filelocking.enabledativado.
• Em um cluster, aponte todos os nós para a mesma instância do Redis.
• Tente novamente a sincronização, o upload ou a movimentação original enquanto monitora os registros.
• Utilize verificações de reparo ou alterações de expiração de bloqueio somente quando as evidências apontarem para danos nos metadados ou bloqueios obsoletos.

Resumindo

A solução mais confiável para erros de tempo limite de bloqueio de arquivos no ownCloud não é remover bloqueios nem aumentar valores de tempo limite arbitrários. Comece identificando se o erro vem de bloqueios transacionais. Em seguida, mova essa carga de trabalho de bloqueio para o Redis e certifique-se de que todos os nós do ownCloud vejam a mesma instância do Redis. Teste novamente a operação exata que falhou e investigue a latência do banco de dados ou do armazenamento se os bloqueios ainda permanecerem ativos por muito tempo.

Essa abordagem segue a documentação atual do ownCloud: o bloqueio transacional de arquivos permanece ativado, o Redis gerencia o estado de bloqueio compartilhado e as configurações de tempo limite de bloqueio manual de arquivos são tratadas como um recurso separado, em vez de uma correção universal para o tempo limite de bloqueio.