151 lines
3.7 KiB
Markdown
151 lines
3.7 KiB
Markdown
# 黑名单管理接口文档
|
||
|
||
## 数据模型
|
||
|
||
### ca_blacklists 表
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| id | BIGINT UNSIGNED | 主键,自增 |
|
||
| target_type | ENUM('user','ip') | 目标类型:user=用户ID,ip=IP地址 |
|
||
| target_value | VARCHAR(255) | 目标值 |
|
||
| status | TINYINT(1) | 状态:0=禁用,1=启用 |
|
||
| expire_time | DATETIME | 过期时间,NULL表示永久 |
|
||
| operator_id | BIGINT UNSIGNED | 操作人ID |
|
||
| operator_name | VARCHAR(50) | 操作人用户名 |
|
||
| remark | VARCHAR(500) | 备注 |
|
||
| created_at | DATETIME | 创建时间 |
|
||
| updated_at | DATETIME | 更新时间 |
|
||
|
||
唯一约束:`target_type` + `target_value`
|
||
|
||
## 接口列表
|
||
|
||
所有接口均需要管理员权限,路径前缀为 `/api`。
|
||
|
||
### 1. 查询黑名单列表
|
||
|
||
- **URL**: `GET /api/blacklists`
|
||
- **权限**: admin
|
||
- **参数**:
|
||
- `target_type`: 可选,user/ip
|
||
- `status`: 可选,0/1
|
||
- `keyword`: 可选,目标值/备注模糊搜索
|
||
- `page`: 可选,默认1
|
||
- `page_size`: 可选,默认20,最大100
|
||
- `sort_by`: 可选,id/created_at/updated_at
|
||
- `sort_order`: 可选,asc/desc
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"list": [...],
|
||
"total": 100,
|
||
"page": 1,
|
||
"page_size": 20
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 添加黑名单
|
||
|
||
- **URL**: `POST /api/blacklists`
|
||
- **权限**: admin
|
||
- **参数**:
|
||
- `target_type`: 必填,user/ip
|
||
- `target_value`: 必填
|
||
- `expire_time`: 可选,格式 YYYY-MM-DD HH:mm:ss
|
||
- `remark`: 可选
|
||
- **响应**: `{"code":200,"message":"黑名单添加成功"}`
|
||
|
||
### 3. 批量添加黑名单
|
||
|
||
- **URL**: `POST /api/blacklists/batch`
|
||
- **权限**: admin
|
||
- **参数**:
|
||
- `items`: 必填,数组,每个元素包含 target_type, target_value, expire_time, remark
|
||
- 单次最多500条
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": { "success": 10, "failed": 0 },
|
||
"message": "批量添加完成,成功 10 条,失败 0 条"
|
||
}
|
||
```
|
||
|
||
### 4. 更新黑名单
|
||
|
||
- **URL**: `PUT /api/blacklists/{id}`
|
||
- **权限**: admin
|
||
- **参数**:
|
||
- `status`: 可选,0/1
|
||
- `expire_time`: 可选
|
||
- `remark`: 可选
|
||
- **响应**: `{"code":200,"message":"黑名单更新成功"}`
|
||
|
||
### 5. 删除黑名单
|
||
|
||
- **URL**: `DELETE /api/blacklists/{id}`
|
||
- **权限**: admin
|
||
- **响应**: `{"code":200,"message":"黑名单删除成功"}`
|
||
|
||
### 6. 批量删除黑名单
|
||
|
||
- **URL**: `POST /api/blacklists/batch-delete`
|
||
- **权限**: admin
|
||
- **参数**:
|
||
- `ids`: 必填,整数数组,单次最多500条
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": { "count": 5 },
|
||
"message": "批量删除成功"
|
||
}
|
||
```
|
||
|
||
### 7. 导入黑名单
|
||
|
||
- **URL**: `POST /api/blacklists/import`
|
||
- **权限**: admin
|
||
- **Content-Type**: multipart/form-data
|
||
- **参数**:
|
||
- `file`: CSV文件,必须包含 target_type、target_value 列
|
||
- **响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": { "success": 10, "failed": 0 },
|
||
"message": "导入完成..."
|
||
}
|
||
```
|
||
|
||
### 8. 导出黑名单
|
||
|
||
- **URL**: `GET /api/blacklists/export`
|
||
- **权限**: admin
|
||
- **参数**:
|
||
- `ids`: 可选,逗号分隔的ID列表,为空则导出全部
|
||
- **响应**: CSV文件下载
|
||
|
||
## 黑名单拦截
|
||
|
||
系统通过 `BlacklistMiddleware` 对所有需要认证的接口进行拦截。当请求的当前用户ID或客户端IP存在于启用状态且未过期的黑名单中时,接口返回:
|
||
|
||
```json
|
||
{
|
||
"code": 403,
|
||
"message": "您的账号或IP已被列入黑名单,禁止访问"
|
||
}
|
||
```
|
||
|
||
### 缓存机制
|
||
|
||
黑名单列表缓存于 `backend/storage/cache/blacklist.json`,默认有效期 60 秒。新增、更新、删除黑名单操作会自动刷新缓存。
|
||
|
||
## 频率限制
|
||
|
||
黑名单管理接口位于 `/api` 路由组,共享 `RateLimitMiddleware(60, 60, 'api')`,即每 60 秒最多 60 次请求。
|