使用说明
FileServer 文件存储服务 API 文档
快速开始
1
注册账号 并登录系统
2
联系管理员分配角色（新用户默认无角色，无法上传）
3
进入 控制台 → Token 管理 创建 API Token（Key 仅显示一次，请立即保存）
4
使用 Token 通过 API 上传文件，或直接在 首页 上传
接口概览
| 项目 | 说明 |
|---|---|
| 上传接口 | POST /api/upload/ |
| 下载接口 | GET /api/files/<uuid>/（无需认证） |
| 认证方式 | Bearer Token（通过 Authorization 请求头传递） |
| 请求格式 | multipart/form-data |
| 文件大小限制 | 100 MB |
认证说明
所有上传请求必须在请求头中携带有效的 API Token：
Authorization: Bearer <your-token-key>
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| file | File | 是 | 要上传的文件 |
| expires_in | Integer | 否 | 文件过期时间（秒），不传则永不过期 |
请求示例
cURL
# 上传文件，永不过期
curl -X POST https://m.yewf.vip/api/upload/ \
-H "Authorization: Bearer YOUR_TOKEN_KEY" \
-F "file=@/path/to/file.pdf"
# 上传文件，1 小时后过期
curl -X POST https://m.yewf.vip/api/upload/ \
-H "Authorization: Bearer YOUR_TOKEN_KEY" \
-F "file=@/path/to/file.pdf" \
-F "expires_in=3600"
Python
import requests
url = "https://m.yewf.vip/api/upload/"
headers = {"Authorization": "Bearer YOUR_TOKEN_KEY"}
with open("report.pdf", "rb") as f:
resp = requests.post(url, headers=headers, files={"file": f})
print(resp.json())
# 带过期时间（1 小时 = 3600 秒）
with open("report.pdf", "rb") as f:
resp = requests.post(
url, headers=headers,
files={"file": f},
data={"expires_in": 3600},
)
print(resp.json())
JavaScript
const formData = new FormData();
formData.append("file", fileInput.files[0]);
formData.append("expires_in", "86400"); // 可选：1 天后过期
const resp = await fetch("/api/upload/", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_TOKEN_KEY" },
body: formData,
});
const data = await resp.json();
console.log(data.url); // 文件下载地址
成功响应
状态码：201 Created
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"url": "https://m.yewf.vip/api/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890/",
"name": "report.pdf",
"size": 1048576,
"expires_at": "2026-04-21T15:30:00+08:00"
}
| 字段 | 类型 | 说明 |
|---|---|---|
| id | String (UUID) | 文件唯一标识 |
| url | String | 文件下载地址，可直接访问 |
| name | String | 原始文件名 |
| size | Integer | 文件大小（字节） |
| expires_at | String / null | ISO 8601 格式的过期时间，null 表示永不过期 |
错误码说明
上传接口
| 状态码 | 错误信息 | 说明 |
|---|---|---|
| 400 | 未提供文件 | 请求中缺少 file 字段 |
| 400 | expires_in 必须为正整数 | expires_in 值小于等于 0 |
| 400 | expires_in 格式无效 | expires_in 不是合法的整数 |
| 401 | 无效或缺失的 Token | 未提供 Token、Token 不存在、已停用或已过期 |
| 403 | 你尚未分配角色，无法上传文件 | 用户未被分配角色 |
| 403 | 单文件大小超限 | 文件大小超过角色设定的单文件上限 |
| 403 | 文件数量已达上限 | 用户文件总数超过角色上限 |
| 403 | 总容量超限 | 用户总存储量超过角色容量上限 |
| 403 | 上传次数已达上限 | 触发频率限制（每分钟/每小时/每天/每月） |
| 413 | Token 容量不足 | 该 Token 的存储容量已满或不足 |
下载接口
| 状态码 | 错误信息 | 说明 |
|---|---|---|
| 404 | 文件不存在 | 文件 ID 无效或文件已被删除 |
| 410 | 文件已过期 | 文件已超过设定的过期时间 |
常用过期时间参考
| 时长 | expires_in 值（秒） |
|---|---|
| 10 分钟 | 600 |
| 1 小时 | 3600 |
| 12 小时 | 43200 |
| 1 天 | 86400 |
| 7 天 | 604800 |
| 30 天 | 2592000 |
| 永不过期 | 不传此参数 |
注意事项
- Token 安全：Token Key 创建后仅显示一次，请立即保存。丢失后需创建新 Token。
- 文件大小：服务器限制单文件最大 100 MB。
- 角色权限：新注册用户默认没有角色，无法上传文件，需管理员分配角色后方可使用。
- Token 容量：每个 Token 可设置独立的容量上限，上传时会检查是否超限。
- 频率限制：根据角色配置，上传频率可能受到每分钟/每小时/每天/每月的限制。
- 文件过期：过期后文件仍保留在服务器上，但无法下载。管理员会定期清理过期文件。