mado S3 Data Catalog

複数のs3アカウントと多数のバケットを横断的に管理することを目的に開発したwebツール。

各ディレクトリに README を残したり、チームで 1 つの共有ノートを書いたりもできます。

ドキュメントを見る → — 使い方、画面のスクリーンショット、導入と設定の手順。

Local UserまたはOIDC SSOでログインでき、Pipelineは人とは別のアクセストークンを使います。開発環境でも認証を必須にしています。

できること

• 横断ブラウズ — 複数の S3 互換ストレージ (接続) を登録し、バケット / ディレクトリを辿る
• プレビュー — テキスト / 画像 / 音声 / MP4動画 / tar・tar.gz・tar.xz の中身を、ダウンロードせずその場で確認
• URL コピー — ファイルの Web URL (共有リンク) / S3 URL / ダウンロードをワンクリック
• ディレクトリ README — 各ディレクトリに Markdown のメモを残せる (履歴つき)
• チーム共有ノート — mado S3 Data Catalog 全体で 1 つの Markdown メモ (履歴つき)
• 波形 / スペクトログラム — 音声ファイルの波形とスペクトログラムをその場で確認 (解析結果はキャッシュ)
• 同期プレイヤー — 複数の音声ファイルを並べて同期再生し聴き比べる
• 配下の集計 — ディレクトリ配下のオブジェクト数と合計サイズを数える (サブディレクトリ / 拡張子別の内訳つき)
• 容量メトリクス — コネクション内の全バケットの容量・オブジェクト数と合計を定期取得し、Rechartsで増減を確認
• 移送の見積もり — その集計をもとに「他の接続へ移したら費用と時間はどれくらいか」を並べて比較。AWS S3 はストレージクラスも選べる
• 接続ごとの権限 — 「一覧は見せるがダウンロードと README 書き戻しは禁止」のように、接続単位で操作を絞れる
• Dataset Lineage — OpenLineageのDataset → Job → Datasetと、版ごとのDatasetVersion → Run → DatasetVersionをReact Flowで辿る
• 認証とRBAC — Local User / OIDC SSO、Viewer・Curator・Operator・Admin、監査ログ
• アクセストークン — 機能ごとの読み取り・送信・編集・削除・実行・管理を選んで発行。再発行・無効化・削除まで一つの一覧で管理

---

アクセス

ダッシュボードのURLをブラウザで開き、SSOまたは管理者が作成したLocal Userでログインします。

左のナビゲーションから Home / Storage / DataLineage / Settings を開けます。画面・区分の名前は、日本語の画面でも英語のまま表示します。

画面は日本語と英語に対応しています。右上の地球アイコンから切り替えられます。ログイン画面と初回パスワード変更画面では、ロゴの右側にあります。選択はブラウザに保存し、同じアプリの別タブにも反映します。未選択ならブラウザの優先言語を使い、ブラウザから言語を取れないときや対応する言語がないときは英語を表示します。切り替えても入力内容や開いている画面を保ちます。

1. ストレージ接続を登録する (Settings)

初回は接続が無いので、まず Settings → 「+ 追加」 で S3 互換ストレージを登録します。

• 名前 — 一覧での表示名
• エンドポイント / リージョン
• アクセスキー / シークレットキー — 保存時に暗号化されます (セキュリティ)
• path-style / ListObjects バージョン — 互換ストレージに合わせて選択
• ユーザーからの表示 — 通常は全員、例外だけホワイトリストで利用者を限定
• この接続で許可する操作 — 危険な導線を接続単位で閉じられます (下記)

登録した接続は後から編集・削除でき、Storage タブが開くデフォルト接続もここで変更できます。

ユーザーからの表示

接続は既定でログイン済みの全ユーザーに表示されます。一部だけ隠したい場合は ホワイトリストを選び、利用を許可するユーザーを選択します。許可されていないユーザーには 接続一覧・転送候補・関連ジョブが表示されず、StorageやDataLineageのURLを直接開いても 存在を明かさないため404になります。connections:manage権限を持つ管理者は、空の ホワイトリストを修正できるよう常にアクセスできます。

この接続で許可する操作

Glacier Deep Archive のように 一覧には出るが GetObject すると失敗する / 復元課金が発生する バケットや、書き戻したくない本番バケットを登録したときのためのトグルです。既定はすべて許可で、危険な接続だけ後から落とします。

