seaweedfs

SeaweedFS

このスキルは、上流リポジトリと Wiki を参考に、SeaweedFS のデプロイと運用を実践的に案内します。

weed mini の簡易手順よりも、複数コンポーネントを使った構成に関する本番環境向けのガイダンスを優先してください。

クイックナビゲーション

状況	開く
システムの構成とブートストラップの手順を把握する	references/getting-started.md
ローカルのオールインワンサンドボックスを立ち上げる	references/quick-start-mini.md
コントロールプレーン、ボリューム、コレクションのトポロジーを確認する	references/topology-and-setup.md
master、volume、filer、client の API サーフェスを確認する	references/api-surfaces.md
レプリケーション、TTL、フェイルオーバー用 master、環境変数を設定する	references/configuration.md
パフォーマンスに関する注記、FAQ のトピック、例を確認する	references/benchmarks-and-use-cases.md
filer のメタデータ、アップロード、JWT、TUS を扱う	references/filer-core.md
filer のメタデータストアを選択してスケールする	references/filer-stores.md
S3 バケット、認証、IAM/OIDC を運用する	references/s3-gateway.md
Cloud Drive とリモートストレージのマウントを計画する	references/cloud-drive.md
バックアップ、メトリクス、修復、シェルのワークフローを実行する	references/backup-and-replication.md, references/operations.md
S3 の暗号化とクライアントツールを選択する	references/encryption.md, references/s3-client-tools.md
トランスポート、JWT、TLS、公開範囲の制御を確認する	references/security.md

使用する場面

• SeaweedFS のデプロイを計画するとき
• 開発環境または本番環境で weed コンポーネントを実行するとき
• filer、S3、クラウド階層のトポロジーを設計するとき
• メタデータストアとレプリケーションパターンを選択するとき
• 公開利用またはマルチテナント利用に向けて SeaweedFS を堅牢化するとき
• バックアップ、メトリクス、クラスター修復のワークフローを運用するとき

基本的なメンタルモデル

• SeaweedFS は、ボリューム管理とファイルおよびオブジェクトへのアクセス経路を分離します。
• filer レイヤーは、ディレクトリ、メタデータストア、高レベルのプロトコルを追加します。
• S3、WebDAV、FUSE などのインターフェースは、同じストレージサービス上に設けられた入口です。
• 本番環境のデプロイでは、トポロジー、認証情報、永続化、監視、復旧手順を明確に文書化してください。

リリースのハイライト（4.48）

