# 文件分享

FileCodeBox 提供了简单易用的文件和文本分享功能。用户可以通过提取码安全地分享和获取文件。

## 分享方式

FileCodeBox 支持两种分享方式：

1. **文本分享** - 直接分享文本内容，适合代码片段、配置文件等
2. **文件分享** - 上传文件进行分享，支持各种文件格式

## 文本分享

### 使用方法

1. 在首页选择「文本分享」标签
2. 在文本框中输入或粘贴要分享的内容
3. 选择过期方式和时间
4. 点击「分享」按钮
5. 获取提取码

### 文本大小限制

::: warning 注意
文本分享的最大内容大小为 **222KB**（227,328 字节）。如果内容超过此限制，建议使用文件分享方式。
:::

文本内容大小按 UTF-8 编码计算，中文字符通常占用 3 个字节。

### API 接口

**POST** `/share/text/`

请求参数：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `text` | string | 是 | 要分享的文本内容 |
| `expire_value` | int | 否 | 过期数值，默认 1 |
| `expire_style` | string | 否 | 过期方式，默认 `day` |

响应示例：

```json
{
  "code": 200,
  "detail": {
    "code": "123456"
  }
}
```

## 文件分享

### 使用方法

1. 在首页选择「文件分享」标签
2. 点击上传区域或拖拽文件到上传区域
3. 选择过期方式和时间
4. 点击「上传」按钮
5. 获取提取码

### 文件大小限制

默认单文件最大上传大小为 **10MB**。管理员可以通过 `uploadSize` 配置项修改此限制。

::: tip 提示
如果需要上传大文件，请联系管理员启用分片上传功能，或调整 `uploadSize` 配置。
:::

### 支持的上传方式

- **点击上传** - 点击上传区域选择文件
- **拖拽上传** - 将文件拖拽到上传区域
- **粘贴上传** - 从剪贴板粘贴图片（部分主题支持）

### API 接口

**POST** `/share/file/`

请求参数（multipart/form-data）：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | file | 是 | 要上传的文件 |
| `expire_value` | int | 否 | 过期数值，默认 1 |
| `expire_style` | string | 否 | 过期方式，默认 `day` |

响应示例：

```json
{
  "code": 200,
  "detail": {
    "code": "654321",
    "name": "example.pdf"
  }
}
```

## 过期设置

FileCodeBox 支持多种灵活的过期方式：

| 过期方式 | 参数值 | 说明 |
|----------|--------|------|
| 按天过期 | `day` | 文件在指定天数后过期 |
| 按小时过期 | `hour` | 文件在指定小时后过期 |
| 按分钟过期 | `minute` | 文件在指定分钟后过期 |
| 永不过期 | `forever` | 文件永久有效 |
| 按次数过期 | `count` | 文件在被下载指定次数后过期 |

::: info 说明
- 管理员可以通过 `expireStyle` 配置项控制用户可选的过期方式
- 管理员可以通过 `max_save_seconds` 配置项限制文件的最长保存时间
:::

### 过期方式示例

```bash
# 文件 3 天后过期
expire_value=3, expire_style=day

# 文件 12 小时后过期
expire_value=12, expire_style=hour

# 文件 30 分钟后过期
expire_value=30, expire_style=minute

# 文件永不过期
expire_value=1, expire_style=forever

# 文件被下载 5 次后过期
expire_value=5, expire_style=count
```

## 提取文件

### 使用方法

1. 在首页的「提取文件」区域输入提取码
2. 点击「提取」按钮
3. 系统会显示文件信息（文件名、大小等）
4. 点击「下载」按钮下载文件，或直接查看文本内容

### 提取码说明

- 提取码通常为 **6 位数字**
- 永不过期的文件使用 **字母数字混合** 的提取码
- 提取码区分大小写（针对字母数字混合的情况）

### API 接口

**查询文件信息**

**POST** `/share/select/`

请求参数：

```json
{
  "code": "123456"
}
```

响应示例（文件）：