項目	オフにすると
バケット / オブジェクトの一覧	この接続では何も見られなくなる (完全に凍結したいとき用)
ファイルのプレビュー	テキスト / 画像 / 音声 / MP4動画のプレビューが開かない
ファイルのダウンロード	DL ボタンと行メニューのダウンロードが消える
圧縮ファイルを開く	tar / tar.gz / tar.xz の中身を開けない
音声情報・波形の表示	音声解析 (ファイル全体の読み込み) が走らない
スペクトログラムの表示	スペクトログラム画像を出さない
README の読み込み	ディレクトリ README のセクションと README 検索が消える
README の編集	「編集 / 作成」が消える (読み込みがオフだと選べません)

オフにした操作は画面から導線が消えるだけでなく、共有 Web URL を直接開いても 403 で止まります。接続capabilityはRBACに重ねる防御層で、connections:manage権限を持つUserだけがSettingsから変更できます (セキュリティ)。

Settings の接続一覧には、制限のかかっている接続に「制限: …」が表示されます。

タグは接続ごとではなく mado S3 Data Catalog 全体の表示トグルです (Settings → 機能)。オフにしても登録済みのタグは消えません。

2. バケット / ディレクトリをブラウズする (Storage)

Storage タブはデフォルト接続を自動で開きます。別の接続に切り替えるときは右上の CONN メニュー、デフォルトの変更は Settings の各接続行の「デフォルトにする」から。

• ディレクトリをクリックして潜る / パンくずで戻る
• 上部の検索ボックスで 前方一致 検索 (再帰検索オプションあり)
• 一覧が多いときは下部のページャでめくる
• 一覧の上と README の見出しに、その情報を S3 から取得した時刻が出ます。取得から1時間を過ぎると経過時間で色が付きます (1〜3時間は緑、3〜6時間は黄、6〜12時間は橙、12〜24時間は赤、24時間以上は暗い赤で時刻が赤地)。一覧では表の上の帯、ファイル一覧の左端の線と地の色も同じ色になります。古いと気づいたら ↻ で取り直してください

3. ファイルをプレビューする

ファイルの行をクリックすると 右側にプレビュー が開きます (テキスト / 画像 / 音声 / MP4動画)。

• プレビューの 左端の境界をドラッグ して幅を調整できます (リストを圧縮せず上に重なる形で広がる)。変更した幅は記憶され、ヘッダの ↔ で既定幅に戻せます
• ヘッダの DL で元ファイルをダウンロード
• テキスト / JSON は 「内容をコピー」 で全文をクリップボードへ
• テキストは形式に合わせて色が付きます (JSON / YAML / TOML / INI・.conf / .env / XML・HTML / Markdown / Python / Shell / SQL / Dockerfile / CSV・TSV は列ごと / ログは時刻とレベル)。形式はファイル名、分からなければ中身から推測します。外れたときは本文の上の 「表示形式」 で選び直せ、選んだ形式は拡張子ごとにブラウザに記憶されます (localStorage の mado.codeLanguage。何でも入る .txt と拡張子の無いファイルは記憶しません)

4. tar / tar.gz / tar.xz の中身を見る

アーカイブを開くと 中のエントリ一覧 が表示されます。エントリをクリックすると個別にプレビュー (テキスト / 画像 / 音声 / MP4動画) でき、テキストは 「内容をコピー」 で全文コピーできます。テキストの色付けと 「表示形式」 は単体のファイルと同じです。

単体の動画・音声と、非圧縮の.tar内の動画・音声は、再生に必要な部分を取得します。500MBや1GB以上のファイルも、全量の取得を待たずに再生・シークできます。.tar内のファイルの位置は一覧と再生で共有し、後ろのページも先頭から走査し直さずに取得します。オブジェクトが変わった場合は索引を作り直します。

索引はprivateな一時SQLiteに保存し、10万件を超えてもメモリ上に全件を保持しません。1回の走査は1万ヘッダー・128回の部分取得・32MiB・10秒までで、準備中の一覧と再生は続きを自動で取得します。索引は15分未使用で破棄し、32アーカイブを保持し、合計2GiBを超えたら未使用の索引から削除します。1索引は512MiBの物理上限より早く容量を検査し、ファイル名は16KiBまでとし、超過時は省略した一覧を返さずエラーにします。ETag付きHEADは1秒だけ共有し、本文のIf-Matchで変更を検出します。

音声解析は単体ファイルを一度だけ一時ファイルへ取得し、probe・波形・スペクトログラムで再利用します。非圧縮tarも対象の音声の範囲だけ取得します。解析用入力の上限は単体2GiB・tar内100MiBで、直接再生には適用しません。一時ファイルは解析完了・失敗・中断時に削除します。

