From 98feeccbe132bb85997b3c028c4eec30a9b9aae0 Mon Sep 17 00:00:00 2001 From: devnomad-byte Date: Fri, 26 Jun 2026 15:19:58 +0800 Subject: [PATCH] docs: note admin account wizard requirement in source-compile install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Method 3 (source compile) instructs users to pre-create config.yaml, but does not mention that doing so disables the setup wizard — the only code path that creates the initial admin account. Users following the README end up with a running server and an empty users table, and login fails with "invalid email or password". The default.admin_email / default.admin_password fields in config.yaml are loaded into the config struct but never read by any code path (setup.SetupConfig.Admin is tagged yaml:"-"), so they cannot serve as an alternative way to seed the admin. Add a "Creating the Admin Account" subsection to Method 3 in all three language READMEs (EN/CN/JA), explaining the wizard dependency and two workarounds: let the wizard generate config.yaml, or temporarily move config.yaml aside to trigger the wizard on first run. Related: #521 (docker variant of the same symptom), #2617, #2350. Co-Authored-By: Claude Opus 4.6 --- README.md | 19 +++++++++++++++++++ README_CN.md | 19 +++++++++++++++++++ README_JA.md | 19 +++++++++++++++++++ 3 files changed, 57 insertions(+) diff --git a/README.md b/README.md index db1c4f6c8a..58f7dac2dd 100644 --- a/README.md +++ b/README.md @@ -542,6 +542,25 @@ If you disable URL validation or response header filtering, harden your network - Enforce TLS-only outbound traffic - Strip sensitive upstream response headers at the proxy +#### ⚠️ Important: Creating the Admin Account + +The initial admin account is **only created via the setup wizard** (served at `http://:8080` on first run). The `default.admin_email` / `default.admin_password` fields in `config.yaml` are **not used** to create it — they exist in the template for historical reasons. + +Because step 5 above pre-creates `config.yaml`, the setup wizard will be **skipped on first run**: the server detects an existing config and boots straight into normal mode with an empty `users` table, so the first login attempt fails with `invalid email or password`. + +**Two ways to create the admin account:** + +1. **Recommended — let the wizard generate `config.yaml`:** Skip step 5 (do not run the `cp`). Start `./sub2api` directly; the setup wizard at `http://localhost:8080` walks you through database, Redis, and admin account setup, then writes `config.yaml` for you. + +2. **If you already created `config.yaml`:** Temporarily move it aside so the wizard can trigger on first run, then restore it afterwards: + ```bash + mv config.yaml config.yaml.bak + ./sub2api # wizard runs at http://localhost:8080 and writes a fresh config.yaml + # stop the server (Ctrl+C) once the wizard completes, then restore your config: + mv config.yaml.bak config.yaml + ./sub2api # restart in normal mode and log in with the admin you just created + ``` + ```bash # 6. Run the application ./sub2api diff --git a/README_CN.md b/README_CN.md index 5c52b0cda1..236a61ae37 100644 --- a/README_CN.md +++ b/README_CN.md @@ -586,6 +586,25 @@ Invalid base URL: invalid url scheme: http - 强制仅允许 TLS 出站 - 在反向代理层移除敏感响应头 +#### ⚠️ 重要：创建管理员账号 + +初始管理员账号**只能通过 setup 向导创建**（首次启动时访问 `http://:8080`）。`config.yaml` 中的 `default.admin_email` / `default.admin_password` 字段**不会被用来创建管理员**——它们只是出于历史原因保留在模板里。 + +由于上面第 5 步预先创建了 `config.yaml`，**setup 向导在首次启动时会被跳过**：服务检测到 config 已存在，会直接进入正常模式，此时 `users` 表为空，首次登录会返回 `invalid email or password`。 + +**创建管理员的两种方式：** + +1. **推荐——让向导自动生成 `config.yaml`：** 跳过上面的第 5 步（不要执行 `cp`）。直接运行 `./sub2api`，访问 `http://localhost:8080`，向导会引导你完成数据库、Redis 和管理员账号配置，并自动写出 `config.yaml`。 + +2. **如果你已经创建了 `config.yaml`：** 首次启动前先把它临时移走以触发向导，完成后再恢复： + ```bash + mv config.yaml config.yaml.bak + ./sub2api # 向导在 http://localhost:8080 启动，并生成新的 config.yaml + # 向导完成后 Ctrl+C 停服，再恢复你的配置： + mv config.yaml.bak config.yaml + ./sub2api # 重启进入正常模式，用刚创建的管理员登录 + ``` + ```bash # 6. 运行应用 ./sub2api diff --git a/README_JA.md b/README_JA.md index 247e42c4bb..59d8a5d796 100644 --- a/README_JA.md +++ b/README_JA.md @@ -540,6 +540,25 @@ URL バリデーションまたはレスポンスヘッダーフィルタリン - TLS のみのアウトバウンドトラフィックを強制 - プロキシで機密性の高い上流レスポンスヘッダーを除去 +#### ⚠️ 重要：管理者アカウントの作成 + +初期管理者アカウントは**セットアップウィザード経由でのみ作成**されます（初回起動時に `http://:8080` にアクセス）。`config.yaml` の `default.admin_email` / `default.admin_password` フィールドは**管理者作成には使われません**。テンプレートに残っているのは歴史的経緯によるものです。 + +上記ステップ 5 で事前に `config.yaml` を作成しているため、**初回起動時にセットアップウィザードはスキップされます**。サーバーは既存の config を検出して通常モードで直接起動し、この時点では `users` テーブルが空のため、初回ログインは `invalid email or password` を返します。 + +**管理者アカウントを作成する 2 つの方法:** + +1. **推奨 — ウィザードに `config.yaml` を自動生成させる:** 上記ステップ 5 をスキップします（`cp` を実行しない）。`./sub2api` を直接起動し、`http://localhost:8080` にアクセスすると、セットアップウィザードがデータベース・Redis・管理者アカウントの設定を案内し、`config.yaml` を自動生成します。 + +2. **すでに `config.yaml` を作成してしまった場合:** 初回起動前に一時的に退避してウィザードを発生させ、完了後に戻します: + ```bash + mv config.yaml config.yaml.bak + ./sub2api # ウィザードが http://localhost:8080 で起動し、新しい config.yaml を生成します + # ウィザード完了後、Ctrl+C でサーバーを停止し、設定を復元します: + mv config.yaml.bak config.yaml + ./sub2api # 通常モードで再起動し、作成した管理者でログインします + ``` + ```bash # 6. アプリケーションを実行 ./sub2api