feat: 初始化对象存储服务

- 支持 API Key 认证
- 文件上传/下载/预览
- 大文件分片上传
- 支持自定义端口和存储目录
This commit is contained in:
Cuishibing
2026-04-25 23:09:43 +08:00
commit bd0c22cd73
9 changed files with 2485 additions and 0 deletions

98
DESIGN.md Normal file
View File

@@ -0,0 +1,98 @@
# 对象存储服务
## 技术栈
- Node.js + Express.js
- SQLite (better-sqlite3) + Sequelize
- 本地文件系统存储
## 快速开始
```bash
npm install
npm start # 默认 3000 端口, ./storage 目录
PORT=8080 npm start # 指定端口
STORAGE_DIR=/data myoss # 指定存储目录
PORT=8080 STORAGE_DIR=/data myoss # 同时指定
```
## 使用方法
### 1. 创建首个 API Keybootstrap
```bash
curl -X POST http://localhost:3000/api/keys/bootstrap -H "Content-Type: application/json" -d '{"name":"root"}'
# 返回: {"key":"xxx","name":"root"}
```
### 2. 上传文件
```bash
curl -X POST http://localhost:3000/api/files \
-H "X-API-Key: YOUR_KEY" \
-F "file=@filename.ext"
```
### 3. 分片上传
```bash
# 初始化
curl -X POST http://localhost:3000/api/uploads/init \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"filename":"large.bin","totalSize":2097152,"totalChunks":2}'
# 上传分片 (每个 1MB)
curl -X POST "http://localhost:3000/api/uploads/UPLOAD_ID/chunk?chunkIndex=0" \
-H "X-API-Key: YOUR_KEY" \
-F "chunk=@chunk0.bin"
# 完成
curl -X POST http://localhost:3000/api/uploads/UPLOAD_ID/complete \
-H "X-API-Key: YOUR_KEY"
```
### 4. 文件操作
- `GET /api/files` - 列表
- `GET /api/files/:key` - 信息
- `GET /api/files/:key/download` - 下载
- `GET /api/files/:key/preview` - 预览
- `DELETE /api/files/:key` - 删除
## API 设计
### 认证 (API Key)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/keys/bootstrap | 初始化首个 Key |
| POST | /api/keys | 创建新 Key |
| GET | /api/keys | 列出所有 Key |
| DELETE | /api/keys/:keyId | 删除 API Key |
### 文件操作
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/files | 上传文件 |
| GET | /api/files | 文件列表 |
| GET | /api/files/:key | 获取文件信息 |
| GET | /api/files/:key/download | 下载链接 |
| GET | /api/files/:key/preview | 预览链接 |
| DELETE | /api/files/:key | 删除文件 |
### 分片上传
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/uploads/init | 初始化分片上传 |
| POST | /api/uploads/:uploadId/chunk | 上传分片 |
| POST | /api/uploads/:uploadId/complete | 完成上传 |
## 鉴权方式
- 通过 Header `X-API-Key` 传递 API Key
- 每个 API Key 关联独立的文件目录
## 数据模型
### APIKey
- id, key, name, created_at
### File
- id, key, filename, size, mime_type, owner_id, created_at
### Chunk (分片)
- id, upload_id, chunk_index, size, stored_path