.tar.gz・.tar.xz内の本文は順次解凍して取得するため、引き続きMDC_PREVIEW_TAR_ENTRY_MAX_BYTESの上限が適用されます。ブラウザで再生できる動画・音声形式が対象です。

5. URL コピー / ダウンロード

各行の ⋯ メニュー から:

• Web URL をコピー — そのファイルのプレビューを直接開く共有リンク (LAN / VPN 内の相手に渡せる)
• S3 URL をコピー — s3://バケット/キー
• このファイルをダウンロード

6. ディレクトリごとの README

各ディレクトリの上部に S3 README が表示されます。編集 (✎) で Markdown を書き、履歴 (⏱) で過去の版を確認できます。長い README は折りたたまれ、「すべて表示」で展開します。

7. チーム共有ノート (Home)

Home は mado S3 Data Catalog 全体で 1 つの Team note (Markdown)。メンバー全員で追記していく共有メモで、編集 / 履歴 が使えます。

8. 配下の集計と移送の見積もり

一覧の上部にある 「配下を集計する」 で、そのディレクトリ配下のオブジェクト数と合計サイズを数えます (ListObjects だけを使うので、ファイルは 1 つもダウンロードしません)。54 万キー規模でも数分で終わりますが、重い接続では Settings のトグルで禁止できます。

集計が終わると、同じモーダルの 「移送の見積もり」 タブで「このデータを他の接続へ移すとどうなるか」を比較できます。

バケット直下ではREADMEの下にある 「バケットの容量メトリクスを見る」 から、接続内の 全バケットを縦に並べた容量履歴画面を開けます。画面上部には全バケットの容量・オブジェクト数の 合計と計測済み件数も表示します。定期計測は初期状態で無効で、周期はコネクション編集画面で 6時間〜7日から選びます。設定変更と 「今すぐ全バケットを計測」 は connections:manage権限を持つUserだけが実行できます。完全なバケット全体走査だけが履歴になり、 途中終了した値はグラフへ混ぜません。 各バケットのカードには 「直下のディレクトリ別」 の内訳も出ます。同じ全体走査で数えた、 バケット直下のディレクトリの容量上位50件です (追加のS3リクエストはありません)。容量・割合・ 前回からの増減を並べ、行を開くとそのディレクトリの推移グラフを表示します。 コネクション編集の 「バケットのメトリクス集計を許可する」 は既定で有効です。 無効にすると強制計測を止め、定期計測の有効化と周期設定も操作できなくなります。 走査の1ページ件数はコネクションごとに100／250／500／1,000件から選べます。 既定は1,000件で、S3互換実装の一覧応答が遅い場合だけ小さくします。

列	内容
所要	楽観〜悲観のレンジ。両端の帯域とオブジェクト数から出す
初期	移動元から出す費用 (egress) + 取り出し + リクエスト料金
月額	移動先に置き続けたときの追加コスト

行を開くと内訳と注意書きが出ます。移動元から出す費用を隠していないのが要点で、AWS から数十 TB 出すと、そのまま置き続けるより高くつくことがあります。

数字の精度について:

• オブジェクト数を見ています。 一般の料金計算ツールは「何 GB か」しか受け取りませんが、実際にはリクエスト料金も所要時間もオブジェクト数で決まります。平均サイズが小さいと帯域ではなくリクエストが律速になり、GB だけの見積もりは桁で外れます
• 所要時間は必ずレンジで出します。 接続ごとの帯域は Settings で実測値に置き換えられます (既定は当て推量です)
• 目的は桁と大小関係を合わせることであって、請求書を再現することではありません。無料枠や既存の使用量との合算は考慮していません

社内ストレージ (AWS / Wasabi 以外) は費用 0 として扱います。「金は掛からないが容量は有限」という実際の判断軸に寄せるため、容量を設定しておくと収まらない移送に警告が出ます。

単価はどこから来るか

AWS の料金 API から取得して DB にキャッシュしています。脚注に取得日が出るので、古ければ 「単価を更新」 を押してください。しばらく更新されていなければ、見積もりを開いたついでに裏で取り直します (その回の表示は古い単価のままで、次回から反映されます)。

外向きの通信ができない環境でも見積もりは出ます。 その場合はリポジトリに同梱されたカタログが使われ、脚注に「同梱の YYYY-MM-DD 版（まだ取得していません）」と出ます。費用 0 が「無料」なのか「単価を引けていない」のかを取り違えないよう、出所は必ず表示されます。

ただし、更新で新しくなるのは AWS の単価だけです。 以下は料金 API から取れないため手で持っており、更新しても変わりません。

