forked from datawhale/whale-town-end
187 lines
3.9 KiB
Markdown
187 lines
3.9 KiB
Markdown
# 管理员后台（Admin Dashboard）
|
||
|
||
本模块提供 Whale Town 的管理员后台能力，包含：
|
||
|
||
- 管理员登录（role=9）
|
||
- 用户列表管理
|
||
- 用户密码重置
|
||
- 运行日志查看（读取 logs/ 下最新日志）
|
||
|
||
> 说明：本项目用户系统原本的 `access_token` 为演示用 Base64 令牌。为了不影响现有用户端流程，管理员后台使用单独的签名 Token（HMAC-SHA256）做鉴权。
|
||
|
||
---
|
||
|
||
## 1. 管理员账号设计
|
||
|
||
### 1.1 角色约定
|
||
|
||
用户表 `users.role`：
|
||
|
||
- `1`：普通用户
|
||
- `9`：管理员（可访问后台）
|
||
|
||
### 1.2 启动引导创建管理员（可选）
|
||
|
||
通过环境变量启用启动引导：在服务启动时，如果不存在指定用户名的用户，则自动创建一个管理员账户（role=9）。
|
||
|
||
在 `.env` 中配置：
|
||
|
||
- `ADMIN_BOOTSTRAP_ENABLED=true`
|
||
- `ADMIN_USERNAME=admin`
|
||
- `ADMIN_PASSWORD=Admin123456`（需满足密码强度：至少8位，包含字母和数字）
|
||
- `ADMIN_NICKNAME=管理员`（可选）
|
||
|
||
注意：
|
||
|
||
- 建议仅在首次部署/开发环境开启，引导创建成功后可关闭。
|
||
- 生产环境务必设置强随机密码与强随机 `ADMIN_TOKEN_SECRET`。
|
||
|
||
---
|
||
|
||
## 2. 管理员鉴权 Token
|
||
|
||
### 2.1 配置项
|
||
|
||
- `ADMIN_TOKEN_SECRET`：签名密钥（至少16字符；生产环境建议≥32并随机）
|
||
- `ADMIN_TOKEN_TTL_SECONDS`：Token 有效期（秒），默认 `28800`（8小时）
|
||
|
||
### 2.2 使用方式
|
||
|
||
管理员登录成功后返回 `access_token`，后续请求在 Header 中携带：
|
||
|
||
- `Authorization: Bearer <access_token>`
|
||
|
||
---
|
||
|
||
## 3. 后端接口
|
||
|
||
### 3.1 管理员登录
|
||
|
||
- `POST /admin/auth/login`
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"identifier": "admin",
|
||
"password": "Admin123456"
|
||
}
|
||
```
|
||
|
||
响应（成功）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"admin": { "id": "1", "username": "admin", "nickname": "管理员", "role": 9 },
|
||
"access_token": "...",
|
||
"expires_at": 1766102400000
|
||
},
|
||
"message": "管理员登录成功"
|
||
}
|
||
```
|
||
|
||
### 3.2 用户列表
|
||
|
||
- `GET /admin/users?limit=100&offset=0`
|
||
- 需要管理员 Token
|
||
|
||
### 3.3 用户详情
|
||
|
||
- `GET /admin/users/:id`
|
||
- 需要管理员 Token
|
||
|
||
### 3.4 重置用户密码
|
||
|
||
- `POST /admin/users/:id/reset-password`
|
||
- 需要管理员 Token
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"new_password": "NewPass1234"
|
||
}
|
||
```
|
||
|
||
### 3.5 运行日志（tail）
|
||
|
||
- `GET /admin/logs/runtime?lines=200`
|
||
- 需要管理员 Token
|
||
|
||
说明：
|
||
|
||
- 开发环境默认读取 `logs/dev.log`
|
||
- 生产环境默认读取 `logs/app.log`
|
||
- `lines` 默认 200，最大 2000
|
||
|
||
### 3.6 下载全部运行日志（archive）
|
||
|
||
- `GET /admin/logs/archive`
|
||
- 需要管理员 Token
|
||
|
||
说明：
|
||
|
||
- 返回一个 `tar.gz` 文件（浏览器会触发下载）
|
||
- 内容为整个 `logs/` 目录（例如开发环境的 `dev.log`，生产环境的 `app.log/access.log/error.log` 等）
|
||
|
||
---
|
||
|
||
## 4. 前端后台（Ant Design）
|
||
|
||
前端工程位于 `client/`，使用 Vite + React + Ant Design。
|
||
|
||
### 4.1 安装依赖
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
pnpm install
|
||
```
|
||
|
||
### 4.2 启动后端
|
||
|
||
```bash
|
||
pnpm run dev
|
||
```
|
||
|
||
### 4.3 启动前端后台
|
||
|
||
```bash
|
||
pnpm -C client dev
|
||
```
|
||
|
||
默认访问：
|
||
|
||
- 前端：`http://localhost:5173`
|
||
- 后端：`http://localhost:3000`
|
||
- Swagger：`http://localhost:3000/api-docs`
|
||
|
||
页面说明：
|
||
|
||
- 用户管理：`/users`
|
||
- 运行日志：`/logs`
|
||
|
||
在“运行日志”页面可点击“下载日志压缩包”获取整个 `logs/` 目录的打包文件。
|
||
|
||
### 4.4 前端配置
|
||
|
||
- 复制 `client/.env.example` 为 `client/.env.local`
|
||
- 可通过 `VITE_API_BASE_URL` 指向后端地址
|
||
|
||
---
|
||
|
||
## 5. 代码位置
|
||
|
||
- 后端：
|
||
- `src/core/admin_core/`：管理员核心逻辑
|
||
- `src/core/guards/admin.guard.ts`：管理员接口鉴权
|
||
- `src/business/admin/`：管理员HTTP API
|
||
- `src/dto/admin*.ts`：管理员请求/响应 DTO
|
||
|
||
- 前端：
|
||
- `client/src/pages/LoginPage.tsx`：管理员登录页
|
||
- `client/src/pages/UsersPage.tsx`：用户管理页（列表+重置密码）
|
||
- `client/src/pages/LogsPage.tsx`：运行日志页
|