# 管理端邮箱与图片验证码登录 服务默认端口 `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 `,包含组件、用户、操作日志、上传签名和代理资源下载。Swagger 文档可直接打开,在 Authorize 中填入登录返回的 Token 后调试业务接口。 验证码响应 `data`: ```json {"captchaCode":"一次性编码","image":"data:image/png;base64,...","expiresIn":120} ``` 图片为 180×60 PNG,答案 5 位,不区分大小写,忽略首尾空格。默认有效期 2 分钟,每次通过参数校验的登录提交都会消费验证码,答错后也需重新获取。 登录请求: ```json {"email":"admin@example.com","captchaCode":"验证码编码","captchaAnswer":"ABCDE"} ``` 邮箱去除首尾空格并转小写后校验,最多 254 字符。成功响应沿用 `{code,message,data,requestId}`,`data` 如下: ```json { "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`。 ```javascript 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` 文件。 新建管理员: ```sql INSERT INTO `sys_user` (`user_code`, `email`, `nickname`, `status`, `user_type`) VALUES (UPPER(REPLACE(UUID(), '-', '')), LOWER(TRIM('your-admin@example.com')), '管理员', 'ACTIVE', 'ADMIN'); ``` 将已有用户授权为管理员: ```sql UPDATE `sys_user` SET `user_type` = 'ADMIN', `status` = 'ACTIVE' WHERE `user_code` = '替换为已有用户唯一编码'; ```