Object Storage Service:ossfs 2.0 よくある質問

マウントエラー：Failed to mount ossfs2

原因：一般的なエラーです。詳細はログで確認してください。このエラーは、通常、権限の誤りまたは設定パラメーターが無効なことが原因で発生します。例：

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

使用している AccessKey には、バケットにアクセスするための権限が不足しています。お使いの AccessKey に必要な権限があること、およびバケット名が正しいことを確認してください。

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

設定した AccessKey が無効です。

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

解決策：ログのエラーメッセージに基づいて設定を修正し、再度マウントしてください。

マウントエラー：Directory does not exist

原因：指定したディレクトリが存在しません。

解決策：ディレクトリを作成してから、マウントコマンドを再実行してください。

マウントエラー：Directory is not empty

原因：ossfs 2.0 では、マウントターゲットとして空のディレクトリを必要としますが、指定されたディレクトリは空ではありません。

解決策：別のファイルシステムがすでにそのディレクトリにマウントされていないか確認してください。マウントされている場合は、umount コマンドでファイルシステムをアンマウントしてください。別のファイルシステムがマウントされていない場合は、ディレクトリ内の残存ファイルを削除してください。別の空のディレクトリにマウントすることもできます。

マウントエラー：version FUSE_3.12' not found

原因：必要なインストールファイルが不足しているため、ossfs 2.0 がシステムにインストールされている libfuse ライブラリにフォールバックしますが、このライブラリが古いためです。

解決策：パッケージをアンインストールし、再インストールしてください。

マウントエラー：Fuse device not found

原因：/dev/fuse デバイスにアクセスできません。この問題は通常、必要なアクセス権限がないコンテナ環境で発生します。

解決策：コンテナでマウントする場合は、特権モードで起動してください。

書き込みエラー：File too large

原因：デフォルトでは、ossfs 2.0 は 8 MiB のパートサイズを使用しており、最大 78.125 GiB のファイルサイズをサポートします。この上限を超えるファイルを書き込むと、このエラーが発生します。

解決策：バケットをマウントする際に、upload_buffer_size オプションを設定して、サポートされる最大ファイルサイズを増やすことができます。upload_buffer_size を設定すると、より多くのメモリが必要になります。ossfs 2.0 は、メモリ使用量を制御するためのtotal_mem_limit オプションをサポートしています。詳細については、「Mount options」をご参照ください。

書き込みエラー：Invalid argument

原因：ossfs 2.0 はランダム書き込みをサポートしていません。ファイル末尾へのデータ追記のみを行うシーケンシャル書き込みのみをサポートします。現在のファイル末尾以外の位置に書き込むと、ossfs 2.0 は "Invalid argument" エラーを返します。次のログはその例です：

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

解決策：アプリケーションでランダム書き込みが必要な場合は、ossfs 1.0 に切り替えてください。多くの場合、ランダム書き込みに見える動作は、実際には同一のファイルハンドルに対する同時書き込みです。その場合は、シングルスレッドでのシーケンシャル書き込みに切り替えてください。ossfs 2.0 はシーケンシャル書き込み向けに最適化されており、単一スレッドで高いスループットを提供します。

マウントターゲットでgit cloneが失敗する

原因：デフォルトでは、ossfs 2.0 は同一ファイルに対する同時読み取りと書き込みをサポートしていません。書き込み中にファイルを読み取ると、古いデータが返されるか、読み取りエラーが発生する可能性があります。git clone コマンドは read-while-write のアクセスパターンを使用するため、次のようなログが出力される場合があります：

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

ログ内の errno 2 は Linux のエラーコード ENOENT であり、ファイルデータの読み取りに失敗したことを示します。他のアプリケーションで読み取りエラーが発生する場合も、ログで同様のメッセージがないか確認してください。これとは別に、読み取り処理が "file not found" エラーを返さずに失敗する場合、アプリケーションがファイルをクローズしていないために OSS へのアップロードが完了していないことが考えられます。

