Skip to content
邀请码与邮箱注册

邀请码与邮箱注册

本文属于“当前架构”文档,描述已经生效的邀请制邮箱注册流程。

为什么是两阶段注册

团队使用邀请制,但邀请码不能代替邮箱验证:

  • 邀请码只回答“这个人被允许注册”,不能证明邮箱属于本人;
  • 如果提交表单就直接建号,填错邮箱会占用 users.email / users.username 唯一约束,留下无法登录的僵尸账号;
  • 一次性邀请码也不应该在“还没验证邮箱”时就被消费。

因此注册拆成两步:

提交邮箱 + 密码 + 邀请码
        │
        ▼
POST /api/v1/auth/register
        │  校验邀请码、邮箱唯一性、重发冷却
        │  写入 pending_registrations(只存 token 哈希 / 密码哈希)
        │  发送验证链接
        ▼
用户点击邮件链接 → 前端 /register/verify?token=...
        │
        ▼
POST /api/v1/auth/register/verify
        │  校验 token、有效期、邮箱与邀请码
        │  原子消费邀请码
        │  创建 users 行
        │  加入默认工作区
        ▼
返回 JWT,直接进入工作台

数据模型

表作用关键字段
invite_codes一次性邀请码code 唯一、expires_at、used_by_id、used_at、is_active
pending_registrations待邮箱验证的申请token_hash 唯一、email、password_hash、invite_code_id、expires_at、consumed_at
users正式账号新增 email_verified_at

设计取舍:

  • 验证链接只存哈希。邮件里的原始 token 不落库,数据库泄露也无法直接重放。
  • 密码在申请阶段就哈希。pending_registrations.password_hash 是 bcrypt 结果, 与正式账号使用同一套哈希,不保存明文。
  • 邀请码不存哈希。管理员需要在 CLI 中重新查看并转发;它的安全边界是 「一次性 + 可过期 + 可吊销」,不是长期密钥。
  • 不删除记录。邀请码使用后保留 used_by_id,待验证记录失效后保留 consumed_at,便于排查“这个码被谁用了”。

一次性语义与并发边界

邀请码软占用

发送验证邮件时,同一个邀请码只允许存在一个未完成的待验证邮箱:

  • 同一个邮箱重复提交(重发链接)会作废旧申请,不额外占用邀请码;
  • 另一个邮箱使用同一邀请码会被 409 拒绝,避免多人同时抢码;
  • 待验证申请过期后,邀请码自动释放给下一次提交。

最终消费是原子操作

验证成功时才真正消费邀请码:

UPDATE invite_codes
SET used_by_id = :user_id, used_at = :now
WHERE id = :invite_id
  AND is_active = 1
  AND used_by_id IS NULL

只有 rowcount = 1 才继续提交账号;否则整个事务回滚。 即使两个验证请求同时到达,也只会有一个账号创建成功。

链接一次性

pending_registrations.consumed_at 在验证成功后写入;同一 token 再次提交会返回 “验证链接无效或已使用”。新申请会作废同邮箱的旧申请,因此只有最新邮件里的链接有效。

邮箱与登录

  • 邮箱统一小写存储;users.email 保持唯一约束。
  • 注册成功后 users.auth_provider = "local",email_verified_at 记录验证时间。
  • Google 登录创建的账号 email_verified_at 仍为 NULL:Google 已验证邮箱, 但这不是“本地邮箱注册”。
  • 登录接口 POST /api/v1/auth/login 的 username 字段同时接受:
    • 原有用户名;
    • 注册邮箱(大小写不敏感)。

前端登录页文案因此改为“邮箱 / 账号”。

注册时的 username 由邮箱 @ 前部分自动生成并清洗为 [a-z0-9_.-]; 若与已有用户名冲突,依次追加 -2、-3…。用户不需要额外想一个登录名。

自动加入默认工作区

新账号如果没有任何工作区,登录后访问业务接口会得到 “当前账号未加入任何工作区”。注册流程在创建账号的同一事务里完成加入:

  1. 优先加入启用中的 ws-default;
  2. 没有 ws-default 时,加入最早创建的启用工作区;
  3. 系统里一个工作区都没有时,创建 ws-default,注册者为 owner。

加入既有工作区的角色固定为 editor:可读写内容,但不能管理成员。 ws-default 被管理员停用且没有其他可用工作区时,注册返回 503, 不会擅自重新启用工作区。

接口与错误语义

接口说明
POST /api/v1/auth/register校验邀请码并发送验证链接,不创建账号
POST /api/v1/auth/register/verify校验链接、创建账号、返回 JWT
状态码场景
400邀请码无效/已使用/已过期;链接无效、已使用或已过期
409邮箱已注册;邀请码被其他注册流程占用;邀请码并发消费失败
429同一邮箱在冷却时间内重复请求验证邮件
503SMTP 未配置或发送失败;默认工作区被停用且无可用工作区

公开接口不会返回 SMTP 原始错误、token 哈希或邀请码是否存在等内部细节。

邮件发送

app/core/mailer.py 负责 SMTP 发送:

  • 587 端口默认 STARTTLS,465 端口使用 SMTP_USE_SSL=true;
  • 验证链接指向 FRONTEND_BASE_URL/register/verify?token=...;
  • 非 DEBUG 环境未配置 SMTP_HOST 时直接返回 503;
  • DEBUG=true 且未配置 SMTP 时,链接写入后端日志,方便本地联调。

验证链接有效期由 REGISTRATION_LINK_EXPIRE_MINUTES 控制,默认 24 小时; 邮件重发冷却由 REGISTRATION_RESEND_INTERVAL_SECONDS 控制,默认 60 秒。

邀请码管理

当前没有邀请码管理 HTTP API 或管理页面,统一走 CLI:

cd backend
uv run python scripts/manage_invite_codes.py create --count 5 --expires-in-days 7 --note "批次"
uv run python scripts/manage_invite_codes.py list
uv run python scripts/manage_invite_codes.py revoke DT-XXXX-XXXX-XXXX

这样做的原因:邀请码属于低频、强审计的运维动作,先不引入新的全局管理员角色 和一套管理后台页面;等出现“非技术人员需要自助发码”的真实需求再补。

当前边界

  • 不支持邮箱找回密码、修改邮箱、重新发送验证邮件按钮;重发通过重新提交注册表单完成。
  • 不把邀请码绑定到指定邮箱;一次性码可以发给任何未注册邮箱。
  • 不自动把已存在的 Google 账号转成邮箱密码账号;同一邮箱已注册时直接提示登录。
  • 邀请码被待验证申请占用时,管理员只能等待过期或吊销后重新发码。