• S3 の信頼できるプロキシ（aws:SourceIp）：security.toml で設定できる許可リストにより、なりすましの脆弱性を再び生じさせることなく、転送ヘッダーをサポートします。直接の TCP ピアが許可リストに含まれる場合は、X-Forwarded-For を右から左へ（続いて X-Real-Ip を）たどって aws:SourceIp を決定します。それ以外の場合は、直接のピアアドレスを使用します。バケットポリシーエンジン、IAM アタッチドポリシーエンジン、IAM ロール／セッションポリシーミドルウェアに適用されます。references/s3-gateway.md と references/security.md を参照してください。
• 管理者バインドのデフォルト：-adminPassword または [https.admin] の mTLS が設定されている場合、-ip のデフォルトは自動的に 0.0.0.0 に切り替わります。認証のないデプロイではループバックがデフォルトのままで、明示的に指定した -ip は常に優先されます。管理者のワーカー／プラグイン gRPC コントロールプレーンも -ip を尊重するようになり、すべてのインターフェースにワイルドカードバインドすることはなくなりました。
• リモートストレージと階層化におけるマルチパートの並行処理：upload_concurrency／download_concurrency は、リモートストレージごと（remote.configure -upload_concurrency／-download_concurrency）および master.toml の S3 バックエンドごとに設定できます。volume.tier.upload|download|move|evict は -concurrent フラグを受け付けます。0／未設定の場合は、従来のデフォルト（S3 ではアップロードパートが 1、ダウンロードパートが 5）が維持されます。references/cloud-drive.md を参照してください。
• S3 の正確性：ListMultipartUploads が Initiated タイムスタンプを返すようになりました（繰り返しのリスト取得では元の時刻が保持されます）。POST ポリシーによるアップロードではオブジェクトのバージョンが保持され、オブジェクトのバージョン削除時にはオブジェクトロックの保持期間が適用されます。Object Lock の設定とオブジェクトロックのアクションは別々に認可されます。プレフィックスより前にソートされるリストマーカーは何も除外しません。エラーレスポンスを返す前にリクエストボディが読み取られ、マルチパート完了時にはアップロードの確定と .uploads の削除がアトミックに実行されます。
• Helm：生成される読み取り専用の S3 ID に List が付与され、マスター設定の変更時にマスターポッドがロールし、admin.allowInsecureBind が管理者認証のレンダリングガードを満たすようになりました。
• Filer：受け入れ済みのメタデータログレコードはシャットダウン後も保持され、メタデータストアが閉じる前にシャットダウン処理の完了を待つようになりました。Filer 独自の disableHttp フラグが追加され、マニフェスト解決時のエラー伝播も整理されました。
• シェル：fs.verify -pruneEntries は、ニードルが失われたエントリーを削除します。また、fs.mergeVolumes は、ソースに孤立したニードルしかない場合に警告します。
• Rust ボリューム：tonic／prost 0.14、ストアのロックを解放しながら行うテールスキャンのストリーミング、8～15 個の引数を取る関数のパラメーター構造体への統合、Windows ビルドの修正。
• Enterprise：新しい KVCache サブシステムが追加されました。これは LLM 推論における KV キャッシュの階層化を目的とした、LMCache 対応の KV キャッシュサービスで、コレクションごとの書き込み並行数と上限付きのクリーンアップメモリを備えています。

リリースの主な変更点（4.41 → 4.45）

• S3 の書き込みパス：大きなチャンクリストは直接書き込みパスでマニフェストチャンクにまとめられ、オブジェクト単位およびマルチパート完了時のアップロードでは filer の maxMB に従ってチャンク化されます。ストレージクラスはキャッシュされた一覧メタデータに保持され、バケットポリシーの書き込みにはバケットポリシーアクションが必要になりました。RenameObject が追加され、アップロード時のバケット自動作成を無効にできるようになり、バージョニング停止中の処理と null 削除マーカーの処理が強化されました。
• IAM／STS の成熟度向上：ドキュメント形式のポリシーを高度な IAM 設定から読み込めるようになり、アタッチされたポリシーから許可されているバケットを一覧表示できます。管理者のロールセッションはそのロールの範囲内に保たれ、IAM 管理アクションは IAM アクションとして認可されます。また、管理 UI にビジュアル IAM ポリシーエディターとバケットポリシー管理機能が追加されました。
• マスター／トポロジーのハートビートダイジェスト：ボリュームのハートビートにダイジェストが含まれ、変更されたボリュームのみを送信することで、変動が続いてもマスターの情報を最新に保ちます。ホットパスでのアロケーションとコピーを削減してメモリの変動を抑え、ボリューム一覧のストリーミングに対応しました。
• イレイジャーコーディングの整理：エンコード、デコード、シャード移動は、中断後にロールバックまたは再開して整合性のある状態に戻るようになりました。ec.balance に -volumeIds フィルターが追加され、EC ライフサイクルを検証するカオスハーネスも追加されました。
• Filer：チャンクセットの書き込み条件を指定できる条件付き UpdateEntry、ディレクトリの変更履歴を監査する filer.meta.scan が追加されました。TUS では最大サイズとセッション有効期限を設定でき、連結拡張にも対応しました。非再帰的に削除されたフォルダーが子要素まで削除することはなくなりました。
• 管理／ワーカー：カタログを維持する Rust プラグインワーカーを備えた Lance カタログが追加されました。seaweed-worker はヘルス、レディネス、メトリクスを提供し、管理画面にはティアごとの容量が表示されます。また、バケットのライフサイクルルールを管理 UI で編集できるようになりました。
• コア：レプリケート／EC シャード／ワーカーの移動にスループット制限が追加されました。Range リクエストは、範囲が重なる部分がない場合にのみ 416 を返し、開始オフセットがファイルサイズと等しい場合は拒否されます。FUSE マウントが Windows（WinFsp）に対応しました。

