myoss/DESIGN.md

对象存储服务

技术栈

• Node.js + Express.js
• SQLite (better-sqlite3) + Sequelize
• 本地文件系统存储

快速开始

npm install
npm start                    # 默认 3000 端口, ./storage 目录
PORT=8080 npm start         # 指定端口
STORAGE_DIR=/data myoss     # 指定存储目录
PORT=8080 STORAGE_DIR=/data myoss  # 同时指定

使用方法

1. 创建首个 API Key（bootstrap）

curl -X POST http://localhost:3000/api/keys/bootstrap -H "Content-Type: application/json" -d '{"name":"root"}'
# 返回: {"key":"xxx","name":"root"}

2. 上传文件

curl -X POST http://localhost:3000/api/files \
  -H "X-API-Key: YOUR_KEY" \
  -F "file=@filename.ext"

3. 分片上传

# 初始化
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