• AWS の最小保存期間と最小課金サイズ、Glacier 系のオブジェクトごとの加算 (40KB)
• Glacier Deep Archive のストレージ単価 (同額の別クラスの値で代用)
• Wasabi のすべて (Wasabi は料金 API を公開していません)

これらは脚注の「一部の値は料金 API から取れないため手入力です」を開くと、何を手で持っているか・いつ一次ソースで確認したか・出典が読めます。候補の行を開けば、その移動先の単価が手入力かどうかも出ます。実際の契約単価があれば 接続の設定でストレージ単価を上書きしてください (そちらが優先されます)。

9. Dataset Lineage

LineageでnamespaceとDataset/Job名を指定すると、MarquezのOpenLineage projectionをグラフ表示します。ノードを選ぶとRegistry正本の版、manifest/hash、保存場所、Git SHA、container、config、model、metricsを確認できます。

Pipelineへの導入方法、DatasetとVersionの分け方、OpenLineage event例、既存データのbackfill、S3接続とのbindingは docs/lineage.mdにまとめています。Lineageを新しく生やす前にこのガイドを確認してください。

• logical表示: Dataset → Job → Dataset
• versions表示: 明示したDatasetVersion UUIDからVersion → Run → Version
• 「最新らしい版」は推測しません。版表示には明示version IDが必要です
• Registryが正本で、Marquez停止中は警告を表示します。mado S3 Data CatalogからMarquezへ直接書き込みません

AdminはAccess → Access Tokensで、アカウントを別に作らずアクセストークンを発行できます。新規作成では権限未選択から始め、Storage・README・Notes・DataLineage・ジョブ・接続・設定などの機能ごとに操作と接続・Namespaceを指定します。内部APIの権限は権限一覧を参照してください。DataLineageの読み取り・送信、Capacityの読み取りを選ぶと、従来の参照・送信・メトリクスAPIも同じトークンで利用できます。参照・送信には許可Namespaceが必要です。値は発行・再発行時に一度だけ表示されます。一覧から権限・有効期限の編集、再発行、無効化・有効化、削除を行えます。既存のService Account keyの値と権限も引き継ぎます。管理APIと移行・検証手順はアクセストークンの仕様を参照してください。

バージョン確認

Settings の一番下 About に、バージョン・稼働中のコミット (GitHub リンク) ・リポジトリが表示されます。

---

セットアップ (管理者向け)

前提

• Docker + Docker Compose v2
• macOS / Linux (dev は macOS Docker Desktop を想定)
• LAN / VPN 内利用前提。インターネット公開は想定していない

クイックスタート (dev)

# 1. .env を用意
cp .env.example .env

# 2. MDC_STORAGE_SECRET_KEY を生成して .env に書く (32 byte hex)
openssl rand -hex 32

# 3. 起動 (--build はコミット情報を About に焼くため初回 / 更新時に推奨)
docker compose -f compose.dev.yaml up -d --build

# 4. 初回Local Adminを作成（対話入力。既知の初期passwordは存在しない）
docker compose -f compose.dev.yaml exec api-internal \
  npm run auth:bootstrap-admin:dev -- --username admin

# 5. ブラウザで http://localhost:5173

dev の DB パスワードは未設定なら開発用の既定値で動きます。初回起動時のみ db/init/00-init.sh が dashboard_rw / dashboard_ro / mado_lineage / mado_worker ロールと dashboard_test DB を作成します。表は api-internal が起動時に移行 (api/migrations) を当てて作ります。作り直したいときは down -v で volume を消してから上げ直してください。

環境変数

このアプリが読む設定の名前はMDC_で始まります（v0.5.0で付けました）。旧名だけが残っていると、api-internal・api-lineage・media-workerは起動時に止まり、替える名前を表示します。旧名と新名の対応はv0.5.0のリリースノートにあります。