リリースの主な変更点（4.40）

• S3 の正確性：コピー元が存在しない場合の CopyObject は、誤解を招くエラーではなく NoSuchKey／NoSuchBucket を返すようになりました。CopyObject の無効なタグ付けは InvalidTag を返します。ネストされたキーに対する PutObjectAcl とオブジェクトタグの書き込みは正しいオブジェクトを対象とし、クエリ文字列内の未エスケープのセミコロンを受け付けるようになりました。
• IAM／OIDC の強化：正式な AssumeRoleWithWebIdentity フローだけでなく、OIDC ベアラートークンによる直接リクエストでもロールの信頼ポリシーが適用されるようになりました。
• Filer／TUS のセキュリティ：TUS の再開可能なアップロードセッションの認可が強化され、HEAD／PATCH／DELETE はセッション固有のターゲットパスに制限されます。これにより、プレフィックスをまたいだアクセスの抜け穴が塞がれました。filer.backup は一時的な not-found エラーでデータを黙って失うことがなくなり、生成された vtproto マーシャラーによりログバッファーのフラッシュが最適化されました。
• イレイジャーコーディング：新しい ec.check.replication シェルコマンドが追加されました。ec.encode は、自ら追加した新しいシャードより古いトポロジースナップショットに基づいて再バランスを行わなくなり、シャードの破棄時には古い .ecsum チェックサムサイドカーが削除されます（Go／Rust で動作を統一）。
• シェル／管理：volume.tier.upload は既存のレプリカを維持するようになりました。volume.check.disk に -resurrectMissingNeedles が追加され、weed shell では現在のクラスターのロック保持者が表示され、cluster.ps では S3 サーバーが一覧表示されます。
• コア：マスターの使用済みサイズ統計がすべてのコレクションを対象とするようになりました。Rust ボリュームサーバーは、最後にインデックスされた needle に対して .dat の整合性を検証し、マウントは無期限に待機する代わりに ENOSPC を通知します。

リリースの主な内容（4.25）

• セキュリティ／管理者向けパス：4.24～4.25 では、破壊的操作や管理者向けのエンドポイントで管理者認証を強化し、filer IAM gRPC 呼び出しに管理者署名付き認証を付与することで、security.toml 使用時の管理 UI の動作を修正しました。
• イレイジャーコーディング／マルチディスク運用：このリリース系列では、マルチディスクおよびサーバー間の構成における EC プランナーとリカバリーの複数のケースを修正しました。古いシャードのクリーンアップや、ソースボリュームをより安全に削除する処理も含まれます。
• S3／IAM の強化：ポリシーのない IAM ユーザーは、暗黙的に過剰な権限を付与されるのではなく、アクセスを拒否されるようになりました。また、OIDC／ウェブ ID と監査機能も引き続き改善されています。

リリースの主な内容（4.26 → 4.28）

• イレイジャーコーディング／マルチディスク運用：EC のプランニングでディスク間にシャードをより確実に配置するようになり、実行計画に disk_id が含まれるようになりました。また、リカバリー時にローカルシャードから失われた .ecx／.vif メタデータを再構築できます。
• 整合性チェック：スクラビング／fsck の処理でサイズがゼロのボリュームも考慮するようになり、これらを黙ってスキップしなくなりました。これは、スパースなトポロジーや作成直後のトポロジーで重要です。
• Filer バックエンドの信頼性：Redis3 でスキップリストの末尾に関するパニック経路を回避し、SQL ベースの filer ストアでアイドル接続プーリングを強制的に無効化しなくなりました。
• S3 監査証跡：GET／HEAD／IAM 操作でリクエスターの ID がより一貫して設定されるようになり、コンプライアンス対応とインシデントのトリアージが改善されます。
• HA ハートビート経路：フォロワーレプリカ上のボリュームサーバーの ping ターゲットをマスターが受け入れるようになり、マルチマスター構成でのフェイルオーバーの可視性が向上します。

