ref-macker-storage

ref-macker-storage — hub 共有ストレージ

macker の hub (collector, HTTP :4478) が持つファイル置き場。実体は hub の <DataDir>/storage/ のただのファイルツリーで、tailnet のどのノードからも 同じ CLI で読み書きできる。「どこか 1 箇所に置けば全マシンから見える」が用途 (成果物・スクショ・設定ファイルの受け渡し)。

CLI

macker storage ls [prefix] [--tag <t>]   # 一覧 (KEY/SIZE/MODIFIED/TAGS)。prefix は前方一致
macker storage find <token>...           # 検索 — key+タグ+note の AND 部分一致 (大文字小文字無視)
macker storage put <local> [key] [--tag a,b] [--note "…"]  # アップロード (上書き可・atomic)
macker storage get <key> [dest|-]        # ダウンロード (dest 省略 = basename、"-" で stdout)
macker storage cat <key>                 # stdout へストリーム (パイプ用)
macker storage tag <key> +a -b [--note "…"|--clear-note]   # タグの付け外し・note 置換
macker storage info <key>                # メタ全表示 (sha256/uploader/source/タグ/note)
macker storage rm <key>                  # 削除 (空になった親フォルダは自動で消える)

メタデータ (タグ・note・sha256・アップロード元) は hub 側の sidecar に自動保存され、 find / --tag / dashboard の検索ボックスから探せる。note 単独の再 put でタグは消えない。

# 例: スクショを hub 経由で別マシンへ
machine-a$ macker storage put ./shot.png shots/2026-06-11/shot.png
machine-b$ macker storage get shots/2026-06-11/shot.png

# 読みはパイプ OK (書きは実ファイルのみ — stdin を渡したい時は一旦ファイルに落とす)
macker storage cat logs/run.txt | grep ERROR

前提と認可

• collector の URL が必要: config の collector か環境変数 MACKER_COLLECTOR (例 http://100.x.y.z:4478)。未設定だと no collector configured エラー。
• 読み (ls/get/cat) = tailnet の認証済みピアなら可 / 書き・削除 (put/rm) = owner か exec_allow のみ。hub マシン上では loopback token (<DataDir>/agent.token) で常に full 権限。

key の規約

• / 区切りの相対パス (docs/readme.md のように擬似フォルダになる)
• 禁止: 先頭/末尾 /、.・.. セグメント、\、制御文字、.tmp- で始まるセグメント
• 上限: key 全体 512B・1 セグメント 255B・ファイル 256MB
• 日本語・スペース入りの key は OK (CLI/API とも自動エスケープ)

Dashboard

hub の http://<hub>:4490/storage — フォルダのドリルダウン、画像/テキストの インライン preview、ドラッグ&ドロップでアップロード、二段確認の削除。

HTTP API (スクリプトから直接叩く場合)

TOKEN=$(cat ~/.local/state/macker/agent.token)   # hub 上での例
curl -H "Authorization: Bearer $TOKEN" "http://<hub>:4478/v1/storage?prefix=docs/"   # 一覧
curl -H "Authorization: Bearer $TOKEN" -T file.bin "http://<hub>:4478/v1/storage/docs/file.bin"  # PUT
curl -H "Authorization: Bearer $TOKEN" -o out.bin "http://<hub>:4478/v1/storage/docs/file.bin"   # GET (Range 可)
curl -X DELETE -H "Authorization: Bearer $TOKEN" "http://<hub>:4478/v1/storage/docs/file.bin"    # 204

ダウンロードには Content-Disposition: attachment + nosniff が付く (ブラウザ直開きで HTML を実行させない安全策)。preview は dashboard 側が安全な形で inline 表示する。

トラブルシュート

症状	原因と対処
no collector configured	MACKER_COLLECTOR か config の collector を設定
collector returned 404 (route なし)	hub の collector が旧バイナリ。hub で go install ./cmd/macker → launchctl kickstart -k gui/$UID/ai.masao.macker-collector
collector returned 403	put/rm は owner/exec_allow 限定。hub の config の policy に login を追加
invalid storage key	上の key 規約を確認 (.. や .tmp- 先頭など)
ls が遅い/ハング	collector 不達。curl http://<hub>:4478/v1/health で生死確認