変数	必須	説明
MDC_PORT	yes	api コンテナの listen ポート (compose 側で 3000 に上書き)
MDC_DATABASE_URL_RW	yes	dashboard_rw 接続 URL。compose 内なので host は postgres
MDC_DATABASE_URL_RO	yes	dashboard_ro 接続 URL
MDC_DATABASE_URL_MIGRATE	yes (api-internal)	DB の管理者 (postgres) の接続 URL。api-internal が起動時に移行を当てるときに使い、無いと起動しない。compose の api-internal は POSTGRES_PASSWORD から組み立てた値で上書きする。compose を使わずに起動する (api/ の npm run dev) ときのために .env にも書く
MDC_TEST_DATABASE_URL	no	テスト用。host から接続するので localhost。未設定なら default に fallback
POSTGRES_PASSWORD	prod:yes / dev:no	postgres スーパーユーザのパスワード。prod は未設定だと起動失敗、dev は既定 postgres
MDC_DASHBOARD_DB_PASSWORD	prod:yes / dev:no	dashboard_rw / dashboard_ro のパスワード。MDC_DATABASE_URL_RW / MDC_DATABASE_URL_RO のパスワードと一致必須。dev 既定 CHANGEME
MDC_LINEAGE_DB_PASSWORD	prod:yes / dev:no	Internet向けapi-lineage専用の最小権限DB role。英数字hexの生成値を推奨
MDC_WORKER_DB_PASSWORD	prod:yes / dev:no	media-worker専用のmado_worker DB role。解析・走査の表だけを読み書きし、認証表は読めない
MDC_STORAGE_SECRET_KEY	yes	storage_connections の S3 認証情報を AES-256-GCM で暗号化するキー (32 byte hex)
MDC_WEB_ORIGIN	yes	CSRF 防御。write 系で許容する Origin (カンマ区切り)。dev: http://localhost:5173 / prod: ダッシュボードを開く URL
MDC_ENV	no	development / test / production。本番composeはを固定し、安全でない認証設定を起動時に拒否

⚠️ POSTGRES_PASSWORD / MDC_DASHBOARD_DB_PASSWORD / MDC_LINEAGE_DB_PASSWORD / MDC_WORKER_DB_PASSWORD は DB ボリュームの初回作成時のみ 反映されます。既存 DB のパスワード変更は env ではなく psql の ALTER ROLE が必要です (詳細は db/README.md)。生成例: openssl rand -hex 24

料金カタログの運用

移送の見積もりに使う単価は、AWS の料金 API から取得して pricing_cache テーブルに 1 行だけキャッシュします (使い方)。

• 取得は pricing.refresh ジョブとして media-worker が実行します。外向きに HTTPS が出られる必要があります (calculator.aws と pricing.us-east-1.amazonaws.com)
• 更新の間隔は app_settings の pricing_refresh_days (既定 1 日)。これより古くなると、見積もりを開いたときに裏で更新ジョブが投入されます。表示はその回だけ古い単価のままです
• 出られない環境でも壊れません。 取得が失敗しても同梱カタログ (api/pricing/catalog.ts) で見積もりは出ます。失敗しても次の投入までは間隔が空くので、ジョブが失敗で埋まることもありません
• 同梱カタログを新しくするには、外に出られるマシンで cd api && npm run pricing:fetch を回して結果をコミットします
• いま何を使っているかは GET /api/internal/pricing でも確認できます (出所・取得日・直近の失敗理由)

認証とLineageの初期化

新規導入では既定passwordを持つAdminを残さないため、Webを公開する前に次のoffline bootstrapを必ず実行します。

初期Adminの作成・再設定には、対話的なbootstrapコマンドを使います（パスワードを引数やshell historyへ残しません）。

docker compose -f compose.prod.yaml exec api-internal \
  npm run auth:bootstrap-admin -- --username admin

passwordはTTYからのみ読み、引数・環境変数・ログには渡しません。初回bootstrap時も入力した一時passwordは初回ログインで変更必須です。平常時はOIDC Adminを使う構成でも、IdP障害用に独立したLocal Adminを1つ維持してください。

PipelineはMDC_API_HOSTNAMEのPOST /api/openlineage/v1/lineageへアクセストークンをBearer送信します。mado S3 Data Catalogがprofile/scope/namespaceを検証し、keyを除いたprincipal envelopeをRegistryへ転送します。production nginxはintranet UI用:8080とOpenLineage専用:8081を分離し、:8081ではこのPOSTだけを受け付け、その他のpath/methodを404にします。Composeは両listenerをhostのloopbackへだけpublishし、MDX edgeではbrowser用MDC_HOSTNAMEと公開API用MDC_API_HOSTNAMEを別TLS vhostとして終端します。

連携向けの読み取りAPIは/api/mado/にまとめています。画面と同じ機能を使う場合は/api/internal/へBearer送信し、機能別の権限を付けます。PrometheusはMDC_HOSTNAMEのGET /api/mado/metrics/<領域>を、容量の読み取り（capacity:read）を許可したアクセストークンで読みます。現在の領域は容量メトリクスの/api/mado/metrics/capacityだけです。いずれもintranet用:8080にだけ置き、:8081では404です。scrape設定と出力するmetricsはdeploy/mdx/README.mdを参照してください。

DBの移行

