運用ガイド / 初期セットアップ

初期セットアップ — 認証と初回管理者アカウント完成

対象: MAESTRO を認証ありで運用し、最初の管理者アカウントを作る人／更新日: 2026-06-10

このガイドの範囲

MAESTRO は認証なし（no-auth）でも動きますが、複数人で使う・外部に出す場合はログインを有効にします。その際に最初に詰まるのが「まだ誰もログインできない状態で、どうやって最初の管理者を作るか」です。本ガイドはローカル認証（ID + パスワード）を前提に、その初回ブートストラップ手順をまとめます。

setup-wizard とは別です
npm run setup のセットアップウィザードは LLM 接続先の設定だけが対象で、認証・初期管理者は対象外です。認証まわりは本ガイドで手動設定します。

前提

config.yaml が存在すること（無ければ config.yaml.example をコピー）。
サーバーをビルド・起動できること（scripts/server.sh start 等）。

ステップ 1 — ローカル認証を有効化し、初回 admin を seed する

初回管理者は「セルフ登録」ではなく、config.yaml に書いておくと起動時に自動作成（seed）される方式です。 auth: ブロックに次を追加します。

auth:
  session_secret: "ランダムな長い文字列"     # 未設定だと再起動ごとにセッション失効
  local:
    enabled: true
    allow_signup: false                  # 後述。true で他ユーザーのセルフ登録を許可
    bootstrap_admin:                      # 起動時に id='local' の管理者を冪等 seed
      email: "admin"                      # ← ログインID（メール形式でなくてOK）
      password: "強いパスワードを設定"        # ← 平文で config に入る。初回ログイン後に変更推奨

キー	意味
`auth.session_secret`	セッション署名鍵。未設定だとプロセスごとのランダム値になり、再起動でログインが切れる。安定運用では必ず設定。
`auth.local.enabled`	`true` でローカル（ID+パスワード）ログインを有効化。これだけで認証が有効になり、OAuth 無しでも保護される。
`auth.local.bootstrap_admin.email`	初回管理者のログインID。後述の通りメール形式は不要。
`auth.local.bootstrap_admin.password`	初回管理者のパスワード。config に平文で保存されるため、初回ログイン後に Settings から変更を推奨。
`auth.local.allow_signup`	`true` で 2人目以降のセルフ登録を許可（作成されるのは承認待ち状態）。

no-auth からの移行はそのまま引き継げる
seed される管理者は固定 ID local で作られます。これは no-auth 時代にデータの所有者として使われていた ID と同じなので、認証なしで溜めたタスクやファイルを、そのまま初回 admin が引き継ぎます。

ステップ 2 — 再起動してログイン

サーバーを再起動する。
起動ログに [auth] seeded local system admin id=local email=... が出ることを確認する（seed は冪等。再起動のたびに config の値でパスワードが更新される）。
ブラウザで /auth/login を開き、ステップ1で設定した ID とパスワードでログインする。そのまま管理者として入れる。

ログインID について（メール不要）

ローカル認証の識別子は内部的に「email」という名前のフィールドですが、メール形式の検証はしていません。 admin や team-taro のような自由な文字列をログインID として使えます。ログイン／登録フォームの入力欄も type="text"・ラベル「ログインID」になっており、ブラウザのメール形式チェックは外れています。

OAuth を併用する場合
Google / Gitea OAuth も使う構成では、そちら側はメールアドレスで識別され、管理者自動昇格は auth.admin_emails のメール一致で判定されます。ローカル認証だけなら自由ID で問題ありません。

ステップ 3 — 2人目以降のユーザー

方法は2通りです。

セルフ登録を許可する: auth.local.allow_signup: true にすると、ログイン画面に登録フォームが出る。登録されたユーザーは承認待ち（pending）になり、そのままではアプリを使えない。管理者が Settings → ユーザー管理 で承認すると有効化される。
管理者が用意する: allow_signup を使わず、管理者がユーザーを作成・有効化する運用も可能。

よくある詰まり

症状	原因 / 対処
起動時に `Cannot read properties of undefined (reading 'google')` で落ちる	古いビルドで `auth.providers` 未設定だと発生した既知不具合（修正済み）。最新を pull・再ビルドすれば解消。暫定回避は `auth:` 直下に `providers: {}` を1行足す。
再起動のたびにログインが切れる	`auth.session_secret` 未設定。安定した値を設定する。
初回 admin でログインできない	入力した ID/パスワードが `bootstrap_admin` の値と一致しているか確認。値を変えて再起動すればパスワードは上書き更新される（seed は冪等）。
UI 変更が反映されない	サーバー再起動だけでは UI は更新されない。`npm run build:ui` を実行してから再起動する。

背景・関連

設定の全項目は config.yaml.example の auth: ブロックのコメント参照。
LLM 接続先の初期設定はセットアップウィザード（npm run setup）が担当。本ガイドの認証はウィザードの対象外。
関連変更: 自由ログインID 対応（PR #448）、auth.providers 未設定クラッシュ修正（PR #447）。