Skip to content
邀请码注册运维

邀请码注册运维

本文只讲操作步骤。注册流程的当前实现与边界见 邀请码与邮箱注册。

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-JKLM

list 会显示“可用 / 已占用(待验证邮箱)/ 已使用(用户名)/ 已吊销 / 已过期”。 已使用的邀请码不能吊销,也不会删除已注册账号。

4. 验证注册链路

  1. 打开 /register,填写邮箱、密码和邀请码;
  2. 页面提示“验证邮件已发送”;
  3. 打开邮件里的链接,落到 /register/verify?token=...;
  4. 页面显示“注册成功”并自动进入项目列表;
  5. 退出后可用“邮箱 + 密码”重新登录。

如果邮件没有收到:

  • 先检查垃圾邮件目录;
  • 确认 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_at
  • invite_codes
  • pending_registrations

Compose 部署与 deploy_release.sh 都会按既有迁移机制应用; 首次部署后可用 manage_invite_codes.py list 确认表已就绪。

本地已有的 SQLite 开发库不会被 create_all 补列,需要手动执行:

ALTER TABLE users ADD COLUMN email_verified_at DATETIME;

或直接删除本地开发库后重新 init_db。新库无需这一步。