127 lines
8.0 KiB
HTML
127 lines
8.0 KiB
HTML
<!DOCTYPE html>
|
||
<html lang="ja">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
<title>初期セットアップ（認証・初回管理者） — MAESTRO</title>
|
||
<link rel="stylesheet" href="guide.css">
|
||
</head>
|
||
<body>
|
||
<div class="wrap">
|
||
<header class="doc">
|
||
<div class="crumbs"><a href="index.html">運用ガイド</a> / 初期セットアップ</div>
|
||
<h1>初期セットアップ — 認証と初回管理者アカウント <span class="badge done">完成</span></h1>
|
||
<p class="meta">対象: MAESTRO を認証ありで運用し、最初の管理者アカウントを作る人 ／ 更新日: 2026-06-10</p>
|
||
</header>
|
||
|
||
<h2>このガイドの範囲</h2>
|
||
<p>
|
||
MAESTRO は認証なし（no-auth）でも動きますが、複数人で使う・外部に出す場合はログインを有効にします。
|
||
その際に最初に詰まるのが「<b>まだ誰もログインできない状態で、どうやって最初の管理者を作るか</b>」です。
|
||
本ガイドはローカル認証（ID + パスワード）を前提に、その初回ブートストラップ手順をまとめます。
|
||
</p>
|
||
<div class="note">
|
||
<b>setup-wizard とは別です</b><br>
|
||
<code>npm run setup</code> のセットアップウィザードは <b>LLM 接続先の設定だけ</b>が対象で、認証・初期管理者は対象外です。
|
||
認証まわりは本ガイドで手動設定します。
|
||
</div>
|
||
|
||
<h2>前提</h2>
|
||
<ul>
|
||
<li><code>config.yaml</code> が存在すること（無ければ <code>config.yaml.example</code> をコピー）。</li>
|
||
<li>サーバーをビルド・起動できること（<code>scripts/server.sh start</code> 等）。</li>
|
||
</ul>
|
||
|
||
<h2>ステップ 1 — ローカル認証を有効化し、初回 admin を seed する</h2>
|
||
<p>
|
||
初回管理者は「セルフ登録」ではなく、<b><code>config.yaml</code> に書いておくと起動時に自動作成（seed）される</b>方式です。
|
||
<code>auth:</code> ブロックに次を追加します。
|
||
</p>
|
||
<pre><code>auth:
|
||
session_secret: "ランダムな長い文字列" # 未設定だと再起動ごとにセッション失効
|
||
local:
|
||
enabled: true
|
||
allow_signup: false # 後述。true で他ユーザーのセルフ登録を許可
|
||
bootstrap_admin: # 起動時に id='local' の管理者を冪等 seed
|
||
email: "admin" # ← ログインID（メール形式でなくてOK）
|
||
password: "強いパスワードを設定" # ← 平文で config に入る。初回ログイン後に変更推奨</code></pre>
|
||
|
||
<table>
|
||
<thead><tr><th>キー</th><th>意味</th></tr></thead>
|
||
<tbody>
|
||
<tr><td><code>auth.session_secret</code></td><td>セッション署名鍵。未設定だとプロセスごとのランダム値になり、再起動でログインが切れる。安定運用では必ず設定。</td></tr>
|
||
<tr><td><code>auth.local.enabled</code></td><td><code>true</code> でローカル（ID+パスワード）ログインを有効化。これだけで認証が有効になり、OAuth 無しでも保護される。</td></tr>
|
||
<tr><td><code>auth.local.bootstrap_admin.email</code></td><td>初回管理者のログインID。後述の通り<b>メール形式は不要</b>。</td></tr>
|
||
<tr><td><code>auth.local.bootstrap_admin.password</code></td><td>初回管理者のパスワード。<b>config に平文で保存される</b>ため、初回ログイン後に Settings から変更を推奨。</td></tr>
|
||
<tr><td><code>auth.local.allow_signup</code></td><td><code>true</code> で 2人目以降のセルフ登録を許可（作成されるのは承認待ち状態）。</td></tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<div class="tip">
|
||
<b>no-auth からの移行はそのまま引き継げる</b><br>
|
||
seed される管理者は固定 ID <code>local</code> で作られます。これは no-auth 時代にデータの所有者として使われていた ID と同じなので、
|
||
認証なしで溜めたタスクやファイルを、そのまま初回 admin が引き継ぎます。
|
||
</div>
|
||
|
||
<h2>ステップ 2 — 再起動してログイン</h2>
|
||
<ol class="steps">
|
||
<li>サーバーを再起動する。</li>
|
||
<li>起動ログに <code>[auth] seeded local system admin id=local email=...</code> が出ることを確認する（seed は冪等。再起動のたびに config の値でパスワードが更新される）。</li>
|
||
<li>ブラウザで <code>/auth/login</code> を開き、<b>ステップ1で設定した ID とパスワード</b>でログインする。そのまま管理者として入れる。</li>
|
||
</ol>
|
||
|
||
<h2>ログインID について（メール不要）</h2>
|
||
<p>
|
||
ローカル認証の識別子は内部的に「email」という名前のフィールドですが、<b>メール形式の検証はしていません</b>。
|
||
<code>admin</code> や <code>team-taro</code> のような<b>自由な文字列をログインID として使えます</b>。
|
||
ログイン／登録フォームの入力欄も <code>type="text"</code>・ラベル「ログインID」になっており、
|
||
ブラウザのメール形式チェックは外れています。
|
||
</p>
|
||
<div class="note">
|
||
<b>OAuth を併用する場合</b><br>
|
||
Google / Gitea OAuth も使う構成では、そちら側はメールアドレスで識別され、管理者自動昇格は <code>auth.admin_emails</code> のメール一致で判定されます。
|
||
ローカル認証だけなら自由ID で問題ありません。
|
||
</div>
|
||
|
||
<h2>ステップ 3 — 2人目以降のユーザー</h2>
|
||
<p>方法は2通りです。</p>
|
||
<ul>
|
||
<li><b>セルフ登録を許可する</b>: <code>auth.local.allow_signup: true</code> にすると、ログイン画面に登録フォームが出る。登録されたユーザーは<b>承認待ち（pending）</b>になり、そのままではアプリを使えない。管理者が <b>Settings → ユーザー管理</b> で承認すると有効化される。</li>
|
||
<li><b>管理者が用意する</b>: allow_signup を使わず、管理者がユーザーを作成・有効化する運用も可能。</li>
|
||
</ul>
|
||
|
||
<h2>よくある詰まり</h2>
|
||
<table>
|
||
<thead><tr><th>症状</th><th>原因 / 対処</th></tr></thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>起動時に <code>Cannot read properties of undefined (reading 'google')</code> で落ちる</td>
|
||
<td>古いビルドで <code>auth.providers</code> 未設定だと発生した既知不具合（修正済み）。最新を pull・再ビルドすれば解消。暫定回避は <code>auth:</code> 直下に <code>providers: {}</code> を1行足す。</td>
|
||
</tr>
|
||
<tr>
|
||
<td>再起動のたびにログインが切れる</td>
|
||
<td><code>auth.session_secret</code> 未設定。安定した値を設定する。</td>
|
||
</tr>
|
||
<tr>
|
||
<td>初回 admin でログインできない</td>
|
||
<td>入力した ID/パスワードが <code>bootstrap_admin</code> の値と一致しているか確認。値を変えて再起動すればパスワードは上書き更新される（seed は冪等）。</td>
|
||
</tr>
|
||
<tr>
|
||
<td>UI 変更が反映されない</td>
|
||
<td>サーバー再起動だけでは UI は更新されない。<code>npm run build:ui</code> を実行してから再起動する。</td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
<h2>背景・関連</h2>
|
||
<ul>
|
||
<li>設定の全項目は <code>config.yaml.example</code> の <code>auth:</code> ブロックのコメント参照。</li>
|
||
<li>LLM 接続先の初期設定はセットアップウィザード（<code>npm run setup</code>）が担当。本ガイドの認証はウィザードの対象外。</li>
|
||
<li>関連変更: 自由ログインID 対応（PR #448）、<code>auth.providers</code> 未設定クラッシュ修正（PR #447）。</li>
|
||
</ul>
|
||
|
||
<footer class="doc">MAESTRO — docs/operations/initial-setup.html ／ 完成版（2026-06-10）</footer>
|
||
</div>
|
||
</body>
|
||
</html>
|