跳到主要内容
版本：Current

认证场景（国内 / 美国）

平台支持 两套互斥的登录方案，按活动现场所在地区与网络环境选用其一。同一套部署 不要混用 两种玩家入口（避免 /login 同时暴露登录码与 OAuth 造成困惑）。

对照总览​

角色国内场景（CN）美国场景（US）
Player/login → 6 位登录码（player-code）/login → Google / Azure AD OAuth
Admin/staff-login → 白名单邮箱 + 密码（staff-credentials）/login 或统一入口 → OAuth，邮箱须在 ADMIN_EMAILS
Display/staff-login → 白名单邮箱 + 密码OAuth，邮箱须在 DISPLAY_EMAILS

国内场景（CN）​

面向文化节等 国内线下活动：玩家无需 Google 账号，工作人员与玩家入口分离。

Player​

  1. Admin 在 /admin 发布登录码
  2. Display /show 大屏展示 6 位码
  3. 玩家打开 /login，CnLoginPanel 输入登录码
  4. NextAuth signIn("player-code") → Backend verify-code → 分配 玩家 #NNN

详见 登录码流程。

Admin / Display​

  1. 打开 /staff-login（不是 /login）
  2. 输入 auth.ts 白名单中的邮箱 + 环境变量 STAFF_ADMIN_PASSWORD / STAFF_DISPLAY_PASSWORD
  3. NextAuth signIn("staff-credentials") → 按角色跳转 /admin 或 /show
信息

国内场景下 不需要 配置 GOOGLE_CLIENT_* / AZURE_AD_*（除非 Staff 也想用 OAuth 作为备选）。

必填环境变量（CN）​

变量用途
STAFF_ADMIN_PASSWORDAdmin 密码登录
STAFF_DISPLAY_PASSWORDDisplay 密码登录
JWT_SECRET / NEXTAUTH_*Session

美国场景（US）​

面向 可稳定访问 Google / Microsoft 账号 的部署：三端均通过 OAuth，无登录码、无 Staff 密码表单。

三端登录​

角色入口Provider
Player/login → UsLoginPanelgoogle 和/或 azure-ad
Admin/login（OAuth 后 middleware 识别 Admin）同上，邮箱 ∈ ADMIN_EMAILS
Display/login同上，邮箱 ∈ DISPLAY_EMAILS
  • 身份标识为 OAuth 返回的 真实 email，大屏显示名一般为邮箱（非 玩家 #NNN）
  • 不使用 POST /api/admin/publish-login-code 与 /staff-login（相关 UI 在 US 构建中隐藏或注释）

启用方式（开发 / 部署）​

  1. 配置 OAuth 环境变量（见 环境变量 美国场景一节）
  2. frontend/src/app/login/page.tsx 启用 RegionToggle、UsLoginPanel，隐藏或注释 CnLoginPanel 为国内专用
  3. 生产环境在 OAuth 控制台登记 NEXTAUTH_URL 回调

详见 添加新功能 — 美区 OAuth。

必填环境变量（US）​

变量用途
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRETGoogle OAuth（常用）
AZURE_AD_*Azure AD（可选）
JWT_SECRET / NEXTAUTH_*Session

不需要 STAFF_*_PASSWORD（除非保留 Staff 作为运维备用入口）。

如何选择场景​

考虑因素建议
现场网络、玩家无 Google国内 + 登录码
玩家与工作人员均有学校/组织 Microsoft 或 Google美国 + OAuth
需要控场、匿名编号、大屏发码国内
长期线上、身份与邮箱审计一致美国

同一 Frontend 代码库通过 登录页组件与构建时 env 切换；BUCSSA 文化节默认 国内场景。

Provider 与 API 对照​

Provider场景用户
player-code国内Player
staff-credentials国内Admin / Display
google美国（+ 可选 Staff）三端
azure-ad美国（+ 可选 Staff）三端

国内场景专用 API：publish-login-code、close-login-code、verify-code（见 REST API）。