DBの移行（api/migrations/*.sql）はapi-internalが起動時に当てます。DBの管理者の接続（MDC_DATABASE_URL_MIGRATE。ComposeがPOSTGRES_PASSWORDから組み立てる）を使い、適用したファイルを名前とSHA-256でschema_migrationsに記録します。api-lineageとmedia-workerは移行を当てる権限を持たず、全部が当たっていることを確かめてから起動します。当てた後のファイルの書き換えを見つけると、どのサービスも起動しません。

v0.4.0まで（移行を手で当ててきたDB）からの更新では、新しいapi-internalを起動する前に一度だけ、当ててある番号までを記録します。手順はdb/README.mdにあります。

OSSリリース

mado S3 Data CatalogはSemVerを採用し、最初のリリースをv0.1.0とします。GitHub上のannotated tagだけがrelease workflowを起動し、通常のmain pushや社内deployからOSS releaseが始まることはありません。

公開時は同一commitからLinux amd64/arm64対応のcompiled OCI imageを3つ作り、GHCRへ配置します。

• ghcr.io/aida0710/mado-api:<tag>: internal APIとOpenLineage API
• ghcr.io/aida0710/mado-media-worker:<tag>: ffmpeg worker
• ghcr.io/aida0710/mado-web:<tag>: Web UIと用途別nginx入口

GitHub Releaseには、image digestを固定したCompose、DBのロールを作る初期化スクリプト、設定例、licenseをまとめたbundleとSHA-256を添付します。DBの移行はmado-apiのimageに入っていて、api-internalが起動時に当てます。OCI imageにはSBOMとbuild provenanceを付与します。release本文はdocs/releases/、公開手順と安全条件はdocs/releasing.mdを正本とします。

OSS releaseと社内環境へのdeployは独立しています。release workflowはdeployment hostへ接続しません。

ソースからの社内デプロイ

./deploy.sh   # main を pull し、compose.prod.yaml で再ビルド + 再起動

deploy.sh は稼働中コミットを About に焼くため git 情報を build に渡します。dev との差分:

• nginx のintranet UI入口を127.0.0.1:8080、OpenLineage専用入口を127.0.0.1:8081へpublishし、どちらも用途別のhost reverse proxyを必須にする (api コンテナはホスト非公開)
• api は image build 時の tsc 成果物 (dist/) を node で実行
• nginx と api は non-root user で動作
• 全コンテナが restart: unless-stopped
• prod は POSTGRES_PASSWORD / MDC_DASHBOARD_DB_PASSWORD が .env に無いと起動しません (弱い既定値の埋め込み防止)

---

セキュリティ

このダッシュボードは認証を備えていますが、公開入口のTLSとネットワーク制御は引き続き必要です:

• 外部公開前にHTTPS必須。標準配布bundleはloopback上のHTTP入口へ用途別TLS proxyを接続します。Browser側TLS終端後にMDC_AUTH_COOKIE_SECURE=trueとMDC_AUTH_MODE=local|oidc|hybridを設定します。
• MDXではcompose.mdx.yamlのedge nginxがbrowser用TLSを終端します。証明書取得・UFW・自動更新はdocs/mdx-tls.mdを参照してください。
• Web UI、/api/auth/、/api/internal/、/api/mado/はintranet内に閉じます。外部公開するhost TLS proxyは127.0.0.1:8081だけへ接続し、OpenLineage ingest以外を公開しません。公開入口には送信元IP 10 req/s（burst 50）・全体50 req/s（burst 200）のrate limit、送信元20・全体200のconnection limit、2 MiB body上限、timeout、Cache-Control: no-storeを設定済みです。
• 開発・テスト環境も認証方式の指定が必須です。初期・一時passwordの変更完了前は、直接APIを呼んでも通常機能を利用できません。
• Browser sessionとアクセストークンを別の主体として扱い、API keyはhashだけを保存します。内部APIは機能別の権限と対象を毎回検証し、連携APIのscopeは互換性を維持します。
• RBACと接続capabilityを重ね、監査ログには成功して実際に状態が変わった操作だけを残します。閲覧、認証拒否、失敗した操作、同じ値の再保存、既存ジョブへの合流は記録しません。変更操作は開始時にdurableなintentを置き、失敗・変更なしなら破棄します。password/token/OIDC code/OpenLineage event本体は保存しません。
• sessionの利用時刻、login attempt、response cache、API keyの最終利用時刻など、認証・cache維持のための内部更新は操作監査の対象外です。
• MDC_STORAGE_SECRET_KEY で storage_connections の S3 認証情報を保存時暗号化 (AES-256-GCM)。DB ダンプだけ漏れても解読不能。
• CSRF 防御: write 系 (POST/PUT/DELETE) は MDC_WEB_ORIGIN と Origin/Referer を照合し、不一致なら 403。
• PG ロール分離: ブラウザ由来の経路は dashboard_rw / dashboard_ro を使い分け、Postgres レベルで DROP TABLE 等を防ぐ。
• 接続ごとのcapabilityはRBACとは別層です。Adminであっても接続側で無効なdownload等は実行できません。
• 接続先の制限（SSRF対策）: 接続のエンドポイントに、loopback・link-local（cloud metadataを含む）・IPv4-mapped IPv6でそれらを表したアドレスは使えません。RFC1918とIPv6 ULAは使えます。DNS名は接続のたびに名前解決の結果を確かめ、拒否するアドレスだけを指していれば接続しません。検査が今より緩かった頃に保存した接続も、使う時点で409になります。アップデートの前に、既存の接続のエンドポイントがloopbackなどを指していないかを確かめてください。
• 接続ホワイトリストは通常接続を全員公開のまま保ち、例外の接続だけUser単位で隠します。非許可時は一覧・Storage API・DataLineage解決・関連job・転送候補を404相当で隠します。DataLineageの手動登録では許可されていない接続を保存場所に使えず（Registryへ紐付けていない接続と同じ422）、Dataset・Versionの詳細でも見えない接続のIDは出しません。

Authentikとの接続、JIT User、group RBAC、Front/Back-channel logoutの登録値は docs/authentik.mdにまとめています。

---

開発者向け

アーキテクチャ

dev / prodとも、ブラウザsession用api-internalとPipeline key用api-lineageを別processにします。Dataset metadataの正本はRegistry、Marquezはoutboxから再構築できるprojectionです。

                 ┌─ docker compose ──────────────────────────────┐
Browser ─:5173 ─►│ front (vite dev / dev)                        │
 またはhost proxy│   または                                      │
                 │ nginx :8080 (intranet UI / prod)              │
                 │   └─► /api/internal/* → api-internal (Hono)   │
                 │   └─► /api/auth/*     → api-internal          │
                 │   └─► /api/mado/*     → api-internal          │
Pipeline ─TLS proxy─► nginx :8081 (POST ingest only)              │
                 │   └─► /api/openlineage/v1/lineage → api-lineage│
                 │                              ├─► media-worker │
                 │                              │    (ffmpeg)    │
                 │                          postgres             │
                 └───────────────────────────────────────────────┘
                 公開ポート: dev=5173
                 host loopback: prod UI=:8080 / OpenLineage=:8081

サービス	dev	prod
front	vite dev (HMR)	(なし、nginx に焼き込み)
nginx	(なし、Vite proxy が代替)	:8080 静的配信・内部API・/api/mado/ + :8081 OpenLineage POST専用
api-internal	tsx watch internal.ts	node dist/internal.js
api-lineage	tsx watch lineage.ts	node dist/lineage.js
media-worker	tsx watch worker.ts	node dist/worker.js
postgres	postgres:16-alpine (127.0.0.1:5432)	postgres:16-alpine (compose 内部のみ)

api-internal・api-lineage・media-workerは、どれもGET /healthzで稼働を返します。DBに届けば200と{"status":"ok"}、届かなければ503と{"error":"database is unavailable","code":"database_unavailable"}です。Composeのhealthcheckは配布イメージに入っているnode dist/scripts/healthcheck.js <ポート>でこれを確かめ、Webのnginxは両APIがhealthyになってから起動します。

APIの仕様 (OpenAPI)

APIの仕様はdocs/openapi.json（OpenAPI 3.1）にあります。ルートの一覧と入出力のスキーマ（api/openapi/route-catalog.ts、応答のスキーマは画面と共有するapi/shared/schemas/）から作ります。ルートを足したり変えたりしたら、一覧を直してcd api && npm run openapi:generateで作り直します。一覧と実際のルート、版（VERSION）とのずれはapi/openapi/openapi.test.tsが見つけます。

よく使うコマンド

docker compose -f compose.dev.yaml up -d --build   # 起動 (About のコミット表示には --build)
docker compose -f compose.dev.yaml logs -f         # ログ追跡
docker compose -f compose.dev.yaml down            # 停止 (volume 残す)
docker compose -f compose.dev.yaml down -v         # 停止 + DB volume 削除

ソース変更は bind mount で反映: front/ → vite HMR / api/ → tsx watch 再起動。

IDE 補完用に host でも install

cd front && npm install && cd ..
cd api   && npm install && cd ..

テスト / Lint

host 上で直接実行 (postgres コンテナだけ立っていれば良い):

docker compose -f compose.dev.yaml up -d postgres
# テスト用 DB (dashboard_test) に移行を当てる。移行を足したときも当て直す
(cd api && MDC_DATABASE_URL_MIGRATE=postgres://postgres:postgres@localhost:5432/dashboard_test npm run db:migrate)
cd api   && npm test && npm run lint
cd front && npm test && npm run lint

画面の見た目 (mado ML Tracking と共通)

画面の部品と枠は mado ML Tracking と同じものを使います。CSS と、両製品に共通の処理・React の部品はデザインシステム @mado/design-system (aida0710/mado-design-systems) にあり、front/ は CSS を次の順に読み込みます。

読み込む物	中身
main.tsx の fonts.css と tokens.css	書体と、ライト・ダークの色・角丸・書体の変数
App.cssのbase.css・components.css・shell.css・code.css・lineage.css（React Flowの既定のCSSはlineage.cssの前に読み込みます）	要素の既定（本文13px、入力欄、リンク、見出し）、ボタン・表・入力欄・ダイアログ・タブ・状態バッジ・メニュー・一覧の上の帯・パンくず、上部バー・サイドバー・ドロワー・ログイン画面、テキストのプレビューの色付け、DataLineageのグラフ
App.cssのfront/styles/*.css	画面ごとの指定（保存先の一覧、プレビュー、メモ・README、設定、DataLineage）

• mado ML Trackingと同じくCSSのlayerは使わず、読み込む順で優先順位が決まります。同じ詳細度なら後に読むfront/styles/が勝ちます。共通の部品の指定を画面に合わせて変えるときは、共通の指定と同じかそれより高い詳細度で書きます（例: 開いた行の中のdlは.responsive-table-details .admin-user-meta）。
• CSSのフレームワーク（Tailwindなど）は使いません。要素の既定はデザインシステムのbase.cssにあるものだけで、余白やリストの印は部品ごとのclassで決めます。
• 部品は共通の class 名 (.button、.page-header、.tabs、.field、.dialog、.toolbar、.popover.menu、.status-success など) で使い、領域のファイルにはその画面に固有の指定だけを書きます。文字の大きさは --font-size-2xs〜--font-size-xl の変数で書きます。
• 画面の枠 (サイドバー・ドロワー・ユーザーメニュー・表示言語の選択・ロゴ)、ダイアログ (ブラウザの <dialog>)、読み込み中・失敗の表示とデータの読み込み (useQuery)、コピー、サイズと経過時間の書式、アクセストークンの期限の選び方は、デザインシステムの @mado/design-system/react などを使います。保存キーは mado. で始めます (mado.theme・mado.locale・mado.navigation.*・mado.codeLanguage)。
• 色は tokens.css の変数で書き、値を直接書きません。ダークテーマは上部バーのボタンで切り替え (localStorage の mado.theme。切り替えるまでは OS の設定に合わせます)、<html data-theme="dark"> で効きます。
• 画面幅の切り替え点は640px・900px・1200pxの3つです。左のサイドバーは1200px以上で名前つき（下のボタンでアイコンだけに畳め、右の境目のドラッグで幅を変えられます）、900px以上でアイコンだけ、それ未満は上部バーのメニューボタンから開くドロワーです。
• アイコンは Lucide (lucide-react) を使います。
• テキストのプレビューの形式の推測と色付けは、デザインシステムの @mado/design-system/code (highlight.js と、CSV・TSV・ログの色付け) を mado ML Tracking と共有します。画面の部品は components/CodeView.tsx、形式の記憶はデザインシステムの useCodeLanguage (保存キーと形式の名前は lib/codeLanguage.ts) です。本文はどちらのテーマでも暗い面に置き、色はどれも面に対して 4.5:1 以上です。

デザインシステムは、GitHub Release に添付された tarball に依存しています (front/package.json)。見た目を変えるときはデザインシステムのリポジトリで版を上げ (main に入ると Release が作られます)、次の手順で取り込みます。

# mado の front で
npm install https://github.com/aida0710/mado-design-systems/releases/download/v<version>/mado-design-system-<version>.tgz

---

クレジット

• 書体: IBM Plex (@mado/design-system に同梱) と Noto Sans JP。どちらも SIL Open Font License 1.1。
• アイコン: Lucide (lucide-react)。ISC License。
• テキストの色付け: highlight.js。BSD 3-Clause License。

---

License

mado S3 Data Catalog is licensed under the Apache License 2.0.