Files
2026-10-19 17:21:23 +08:00

6.5 KiB
Raw Permalink Blame History

邮箱与图片验证码登录

用户端默认端口 8991。除 GET /api/auth/captcha、POST /api/auth/login 和跨域预检外,所有 /api/** 业务接口都需要 Authorization: Bearer <token>,包括组件详情、匹配、需求会话、私有图片和 SSE。JSON 返回统一为 {code, message, data, requestId}。

此流程沿用参考项目:邮箱与图片验证码登录,首次自动注册;不发送邮件、不验证邮箱归属。user_type 不作为客户端可提交字段。用户端仅返回唯一 userCode,不暴露数据库主键。

1. 接口

获取验证码

GET /api/auth/captcha,无需登录,响应设置 Cache-Control: no-store。

{
  "code": "OK",
  "message": "success",
  "data": {
    "captchaCode": "一次性验证码编码",
    "image": "data:image/png;base64,...",
    "expiresIn": 120
  },
  "requestId": "请求编号"
}

图片为 180×60 PNG,包含 5 位数字或大写字母。image 可直接作为验证码图片的 src。有效期默认 120 秒,答案忽略大小写和首尾空格。每次有效参数的登录提交都会消费对应验证码,答错后也必须重新获取。

登录

POST /api/auth/login,Content-Type: application/json,无需登录。

{"email":"user@example.com","captchaCode":"验证码编码","captchaAnswer":"ABCDE"}

邮箱去除首尾空格、转小写后校验,最长 254 字符;验证码编码和答案必填,最长分别为 64、32 字符。成功示例:

{
  "code": "OK",
  "message": "success",
  "data": {
    "token": "登录凭证",
    "tokenType": "Bearer",
    "expiresIn": 86400,
    "user": {
      "userCode": "0123456789ABCDEF0123456789ABCDEF",
      "nickname": "用户_01234567",
      "email": "user@example.com"
    }
  },
  "requestId": "请求编号"
}

首次登录创建 ACTIVE / NORMAL 用户,昵称为“用户_用户编码前8位”。同邮箱并发首次登录复用同一用户。用户编码创建后不可修改。

Token 是 32 字节安全随机值的无填充 Base64URL 编码,有效期默认 24 小时;访问不续期。同一用户可持有多个 Token。

当前用户与退出

  • GET /api/users/me:返回 data={userCode,nickname,email}。
  • POST /api/auth/logout:撤销当前 Token,返回 data=null,其他登录态继续有效。再次使用已撤销 Token 返回 401。

以上接口均须携带 Bearer Token。用户被后台禁用后,登录返回 403,已有 Token 在下一次业务请求时被拒绝。

HTTP 状态 code 处理方式
400 CAPTCHA_INVALID 验证码错误、过期或已消费,重新获取图片
401 UNAUTHORIZED 未登录、Token 无效或账号已不可用,重新登录
403 ACCOUNT_DISABLED 用户已禁用,联系管理员
422 INVALID_REQUEST 检查邮箱、必填字段、长度或未知字段
503 DATABASE_UNAVAILABLE 数据库暂不可用,稍后重试
503 USER_CODE_EXHAUSTED 用户编码分配重试失败,稍后重试

2. 前端调用与需求归属

const challenge = (await (await fetch('/api/auth/captcha')).json()).data;
// 将 challenge.image 展示给用户,answer 为用户输入的图片答案。
const response = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email, captchaCode: challenge.captchaCode, captchaAnswer: answer })
});
if (!response.ok) throw await response.json();
const { token } = (await response.json()).data;

const current = await fetch('/api/users/me', {
  headers: { Authorization: `Bearer ${token}` }
});

// 私有图片需要认证头,通过 Blob URL 展示,Token 不放在 URL 中。
const imageResponse = await fetch(previewUrl, {
  headers: { Authorization: `Bearer ${token}` }
});
if (!imageResponse.ok) throw await imageResponse.json();
const objectUrl = URL.createObjectURL(await imageResponse.blob());
imageElement.src = objectUrl;
// 图片不再使用时执行 URL.revokeObjectURL(objectUrl)。

POST SSE 同样在 fetch 的 headers 中携带 Authorization,详见 需求联调文档。不再需要访客 Cookie 或 credentials: 'include'。

会话归属由服务端认证的 userCode 决定,存储为 SHA-256("user:" + userCode)。同一用户在不同设备登录后可通过原业务编码访问自己的会话;其他用户访问返回 404。客户端不传 userId、userCode 或归属摘要来指定所有者。

历史匿名 Cookie 不授予访问权,也不会触发会话认领。历史匿名数据保留至现有过期任务清理。

3. 配置与运行

环境变量 默认值 说明
APP_AUTH_CAPTCHA_TTL PT2M 验证码有效期,至少 1 秒
APP_AUTH_TOKEN_TTL PT24H 登录态有效期,至少 1 秒
APP_DEMAND_ALLOWED_ORIGINS 沿用各环境配置 /api/** 跨域白名单,允许 Authorization 请求头

验证码和登录态分别使用最多 10000 条的 Caffeine 缓存。当前按单实例部署;重启、缓存容量淘汰或有效期结束后凭证失效。用户和会话数据持久化保留;多实例共享登录态需后续切换为共享存储。

用户端和管理端分别引入自己的安全模块,独立保存 Token 和验证码。后台用户管理使用邮箱,删除入口改为禁用账号;上传与审计使用真实登录管理员。

4. 发布前手动执行的迁移 SQL

以下 SQL 基于提供的邮箱版 sys_user(索引名 uk_sys_user_phone,索引列为 email),仅执行一次;已有该字段或索引的环境先核对结构。应用不自动迁移,仓库 .sql 文件未修改。先执行 SQL,再发布用户端和管理端新代码。

ALTER TABLE `sys_user`
  ADD COLUMN `user_code` char(32)
    CHARACTER SET ascii COLLATE ascii_bin
    NULL COMMENT '用户唯一编码,对外使用且创建后不可修改'
    AFTER `id`;

UPDATE `sys_user`
SET `user_code` = UPPER(REPLACE(UUID(), '-', ''))
WHERE `user_code` IS NULL;

ALTER TABLE `sys_user`
  MODIFY COLUMN `user_code` char(32)
    CHARACTER SET ascii COLLATE ascii_bin
    NOT NULL COMMENT '用户唯一编码,对外使用且创建后不可修改',
  ADD UNIQUE KEY `uk_sys_user_code` (`user_code`),
  RENAME INDEX `uk_sys_user_phone` TO `uk_sys_user_email`;

ALTER TABLE `robot_demand_conversation`
  MODIFY COLUMN `owner_hash` char(64)
    CHARACTER SET ascii COLLATE ascii_bin
    NOT NULL COMMENT '登录用户归属摘要,历史匿名归属保留至过期';