TT Lab
ブログ

한국어 日本語

はじめる
ブログ

ブログ

よみがえるフラグと空っぽに見えるバケット: SeaweedFS weed miniのヘルプPRが動作変更につながった話

2026-10-16 · 16 分で読めます · #오픈소스#오픈소스 기여#SeaweedFS#오브젝트 스토리지#코드 리뷰#오픈소스 기여 기록

結果: マージ（2026-10-16、 seaweedfs/seaweedfs#11755). ）は実際にはGitHubのPR・レビューの原文、SeaweedFSのソース（PRのベースコミット 590a75b9）、TT Labリポジトリのコミット・ドキュメントの記録から取得しました。時刻は韓国時間です。2026-10-17時点でこの変更が含まれているリリースはまだありません（最新リリースは4.48、2026-09-28）。

目次

一言まとめ
PR seaweedfs/seaweedfs#11755 mini: note mini.options and Docker filer.toml pitfalls in help
変更内容 weed mini -h ヘルプの最後にNotesの11行を追加。コードの動作はそのまま
反応 3つのレビューボットが9分以内にレビューし、3つの指摘。メンテナーが動作を修正する #11758 を開いて先にマージ
結果 メンテナーが私たちのブランチにNotes修正コミットを追加して1つのコミットとしてマージ（私たちが著者、メンテナーが共同執筆者）
所要時間 PR公開 10-15 08:15 → マージ 10-16 10:44、約26時間半
기여 한 건의 흐름 — SeaweedFS #11755 의 경우 왼쪽은 매번 같은 단계, 오른쪽은 이번에 있었던 일(한국 시간) 1 운영 중 발견 플래그를 지워도 값이 되살아남(09-19) 복원한 사본의 버킷이 비어 보임(09-24) 2 실측·소스 확인 로컬에서 재현, mini.go 의 저장·적용 함수와 이미지의 filer.toml 을 읽음 3 패치 weed mini -h 에 Notes 11줄 동작은 바꾸지 않음, DCO 서명 4 PR 10-15 08:15 공개, 템플릿의 AI 체크 항목과 고지 문장을 채움 5 봇·리뷰 봇 셋이 9분 안에 지적 셋(포트 예외 등) 메인테이너가 #11758 로 동작을 고침 6 머지 10-16 10:44, Notes 를 새 동작에 맞춰 한 커밋으로(공동 저자 표기) 5번에서 우리가 답하기 전에 메인테이너가 먼저 움직였다
図：コントリビューション1件の流れと#11755で起きたこと

1. 何が問題だったのか：私たちが経験した現象

weed mini はSeaweedFSのマスター、ボリュームサーバー、ファラ、S3ゲートウェイを1つのプロセスで起動するモードです。TT Labのクラスターはこれを2つの場所で使っています。コミュニティ・ブログのメディアストレージ、そして本番DBのバックアップストレージです。バックアップストレージはもともとMinIOでしたが、MinIOがバイナリ・イメージの配布を終了したため、2026-09にSeaweedFSへ移行しました。

罠その1：削除したフラグが復活する（2026-09-19）

メディアストレージでボリュームの増設が止まり、原因は再起動を繰り返すうちに引き継がれたマスターのraft状態でした。シングルマスターなので維持すべき状態がないため、 -master.resumeState=false を付与して毎回新しく起動するようにしました。

ところがローカルでテストしてみたところ、この行をコマンドラインから 削除して 再起動しても、もう一度 false の状態で起動しました。miniがコマンドラインフラグをデータディレクトリの mini.options ファイルに書き込み、次回の起動時に再び読み込むためでした。マニフェストには「元に戻すときにこの行を削除するな」というコメントを残しました。 weed mini -h のどこにもこのファイルについての記載はありませんでした。

罠その2：復元したコピーのバケットが空っぽに見える（2026-09-24）

バックアップは復元できてこそバックアップです。バックアップストレージのデータディレクトリをNASにコピーした複製に対して同じイメージでminiを起動し、復元テストを行いました。複製をコンテナの別のパスにアタッチし、 -dir をそのパスに指定したところ、 2つのバケットしか見えずオブジェクトが0個でした。エラーは発生しませんでした。複製を /data にアタッチしたときは、MinIOから移行してきた10,004個のオブジェクトがキー、サイズ、SHA-256に至るまでコピー時と同じように読み込めました。

どちらの件も「設定を間違えた」のではなく、「ツールが教えてくれないルールが存在した」というケースでした。このような罠には、次に触る人も同じように引っかかります。

2. 原因：ソースのどの行か

以下の行番号はすべてPRのベースコミット 590a75b9 を基準としています。TT Labが使用していたバージョン4.29でも同じ関数の内容が同じでした（タグ4.29の mini.go を開いて比較）。

weed mini 의 두 함정 ① mini.options — #11758 이전 기동 1 -master.resumeState=false mini.options 에 기록 resumeState=false 기동 2: 줄을 지움 값 true = 기본값 저장된 false 를 다시 적용 오류도 안내도 없음 기준은 「명령줄에 줬나」가 아니라 「지금 값이 기본값인가」 ② #11758 이후 명령줄 플래그는 저장하지 않고, 늘 저장값을 이긴다 계산한 값(볼륨 상한)만 고정, 적용하면 기동 때 한 줄 출력 ③ 공식 이미지의 filer.toml -dir=/restore 사본을 붙인 곳 볼륨 파일 사본에 그대로 있음 /etc/seaweedfs/filer.toml dir = /data/filerldb2 파일러 메타데이터 /data 의 빈 새 저장소 버킷은 보이는데 객체는 0개, 오류 없음
図：weed miniの2つの罠と#11758適用後の様子

