# FileBin 文件上传下载服务

基于 Cloudflare Workers + Durable Objects（SQLite 持久化存储）的文件上传下载服务。上传成功后返回下载链接，支持 TTL 过期、分块上传、断点续传下载。

Base URL: `https://files.kekeke.cc.cd`

## 认证方式

上传、列表、清理接口需要令牌认证，两种传法任选其一：

- 请求头: `Authorization: Bearer <token>`
- 请求头: `X-API-Token: <token>`

下载、详情接口无需认证。删除接口使用上传时返回的管理密钥。

## 快速开始

```bash
# 1. 上传文件（直接上传，建议 20MB 以内；更大的文件用分块上传）
TOKEN=你的令牌
curl -X POST "https://files.kekeke.cc.cd/api/upload?filename=photo.jpg&mime=image/jpeg&ttl=7d" \
  -H "Authorization: Bearer $TOKEN" \
  --data-binary @photo.jpg

# 响应示例
# {
#   "ok": true,
#   "id": "a1b2c3......",
#   "url": "https://files.kekeke.cc.cd/api/files/a1b2c3......",
#   "manage_key": "xxxxxx",
#   "filename": "photo.jpg",
#   "mime": "image/jpeg",
#   "size": 123456,
#   "uploaded_at": "2026-09-21T10:00:00.000Z",
#   "expires_at": null,
#   "storage": "direct"
# }

# 2. 下载文件
curl -O "https://files.kekeke.cc.cd/api/files/a1b2c3......"

# 3. 删除文件（用 manage_key）
curl -X DELETE "https://files.kekeke.cc.cd/api/files/a1b2c3......" -H "X-Manage-Key: xxxxxx"

# 4. 查看文档（JSON 版）
curl "https://files.kekeke.cc.cd/api/docs"
```

## 全部接口

### GET /
返回本文档（纯文本）。

### GET /api/docs
返回结构化 JSON 文档。

### GET /api/health
健康检查。响应: `{"ok":true,"service":"filebin","time":...}`

### POST /api/upload （需令牌）
直接上传单个文件，文件体为请求原始内容。

查询参数:

| 参数 | 必填 | 说明 |
|------|------|------|
| filename | 否 | 文件名，默认 file.bin，最长 120 字符 |
| mime | 否 | MIME 类型，默认 application/octet-stream |
| ttl | 否 | 过期时间: 1h / 1d / 7d / 30d，默认永久 |

限制: 单文件不超过 100MB（超过 20MB 建议用分块上传，更稳）；每 IP 每分钟 20 次。

成功响应字段: ok, id, url, manage_key, filename, mime, size, uploaded_at, expires_at, storage

### POST /api/upload/init （需令牌）
初始化分块上传，请求体为 JSON:

```json
{
  "filename": "big.zip",
  "mime": "application/zip",
  "size": 52428800,
  "chunk_size": 10485760,
  "ttl": "1d"
}
```

| 字段 | 必填 | 说明 |
|------|------|------|
| filename | 否 | 文件名 |
| mime | 否 | MIME 类型 |
| size | 是 | 总字节数（整数，不超过 100MB） |
| chunk_size | 否 | 每块字节数，默认 10MB，范围 1KB 到 95MB，块数不超过 32 |
| ttl | 否 | 1h / 1d / 7d / 30d |

成功响应: ok, id(会话ID), url, manage_key（务必保存）, filename, mime, size, chunk_size, chunks, expires_at

### PUT /api/upload/{id}/{index}
上传第 index 块（从 0 开始），请求体为该块的原始字节。

成功响应: `{"ok":true,"id":"...","index":0,"received":true,"bytes":10485760}`

### GET /api/upload/{id}/status
查看分块接收进度。

响应: ok, id, status, chunks, chunk_size, received(已收数组), missing(缺失数组)

### POST /api/upload/{id}/complete
完成分块上传，校验所有分块后生效。可重复调用（幂等）。

成功响应: ok, id, url, filename, mime, size, chunks, completed_at, expires_at

### GET /api/files （需令牌）
文件列表（含未完成的上传会话），按时间倒序。

查询参数: limit（可选，默认 100，最大 500）

响应: ok, total, count, files[{id, filename, mime, size, uploaded_at, expires_at, storage, status, expired}]

### GET /api/files/{id}
下载文件。支持:

- Range 断点续传（`Range: bytes=0-99`），返回 206
- If-None-Match / ETag 缓存，返回 304
- If-Range 条件范围请求
- HEAD 请求只返回头部

### GET /api/files/{id}/info
文件详情（公开）。响应: ok, id, filename, mime, size, uploaded_at, completed_at, expires_at, storage, status, etag, url

### DELETE /api/files/{id}
删除文件。认证: 请求头 X-Manage-Key 或查询参数 manage_key（上传时返回的管理密钥）。

### POST /api/cleanup （需令牌）
手动触发清理：删除过期文件、废弃上传会话与孤儿数据。

## 错误码

| 状态码 | code | 说明 |
|--------|------|------|
| 400 | BAD_JSON / INVALID_PARAM / EMPTY_BODY / SIZE_MISMATCH / MISSING_MANAGE_KEY | 请求参数问题 |
| 401 | UNAUTHORIZED | 令牌缺失或错误 |
| 403 | WRONG_MANAGE_KEY | 管理密钥错误 |
| 404 | NOT_FOUND | 文件或会话不存在 |
| 409 | CONFLICT / INCOMPLETE | 会话状态冲突或分块不完整 |
| 410 | EXPIRED | 文件已过期 |
| 413 | PAYLOAD_TOO_LARGE | 超过大小限制 |
| 416 | - | Range 越界（带 Content-Range: bytes */size） |
| 429 | RATE_LIMITED | 请求过于频繁 |
| 500 | INTERNAL / STORAGE_ERROR | 服务内部错误 |
| 502 | DO_UNREACHABLE | 存储服务暂不可达 |

所有错误响应均为: `{"ok":false,"error":{"code":"...","message":"..."}}`

## 限制说明

| 项目 | 限制 |
|------|------|
| 单文件 | 100MB |
| 分块数 | 最多 32 块 |
| TTL | 1h / 1d / 7d / 30d，默认永久 |
| 上传频率 | 每 IP 每分钟 20 次 |
| 下载频率 | 每 IP 每分钟 300 次 |
| 总存储 | 约 5GB（Durable Objects 免费额度） |

## 注意事项

1. 分块上传的文件在上传完成前不可下载；上传会话超过 24 小时未完成会被自动清理。
2. 过期文件由每日定时任务清理，也可手动调用 POST /api/cleanup。
3. 下载链接是最终的分享地址，支持断点续传，文件内容不可变。