邀请码与邮箱注册
本文属于“当前架构”文档,描述已经生效的邀请制邮箱注册流程。
为什么是两阶段注册
团队使用邀请制,但邀请码不能代替邮箱验证:
- 邀请码只回答“这个人被允许注册”,不能证明邮箱属于本人;
- 如果提交表单就直接建号,填错邮箱会占用
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…。用户不需要额外想一个登录名。
自动加入默认工作区
新账号如果没有任何工作区,登录后访问业务接口会得到 “当前账号未加入任何工作区”。注册流程在创建账号的同一事务里完成加入:
- 优先加入启用中的
ws-default; - 没有
ws-default时,加入最早创建的启用工作区; - 系统里一个工作区都没有时,创建
ws-default,注册者为owner。
加入既有工作区的角色固定为 editor:可读写内容,但不能管理成员。
ws-default 被管理员停用且没有其他可用工作区时,注册返回 503,
不会擅自重新启用工作区。
接口与错误语义
| 接口 | 说明 |
|---|---|
POST /api/v1/auth/register | 校验邀请码并发送验证链接,不创建账号 |
POST /api/v1/auth/register/verify | 校验链接、创建账号、返回 JWT |
| 状态码 | 场景 |
|---|---|
400 | 邀请码无效/已使用/已过期;链接无效、已使用或已过期 |
409 | 邮箱已注册;邀请码被其他注册流程占用;邀请码并发消费失败 |
429 | 同一邮箱在冷却时间内重复请求验证邮件 |
503 | SMTP 未配置或发送失败;默认工作区被停用且无可用工作区 |
公开接口不会返回 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 账号转成邮箱密码账号;同一邮箱已注册时直接提示登录。
- 邀请码被待验证申请占用时,管理员只能等待过期或吊销后重新发码。