# Token认证使用指南

## 🎯 概述

新的Token认证系统提供了类似HuggingFace的使用体验，用户可以通过提供基本信息获取访问令牌，然后使用该令牌进行文件上传操作。

## 🚀 快速开始

### 1. 获取访问令牌

```bash
curl -X POST "https://file-upload-server.ai4s.com.cn/api/token/generate" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "your_user_id",
    "user_name": "Your Name",
    "role": "user",
    "max_file_size": 1099511627776,
    "daily_upload_limit": 100
  }'
```

**响应示例：**
```json
{
  "access_token": "hf_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",
  "token_type": "Bearer",
  "user_info": {
    "user_id": "your_user_id",
    "user_name": "Your Name",
    "role": "user",
    "max_file_size": 1099511627776,
    "daily_upload_limit": 100
  }
}
```

### 2. 使用Token上传文件

```bash
# 使用Bearer Token认证
curl -X POST "https://file-upload-server.ai4s.com.cn/api/upload/check" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hf_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890" \
  -d '{
    "file_name": "example.txt",
    "file_size": 1024,
    "file_md5": "d41d8cd98f00b204e9800998ecf8427e",
    "dataset_name": "my-dataset"
  }'
```

## 🔧 API接口详情

### Token管理接口

#### 生成Token
- **POST** `/api/token/generate`
- **描述**: 为用户生成访问令牌

**请求参数：**
```json
{
  "user_id": "string (必需)",
  "user_name": "string (必需)",
  "role": "user|admin|guest (默认: user)",
  "max_file_size": "number (字节，默认: 1TB)",
  "daily_upload_limit": "number (默认: 100)"
}
```

#### 验证Token
- **POST** `/api/token/verify?token=<access_token>`
- **描述**: 验证Token有效性

#### 撤销Token
- **DELETE** `/api/token/revoke?token=<access_token>`
- **描述**: 撤销指定Token

#### 查询用户Token
- **GET** `/api/token/user/{user_id}/tokens`
- **描述**: 获取用户的所有Token信息

#### 查询可用角色
- **GET** `/api/token/roles`
- **描述**: 获取系统支持的用户角色

## 🐍 Python SDK集成

### 更新SDK支持Token认证

```python
import requests

class FileUploadClient:
    def __init__(self, base_url, access_token=None):
        self.base_url = base_url
        self.access_token = access_token
        self.session = requests.Session()
        
        if access_token:
            self.session.headers.update({
                "Authorization": f"Bearer {access_token}"
            })
    
    @classmethod
    def from_user_info(cls, base_url, user_id, user_name, **kwargs):
        """通过用户信息自动获取Token"""
        token_data = {
            "user_id": user_id,
            "user_name": user_name,
            **kwargs
        }
        
        response = requests.post(f"{base_url}/api/token/generate", json=token_data)
        response.raise_for_status()
        
        result = response.json()
        access_token = result["access_token"]
        
        return cls(base_url, access_token)
    
    def upload_file(self, file_path, dataset_name):
        """上传文件"""
        # 检查文件状态
        check_data = {
            "file_name": os.path.basename(file_path),
            "file_size": os.path.getsize(file_path),
            "file_md5": self._calculate_md5(file_path),
            "dataset_name": dataset_name
        }
        
        response = self.session.post(
            f"{self.base_url}/api/upload/check",
            json=check_data
        )
        response.raise_for_status()
        
        # 后续上传逻辑...

# 使用示例
client = FileUploadClient.from_user_info(
    base_url="https://file-upload-server.ai4s.com.cn",
    user_id="your_user_id",
    user_name="Your Name",
    role="user",
    expires_hours=24
)

client.upload_file("./data.txt", "my-dataset")
```

## 🔐 认证方式

系统支持以下Token传递方式：

### 1. Bearer Token（推荐）
```bash
Authorization: Bearer hf_your_access_token_here
```

### 2. 查询参数（仅限验证接口）
```bash
?token=hf_your_access_token_here
```

## 👥 用户角色

| 角色 | 权限 | 描述 |
|------|------|------|
| `admin` | 所有权限 | 管理员，可访问所有数据集和功能 |
| `user` | 标准权限 | 普通用户，按配置的权限访问 |
| `guest` | 只读权限 | 访客用户，受限的访问权限 |

## ⚡ 权限控制

### 数据集权限
- `allowed_datasets` 为空：可访问所有数据集
- `allowed_datasets` 有值：只能访问指定的数据集
- `admin` 角色：无视 `allowed_datasets` 限制

### 文件大小限制
- `max_file_size`：单个文件最大大小（字节）
- 超过限制的文件会被拒绝上传

### 使用频率限制
- `daily_upload_limit`：每日最大上传次数
- 达到限制后需要等到次日重置

## 🕐 Token管理

### Token格式
```
hf_<32位随机字符串>
```

### 过期策略
- **永不过期**：Token一旦生成，永久有效
- 简化管理：无需担心Token过期问题

### 安全存储
- Token使用SHA256哈希存储在MySQL数据库
- 支持Token手动撤销（删除）
- 简化的权限管理

## 📊 使用统计

每个Token会记录：
- 总使用次数
- 每日使用次数
- 最后使用时间
- 创建时间和过期时间

## 🔄 迁移指南

### 从API Key迁移到Token

**旧方式（API Key）：**
```python
sdk = FileUploadSDK(api_key="ak_12345_...")
```

**新方式（Token）：**
```python
client = FileUploadClient.from_user_info(
    base_url="https://file-upload-server.ai4s.com.cn",
    user_id="12345",
    user_name="用户名"
)
```

### 兼容性
- 系统保持对旧API Key的支持
- 可以同时使用两种认证方式
- 建议新项目使用Token认证

## 🐛 故障排查

### 常见错误

#### 401 Unauthorized
```json
{"detail": "缺少访问令牌，请在请求头中添加 Authorization: Bearer <token>"}
```
**解决**: 确保在请求头中正确添加Bearer Token

#### 401 Invalid Token
```json
{"detail": "无效或过期的访问令牌"}
```
**解决**: Token可能已过期或被撤销，需要重新生成

#### 403 Forbidden
```json
{"detail": "无权访问数据集: dataset-name"}
```
**解决**: 检查用户的 `allowed_datasets` 配置

#### 429 Too Many Requests
```json
{"detail": "今日上传次数已达上限，请明天再试"}
```
**解决**: 已达到每日上传限制，等待次日重置

## 📝 最佳实践

1. **安全存储Token**: 不要在代码中硬编码Token
2. **合理设置过期时间**: 根据使用频率设置适当的过期时间
3. **及时撤销**: 不再使用的Token应及时撤销
4. **权限最小化**: 只授予必要的权限
5. **监控使用**: 定期检查Token使用情况