リリースの主な内容（4.34 → 4.39）

• S3 の正確性／コンプライアンス：マルチパートコピーのチェックサム保持、アカウントを持たない ID への admin ではなく個別の所有者の割り当て、SigV4 のクエリ値のソート、Range オフセットの検証、タグ値に含まれる等号の保持、静的設定ファイルのホットリロードを追加しました（4.34～4.36）。
• Iceberg／S3 Tables：ネームスペースプロパティの更新、テーブル登録、複数テーブルのトランザクションコミット、ビューのサポート、テーブル名の変更、呼び出し元のスコープに基づく S3 Tables 認可に対応しました（4.36）。
• IAM／STS：ロールの信頼ポリシーによる AssumeRole の認可、STS セッションポリシーにおける明示的な拒否の適用、リソースポリシーの ABAC で使用する OIDC グループ／ロールの公開に対応しました（4.36）。
• ボリュームサーバーのクラッシュ安全性：起動時に復旧可能な EC シャードを削除しないようにし、永続的な .cpc マーカーを用いたクラッシュ安全なコンパクションのコミットを実装しました。また、削除済みでありながら開いたままのディスクリプターに対するファントムボリュームの検出を追加しました（4.34～4.35）。
• イレイジャーコーディングの正確性（Rust との同等性）：EC スクラブの改善、EC のストレージ／読み取り経路の修正、Rust ボリュームサーバーのスクラブ機能の同等性に加え、S3 CRC チェックサムに対応しました（4.38）。
• FUSE マウント：同時書き込みに対するライトバック許容時間枠での書き込みパターン検出と、非 root ユーザーによるアクセスを高速化する補助グループ ID のキャッシュに対応しました（4.35）。
• パフォーマンス／可観測性：プロファイリングとスループットベンチマークを伴うパフォーマンス CI、Rust ボリュームサーバーのストリーミング最適化、管理ダッシュボードのネイティブなスパークライン傾向グラフとバケットごとの S3 メトリクスを追加しました。また、大容量のコールド GetObject がハングするのではなく 503 を返すようになりました（4.34～4.37）。
• 運用：EC シャードコピーでの非同期バッファー付き書き込み、ボリューム階層化と filer メタデータの最適化、論理サイズに基づく S3 クォータの測定、マウントフェイルオーバーの強化を追加しました（4.39）。

リリースの主な内容（4.31 -> 4.33）

• S3 のバージョニング／IAM：バージョン管理された PutObject のアトミックなコミット、適切な NoSuchVersion エラー、最新ポインターの修復と復旧、一時停止中のバージョニングにおける削除処理、管理対象 IAM ポリシーのバージョン、およびバケットの読み取り専用クォータの適用に対応しました。4.33 ではさらに、HTTP 日付条件、チェックサムのトレーラーヘッダー、空の v4 署名付きヘッダー名に関する問題を修正しました。
• イレージャーコーディングの整合性：ビット腐敗検出用のシャードごとのチェックサムサイドカー（4.31）、マシン間でシャードを均等に分散し、同じマシン上のサーバーを単一の障害ドメインとして扱う処理と、削除前のシャード配置検証（4.32）、および異なるエンコード実行の EC シャードが混在したり、再起動時に偽の .dat が残ったりするのを防ぐガード（4.33）に対応しました。
• ボリュームサーバー：自動サイズ設定ディスクでの maxVolumeCount のデッドゾーンを修正し、削除末尾の圧縮後もボリュームを書き込み可能な状態に維持し、再起動時に .vif から EC データシャード数を解決するようにしました（4.31）。さらに、ディスクの健全性を検出する CheckDisk を追加しました（4.32）。
• Filer のスケーラビリティ：BFS メタデータのメモリ使用量に上限を設け、S3 の一覧表示順をバイト単位の辞書順にしました（4.31）。メタデータサブスクリプションのログファイルをストリーミング処理するようにしました（4.32）。また、オブジェクトサイズ分布のメトリクス、マウント再接続時の OOM 修正、チャンクごとのリプレイ、上限付きフラッシュキュー、Elasticsearch 8（elastic8）のサポートを追加しました（4.33）。
• 管理／ワーカー：レーンを考慮したスケジューラーのプルーニング、永続化された状態に対する -dataDir のデフォルト設定、起動時の実行中タスクの再読み込み（4.32）に加えて、クラスター内の全ボリューム一覧を JSON でエクスポートできるようにしました（4.33）。
• Rust ボリュームサーバー：負荷時の OOM を防ぐため、リクエストボディと保存コンテンツの展開に上限を設けました（4.31）。さらに、EC シャードの削除後、再起動時に偽の .dat が残る問題を修正しました（4.33）。

