Funyard 登录方案 v2
产品方案 · 2026-11-13 · 依据:Lin 11-12 至 11-13 的原话 + origin/main(053fc17)代码现状。只做 Lin 说过的;现有功能不重新设计。
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 登录,仍回到填码页(24 小时内);超过 24 小时,从头再走一遍 Google。
- 这个 Google 账号以前填过码:直接进控制台,不再问码。
老客户:密码登录,和现在一样
老客户如果点了 Google 按钮:
- Google 邮箱和老账号邮箱相同(Google 确认过这个邮箱):直接进他的老账号控制台。没有任何新页面、没有绑定页、没有提示。之后他用密码或 Google 都进同一个账号(Lin 2026-11-13 决定)。
- Google 邮箱和老账号邮箱不同:等同新客户,要填邀请码才会开一个新的账号,和老账号无关。
内部管理员:admin.funyard.org
3. 页面
只画新增或改动的页面。黄色虚线 = 本次新增的元素,其余保持现状。
状态(Google 回来失败时显示在按钮上方):
Google sign-in didn't finish. Please try again.
你已用 Google 账号 ann@gmail.com 验证。第一次使用请填写我们发给你的邀请码。
Signed in with Google as ann@gmail.com. Enter the invite code we sent you.
状态:
This code is invalid, already used, or expired.
Too many attempts. Try again in a minute.
「换个 Google 账号」= 退出当前登录,回到登录页。
没有 Google 按钮。状态:
Incorrect account or password.
非管理员账号密码对了也显示这句,不透露账号是否存在。登录前一步的白名单页由 Cloudflare 提供,不用我们做。
| 邀请码 / Code | 生成时间 / Created | 过期时间 / Expires | 状态 / Status |
|---|---|---|---|
| K7QM-3XPD-9TRA | 11-13 10:02 | 不过期 / Never | 可用 / Unused |
| P2WD-8HNC-4LXE | 11-12 18:40 | 11-20 00:00 | 已用 / Used |
| R9TB-6KQA-2MVF | 11-01 09:15 | 11-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)对应的服务器记录。
整体结构
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} → 前端进 /dashboard | 400 INVALID_INVITE_CODE(不存在/已用/过期,统一一句)、429、401 未登录 | 2、6 |
GET /funyard/account/verify/method | 已登录客户 | 告诉前端确认弹窗要不要密码框 | {method:'password'} 或 {method:'session'} | 401 | 10 |
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 到进控制台
已知技术风险(如实)
- 登录库不直接支持「先 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 节);后台用户列表里会短暂看到这些行。 - 同邮箱直接进老账号(Lin 2026-11-13 决定)怎么实现。核实 Better Auth 1.7.10(
oauth2/link-account.mjs):Google 回调时,若找不到这个 Google ID,会按邮箱找现有账号;能否直接挂上取决于登录库的「账号关联」配置。现在是关着的(auth.tsaccountLinking.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 不受影响;以后升级登录库前必须先处理这一点,否则同邮箱关联会失效。 - 同邮箱的管理员账号:Google 邮箱若与某个管理员账号相同,在主站会登录进那个账号,但主站不给任何后台能力(
/admin、/funyard/admin/*一律 404);后台admin.funyard.org只认后台网址上的密码登录会话,Google 会话进不去。不新增规则。
后台独立站:同一个服务怎么分开
- 按网址分流:同一个 Worker 再绑一个域名
admin.funyard.org。请求进来先看网址:- 后台网址只放行:后台页面、
/api/auth的密码登录/查询会话/退出、/funyard/admin/*、密码确认/funyard/account/verify;其余(控制台、Google 登录、/funyard/v1等)404。 - 主站网址:
/admin、/admin/*、/funyard/admin/*一律 404,管理员登录了也一样(现在是管理员能看到,要改)。
- 后台网址只放行:后台页面、
- 登录状态不互通:两边各用一套登录配置(后台的网址、cookie 名
funyard-admin、不开 Google)。浏览器 cookie 只发给种它的那个网址;服务器再用session.site双保险:后台只认admin会话,主站只认main会话,复制 cookie 也用不了。 - 只放管理员:后台登录时,密码对但账号不是
admin,不发会话,返回和密码错一样的提示。 - 现有的管理员账号、后台功能、后台写操作的密码确认都不变,只是换了网址。
只有 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/social | 7 |
| 填码:每账号每分钟 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 + 会话分站 + 只放管理员 | 探测后台、拿主站登录进后台 | Worker | 5 |
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 建应用,白名单填内部人员邮箱(登录方式选邮箱验证码)。先配白名单,再绑域名,避免后台裸露。 |
| 2 | Google 登录 + 邀请码: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 决定)
- Google 邮箱与老账号同邮箱:已由 Lin 决定(2026-11-13)——直接进老账号,无任何界面和提示。实现见第 4 节「已知技术风险」。
- 白名单方式:用 Cloudflare Access 按内部人员邮箱放行(免费 50 人内),而不是固定 IP(内部人员网络会变)。
- 后台现有「邀请与人工恢复」页(管理员手工发设密码链接、批量内测账号、找回链接)保持原样不动。这是管理员手工开号/恢复的内部工具,不是公开注册;本次不改也不删。
8. 没做清单
- 邮箱密码注册、首页注册入口
- 绑定/解绑 Google 的界面,任何账号合并操作(同邮箱 Google 自动进老账号是 Lin 定的,不需要用户操作)
- 给 Google 账号设置密码
- 找回密码、重置密码(任何方式)
- 账号注销
- 后台用 Google 登录
- 新增的联系客服、人工恢复、人工核验流程和文案
- 邀请码批量生成、可用次数配置、作废、使用记录详情(谁用的、何时用)
- 注册每日上限、紧急开关、自动暂停、风险提示、重新验证
- 人机验证(Turnstile 等)
- 退出所有设备
- 注册来源统计、条款版本记录
- 新客户开户赠送额度(沿用现有开户:零余额、默认限额)
- Passkey、两步验证恢复