5.5 KiB
管理端邮箱与图片验证码登录
服务默认端口 8992。仅允许 sys_user 中 status=ACTIVE、user_type=ADMIN 的账号登录;未知邮箱和普通用户返回 403 / ADMIN_ACCESS_DENIED,不自动创建账号或提升权限。流程不发送邮件、不验证邮箱归属,与用户端采用相同的图片验证码交互。
1. 接口与调用
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /admin-api/auth/captcha |
无需登录,获取一次性图片验证码 |
| POST | /admin-api/auth/login |
无需登录,邮箱与图片验证码登录 |
| POST | /admin-api/auth/logout |
撤销当前管理员 Token |
| GET | /admin-api/users/me |
获取当前管理员,不返回数据库主键 |
除验证码、登录和 OPTIONS 预检外,所有 /admin-api/** 业务接口都要求 Authorization: Bearer <token>,包含组件、用户、操作日志、上传签名和代理资源下载。Swagger 文档可直接打开,在 Authorize 中填入登录返回的 Token 后调试业务接口。
验证码响应 data:
{"captchaCode":"一次性编码","image":"data:image/png;base64,...","expiresIn":120}
图片为 180×60 PNG,答案 5 位,不区分大小写,忽略首尾空格。默认有效期 2 分钟,每次通过参数校验的登录提交都会消费验证码,答错后也需重新获取。
登录请求:
{"email":"admin@example.com","captchaCode":"验证码编码","captchaAnswer":"ABCDE"}
邮箱去除首尾空格并转小写后校验,最多 254 字符。成功响应沿用 {code,message,data,requestId},data 如下:
{
"token":"登录凭证",
"tokenType":"Bearer",
"expiresIn":86400,
"user":{"userCode":"0123456789ABCDEF0123456789ABCDEF","nickname":"管理员","email":"admin@example.com"}
}
GET /admin-api/users/me 返回同样的 user 字段内容。Token 默认有效期 24 小时,不滑动续期;同一管理员可同时保持多个登录态,退出仅撤销当前 Token。验证码和登录响应均设置 Cache-Control: no-store。
const challenge = (await (await fetch('/admin-api/auth/captcha')).json()).data;
// challenge.image 用于展示图片;answer 为管理员输入的答案。
const response = await fetch('/admin-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('/admin-api/users/me', {
headers: { Authorization: `Bearer ${token}` }
});
不要将 Token 放在 URL 中。代理图片、模型或下载文件也需通过带认证头的 fetch 或加载器读取。公开 OSS/CDN 地址按资源服务原有方式访问,OSS 直传表单仍使用签名字段,不向 OSS 发送管理端 Token。
2. 权限、上传与审计
- 每次请求从数据库检查状态和角色。禁用或删除用户后已有 Token 返回
401 / UNAUTHORIZED;管理员降级为普通用户后返回403 / ADMIN_ACCESS_DENIED。 - 上传会话绑定当前登录管理员的内部用户主键;不同管理员不能续签或使用对方的上传会话。原配置操作人签发的上传会话需要重新申请。
- 组件操作的审计操作人来自当前管理员的主键和昵称;认证失败只记录运行日志,不伪造业务操作人。multipart 等早期业务失败仍记录真实管理员。
- 用户端和管理端共用验证码与 Token 基础代码,但拥有独立进程缓存和独立身份主体;两端 Token 和验证码不能互用。退出某一端不影响另一端。
| HTTP 状态 | code | 处理方式 |
|---|---|---|
| 400 | CAPTCHA_INVALID |
验证码错误、过期或已消费,重新获取 |
| 401 | UNAUTHORIZED |
未登录、Token 无效或用户已不可用,重新登录 |
| 403 | ADMIN_ACCESS_DENIED |
账号没有管理员权限 |
| 403 | ACCOUNT_DISABLED |
管理员账号已禁用 |
| 422 | INVALID_REQUEST |
邮箱、必填字段或长度不合法 |
| 503 | DATABASE_UNAVAILABLE |
数据库暂不可用,稍后重试 |
3. 配置和初始管理员
验证码和登录态分别使用最多 10000 条的进程内 Caffeine 缓存,按单实例部署;重启、容量淘汰或过期后凭证失效。缓存不影响数据库中的用户和业务数据。
| 配置 | 默认值与说明 |
|---|---|
APP_ADMIN_AUTH_CAPTCHA_TTL |
PT2M,至少 1 秒;未设置时沿用 APP_AUTH_CAPTCHA_TTL |
APP_ADMIN_AUTH_TOKEN_TTL |
PT24H,至少 1 秒;未设置时沿用 APP_AUTH_TOKEN_TTL |
APP_ADMIN_ALLOWED_ORIGINS |
沿用管理端域名白名单,允许 Authorization 请求头;401/403 保留跨域响应头 |
APP_ADMIN_OPERATOR_ID / APP_ADMIN_OPERATOR_NAME 已不再使用。此改造无需新增表字段,沿用上次邮箱用户及 user_code 迁移后的表结构。
首次管理员由数据库预先授权。选择以下一种方式手动执行,替换为实际邮箱或已有用户编码,应用不会自动执行,也未修改 .sql 文件。
新建管理员:
INSERT INTO `sys_user` (`user_code`, `email`, `nickname`, `status`, `user_type`)
VALUES (UPPER(REPLACE(UUID(), '-', '')), LOWER(TRIM('your-admin@example.com')),
'管理员', 'ACTIVE', 'ADMIN');
将已有用户授权为管理员:
UPDATE `sys_user`
SET `user_type` = 'ADMIN', `status` = 'ACTIVE'
WHERE `user_code` = '替换为已有用户唯一编码';