Funyard 登录方案 v2

产品方案 · 2026-11-13 · 依据:Lin 11-12 至 11-13 的原话 + origin/main(053fc17)代码现状。只做 Lin 说过的;现有功能不重新设计。

结论:主站登录页在现有「邮箱/用户名 + 密码」下面加一个「使用 Google 登录」。新客户只能走 Google,第一次进来填一个我们在后台生成的邀请码,填对才开账号进控制台。老客户照旧用密码;如果他点 Google、且 Google 邮箱和老账号邮箱相同,直接进老账号。后台搬到 admin.funyard.org,只让白名单里的内部人员打开,用管理员账号密码登录;主站 /admin 一律 404。

1. 一页看懂

这次做什么(逐条对应 Lin 的要求)

#Lin 的要求这次落成什么
1保留邮箱密码,增加 Google,两种都能用登录页现有表单不动,下面多一个「使用 Google 登录」按钮。
2新用户只走 Google,要邀请码;不做邮箱密码注册,首页不放注册入口Google 第一次进来先到「填邀请码」页,填对才开账号。没有任何注册页;首页现在就没有注册入口(核实:InvitationEntry.tsx 在 main 上没有被任何页面引用),保持。
3后台配置邀请码:生成 + 过期时间;不限时效后台新增「邀请码」页:一次生成一个码,过期时间可填可不填(不填 = 永不过期);列表看所有码、是否已用、是否过期。一码只能用一次。
4登录态 30 天,存浏览器开发已在单独做(现在代码里是 1 天:auth.ts expiresIn: 86400),本方案不重复。
5后台拆到 admin.funyard.org,只能 admin 账号登录,白名单只放内部人员,注意攻击;主站 /admin 404同一个服务按网址区分主站和后台。后台网址前面挂 Cloudflare 白名单;后台登录只接受管理员账号密码;两边登录状态不互通;主站 /admin 和后台接口一律 404。
6客户用邀请码只登 funyard.org 控制台看自己的数据Google 新客户填码后进入的就是现有控制台 /dashboard,权限和现在的客户一样,只看自己的数据。
7开放注册填邀请码,注意 DDoS,先用免费方案全部用 Cloudflare 免费能力 + 代码里的限流,见第 5 节。
8忘记密码自己找 Google不做任何找回密码功能。
9账号注销暂时不给不做。
10只有 Google 的用户做要输密码的操作:登录了就行只有 Google、没有密码的客户,做现在要输密码确认的操作时,只点「确认」,不输密码。

