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

5.5 KiB
Raw Permalink Blame History

管理端邮箱与图片验证码登录

服务默认端口 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` = '替换为已有用户唯一编码';