mini.options：「コマンドラインで渡したか」ではなく「デフォルト値と同じか」

そのため、 -master.resumeState=false を一度でも指定するとファイルに残り、その行を削除して次に起動したときは値がデフォルトの true であるため、ファイルの false が再度適用されます。コマンドラインに =true を 明示しても デフォルト値と同じなので結果は同じになります — ポートフラグを除いて。私たちがマニフェストに残した「行を削除せず =true に変更すること」というコメントも、ソースの仕様通りにいえば通用しないアドバイスです（ソースを読み解いた結果であり、実測はしていません）。しかもminiはデフォルトのログ出力を抑制するため、「保存されたオプションを適用した」というメッセージ（V(2)）はデフォルト設定では表示されません。

filer.toml：イメージがメタデータの場所を固定してしまう

その結果、ボリュームファイルは -dir に、filerのメタデータは /data/filerldb2 に送られます。 -dir を別の場所に移動し、その場所だけを残しておくと、メタデータはコンテナと一緒に消滅します。私たちの復元テストで2つのバケットが見えたのは、起動フラグ -bucket が空のメタデータの上にバケットを新しく作成したためだと推測されます（ソースのバケット作成コードとマニフェストのフラグからの解釈）。

3. 何を変更したのか：diffの要点

コードには手を加えず、 cmdMini の Long のヘルプの最後にNotesを追加しました。最初に送信したバージョンの要点です。

+Notes:
+- Flags are saved to <dir>/mini.options and applied again on the next
+  start to every flag that is not given on the command line. Removing a
+  flag, or passing it with its default value, does not restore the
+  default on the next start. Edit or delete mini.options instead.
+- The official Docker image ships /etc/seaweedfs/filer.toml, which keeps
+  the filer metadata in /data/filerldb2 regardless of -dir. If you set
+  -dir to another path, keep /data on a persistent volume as well.
+  ...

ヘルプのみを修正した理由は2つあります。動作を変更するのはメンテナーが判断すべき設計上の問題であり、外部コントリビューターの最初のPRは小さく検証しやすいものでなければ受け入れられやすいためです。SeaweedFSのPRテンプレートには「AIで作成したPRはすべての行をレビューし最小限に抑えた」というチェック項目があり、両方を満たした上で、本館の最後にAIの助けを借りて作成し自身でレビューしたという一文を記載しました。コミットにはDCO署名（Signed-off-by）とSSH署名を付与しました。テストは gofmt と上記の関数をソースベースで比較したことがすべてであると、本文にそのまま記載しました。

4. ボットとメンテナーはどのように反応したか

9分以内にやってきた3つのボット

PRを開いてすぐ（10-15 08:16–08:24）にDevin、CodeRabbit、Greptileの3つのレビューボットが参加しました。公開された指摘は3つで、すべて最初のNoteに関するものでした。

第2節のソースをもう一度見ると、ボットの指摘が正しかったです。私たちの文章は一般的なフラグには当てはまりますが、8つのポートには当てはまりませんでした。例外リスト（portFlagNames）を読んだにもかかわらず、文章に反映させ忘れていたのです。

私たちが返答する前にメンテナーが動いた

率直に言って、これらの指摘に対して私たちは1日の間、返答も修正もしませんでした。その間（10-15 23:15）にメンテナーが私たちのPRに言及し、 #11758 を開きました。問題の定義は私たちのPRが記述した2つの罠そのままであり、解決策はヘルプではなく動作そのものの修正でした。

#11758が10-16 10:36にマージされ、その3分後にメンテナーは私たちのブランチにNotesを新しい動作に合わせて修正したコミットを追加しました。1つ目のNoteには「コマンドラインフラグは保存されず常に保存された値を上書きする、保存されるのは計算値のみ」、2つ目のNoteには「-dir の外にある場合、起動時に警告を発する」が追加されました。コメントでは、この変更のおかげでデフォルト値の比較やポートの例外を指摘していたボットの指摘がもはや該当しなくなったと整理されました。

ボットの2度目の指摘と順序の説明

新しいコミットに対してGreptileが再び2つの指摘を行いました。「ソースにはコマンドラインフラグを保存するコードがある」、「-dir の外側を検査するコードがない」。ボットは#11758以前のコードを参照していました。メンテナーが2つの行コメントのそれぞれに「このPRは#11758の後の順序であり、そのPRが保存を廃止し検査を追加する」と返答し、ボットは1分も経たずに2つの指摘を取り下げました。そして10:44にマージされました。

マージは2つのコミットを1つにまとめるsquashであり、コミットの著者は私たちのアカウント、メンテナーは Co-authored-by として記録されました。最終的なヘルプ13行のうち、私たちが書いた文章がそのまま残ったのは2つ目のNoteの大半であり、1つ目のNoteはメンテナーが新しい動作に合わせて書き直しました。

5. 学んだこと：オープンソースコントリビューションのコツ

TTの一言。 ヘルプに「ここに穴があります」と貼り紙をしたら、管理人がやってきて穴を塞いでしまいました！それでも看板は残しておいてくれたそうです。ボットから「看板の文字が少し間違っています」と言われたら、翌日ではなくその日のうちに書き直すことにしました。

リンク

すべての資料は2026年10月17日に閲覧しました。

ログインするといいねできます

コメント

まだコメントはありません。

ログインするとコメントできます