解決策：関連するコマンドの使用を避けてください。git clone はローカルディスクに対して実行し、その後cp コマンドでファイルをマウントターゲットにコピーしてください。

同一ファイルへの同時書き込みが失敗する

原因：ossfs 2.0 で同一ファイルに対して複数のファイルハンドルが開かれている場合、シーケンシャル書き込みを行えるハンドルは1つのみです。他のファイルハンドルからの書き込みは失敗します。次のログはエラーの例です：

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

解決策：同一ファイルへの同時書き込みを避けてください。ossfs 2.0 はシーケンシャル書き込み向けに最適化されており、単一スレッドで高いスループットを提供します。

アンマウントエラー：Target is busy

原因：/mnt/ossfs2 のマウントターゲットディレクトリ内のファイルにアクセスしているプロセスがあり、アンマウント処理がブロックされています。

解決策：

1. lsof /mnt/ossfs2 コマンドを使用して、当該ディレクトリにアクセスしているプロセスを特定します。

2. プロセスを停止します。

3. アンマウントコマンドを再実行します。

ログに多数の404エラーが出力される

背景：ossfs 2.0 のログでは、404 Not Found のエントリが頻繁に出力されます。多くの場合、これはシステムエラーではなく、ossfs 2.0 がローカルファイルシステムのセマンティクスをエミュレートするために必要な想定動作です。

ファイルに対する操作を実行する前に、オペレーティングシステムは対象オブジェクトが存在するかどうかを確認します。この確認により、OSS に対して多数のプローブリクエストが発生する場合があります。オブジェクトが存在しない場合、OSS は 404 ステータスコードを返します。

次の手順は、ossfs 2.0 がオブジェクトが存在するかどうかを確認するために使用する一連の処理を示しています：

1. GetObjectMeta リクエストを送信し、object などの指定パスがオブジェクトとして存在するかどうかを確認します。

   オブジェクトが存在する場合は、メタデータが返されます。オブジェクトが存在しない場合は 404 エラーが返され、次の手順に進みます。

   説明

   オブジェクトが存在しない場合でも、ossfs 2.0 は当該パスがディレクトリかどうかを判定する必要があります。

2. 404 エラーを受け取った後、ListObjects リクエストを送信し、指定パスが「ディレクトリ」であるかどうか、つまりプレフィックスが object/ のオブジェクトを照会します。

   結果が空の場合、そのパスは存在しません。結果が空でない場合、ディレクトリが存在し、システムはその内容を一覧表示します。

原因：

• stat などのコマンドで存在しないファイルにアクセスすると、システムは 404 エラーを返します。これはローカルファイルシステムの "No such file or directory" エラーに対応します。

• ファイルまたはディレクトリを一括作成する前に、オペレーティングシステムは対象のファイルまたはディレクトリが存在するかどうかを確認します。存在しない場合にのみ作成リクエストを送信します。この確認中に生成される 404 エラーは想定動作であり、システム障害を示すものではありません。

解決策：404 エラーは想定動作ですが、高い同時実行性やバッチ処理のシナリオでプローブリクエストが頻発すると、パフォーマンスに影響する可能性があります。次のオプションを使用してパフォーマンスを最適化できます：

1. --attr_timeout を増やして、メタデータキャッシュの保持時間を延長します。デフォルトは 60 秒です。

   メタデータの有効期限が切れる前にファイルまたはディレクトリを照会すると、OSS へのリクエストの繰り返しを回避できます。

2. --oss_negative_cache_size と --oss_negative_cache_timeout を設定して、ネガティブキャッシュを有効にします。

   存在しないファイルを初回に照会した際の結果がメモリにキャッシュされます。同じファイルへの後続の照会は、有効期限が切れるまでローカルのネガティブキャッシュから返されるため、OSS への追加リクエストを回避できます。

   • --oss_negative_cache_size：OSS ファイルのネガティブキャッシュに保持するエントリ数です。デフォルト値は 10,000 です。

   • --oss_negative_cache_timeout：OSS ファイルのネガティブキャッシュのタイムアウトです。デフォルト値は 0 です。