```json
{
  "code": 200,
  "detail": {
    "code": "123456",
    "name": "example.pdf",
    "size": 1048576,
    "text": "https://example.com/download/..."
  }
}
```

响应示例（文本）：

```json
{
  "code": 200,
  "detail": {
    "code": "123456",
    "name": "Text",
    "size": 1024,
    "text": "这是分享的文本内容..."
  }
}
```

**直接下载文件**

**GET** `/share/select/?code=123456`

此接口会直接返回文件内容，适合在浏览器中直接访问。

## 分片上传（大文件）

对于大文件上传，FileCodeBox 支持分片上传功能。此功能需要管理员启用（`enableChunk=1`）。

### 分片上传流程

```mermaid
sequenceDiagram
    participant C as 客户端
    participant S as 服务器
    
    C->>S: 1. 初始化上传 (POST /chunk/upload/init/)
    S-->>C: 返回 upload_id 和分片信息
    
    loop 每个分片
        C->>S: 2. 上传分片 (POST /chunk/upload/chunk/{upload_id}/{chunk_index})
        S-->>C: 返回分片哈希
    end
    
    C->>S: 3. 完成上传 (POST /chunk/upload/complete/{upload_id})
    S-->>C: 返回提取码
```

### 1. 初始化上传

**POST** `/chunk/upload/init/`

请求参数：

```json
{
  "file_name": "large_file.zip",
  "file_size": 104857600,
  "chunk_size": 5242880,
  "file_hash": "sha256_hash_of_file"
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file_name` | string | 是 | 文件名 |
| `file_size` | int | 是 | 文件总大小（字节） |
| `chunk_size` | int | 否 | 分片大小，默认 5MB |
| `file_hash` | string | 是 | 文件的 SHA256 哈希值 |

响应示例：

```json
{
  "code": 200,
  "detail": {
    "existed": false,
    "upload_id": "abc123def456",
    "chunk_size": 5242880,
    "total_chunks": 20,
    "uploaded_chunks": []
  }
}
```

### 2. 上传分片

**POST** `/chunk/upload/chunk/{upload_id}/{chunk_index}`

- `upload_id` - 初始化时返回的上传会话 ID
- `chunk_index` - 分片索引，从 0 开始

请求体：分片文件数据（multipart/form-data）

响应示例：

```json
{
  "code": 200,
  "detail": {
    "chunk_hash": "sha256_hash_of_chunk"
  }
}
```

### 3. 完成上传

**POST** `/chunk/upload/complete/{upload_id}`

请求参数：

```json
{
  "expire_value": 1,
  "expire_style": "day"
}
```

响应示例：

```json
{
  "code": 200,
  "detail": {
    "code": "789012",
    "name": "large_file.zip"
  }
}
```

### 断点续传

分片上传支持断点续传。如果上传中断，可以：

1. 重新调用初始化接口，使用相同的 `file_hash`
2. 服务器会返回已上传的分片列表 `uploaded_chunks`
3. 客户端只需上传未完成的分片

## 错误处理

### 常见错误码

| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 403 | 文件大小超过限制 | 减小文件大小或联系管理员调整限制 |
| 403 | 内容过多 | 文本超过 222KB，请使用文件分享 |
| 403 | 上传频率限制 | 等待一段时间后重试 |
| 404 | 文件不存在 | 检查提取码是否正确 |
| 404 | 文件已过期 | 文件已过期或下载次数已用完 |

### 频率限制

为防止滥用，系统对上传和提取操作有频率限制：

- **上传限制**：默认每分钟最多 10 次上传
- **错误限制**：默认每分钟最多 1 次错误尝试

::: tip 提示
如果遇到频率限制，请等待限制时间窗口过后再重试。
:::

## 下一步

- [配置说明](/guide/configuration) - 了解如何配置分享相关设置
- [存储配置](/guide/storage) - 了解文件存储方式
- [安全设置](/guide/security) - 了解安全相关配置
- [管理面板](/guide/management) - 了解如何管理分享的文件