Object Storage Service:ossfs 2.0 FAQ

Erro de montagem: Failed to mount ossfs2

Análise do problema: Erro genérico. Consulte os logs para obter detalhes específicos. Geralmente, esse erro ocorre devido a permissões incorretas ou parâmetros de configuração inválidos. Exemplo:

2025/03/21 15:09:59.124152|ERROR|th=00007F1238FF5780|ossfs_v2.cpp:1469|Check bucket failed with err: AccessDenied

A AccessKey utilizada não tem permissão para acessar o bucket. Verifique se sua AccessKey possui as permissões necessárias e se o nome do bucket está correto.

2025/03/21 15:14:29.671470|ERROR|th=00007F2304FF5780|ossfs_v2.cpp:1469|Check bucket failed with err: InvalidAccessKeyId

A AccessKey configurada é inválida.

2025/03/21 15:15:13.805814|ERROR|th=00007FD591D38780|ossfs_v2.cpp:1469|Check bucket failed with err: SignatureDoesNotMatch

Solução: Corrija a configuração com base na mensagem de erro dos logs e tente montar novamente.

Erro de montagem: Directory does not exist

Análise do problema: O diretório especificado não existe.

Solução: Crie o diretório e execute o comando de montagem novamente.

Erro de montagem: Directory is not empty

Análise do problema: O ossfs 2.0 exige que o diretório de destino da montagem esteja vazio, mas o diretório especificado contém arquivos.

Solução: Verifique se já existe outro sistema de arquivos montado nesse diretório. Em caso afirmativo, desmonte-o com o comando umount. Se não houver outro sistema de arquivos montado, remova quaisquer arquivos residuais do diretório. Alternativamente, monte em um diretório vazio diferente.

Erro de montagem: version FUSE_3.12' not found

Análise do problema: Arquivos de instalação obrigatórios estão ausentes. Isso faz com que o ossfs 2.0 recorra à biblioteca libfuse instalada no sistema, que está desatualizada.

Solução: Desinstale o pacote e reinstale-o.

Erro de montagem: Fuse device not found

Análise do problema: O dispositivo /dev/fuse não está acessível. Esse problema geralmente ocorre em ambientes de container sem as permissões de acesso necessárias.

Solução: Ao montar em um container, inicie-o em modo privilegiado.

Erro de gravação: File too large

Análise do problema: Por padrão, o ossfs 2.0 utiliza tamanho de parte de 8 MiB, o que suporta arquivos de até 78.125 GiB. Esse erro ocorre ao tentar gravar um arquivo que excede esse limite.

Solução: Ao montar um bucket, configure a opção upload_buffer_size para aumentar o tamanho máximo de arquivo suportado. Configurar upload_buffer_size consome mais recursos de memória. O ossfs 2.0 oferece a opção total_mem_limit para controlar o uso de memória. Para mais informações, consulte Opções de montagem.

Erro de gravação: Invalid argument

Análise do problema: O ossfs 2.0 não suporta gravações aleatórias. Ele aceita apenas gravações sequenciais que adicionam dados ao final do arquivo. Tentativas de gravar em qualquer posição que não seja o final atual do arquivo resultam no erro "Invalid argument". O log abaixo mostra um exemplo:

2025/04/14 11:00:39.307250|INFO |th=00007FEB88011870|fs.cpp:877|open file /fio/random-write-file.0.0
  nodeid: 5, flags: 32770, read_only: 0, truncate: 0, append: 0
2025/04/14 11:00:39.307551|ERROR|th=00007FEB88011DB0|file.cpp:294|append only file size: 0, offset: 63963136, write_off_: 0

Solução: Caso sua aplicação exija gravações aleatórias, use o ossfs 1.0. Em muitos casos, o que parece ser gravação aleatória é, na verdade, gravação concorrente no mesmo identificador de arquivo. Nesse cenário, adote gravações sequenciais em thread única. O ossfs 2.0 é otimizado para gravações sequenciais e oferece alto throughput com uma única thread.

Falha no git clone no destino de montagem

Análise do problema: Por padrão, o ossfs 2.0 não suporta leituras e gravações simultâneas no mesmo arquivo. Ler um arquivo durante a gravação pode retornar dados obsoletos ou causar erro de leitura. O comando git clone utiliza um padrão de acesso de leitura durante a gravação, o que pode gerar entradas de log semelhantes às seguintes:

