邀请码注册运维
本文只讲操作步骤。注册流程的当前实现与边界见 邀请码与邮箱注册。
1. 配置邮件发送
生产环境必须配置 SMTP,否则非 DEBUG 环境的注册接口会返回 503:
FRONTEND_BASE_URL=https://tim.run.place
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=no-reply@example.com
SMTP_PASSWORD=change-me
SMTP_FROM=no-reply@example.com
SMTP_FROM_NAME=DyeingTime
SMTP_USE_TLS=true
SMTP_USE_SSL=false- 587 端口通常用 STARTTLS:
SMTP_USE_TLS=true、SMTP_USE_SSL=false; - 465 端口通常用 SSL:
SMTP_USE_SSL=true、SMTP_USE_TLS=false; SMTP_FROM留空时回退为SMTP_USERNAME;FRONTEND_BASE_URL必须是用户浏览器能打开的地址,不能填后端 API 地址。
可选调整:
# 验证链接有效期,默认 1440 分钟(24 小时)
REGISTRATION_LINK_EXPIRE_MINUTES=1440
# 同一邮箱重复请求验证邮件的冷却时间,默认 60 秒
REGISTRATION_RESEND_INTERVAL_SECONDS=60本地开发没有 SMTP 时:
DEBUG=true此时验证链接会打印在后端日志里,不会真的发邮件。
2. 生成邀请码
cd backend
uv run python scripts/manage_invite_codes.py create --count 5 --expires-in-days 7 --note "内部测试批次"输出示例:
已生成 5 个邀请码:
DT-ABCD-EFGH-JKLM
...每个邀请码只能注册一个账号。--expires-in-days 不传表示永不过期;
--note 只用于运维辨识。
3. 查看与吊销
cd backend
uv run python scripts/manage_invite_codes.py list
uv run python scripts/manage_invite_codes.py revoke DT-ABCD-EFGH-JKLMlist 会显示“可用 / 已占用(待验证邮箱)/ 已使用(用户名)/ 已吊销 / 已过期”。
已使用的邀请码不能吊销,也不会删除已注册账号。
4. 验证注册链路
- 打开
/register,填写邮箱、密码和邀请码; - 页面提示“验证邮件已发送”;
- 打开邮件里的链接,落到
/register/verify?token=...; - 页面显示“注册成功”并自动进入项目列表;
- 退出后可用“邮箱 + 密码”重新登录。
如果邮件没有收到:
- 先检查垃圾邮件目录;
- 确认
SMTP_HOST/ 账号密码 / 发件人配置正确; - 本地开发可设置
DEBUG=true,从后端日志复制验证链接; - 60 秒内重复提交会返回 429,这是邮件冷却,不是邀请码失效。
5. 常见错误
| 提示 | 原因 | 处理 |
|---|---|---|
| 邀请码无效、已使用或已过期 | 码不存在、已被消费、被吊销或过期 | 重新生成一个邀请码 |
| 邀请码已被其他注册流程占用 | 同一个码已发给另一个邮箱且链接未过期 | 等链接过期,或吊销后重新发码 |
| 该邮箱已注册,请使用原登录方式 | users.email 已存在(含 Google 账号) | 用原方式登录,或换邮箱 |
| 验证链接已过期,请重新注册 | 超过 REGISTRATION_LINK_EXPIRE_MINUTES | 回注册页重新提交 |
| 验证邮件已发送,请稍后再试 | 60 秒冷却期内重复提交 | 等待冷却结束 |
| 验证邮件发送失败 / 邮件服务未配置 | SMTP 配置错误或缺失 | 检查 SMTP 配置与后端日志 |
6. 数据库迁移
新增表与列在 backend/sql/054-add-email-invite-registration.sql:
users.email_verified_atinvite_codespending_registrations
Compose 部署与 deploy_release.sh 都会按既有迁移机制应用;
首次部署后可用 manage_invite_codes.py list 确认表已就绪。
本地已有的 SQLite 开发库不会被 create_all 补列,需要手动执行:
ALTER TABLE users ADD COLUMN email_verified_at DATETIME;或直接删除本地开发库后重新 init_db。新库无需这一步。