436 lines
9.3 KiB
Markdown
436 lines
9.3 KiB
Markdown
# 文件管理 API 接口文档
|
||
|
||
**Base URL:** `/api/v1/file-manager`
|
||
|
||
---
|
||
|
||
## 1. 列出目录内容
|
||
|
||
**GET** `/api/v1/file-manager/list`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| path | string | query | 否 | 相对路径，空字符串返回根目录（projects/prompt） |
|
||
| recursive | bool | query | 否 | 是否递归列出子目录，默认 false |
|
||
|
||
```bash
|
||
curl -X GET "/api/v1/file-manager/list?path=projects&recursive=false"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"path": "projects",
|
||
"items": [
|
||
{
|
||
"name": "report.pdf",
|
||
"path": "projects/report.pdf",
|
||
"type": "file",
|
||
"size": 102400,
|
||
"modified": 1700000000.0,
|
||
"created": 1699000000.0
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 上传文件
|
||
|
||
**POST** `/api/v1/file-manager/upload`
|
||
|
||
请求方式：表单数据上传（multipart/form-data）
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| file | file | form | 是 | 上传的文件 |
|
||
| path | string | form | 否 | 目标目录路径，默认 `projects` |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/upload" \
|
||
-F "file=@document.pdf" \
|
||
-F "path=projects/dataset"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "文件上传成功",
|
||
"filename": "document.pdf",
|
||
"original_filename": "document.pdf",
|
||
"path": "projects/dataset/document.pdf",
|
||
"size": 102400
|
||
}
|
||
```
|
||
|
||
> 注：文件名中的空格会自动替换为下划线。
|
||
|
||
---
|
||
|
||
## 3. 下载文件
|
||
|
||
**GET** `/api/v1/file-manager/download/{file_path}`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| file_path | string | path | 是 | 文件相对路径 |
|
||
|
||
```bash
|
||
curl -X GET "/api/v1/file-manager/download/projects/report.pdf" -o report.pdf
|
||
```
|
||
|
||
响应：文件二进制流，`Content-Type` 根据文件类型自动推断。
|
||
|
||
---
|
||
|
||
## 4. 删除文件或目录
|
||
|
||
**DELETE** `/api/v1/file-manager/delete`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| path | string | query | 是 | 要删除的路径 |
|
||
|
||
```bash
|
||
curl -X DELETE "/api/v1/file-manager/delete?path=projects/report.pdf"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "文件删除成功",
|
||
"path": "projects/report.pdf"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 创建文件夹
|
||
|
||
**POST** `/api/v1/file-manager/create-folder`
|
||
|
||
请求方式：JSON
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| path | string | body | 否 | 父目录路径，默认 `projects` |
|
||
| name | string | body | 是 | 文件夹名称 |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/create-folder" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"path": "projects", "name": "new-folder"}'
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "文件夹创建成功",
|
||
"path": "projects/new-folder"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 重命名文件或文件夹
|
||
|
||
**POST** `/api/v1/file-manager/rename`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| old_path | string | query | 是 | 原路径 |
|
||
| new_name | string | query | 是 | 新名称 |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/rename?old_path=projects/old-name.pdf&new_name=new-name.pdf"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "重命名成功",
|
||
"old_path": "projects/old-name.pdf",
|
||
"new_path": "projects/new-name.pdf"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 移动文件或文件夹
|
||
|
||
**POST** `/api/v1/file-manager/move`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| source_path | string | query | 是 | 源路径 |
|
||
| target_path | string | query | 是 | 目标路径 |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/move?source_path=projects/a.pdf&target_path=projects/sub/a.pdf"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "移动成功",
|
||
"source_path": "projects/a.pdf",
|
||
"target_path": "projects/sub/a.pdf"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 复制文件或文件夹
|
||
|
||
**POST** `/api/v1/file-manager/copy`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| source_path | string | query | 是 | 源路径 |
|
||
| target_path | string | query | 是 | 目标路径 |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/copy?source_path=projects/a.pdf&target_path=projects/a-copy.pdf"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "复制成功",
|
||
"source_path": "projects/a.pdf",
|
||
"target_path": "projects/a-copy.pdf"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 搜索文件
|
||
|
||
**GET** `/api/v1/file-manager/search`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| query | string | query | 是 | 搜索关键词（匹配文件名） |
|
||
| path | string | query | 否 | 搜索路径，为空则搜索所有支持目录 |
|
||
| file_type | string | query | 否 | 文件类型过滤（如 `.pdf`） |
|
||
|
||
```bash
|
||
curl -X GET "/api/v1/file-manager/search?query=report&path=projects&file_type=.pdf"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"query": "report",
|
||
"path": "projects",
|
||
"results": [
|
||
{
|
||
"name": "report.pdf",
|
||
"path": "projects/report.pdf",
|
||
"type": "file"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 读取文件内容
|
||
|
||
**GET** `/api/v1/file-manager/read`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| path | string | query | 是 | 文件相对路径 |
|
||
|
||
```bash
|
||
curl -X GET "/api/v1/file-manager/read?path=projects/config.json"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"content": "{\"key\": \"value\"}",
|
||
"path": "projects/config.json",
|
||
"size": 16,
|
||
"modified": 1700000000.0,
|
||
"encoding": "utf-8",
|
||
"mime_type": "application/json"
|
||
}
|
||
```
|
||
|
||
> 限制：最大 10MB。自动尝试 utf-8 / gbk / gb2312 / latin-1 编码。
|
||
|
||
---
|
||
|
||
## 11. 保存文件内容
|
||
|
||
**POST** `/api/v1/file-manager/save`
|
||
|
||
请求方式：JSON
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| path | string | body | 是 | 文件相对路径 |
|
||
| content | string | body | 是 | 文件内容 |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/save" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"path": "projects/config.json", "content": "{\"key\": \"new-value\"}"}'
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "文件保存成功",
|
||
"path": "projects/config.json",
|
||
"size": 20,
|
||
"modified": 1700000000.0,
|
||
"encoding": "utf-8"
|
||
}
|
||
```
|
||
|
||
> 限制：最大 5MB。保存前自动创建备份，写入失败时自动回滚。
|
||
|
||
---
|
||
|
||
## 12. 获取文件/文件夹详细信息
|
||
|
||
**GET** `/api/v1/file-manager/info/{file_path}`
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| file_path | string | path | 是 | 文件或文件夹路径 |
|
||
|
||
```bash
|
||
curl -X GET "/api/v1/file-manager/info/projects/report.pdf"
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"info": {
|
||
"name": "report.pdf",
|
||
"path": "projects/report.pdf",
|
||
"type": "file",
|
||
"size": 102400,
|
||
"modified": 1700000000.0,
|
||
"created": 1699000000.0,
|
||
"permissions": "644",
|
||
"mime_type": "application/pdf",
|
||
"preview": "文件前1000字符预览..."
|
||
}
|
||
}
|
||
```
|
||
|
||
> 小于 1MB 的文本文件会包含 `preview` 字段。
|
||
|
||
---
|
||
|
||
## 13. 下载文件夹为 ZIP
|
||
|
||
**POST** `/api/v1/file-manager/download-folder-zip`
|
||
|
||
请求方式：JSON
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| path | string | body | 是 | 文件夹路径 |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/download-folder-zip" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"path": "projects/dataset"}' -o dataset.zip
|
||
```
|
||
|
||
响应：ZIP 文件二进制流（`application/zip`）。
|
||
|
||
> 限制：最大 500MB，最多 10000 个文件。
|
||
|
||
---
|
||
|
||
## 14. 批量下载为 ZIP
|
||
|
||
**POST** `/api/v1/file-manager/download-multiple-zip`
|
||
|
||
请求方式：JSON
|
||
|
||
| 参数 | 类型 | 位置 | 必填 | 说明 |
|
||
|------|------|------|------|------|
|
||
| paths | string[] | body | 是 | 文件/文件夹路径数组 |
|
||
| filename | string | body | 否 | ZIP 文件名，默认 `batch_download.zip` |
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/download-multiple-zip" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"paths": ["projects/a.pdf", "projects/sub"], "filename": "export.zip"}' \
|
||
-o export.zip
|
||
```
|
||
|
||
响应：ZIP 文件二进制流（`application/zip`）。
|
||
|
||
> 限制：最大 500MB，最多 10000 个文件。
|
||
|
||
---
|
||
|
||
## 15. 批量操作
|
||
|
||
**POST** `/api/v1/file-manager/batch-operation`
|
||
|
||
请求方式：JSON（操作数组）
|
||
|
||
支持操作类型：`delete` / `move` / `copy`
|
||
|
||
```bash
|
||
curl -X POST "/api/v1/file-manager/batch-operation" \
|
||
-H "Content-Type: application/json" \
|
||
-d '[
|
||
{"type": "delete", "path": "projects/old.pdf"},
|
||
{"type": "move", "source_path": "projects/a.pdf", "target_path": "projects/archive/a.pdf"},
|
||
{"type": "copy", "source_path": "projects/b.pdf", "target_path": "projects/backup/b.pdf"}
|
||
]'
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"results": [
|
||
{"type": "delete", "success": true, "message": "删除成功"},
|
||
{"type": "move", "success": true, "message": "移动成功"},
|
||
{"type": "copy", "success": true, "message": "复制成功"}
|
||
],
|
||
"total": 3,
|
||
"successful": 3
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 通用说明
|
||
|
||
- **路径约束**：所有路径必须以 `projects` 或 `prompt` 开头，否则返回 400
|
||
- **安全机制**：路径经过规范化处理，防止目录遍历攻击
|
||
- **隐藏文件**：以 `.` 开头的文件/目录在列出和搜索时自动跳过
|
||
- **错误响应格式**：
|
||
```json
|
||
{
|
||
"detail": "错误描述信息"
|
||
}
|
||
```
|