2025/03/21 14:50:52.412572|ERROR|th=00007FE970FF4940|file.cpp:1385|src file /libfuse/.git/objects/pack/tmp_pack_PFRsQf read failed, read : -1, expectRead : 1048576, size_ : 4556308, offset : 0, errno: 2

No log, errno 2 corresponde ao código de erro Linux ENOENT, indicando que os dados do arquivo não foram lidos corretamente. Se encontrar erros de leitura com outras aplicações, procure mensagens similares nos logs. Quando uma operação de leitura falha sem retornar o erro "arquivo não encontrado", isso pode ocorrer porque a aplicação não fechou o arquivo, impedindo seu upload para o OSS.

Solução: Evite usar os comandos relacionados. Execute o git clone para um disco local e utilize o comando cp para copiar os arquivos para o destino de montagem.

Falha em gravações simultâneas no mesmo arquivo

Análise do problema: Quando múltiplos identificadores de arquivo estão abertos para o mesmo arquivo no ossfs 2.0, apenas um deles suporta gravações sequenciais. Operações de gravação de outros identificadores falharão. O log a seguir exemplifica esse erro:

2025/03/21 14:59:22.765822|ERROR|th=00007FE990006990|file.cpp:231|file 181 has already been written!

Solução: Evite gravações simultâneas no mesmo arquivo. O ossfs 2.0 é otimizado para gravações sequenciais, permitindo que uma única thread atinja alto throughput.

Erro de desmontagem: Target is busy

Análise do problema: Um processo que acessa arquivos no diretório de destino de montagem /mnt/ossfs2 está bloqueando a operação de desmontagem.

Solução:

1. Execute o comando lsof /mnt/ossfs2 para identificar os processos que acessam o diretório.

2. Interrompa o processo identificado.

3. Execute o comando de desmontagem novamente.

Múltiplos erros 404 nos logs

Informações de contexto: Entradas 404 Not Found são comuns nos logs do ossfs 2.0. Na maioria dos casos, não são erros do sistema, mas comportamentos esperados que permitem ao ossfs 2.0 emular a semântica de sistemas de arquivos locais.

Antes de executar uma operação em um arquivo, o sistema operacional verifica se o objeto de destino existe. Essa verificação pode gerar diversas requisições de sondagem ao OSS. Caso o objeto não exista, o OSS retorna o código de status 404.

Os passos a seguir descrevem o processo completo que o ossfs 2.0 utiliza para verificar a existência de um objeto:

1. Envia uma requisição GetObjectMeta para determinar se um caminho específico, como object, existe como um objeto real.

   Se o objeto existir, o sistema retorna seus metadados. Caso contrário, retorna um erro 404 e prossegue para a próxima etapa.

   Nota

   Mesmo que o objeto não exista, o ossfs 2.0 ainda precisa determinar se o caminho corresponde a um diretório.

2. Após receber um erro 404, envia uma requisição ListObjects para verificar se o caminho especificado é um 'diretório', ou seja, consulta objetos com o prefixo object/.

   Se o resultado for vazio, o caminho não existe. Se houver resultados, o diretório existe e o sistema lista seu conteúdo.

Análise do problema:

• Ao usar comandos como stat para acessar um arquivo inexistente, o sistema retorna um erro 404, mapeado para o erro "No such file or directory" do sistema de arquivos local.

• Antes de criar arquivos ou diretórios em lote, o sistema operacional verifica se os destinos já existem. A requisição de criação é enviada apenas se eles não existirem. Os erros 404 gerados durante essa verificação são comportamentos esperados e não indicam falha no sistema.

Solução: Embora os erros 404 sejam esperados, requisições de sondagem frequentes em cenários de alta concorrência ou operações em lote podem afetar o desempenho. Utilize as opções abaixo para otimizar a performance:

1. Aumente o valor de --attr_timeout para estender a duração do cache de metadados. O valor padrão é 60 s.

   Consultar um arquivo ou diretório antes que seus metadados expirem evita requisições repetidas ao OSS.

2. Configure --oss_negative_cache_size e --oss_negative_cache_timeout para ative o cache negativo.

   Quando um arquivo inexistente é consultado pela primeira vez, o resultado é armazenado em memória. Consultas subsequentes ao mesmo arquivo são atendidas pelo cache negativo local até sua expiração, evitando novas requisições ao OSS.

   • --oss_negative_cache_size: Quantidade de entradas no cache negativo para arquivos do OSS. O valor padrão é 10.000.

   • --oss_negative_cache_timeout: Tempo de expiração do cache negativo de arquivos do OSS. O valor padrão é 0.