First admin bootstrap

自托管 Appaloft 第一次启动时需要一个本地管理员。这个账号用于登录 Web console、完成后续 organization 配置，并在 admin authorization 开放后管理 deploy token 和成员。

首次管理员可以由安装器通过受信任的安装输入创建：

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- \
  --first-admin-email admin@example.com \
  --first-admin-name "Admin"

如果没有传 --first-admin-password，安装器会生成一次性密码，并只在 Appaloft 容器健康后从受信任 handoff 输出读取并打印一次。请立即保存该密码。重新运行安装器时，如果已经存在管理员或 organization owner，bootstrap 会安全跳过，不会再次显示密码。

如果需要提供自己的初始密码，可以传：

curl -fsSL https://appaloft.com/install.sh | sudo sh -s -- \
  --first-admin-email admin@example.com \
  --first-admin-password "$APPALOFT_INITIAL_ADMIN_PASSWORD"

安装器不会把你提供的密码回显到输出里。不要把密码写进仓库配置、shell history、CI 日志、issue、 PR 评论或部署输出。

容器或自托管运行时也可以通过受信任的环境变量在启动时自动创建首次管理员，而不写 handoff 文件：

APPALOFT_FIRST_ADMIN_EMAIL=admin@example.com
APPALOFT_FIRST_ADMIN_DISPLAY_NAME=Admin
APPALOFT_FIRST_ADMIN_ORGANIZATION_NAME="Self-hosted Appaloft"
APPALOFT_FIRST_ADMIN_ORGANIZATION_SLUG=self-hosted-appaloft
APPALOFT_FIRST_ADMIN_PASSWORD="$APPALOFT_INITIAL_ADMIN_PASSWORD"

启动时 bootstrap 只会在同时配置 email 和 password 时自动执行；如果没有提供 password，必须配置 APPALOFT_BOOTSTRAP_FIRST_ADMIN_OUTPUT_FILE，这样生成的一次性密码才有受信任的 handoff 输出。

如果安装器没有收到 first-admin email，安装后打开打印出来的 console URL 即可。console 会检查 bootstrap status，并把首次访问者引导到 /bootstrap/auth/first-admin。你也可以直接打开这个设置路径。 该页面会先读取 bootstrap status；如果实例已经有管理员，会引导你去 /login 登录，而不会再次创建账号。

CLI bootstrap 走同一条 application command/query 路径：

appaloft auth bootstrap-status
appaloft auth bootstrap-first-admin \
  --email admin@example.com \
  --display-name "Admin"

安装器会打印 console URL。没有配置域名时，通常是服务器的 3721 端口；配置了 --domain 时， 使用对应的 HTTPS 域名。

用已配置账号的 email 和密码登录。登录后，Appaloft 会把你识别为用户会话，并按 organization role 保护产品 mutation。没有 session 的 mutation 会返回 401 product_auth_missing；已登录但不属于目标 organization 或 role 不足时，会返回 403 product_auth_forbidden。

如需结束当前浏览器会话，使用 console 顶部栏或用户菜单里的 退出登录。console 会清理已缓存的 session 状态并返回 /login。

安装和 console setup 可以读取公开 bootstrap status：

GET /api/bootstrap/auth/status

当 status 表示需要创建首次管理员时，可以调用一次 setup endpoint：

POST /api/bootstrap/auth/first-admin

bootstrap status 是刻意公开的；setup endpoint 只在首次配置未完成时可用。一旦已经存在管理员或 organization owner，Web 不再显示创建管理员入口，直接访问 setup page 会回到登录页，setup endpoint 会返回 404 first_admin_bootstrap_disabled，不会 dispatch 创建命令、创建新管理员或返回密码。

Google、GitHub 或通用 OIDC 可以稍后再配置。缺少 OAuth client id、client secret、callback URL 或 trusted origin 时，OAuth 登录应保持关闭，但这不应该阻塞本地 first-admin 登录。

先用本地管理员完成首次登录；确认 console 可用后，再添加 OAuth 配置：

callback URL 使用 auth API origin；GitHub 和 Google 默认路径是 <APPALOFT_BETTER_AUTH_URL>/api/auth/callback/<provider>，通用 OIDC 默认路径是 <APPALOFT_BETTER_AUTH_URL>/api/auth/oauth2/callback/oidc。browser console origin 必须通过 APPALOFT_WEB_ORIGIN 配置为 trusted origin。

不要为了绕过首次登录而手工编辑数据库用户、member 或 organization 记录。

首次管理员会成为初始 organization 的 owner。登录后，使用 Organization team management 查看当前 organization context、邀请成员、更新非 owner 角色、移交 owner、移除非 owner 成员，并处理 401 product_auth_missing 和 403 product_auth_forbidden。

如果忘记生成的一次性密码，重新运行安装器不会再次显示旧密码。优先使用已登录的管理员会话或后续 正式的管理员恢复流程。早期自托管实例在没有可用管理员时，应从受信任备份恢复，而不是直接修改 auth 数据库表。

如果安装后无法登录：

• 确认使用的是安装器打印的 console URL，而不是项目资源域名。
• 检查首次管理员 email 是否和安装输入一致。
• 查看安装器输出是否显示 bootstrap 已跳过；如果已跳过，说明实例里已经存在管理员或 owner。
• 看到 401 product_auth_missing 时重新登录；看到 403 product_auth_forbidden 时确认当前用户属于 目标 organization 且有 admin 或 owner role。