Metadata-Version: 2.2
Name: large-file-upload-sdk
Version: 3.5.2
Summary: Large File Upload SDK - Support chunked upload, resumable transfer, and Token authentication
Home-page: https://github.com/your-username/file-upload-server
Author: SAIS Development Team
Author-email: SAIS Development Team <dev@sais.com.cn>
License: MIT
Project-URL: Homepage, https://github.com/your-username/file-upload-server
Project-URL: Documentation, https://github.com/your-username/file-upload-server#readme
Project-URL: Repository, https://github.com/your-username/file-upload-server
Project-URL: Bug Reports, https://github.com/your-username/file-upload-server/issues
Keywords: file upload,large file,chunked upload,resumable upload,file transfer,token authentication
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Archiving
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Requires-Dist: urllib3>=1.26.0
Requires-Dist: oss2>=2.18.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: black>=21.0; extra == "dev"
Requires-Dist: flake8>=3.8; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# File Upload Server

星河启智二期用于上传大文件的服务器 - 基于 FastAPI 构建，文件存储到阿里云 OSS

## 功能特性

- ✅ **OSS 直传**: SDK 通过 oss2 直接上传到 OSS，支持断点续传和分片上传
- ✅ **MD5校验**: 可选的文件MD5校验，确保数据完整性
- ✅ **Token认证**: 类似HuggingFace的Token认证机制，安全便捷
- ✅ **权限控制**: 支持用户角色和数据集访问权限管理
- ✅ **使用限制**: 支持文件大小和每日上传次数限制
- ✅ **上传记录**: 自动保存上传记录到数据库，支持查询和统计
- ✅ **RESTful API**: 提供完整的REST API接口
- ✅ **Docker支持**: 支持容器化部署

## 架构

```
用户电脑 ---(oss2 直传)--> 阿里云 OSS (inspire-alluxio-prod)
   |                              |
   +--- SDK 获取凭证 --> 服务器 ---+--- 记录上传完成
                                  +--- 通知前端
```

文件存储路径: `oss://inspire-alluxio-prod/{dataset_id}/{filename}`

## 快速开始

### 安装 SDK

```bash
pip install large-file-upload-sdk
```

### 上传文件

```python
from file_upload_sdk import FileUploadSDK

sdk = FileUploadSDK(
    base_url="https://file-upload-server.ai4s.com.cn",
    access_token="hf_your_token_here",
)

result = sdk.upload_file(
    file_path="/path/to/local_file.csv",
    dataset_id="my-dataset",
    progress_callback=lambda p: print(f"\r上传进度: {p:.1f}%", end="", flush=True),
)

print()
if result["success"]:
    print(f"上传成功! 路径: {result.get('file_path', '')}")
else:
    print(f"上传失败: {result['error']}")
```

### Token 认证

```python
# 方式1：直接使用已有Token
sdk = FileUploadSDK(
    base_url="https://file-upload-server.ai4s.com.cn",
    access_token="hf_your_token_here",
)

# 方式2：使用用户信息自动获取Token
sdk = FileUploadSDK(
    base_url="https://file-upload-server.ai4s.com.cn",
    user_id=12345,
    user_name="张三",
)
```

## 服务端部署

### 环境变量

| 配置项 | 说明 |
|--------|------|
| `OSS_ENDPOINT` | OSS Endpoint（默认 `https://oss-cn-wulanchabu.aliyuncs.com`） |
| `OSS_BUCKET` | OSS Bucket（默认 `inspire-alluxio-prod`） |
| `OSS_ACCESS_KEY_ID` | OSS AccessKey ID（必填） |
| `OSS_ACCESS_KEY_SECRET` | OSS AccessKey Secret（必填） |
| `MYSQL_HOST` | MySQL 地址 |
| `MYSQL_PORT` | MySQL 端口 |
| `MYSQL_USER` | MySQL 用户名 |
| `MYSQL_PASSWORD` | MySQL 密码 |
| `MYSQL_DATABASE` | MySQL 数据库名 |

### Docker 部署

```bash
docker run -d \
  --name file-upload-server \
  -p 8000:8000 \
  -e OSS_ACCESS_KEY_ID=your_ak \
  -e OSS_ACCESS_KEY_SECRET=your_sk \
  -e MYSQL_HOST=your_mysql_host \
  -e MYSQL_PASSWORD=your_mysql_password \
  file-upload-server
```

## API 接口

服务启动后访问 `http://localhost:8000/docs` 查看完整的API文档

### 主要接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/health` | GET | 健康检查 |
| `/api/token/generate` | POST | 生成访问令牌 |
| `/api/token/verify` | POST | 验证令牌有效性 |
| `/api/token/revoke` | DELETE | 撤销访问令牌 |
| `/api/oss-upload/init` | POST | 获取 OSS 上传凭证 |
| `/api/oss-upload/complete` | POST | 通知上传完成 |
| `/api/oss-upload/status/{task_id}` | GET | 查询上传任务状态 |
| `/api/upload/records` | GET | 查询上传记录 |
| `/api/upload/records/stats` | GET | 获取上传统计信息 |

## 相关文档

- [Token认证使用指南](TOKEN_USAGE_EXAMPLE.md)
- [上传记录功能指南](UPLOAD_RECORDS_GUIDE.md)
- [上传记录API文档](API_UPLOAD_RECORDS.md)
