6.5 KiB
邮箱与图片验证码登录
用户端默认端口 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 '登录用户归属摘要,历史匿名归属保留至过期';