106 lines
5.5 KiB
Markdown
106 lines
5.5 KiB
Markdown
# 管理端邮箱与图片验证码登录
|
||
|
||
服务默认端口 `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`:
|
||
|
||
```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` = '替换为已有用户唯一编码';
|
||
```
|