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

106 lines
5.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 管理端邮箱与图片验证码登录
服务默认端口 `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` = '替换为已有用户唯一编码';
```