リリースの主な内容（4.29 -> 4.30）

• S3 の書き込み／認証パス：オブジェクト書き込みを Filer 側の所有者ルーティングと ObjectTransaction バッチに移行し、分散ロックの負荷を軽減しました。4.30 ではさらに、パストラバーサルの拒否、所有権制御の検証、MetadataDirective=REPLACE、署名なしストリーミングアップロードにおける JWT の処理を強化しました。
• FUSE と Filer の連携：POSIX アドバイザリロックを -dlm 使用時に Filer の所有権経由でルーティングするようになりました。セッションリース、キープアライブ、リング変更時のクールダウン、マウントをまたぐ書き込みワークロードにおけるライトバックキャッシュのクラッシュ問題も修正しました。
• イレージャーコーディングとボリューム修復：EC の配置で共通の ecbalancer.Place パスと配置スナップショットを使用するようになりました。一方、4.30 では信頼できるレプリカの選択、空のスタブのクリーンアップ、.vif の保持、バキューム後の書き込み可能ボリューム通知が改善されました。また、読み取り専用状態のまま停滞したボリュームやマージ検証に関するシェルの安全性も向上しました。
• 運用インターフェイス：管理機能で Prometheus メトリクスを公開するようになりました。また、S3／IAM／ボリューム／Filer／Master の各プロセスに、オーケストレーションのチェック用として /healthz と /readyz のプローブを追加しました。
• Filer、同期、リモートシンク：Redis2 が KV メソッドで keyPrefix を適用するようになりました。Postgres Filer の書き込みはデフォルトで ON CONFLICT アップサートを使用し、検出対象から削除済みの Filer を除外します。また、同期／リモートストレージのパスで、チャンクサイズ、マニフェスト、オフセット、MIME メタデータをより確実に保持するようになりました。

リリースの主な内容（4.20）

• S3／IAM：組み込み IAM フローに ListUserPolicies、グループのインラインポリシー操作、より安全なユーザーポリシーの往復処理、DeleteBucket 時のバケット単位のクリーンアップを追加しました。
• マウント／FUSE：weed mount にマウント間の書き込み調整用 -dlm を追加し、POSIX メタデータの動作、nlink のカウント、Filer RPC の効率を改善しました。
• Master の配置：ボリュームの割り当てでサイズをより考慮するようになりました。読み取り専用への移行時にまず保留中のサイズ変更を処理するようになり、一部の DC／ラック構成で無限に増加する原因となるトポロジーのバグを修正しました。
• Filer の信頼性：PgBouncer／Postgres との互換性を改善し、正常なシャットダウン時の破損を修正しました。また、メモリ／CPU の性能低下を招いていた Filer の冗長なディスク読み取りを削除しました。
• 運用インターフェイス：weed shell にグループ管理用ヘルパーを追加し、S3 ユーザーのプロビジョニングで既存ユーザーをより安全に処理するようになりました。また、Master／ボリュームで start_time_seconds メトリクスをエクスポートするようになりました。

禁止事項

• 本番環境では weed mini を使用しないでください。
• 単一バイナリのデフォルト設定を、本番環境で安全な構成として扱わないでください。
• 認証、TLS、ネットワーク境界を確認する前に、S3 や filer のエンドポイントを公開しないでください。
• HA、スケーリング、バックアップの特性を検証せずに、filer ストアを選択しないでください。
• 復元の検証を行わずに、バックアップやレプリケーションのフローを設計しないでください。

リンク

• ドキュメント
• リリース
• GitHub
• Docker Hub