167 lines
3.7 KiB
Markdown
167 lines
3.7 KiB
Markdown
# 文件接口（上传 / 列目录 / 下载）
|
||
|
||
API v1 只提供最小化的文件能力，用于把外部输入文件放入工作区，并下载产物。
|
||
|
||
核心限制：
|
||
|
||
- **上传只能落在 `project/user_upload/` 目录及其子目录**；
|
||
- 列目录/下载也只允许访问 `user_upload` 内部路径（路径穿越会被拒绝）。
|
||
|
||
> 目录结构见 `auth.md`。
|
||
|
||
## 1) 上传文件
|
||
|
||
### POST `/api/v1/files/upload`
|
||
|
||
#### 请求
|
||
|
||
- Headers：`Authorization: Bearer <TOKEN>`
|
||
- Content-Type：`multipart/form-data`
|
||
- Form 字段：
|
||
- `file`：必填，上传的文件对象
|
||
- `filename`：可选，覆盖原文件名（会做安全清洗）
|
||
- `dir`：可选，`user_upload` 下的子目录（例如 `docs/`）；不传则落在 `user_upload/` 根目录
|
||
|
||
> 如果你希望“完全不允许指定目录”，客户端请不要传 `dir`，统一上传到根目录即可。
|
||
|
||
#### 响应
|
||
|
||
成功（200）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"path": "docs/spec.pdf",
|
||
"filename": "spec.pdf",
|
||
"size": 12345,
|
||
"sha256": "..."
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `path`：相对 `user_upload` 的路径（用于 list/download）
|
||
- `sha256`：服务端计算的文件哈希（便于客户端校验/去重）
|
||
|
||
可能错误：
|
||
|
||
- `400`：缺少 file / 文件名非法 / 目录非法
|
||
- `401`：缺少或无效 token
|
||
- `503`：系统未初始化
|
||
- `500`：保存失败（例如写入异常、扫描/隔离异常等）
|
||
|
||
#### curl 示例
|
||
|
||
上传到根目录：
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
-F "file=@./hello.txt" \
|
||
http://localhost:8091/api/v1/files/upload
|
||
```
|
||
|
||
上传到子目录：
|
||
|
||
```bash
|
||
curl -sS -X POST \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
-F "dir=inputs" \
|
||
-F "file=@./hello.txt" \
|
||
http://localhost:8091/api/v1/files/upload
|
||
```
|
||
|
||
## 2) 列出目录内容
|
||
|
||
### GET `/api/v1/files?path=<dir>`
|
||
|
||
#### 请求
|
||
|
||
- Headers：`Authorization: Bearer <TOKEN>`
|
||
- Query：
|
||
- `path`：可选，相对 `user_upload` 的目录路径；不传表示根目录
|
||
|
||
#### 响应
|
||
|
||
成功（200）：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"base": "inputs",
|
||
"items": [
|
||
{
|
||
"name": "hello.txt",
|
||
"is_dir": false,
|
||
"size": 16,
|
||
"modified_at": 1769182550.594278,
|
||
"path": "inputs/hello.txt"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `base`：你请求的目录（相对 `user_upload`），根目录时为 `.`
|
||
- `items[].path`：相对 `user_upload` 的路径（用于下载或继续列目录）
|
||
- `modified_at`：文件 mtime（UNIX 秒）
|
||
|
||
可能错误：
|
||
|
||
- `400`：path 不是目录或 path 非法
|
||
- `401`：缺少或无效 token
|
||
- `404`：目录不存在
|
||
- `503`：系统未初始化
|
||
|
||
#### curl 示例
|
||
|
||
```bash
|
||
curl -sS \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"http://localhost:8091/api/v1/files?path=inputs"
|
||
```
|
||
|
||
## 3) 下载文件/目录
|
||
|
||
### GET `/api/v1/files/download?path=<file_or_dir>`
|
||
|
||
#### 请求
|
||
|
||
- Headers：`Authorization: Bearer <TOKEN>`
|
||
- Query：
|
||
- `path`：必填，相对 `user_upload` 的文件或目录路径
|
||
|
||
#### 响应
|
||
|
||
1) 若 `path` 指向文件：返回文件二进制流（`Content-Disposition: attachment`）。
|
||
2) 若 `path` 指向目录：服务端会把目录打包成 zip 后返回（`application/zip`）。
|
||
|
||
可能错误：
|
||
|
||
- `400`：缺少 path 或 path 非法
|
||
- `401`：缺少或无效 token
|
||
- `404`：文件/目录不存在
|
||
- `503`：系统未初始化
|
||
|
||
#### curl 示例
|
||
|
||
下载文件：
|
||
|
||
```bash
|
||
curl -L -o out.txt \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"http://localhost:8091/api/v1/files/download?path=hello.txt"
|
||
```
|
||
|
||
下载目录（zip）：
|
||
|
||
```bash
|
||
curl -L -o inputs.zip \
|
||
-H "Authorization: Bearer <TOKEN>" \
|
||
"http://localhost:8091/api/v1/files/download?path=inputs"
|
||
```
|
||
|
||
> zip 内的路径目前是相对 `project/` 的（因此通常会包含 `user_upload/` 前缀）。
|
||
|