另:隐私政策和服务条款页面(/privacy、/terms)本期不做(负责人 2026-11-13 决定,PR #114 已关闭),本方案不涉及。

不做什么

绑定/解绑 Google、给 Google 账号设密码、找回密码、注销、邮箱密码注册、任何新的客服或人工核验流程。完整列表见 第 8 节。

谁在哪个网址、用什么方式登录、能看到什么

谁网址怎么登录能看到什么
新客户funyard.org/login只能用 Google;第一次要填邀请码自己的控制台 /dashboard
老客户funyard.org/login和现在一样:用户名或邮箱 + 密码;也可以点 Google,Google 邮箱与老账号邮箱相同时直接进老账号自己的控制台 /dashboard(不变)
内部管理员admin.funyard.org先过 Cloudflare 白名单,再用管理员账号 + 密码内部后台(配置 Key、用户、邀请码等)

2. 三条路径

新客户:Google → 填邀请码 → 控制台

登录页→点「使用 Google 登录」→Google 登录/同意→填邀请码页→控制台

老客户:密码登录,和现在一样

登录页→输用户名或邮箱 + 密码→控制台

老客户如果点了 Google 按钮:

内部管理员:admin.funyard.org

打开 admin.funyard.org→Cloudflare 白名单验证→后台登录页:管理员账号 + 密码→后台
不在白名单→打不开后台网址 非管理员账号→提示账号或密码不正确 主站 funyard.org/admin→404

3. 页面

只画新增或改动的页面。黄色虚线 = 本次新增的元素,其余保持现状。

funyard.org/login(改)
登录 FunYard
用户名或邮箱 / Username or email
输入用户名或邮箱
密码 / Password
输入账户密码
登录 FunYard / Sign in to FunYard
或 / or
G 使用 Google 登录 / Continue with Google

状态(Google 回来失败时显示在按钮上方):

Google 登录没有完成,请重试。
Google sign-in didn't finish. Please try again.
funyard.org/invite(新)
填写邀请码 / Enter invite code

你已用 Google 账号 ann@gmail.com 验证。第一次使用请填写我们发给你的邀请码。
Signed in with Google as ann@gmail.com. Enter the invite code we sent you.

邀请码 / Invite code
例如 K7QM-3XPD-9TRA
进入控制台 / Continue
换个 Google 账号 / Use another Google account

状态:

邀请码不对、已被用过或已过期。
This code is invalid, already used, or expired.
尝试太频繁,请一分钟后再试。
Too many attempts. Try again in a minute.

「换个 Google 账号」= 退出当前登录,回到登录页。

admin.funyard.org/login(新网址)
Funyard 内部后台 / Funyard Admin
用户名或邮箱 / Username or email
密码 / Password
登录后台 / Sign in

没有 Google 按钮。状态:

账号或密码不正确。
Incorrect account or password.

非管理员账号密码对了也显示这句,不透露账号是否存在。登录前一步的白名单页由 Cloudflare 提供,不用我们做。

admin.funyard.org → 邀请码(新)
邀请码 / Invite codes
过期时间(可不填,不填永不过期)/ Expires (optional)
年 / 月 / 日 时:分
生成邀请码 / Generate code
新邀请码 / New code:K7QM-3XPD-9TRA 复制 / Copy
邀请码 / Code生成时间 / Created过期时间 / Expires状态 / Status
K7QM-3XPD-9TRA11-13 10:02不过期 / Never可用 / Unused
P2WD-8HNC-4LXE11-12 18:4011-20 00:00已用 / Used
R9TB-6KQA-2MVF11-01 09:1511-10 00:00已过期 / Expired

点「生成」按后台现有写操作规矩弹出密码确认(现有组件,不新做)。列表按生成时间倒序。

其他页面跟着变的一处:控制台「安全设置」里的「修改密码」,只有 Google 的客户不显示(他们没有密码可改)。要输密码确认的弹窗,对他们只显示「确认 / Confirm」按钮,没有密码框(要求 10)。

CLI 授权页(/cli/authorize)复用同一个登录表单,所以也会出现 Google 按钮;否则只有 Google 的客户无法授权 CLI。

4. 后端

术语:Worker = 跑在 Cloudflare 上的我们的服务(一个程序同时服务主站和后台)。Better Auth = 我们用的登录库(1.7.10,已锁版本),负责密码校验、Google 登录、发登录凭证。D1 = Cloudflare 的数据库,存账号和登录状态。账本 = 存余额、Key、调用记录的另一个存储(Durable Object),本次只调用现有「开户」动作。会话 = 浏览器里那张登录凭证(cookie)对应的服务器记录。

整体结构

客户浏览器funyard.org 内部人员浏览器admin.funyard.org CloudflareDDoS 防护 · 已有 Cloudflare 白名单Access · 新配 Worker(同一个) 按网址分流 主站密码 + Google 登录/admin → 404 后台只有密码登录只放管理员 Better Auth(登录库)在 Worker 里运行 Google只确认「你是谁」 D1:账号 / 会话 / 邀请码 账本:开户、余额、Key

Google 只告诉我们「这个人是哪个 Google 账号、邮箱是什么」。我们不存 Google 密码,也不替用户管 Google 账号(要求 8)。

数据表改动(D1)

表 · 字段用途对应要求
新表 invite_codes
code(主键)邀请码本身,12 位随机字母数字,展示成 XXXX-XXXX-XXXX。后台要能看到码,所以存原文。3
created_at生成时间,列表排序和展示用。3
expires_at(可空)过期时间;空 = 永不过期。3
used_by(可空)被哪个账号用掉;非空 = 已用。保证一码一次。2、3
现有表加一列
session.site这张登录凭证属于 main(主站)还是 admin(后台)。两边只认自己的,登录状态不互通。5
现有字段新增一个取值(不改表结构)
user.role = 'pending'「已过 Google、还没填码」。现有取值 customer / admin 不变。2
沿用、不改:user(Google 用户的邮箱、名字写这里)、account(登录库本来就用它记「这个人用 Google 登录」:providerId='google',没有密码)、verification(登录库存 Google 跳转的防伪参数,10 分钟过期)。

新增接口

接口谁能调做什么成功失败要求
POST /api/auth/sign-in/social
登录库自带,主站放开
任何人(仅主站)开始 Google 登录,{provider:'google', callbackURL:'/dashboard', newUserCallbackURL:'/invite', errorCallbackURL:'/login'}返回 Google 授权网址,浏览器跳过去429 太频繁1
GET /api/auth/callback/google
登录库自带,主站放开
Google 跳回确认 Google 身份;已有 Google 登录的、或 Google 已验证邮箱与现有账号相同的,直接发该账号的会话;其余新用户建 pending 账号并发会话跳 /dashboard(老)或 /invite(新)跳 /login?error=…:Google 登录没有完成1、2
POST /funyard/account/invite/redeem已登录且 role='pending'{code} 校验并用掉邀请码,开账本,转为客户{ok:true} → 前端进 /dashboard400 INVALID_INVITE_CODE(不存在/已用/过期,统一一句)、429、401 未登录2、6
GET /funyard/account/verify/method已登录客户告诉前端确认弹窗要不要密码框{method:'password'} 或 {method:'session'}40110
GET /funyard/admin/invite-codes后台管理员(仅后台网址)列出全部邀请码,状态由 used_by/expires_at 算出{codes:[{code,created_at,expires_at,status}]}404(非管理员/主站,与现有后台一致)3
POST /funyard/admin/invite-codes后台管理员 + 现有密码确认{expires_at|null} 生成一个码{code,expires_at}404、403 未确认、400 过期时间早于现在3

另外两处现有接口改行为:/funyard/account/* 对 pending 一律返回 403 INVITE_CODE_REQUIRED(只放行 invite/redeem),前端据此跳 /invite;/funyard/account/verify 对没有密码的账号免密(见下)。

时序:从点 Google 到进控制台

浏览器 Worker + Better Auth Google D1 账本 ① 点 Google:POST sign-in/social ② 存防伪参数(verification,10 分钟) ③ 返回 Google 网址 ④ 用户在 Google 登录、同意 ⑤ 回调 callback/google?code&state ⑥ 用 code 换身份(邮箱、名字、Google ID) ⑦ 查 Google ID 或同邮箱(Google 已验证)是否已有账号  已有 → 发会话,跳 /dashboard(结束) ⑧ 新人:写 user(role=pending) + account(google) + session ⑨ 种 cookie,跳 /invite 「已过 Google、没填码」= D1 里 role=pending 的账号 + 它的会话;24 小时内没填码,定时任务删除账号和会话 ⑩ 填码:POST invite/redeem ⑪ 码未用、未过期 → 标记 used_by=此人 ⑫ 开户(现有动作:零余额、默认限额,可重试不重复) ⑬ role: pending → customer ⑭ {ok:true} ⑮ 进入 /dashboard ⑪ 成功后若 ⑫ 失败:码已绑定此人,再点一次「进入控制台」从 ⑫ 继续,不会被判为「码已用」。

已知技术风险(如实)

  1. 登录库不直接支持「先 Google、填码之后才建账号」。核实 Better Auth 1.7.10(oauth2/link-account.mjs):Google 回调时新用户会被当场写进 user 表;能关掉自动注册(disableImplicitSignUp),但关掉后 Google 身份直接丢弃,回不到填码这一步。
    做法:不关,用登录库的「建用户前」钩子(databaseHooks.user.create.before)把 Google 新用户标成 role='pending';pending 不开账本、不能用任何控制台功能,填码成功才转为 customer 并开户。
    风险:任何有 Google 账号的人都能留下一条 pending 行 → 每 IP 限流 + 24 小时清理(第 5 节);后台用户列表里会短暂看到这些行。
  2. 同邮箱直接进老账号(Lin 2026-11-13 决定)怎么实现。核实 Better Auth 1.7.10(oauth2/link-account.mjs):Google 回调时,若找不到这个 Google ID,会按邮箱找现有账号;能否直接挂上取决于登录库的「账号关联」配置。现在是关着的(auth.ts accountLinking.enabled:false,登录库返回 account not linked)。
    做法:只改配置,不写新界面:accountLinking: { enabled: true, requireLocalEmailVerified: false },不把 google 放进 trustedProviders。这样登录库只在 Google 返回「邮箱已验证」时才挂到老账号(不信任的来源必须 emailVerified=true),挂上后在 account 表多一行 providerId='google',老账号的密码、Key、余额、角色都不动(updateUserInfoOnLink 保持默认关,不改名字)。系统里只配了 Google 一个外部登录,主动关联接口(/link-social)仍被网关挡住,所以没有绑定入口。
    为什么要 requireLocalEmailVerified:false:现有账号的 emailVerified 全是 0(邀请、批量、旧系统导入都按 0 写入),不关这项就一个也挂不上。
    安全前提(如实):谁能用这个邮箱通过 Google 验证,谁就能进这个老账号。所以前提是老账号登记的邮箱确实属于本人;如果当初录错成别人的邮箱,那个人用 Google 就能进来。内部占位邮箱(如 @migration.invalid、@example.invalid)收不到信,不受影响。
    升级风险:登录库把 requireLocalEmailVerified 标为下个小版本移除(届时强制要求本地邮箱已验证)。我们锁在 1.7.10 不受影响;以后升级登录库前必须先处理这一点,否则同邮箱关联会失效。
  3. 同邮箱的管理员账号:Google 邮箱若与某个管理员账号相同,在主站会登录进那个账号,但主站不给任何后台能力(/admin、/funyard/admin/* 一律 404);后台 admin.funyard.org 只认后台网址上的密码登录会话,Google 会话进不去。不新增规则。

后台独立站:同一个服务怎么分开

只有 Google 的用户怎么过「输密码确认」(要求 10)

核实 main 现状:客户侧要输密码确认的操作是这 3 个(auth-gateway.ts validateVerificationOperation + accounting.ts):

操作现在只有 Google 的客户
撤销 API Key(key.revoke,控制台 Key 页)输当前密码只点「确认」
创建 API Key(key.create,接口支持;控制台目前没有入口,Key 由 CLI 授权产生)输当前密码只点「确认」
修改密码(auth.account.write)输当前密码不适用,页面不显示
CLI 授权不输密码(已登录即可)不变

放行方式:/funyard/account/verify 发「一次性确认凭证」前,查 D1 account 表这个人有没有密码(providerId='credential')。有 → 照旧要密码(包括用同邮箱 Google 进来的老账号:他本来有密码,确认时仍输密码,和现在一样)。没有 → 不要密码,其余检查全部照旧:必须来自本站、会话有效、安全版本一致、每人每分钟 5 次、凭证只对这一次操作有效。后台的 admin.write 不受影响(管理员都是密码账号)。

5. 防攻击(只用免费手段)

手段挡什么放在哪要求
Cloudflare 代理与 DDoS 防护(已有,免费)大流量冲击两个域名前面7
入口限流:每 IP 每分钟 600 次(已有)单 IP 刷任意接口Worker 最前面7
发起 Google 登录:每 IP 每分钟 10 次(新加一条规则)批量制造 pending 账号登录库限流 /sign-in/social7
填码:每账号每分钟 5 次、每 IP 每分钟 30 次猜邀请码redeem 接口(用现有 account_lifecycle_limits 计数表)7
邀请码 12 位随机(约 60 位熵)猜邀请码生成时7
pending 24 小时清理垃圾账号堆积现有每分钟定时任务7
Cloudflare Access 白名单(免费 50 人内)外部人打开后台admin.funyard.org 前5
后台密码登录:每 IP 每分钟 5 次(已有)撞密码登录库限流5
主站 /admin 404 + 会话分站 + 只放管理员探测后台、拿主站登录进后台Worker5

6. 要改的现行规矩(AGENTS.md)

现行文字改成
Accounts use password-only authentication. Passkey/TOTP HTTP endpoints are disabled; retain legacy identity schemas for existing data.Customers sign in on funyard.org with password or Google; new customers can only join through Google plus a one-time admin-issued invite code. Admins sign in only at admin.funyard.org with password. Passkey/TOTP HTTP endpoints are disabled; retain legacy identity schemas for existing data.
Sensitive mutations require password-confirmed scoped proofs and session authentication epochs, except CLI approval: explicit consent uses the current browser session and bound grant.Sensitive mutations require scoped proofs and session authentication epochs. Accounts with a password confirm with it; Google-only accounts (no password) confirm with the current session. CLI approval: explicit consent uses the current browser session and bound grant.

同一个 PR 里按 docs/README.md 规矩同步更新 docs/ACCOUNT-RECOVERY.md 开头的「统一使用密码登录」一句和 client/AUTH_CONTRACT.md 的 Current policy 段。

7. 上线步骤

依据 docs/AUTO-DEPLOY.md、scripts/production-policy.json:新增 server/migrations/ 文件或改 server/wrangler.production.jsonc 都会被发布门禁拦住,自动发布不跑数据库迁移、不改域名,必须维护者单独做云验收后登记策略才能上线。core.ts(账本结构)本方案不改。

步开发内容维护者云验收Lin 亲手配置
1后台独立站:按网址分流、主站 /admin 404、session.site 列(D1 迁移 0007)、后台只放管理员、生产配置加 admin.funyard.org 域名和后台网址变量。要:D1 迁移 + 生产配置改动,在隔离环境验收后登记策略;验收后由维护者绑定域名。Cloudflare Zero Trust → Access:为 admin.funyard.org 建应用,白名单填内部人员邮箱(登录方式选邮箱验证码)。先配白名单,再绑域名,避免后台裸露。
2Google 登录 + 邀请码:invite_codes 表(D1 迁移 0008)、登录页 Google 按钮、/invite 页、redeem 接口、pending 拦截与清理、后台邀请码页、无密码账号免密确认、上面的 AGENTS.md 改动。要:D1 迁移验收后登记策略;预发用真 Google 账号走一遍新客户、老客户、同邮箱三条路。Google Cloud Console:建项目 → OAuth 同意屏幕(外部、应用名 Funyard、只要 email/profile 权限、填 /privacy /terms 链接、发布为正式)→ 建「Web 应用」凭据,回调地址填 https://funyard.org/api/auth/callback/google(预发另加预发地址)→ 把 Client ID / Secret 交给维护者用 wrangler secret put 存为 Worker 密钥,不进仓库。

两步都改 server/src/index.ts,必须先 1 后 2 串行。登录态 30 天那件事独立进行,不依赖这两步。

开发按默认做法进行的点(第 1 条已由 Lin 决定)

  1. Google 邮箱与老账号同邮箱:已由 Lin 决定(2026-11-13)——直接进老账号,无任何界面和提示。实现见第 4 节「已知技术风险」。
  2. 白名单方式:用 Cloudflare Access 按内部人员邮箱放行(免费 50 人内),而不是固定 IP(内部人员网络会变)。
  3. 后台现有「邀请与人工恢复」页(管理员手工发设密码链接、批量内测账号、找回链接)保持原样不动。这是管理员手工开号/恢复的内部工具,不是公开注册;本次不改也不删。

8. 没做清单