orion/filecodebox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 利用AI更新文档

Browse Source
This commit is contained in:
Lan
2025-12-01 14:10:06 +08:00
parent d7200f6b9b
commit a20a0beb79
20 changed files with 4598 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/guide/configuration.md
+206
View File
@@ -0,0 +1,206 @@
# 配置说明
FileCodeBox 提供了丰富的配置选项，可以通过管理面板或直接修改配置来自定义系统行为。本文档详细介绍所有可用的配置项。
## 配置方式
FileCodeBox 支持两种配置方式：
1. **管理面板配置**（推荐）：访问 `/admin` 进入管理面板，在设置页面修改配置
2. **数据库配置**：配置存储在 `data/filecodebox.db` 数据库中
::: tip 提示
首次启动时，系统会使用 `core/settings.py` 中的默认配置。修改后的配置会保存到数据库中。
:::
## 基础设置
### 站点信息
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `name` | string | `文件快递柜 - FileCodeBox` | 站点名称，显示在页面标题和导航栏 |
| `description` | string | `开箱即用的文件快传系统` | 站点描述，用于 SEO |
| `keywords` | string | `FileCodeBox, 文件快递柜...` | 站点关键词，用于 SEO |
| `port` | int | `12345` | 服务监听端口 |
### 通知设置
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `notify_title` | string | `系统通知` | 通知标题 |
| `notify_content` | string | 欢迎信息 | 通知内容，支持 HTML |
| `page_explain` | string | 法律声明 | 页面底部说明文字 |
| `robotsText` | string | `User-agent: *\nDisallow: /` | robots.txt 内容 |
## 上传设置
### 文件上传限制
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `openUpload` | int | `1` | 是否开启上传功能（1=开启，0=关闭） |
| `uploadSize` | int | `10485760` | 单文件最大上传大小（字节），默认 10MB |
| `enableChunk` | int | `0` | 是否启用分片上传（1=启用，0=禁用） |
::: warning 注意
`uploadSize` 的单位是字节。10MB = 10 * 1024 * 1024 = 10485760 字节
:::
### 上传频率限制
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `uploadMinute` | int | `1` | 上传限制的时间窗口（分钟） |
| `uploadCount` | int | `10` | 在时间窗口内允许的最大上传次数 |
例如：默认配置表示每 1 分钟内最多允许上传 10 次。
### 文件过期设置
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `expireStyle` | list | `["day","hour","minute","forever","count"]` | 可选的过期方式 |
| `max_save_seconds` | int | `0` | 文件最大保存时间（秒），0 表示不限制 |
过期方式说明：
- `day` - 按天过期
- `hour` - 按小时过期
- `minute` - 按分钟过期
- `forever` - 永不过期
- `count` - 按下载次数过期
## 主题设置
### 主题选择
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `themesSelect` | string | `themes/2024` | 当前使用的主题 |
| `themesChoices` | list | 见下方 | 可用主题列表 |
默认可用主题：
```json
[
{
"name": "2023",
"key": "themes/2023",
"author": "Lan",
"version": "1.0"
},
{
"name": "2024",
"key": "themes/2024",
"author": "Lan",
"version": "1.0"
}
]
```
### 界面样式
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `opacity` | float | `0.9` | 界面透明度（0-1） |
| `background` | string | `""` | 自定义背景图片 URL，为空则使用默认背景 |
## 管理员设置
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `admin_token` | string | `FileCodeBox2023` | 管理员登录密码 |
| `showAdminAddr` | int | `0` | 是否在首页显示管理入口（1=显示，0=隐藏） |
::: danger 安全警告
请务必在生产环境中修改默认的 `admin_token`！使用默认密码会导致严重的安全风险。
:::
## 安全设置
### 错误次数限制
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `errorMinute` | int | `1` | 错误限制的时间窗口（分钟） |
| `errorCount` | int | `1` | 在时间窗口内允许的最大错误次数 |
此设置用于防止暴力破解提取码。
## 存储设置
### 存储类型
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `file_storage` | string | `local` | 存储后端类型 |
| `storage_path` | string | `""` | 自定义存储路径 |
支持的存储类型：
- `local` - 本地存储
- `s3` - S3 兼容存储（AWS S3、阿里云 OSS、MinIO 等）
- `onedrive` - OneDrive 存储
- `webdav` - WebDAV 存储
- `opendal` - OpenDAL 存储
详细的存储配置请参考 [存储配置](/guide/storage)。
## 配置示例
### 示例 1：小型个人使用
适合个人或小团队使用，限制较宽松：
```python
{
"name": "我的文件分享",
"uploadSize": 52428800, # 50MB
"uploadMinute": 5, # 5分钟
"uploadCount": 20, # 最多20次
"expireStyle": ["day", "hour", "forever"],
"admin_token": "your-secure-password",
"showAdminAddr": 1
}
```
### 示例 2：公开服务
适合公开服务，需要更严格的限制：
```python
{
"name": "公共文件快递柜",
"uploadSize": 10485760, # 10MB
"uploadMinute": 1, # 1分钟
"uploadCount": 5, # 最多5次
"errorMinute": 5, # 5分钟
"errorCount": 3, # 最多3次错误
"expireStyle": ["hour", "minute", "count"],
"max_save_seconds": 86400, # 最长保存1天
"admin_token": "very-secure-password-123",
"showAdminAddr": 0
}
```
### 示例 3：企业内部使用
适合企业内部使用，支持大文件和分片上传：
```python
{
"name": "企业文件中转站",
"uploadSize": 1073741824, # 1GB
"enableChunk": 1, # 启用分片上传
"uploadMinute": 10, # 10分钟
"uploadCount": 100, # 最多100次
"expireStyle": ["day", "forever"],
"file_storage": "s3", # 使用S3存储
"admin_token": "enterprise-secure-token",
"showAdminAddr": 1
}
```
## 下一步
- [存储配置](/guide/storage) - 了解如何配置不同的存储后端
- [安全设置](/guide/security) - 了解如何增强系统安全性
- [文件分享](/guide/share) - 了解文件分享功能
docs/guide/management.md
+412
View File
@@ -0,0 +1,412 @@
# 管理面板
FileCodeBox 提供了功能完善的管理面板，让管理员可以方便地管理文件、查看系统状态和修改配置。本文档介绍管理面板的各项功能和使用方法。
## 访问管理面板
### 登录方式
管理面板位于 `/admin` 路径。访问方式：
1. 在浏览器中访问 `http://your-domain.com/admin`
2. 输入管理员密码（`admin_token` 配置项的值）
3. 点击登录按钮
::: tip 提示
默认管理员密码是 `FileCodeBox2023`。请务必在生产环境中修改此密码，详见 [安全设置](/guide/security)。
:::
### 显示管理入口
默认情况下，首页不显示管理面板入口。您可以通过配置控制是否显示：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `showAdminAddr` | int | `0` | 是否在首页显示管理入口（1=显示，0=隐藏） |
::: warning 安全建议
在公开服务中，建议保持 `showAdminAddr` 为 `0`，通过直接访问 `/admin` 路径进入管理面板，减少被恶意扫描的风险。
:::
### 认证机制
管理面板使用 JWT（JSON Web Token）进行身份认证：
1. 登录成功后，服务器返回一个包含管理员身份的 Token
2. 后续请求通过 `Authorization: Bearer <token>` 头部携带 Token
3. Token 用于验证管理员身份，确保只有授权用户可以访问管理功能
## 仪表盘
登录后首先看到的是仪表盘页面，展示系统的整体运行状态。
### 统计指标
仪表盘显示以下关键指标：
| 指标 | 说明 |
|------|------|
| **文件总数** (`totalFiles`) | 系统中存储的文件总数量 |
| **存储使用量** (`storageUsed`) | 所有文件占用的总存储空间（字节） |
| **系统运行时间** (`sysUptime`) | 系统首次启动的时间 |
| **昨日上传数** (`yesterdayCount`) | 昨天一整天上传的文件数量 |
| **昨日上传量** (`yesterdaySize`) | 昨天上传文件的总大小（字节） |
| **今日上传数** (`todayCount`) | 今天到目前为止上传的文件数量 |
| **今日上传量** (`todaySize`) | 今天上传文件的总大小（字节） |
### 指标说明
- **文件总数**：包括所有未过期的文件和文本分享
- **存储使用量**：显示实际文件占用的存储空间，不包括数据库等系统文件
- **昨日/今日统计**：基于文件创建时间计算，用于了解系统使用趋势
::: tip 提示
存储使用量显示的是字节数。例如 `10485760` 表示约 10MB。
:::
## 文件管理
### 文件列表
文件管理页面展示系统中所有已分享的文件，支持分页浏览和搜索。
**列表信息包括：**
- 文件 ID
- 提取码（code）
- 文件名前缀（prefix）
- 文件后缀（suffix）
- 文件大小
- 创建时间
- 过期时间
- 剩余下载次数
### 搜索文件
使用搜索功能可以快速找到特定文件：
1. 在搜索框中输入关键词
2. 系统会根据文件名前缀（prefix）进行模糊匹配
3. 搜索结果实时更新
**搜索示例：**
- 输入 `report` 可以找到所有文件名包含 "report" 的文件
- 输入 `.pdf` 可以找到所有 PDF 文件（如果文件名包含此字符串）
### 分页浏览
文件列表支持分页显示：
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `page` | `1` | 当前页码 |
| `size` | `10` | 每页显示数量 |
### 删除文件
管理员可以删除任意文件：
1. 在文件列表中找到要删除的文件
2. 点击删除按钮
3. 确认删除操作
::: danger 警告
删除操作不可恢复！文件将从存储后端永久删除，同时删除数据库中的记录。
:::
**删除流程：**
1. 系统首先从存储后端（本地/S3/OneDrive 等）删除实际文件
2. 然后从数据库中删除文件记录
3. 删除后，对应的提取码将失效
### 下载文件
管理员可以直接下载任意文件：
1. 在文件列表中找到目标文件
2. 点击下载按钮
3. 文件将通过浏览器下载
对于文本分享，系统会直接返回文本内容而不是下载文件。
### 修改文件信息
管理员可以修改已分享文件的部分信息：
| 可修改字段 | 说明 |
|------------|------|
| `code` | 提取码（必须唯一，不能与其他文件重复） |
| `prefix` | 文件名前缀 |
| `suffix` | 文件后缀名 |
| `expired_at` | 过期时间 |
| `expired_count` | 剩余下载次数 |
**修改提取码：**
```
原提取码：abc123
新提取码：myfile2024
```
::: warning 注意
修改提取码时，系统会检查新提取码是否已被使用。如果已存在相同的提取码，修改将失败。
:::
## 本地文件管理
除了管理已分享的文件，管理面板还提供了本地文件管理功能，用于管理 `data/local` 目录中的文件。
### 查看本地文件
本地文件列表显示 `data/local` 目录中的所有文件：
| 信息 | 说明 |
|------|------|
| 文件名 | 文件的完整名称 |
| 创建时间 | 文件的创建时间 |
| 文件大小 | 文件大小（字节） |
### 分享本地文件
可以将本地文件快速分享：
1. 在本地文件列表中选择要分享的文件
2. 设置过期方式和过期值
3. 点击分享按钮
4. 系统生成提取码
**分享参数：**
| 参数 | 说明 |
|------|------|
| `filename` | 要分享的文件名 |
| `expire_style` | 过期方式（day/hour/minute/forever/count） |
| `expire_value` | 过期值（天数/小时数/分钟数/下载次数） |
### 删除本地文件
可以删除 `data/local` 目录中的文件：
1. 在本地文件列表中找到要删除的文件
2. 点击删除按钮
3. 确认删除
::: tip 使用场景
本地文件管理功能适用于：
- 批量上传文件到服务器后进行分享
- 管理通过其他方式上传到服务器的文件
- 清理不需要的本地文件
:::
## 系统设置
### 查看配置
在系统设置页面可以查看当前所有配置项的值。配置项按类别分组显示：
- 基础设置（站点名称、描述等）
- 上传设置（文件大小限制、频率限制等）
- 存储设置（存储类型、路径等）
- 主题设置（主题选择、透明度等）
- 安全设置（管理员密码、错误限制等）
### 修改配置
管理员可以通过管理面板修改大部分配置：
1. 进入系统设置页面
2. 找到要修改的配置项
3. 输入新的值
4. 点击保存按钮
**可修改的配置项：**
| 类别 | 配置项示例 |
|------|------------|
| 基础设置 | `name`, `description`, `keywords`, `notify_title`, `notify_content` |
| 上传设置 | `uploadSize`, `uploadMinute`, `uploadCount`, `openUpload`, `enableChunk` |
| 过期设置 | `expireStyle`, `max_save_seconds` |
| 主题设置 | `themesSelect`, `opacity`, `background` |
| 安全设置 | `admin_token`, `showAdminAddr`, `errorMinute`, `errorCount` |
| 存储设置 | `file_storage`, `storage_path` 及各存储后端的配置 |
::: warning 注意
- `admin_token`（管理员密码）不能设置为空
- `themesChoices`（主题列表）不可通过管理面板修改
- 修改存储设置后，已有文件不会自动迁移
:::
### 配置生效
配置修改后立即生效，无需重启服务。配置保存在数据库中，重启后仍然有效。
**配置存储位置：**
- 数据库：`data/filecodebox.db`
- 表名：`keyvalue`
- 键名：`settings`
## API 接口
管理面板的所有功能都通过 REST API 实现，以下是主要接口：
### 认证接口
**登录**
```
POST /admin/login
Content-Type: application/json
{
"password": "your-admin-password"
}
```
响应：
```json
{
"code": 200,
"detail": {
"token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer"
}
}
```
### 仪表盘接口
**获取统计数据**
```
GET /admin/dashboard
Authorization: Bearer <token>
```
### 文件管理接口
**获取文件列表**
```
GET /admin/file/list?page=1&size=10&keyword=
Authorization: Bearer <token>
```
**删除文件**
```
DELETE /admin/file/delete
Authorization: Bearer <token>
Content-Type: application/json
{
"id": 123
}
```
**下载文件**
```
GET /admin/file/download?id=123
Authorization: Bearer <token>
```
**修改文件信息**
```
PATCH /admin/file/update
Authorization: Bearer <token>
Content-Type: application/json
{
"id": 123,
"code": "newcode",
"expired_at": "2024-12-31T23:59:59"
}
```
### 本地文件接口
**获取本地文件列表**
```
GET /admin/local/lists
Authorization: Bearer <token>
```
**删除本地文件**
```
DELETE /admin/local/delete
Authorization: Bearer <token>
Content-Type: application/json
{
"filename": "example.txt"
}
```
**分享本地文件**
```
POST /admin/local/share
Authorization: Bearer <token>
Content-Type: application/json
{
"filename": "example.txt",
"expire_style": "day",
"expire_value": 7
}
```
### 配置接口
**获取配置**
```
GET /admin/config/get
Authorization: Bearer <token>
```
**更新配置**
```
PATCH /admin/config/update
Authorization: Bearer <token>
Content-Type: application/json
{
"admin_token": "new-password",
"uploadSize": 52428800
}
```
## 常见问题
### 忘记管理员密码
如果忘记了管理员密码，可以通过以下方式重置：
1. 停止 FileCodeBox 服务
2. 使用 SQLite 工具打开 `data/filecodebox.db`
3. 查询 `keyvalue` 表中 `key='settings'` 的记录
4. 修改 JSON 中的 `admin_token` 值
5. 重启服务
```sql
-- 查看当前配置
SELECT * FROM keyvalue WHERE key = 'settings';
-- 或者删除配置，恢复默认密码
DELETE FROM keyvalue WHERE key = 'settings';
```
### 文件删除失败
如果删除文件时出现错误，可能的原因：
1. **存储后端连接失败**：检查存储配置是否正确
2. **文件已不存在**：文件可能已被手动删除
3. **权限不足**：检查存储目录的写入权限
### 配置修改不生效
如果修改配置后没有生效：
1. 检查是否点击了保存按钮
2. 刷新页面查看配置是否已保存
3. 检查浏览器控制台是否有错误信息
4. 确认配置值的格式是否正确（如数字类型不要输入字符串）
## 下一步
- [配置说明](/guide/configuration) - 了解所有配置选项的详细说明
- [安全设置](/guide/security) - 了解如何增强系统安全性
- [存储配置](/guide/storage) - 配置不同的存储后端
docs/guide/security.md
+324
View File
@@ -0,0 +1,324 @@
# 安全设置
FileCodeBox 提供了多层安全机制来保护您的文件分享服务。本文档介绍如何正确配置安全选项，确保系统安全运行。
## 管理员密码
### 修改默认密码
::: danger 重要安全警告
FileCodeBox 的默认管理员密码是 `FileCodeBox2023`。**在生产环境中必须立即修改此密码！**使用默认密码会导致任何人都可以访问您的管理面板。
:::
修改管理员密码有两种方式：
**方式一：通过管理面板修改（推荐）**
1. 访问 `/admin` 进入管理面板
2. 使用当前密码登录
3. 进入「系统设置」页面
4. 找到 `admin_token` 配置项
5. 输入新的安全密码并保存
**方式二：通过数据库修改**
配置存储在 `data/filecodebox.db` 数据库的 `keyvalue` 表中，可以直接修改 `admin_token` 的值。
### 密码安全建议
- 使用至少 16 个字符的强密码
- 包含大小写字母、数字和特殊字符
- 避免使用常见词汇或个人信息
- 定期更换密码
```python
# 推荐的密码格式示例
"admin_token": "Xk9#mP2$vL5@nQ8&wR3"
```
### 隐藏管理入口
默认情况下，管理面板入口是隐藏的。您可以通过 `showAdminAddr` 配置控制是否在首页显示管理入口：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `showAdminAddr` | int | `0` | 是否显示管理入口（1=显示，0=隐藏） |
::: tip 建议
在公开服务中，建议保持 `showAdminAddr` 为 `0`，通过直接访问 `/admin` 路径进入管理面板。
:::
## IP 速率限制
FileCodeBox 内置了基于 IP 的速率限制机制，可以有效防止滥用和攻击。
### 上传频率限制
限制单个 IP 在指定时间内的上传次数：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `uploadMinute` | int | `1` | 上传限制的时间窗口（分钟） |
| `uploadCount` | int | `10` | 在时间窗口内允许的最大上传次数 |
**工作原理：**
- 系统记录每个 IP 的上传请求
- 当某 IP 在 `uploadMinute` 分钟内的上传次数达到 `uploadCount` 时
- 该 IP 的后续上传请求将被拒绝，返回 HTTP 423 错误
- 等待时间窗口过期后，计数器重置
**配置示例：**
```python
# 宽松配置：5分钟内最多上传20次
{
"uploadMinute": 5,
"uploadCount": 20
}
# 严格配置：1分钟内最多上传3次
{
"uploadMinute": 1,
"uploadCount": 3
}
```
### 错误次数限制
限制单个 IP 的错误尝试次数，防止暴力破解提取码：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `errorMinute` | int | `1` | 错误限制的时间窗口（分钟） |
| `errorCount` | int | `1` | 在时间窗口内允许的最大错误次数 |
**工作原理：**
- 当用户输入错误的提取码时，系统记录该 IP 的错误次数
- 当错误次数达到 `errorCount` 时，该 IP 将被暂时锁定
- 锁定时间为 `errorMinute` 分钟
- 锁定期间，该 IP 的所有提取请求都将被拒绝
**配置示例：**
```python
# 防暴力破解配置：5分钟内最多允许3次错误
{
"errorMinute": 5,
"errorCount": 3
}
```
::: warning 注意
默认配置 `errorMinute=1, errorCount=1` 非常严格，意味着输入一次错误的提取码后需要等待1分钟才能重试。根据实际需求调整此配置。
:::
## 上传限制
### 文件大小限制
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `uploadSize` | int | `10485760` | 单文件最大上传大小（字节），默认 10MB |
| `openUpload` | int | `1` | 是否开启上传功能（1=开启，0=关闭） |
**常用大小换算：**
- 10MB = 10 * 1024 * 1024 = `10485760`
- 50MB = 50 * 1024 * 1024 = `52428800`
- 100MB = 100 * 1024 * 1024 = `104857600`
- 1GB = 1024 * 1024 * 1024 = `1073741824`
### 文件过期设置
通过文件过期机制，可以自动清理过期文件，减少存储占用和安全风险：
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `expireStyle` | list | `["day","hour","minute","forever","count"]` | 可选的过期方式 |
| `max_save_seconds` | int | `0` | 文件最大保存时间（秒），0 表示不限制 |
**过期方式说明：**
- `day` - 按天数过期
- `hour` - 按小时过期
- `minute` - 按分钟过期
- `forever` - 永不过期（需要字符串提取码）
- `count` - 按下载次数过期
**安全建议：**
对于公开服务，建议：
1. 移除 `forever` 选项，避免文件永久存储
2. 设置 `max_save_seconds` 限制最长保存时间
3. 优先使用 `count` 方式，下载后自动删除
```python
# 公开服务推荐配置
{
"expireStyle": ["hour", "minute", "count"],
"max_save_seconds": 86400 # 最长保存1天
}
```
### 关闭上传功能
在某些情况下，您可能需要临时关闭上传功能：
```python
{
"openUpload": 0 # 关闭上传功能
}
```
## 反向代理安全配置
在生产环境中，通常会使用 Nginx 或其他反向代理服务器。以下是安全配置建议：
### Nginx 配置示例
```nginx
server {
listen 80;
server_name your-domain.com;
# 强制 HTTPS 重定向
return 301 https://$server_name$request_uri;
}
server {
listen 443 ssl http2;
server_name your-domain.com;
# SSL 证书配置
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_prefer_server_ciphers on;
# 安全头部
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header X-XSS-Protection "1; mode=block" always;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
# 限制请求体大小（与 uploadSize 配置一致）
client_max_body_size 100M;
# 传递真实 IP
location / {
proxy_pass http://127.0.0.1:12345;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 静态资源缓存
location /assets {
proxy_pass http://127.0.0.1:12345;
proxy_cache_valid 200 7d;
add_header Cache-Control "public, max-age=604800";
}
}
```
### 关键安全配置说明
**1. 传递真实 IP**
FileCodeBox 的 IP 限制功能依赖于获取客户端真实 IP。系统会按以下顺序获取 IP：
1. `X-Real-IP` 请求头
2. `X-Forwarded-For` 请求头
3. 直接连接的客户端 IP
确保反向代理正确设置这些头部：
```nginx
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
```
**2. 请求体大小限制**
Nginx 的 `client_max_body_size` 应该与 FileCodeBox 的 `uploadSize` 配置一致或略大：
```nginx
client_max_body_size 100M; # 允许上传最大 100MB
```
**3. HTTPS 加密**
强烈建议在生产环境中启用 HTTPS：
- 保护用户上传的文件内容
- 保护管理员登录凭据
- 防止中间人攻击
### Caddy 配置示例
```nginx
your-domain.com {
reverse_proxy localhost:12345
header {
X-Frame-Options "SAMEORIGIN"
X-Content-Type-Options "nosniff"
X-XSS-Protection "1; mode=block"
Strict-Transport-Security "max-age=31536000; includeSubDomains"
}
}
```
## 安全检查清单
部署 FileCodeBox 前，请确认以下安全配置：
- [ ] 已修改默认管理员密码 `admin_token`
- [ ] 已隐藏管理入口 `showAdminAddr: 0`
- [ ] 已配置合适的上传频率限制
- [ ] 已配置错误次数限制防止暴力破解
- [ ] 已设置合理的文件大小限制
- [ ] 已配置文件过期策略
- [ ] 已启用 HTTPS 加密
- [ ] 反向代理已正确传递真实 IP
- [ ] 已设置安全响应头部
## 推荐安全配置
### 公开服务配置
```python
{
"admin_token": "your-very-secure-password",
"showAdminAddr": 0,
"uploadSize": 10485760, # 10MB
"uploadMinute": 1,
"uploadCount": 5,
"errorMinute": 5,
"errorCount": 3,
"expireStyle": ["hour", "minute", "count"],
"max_save_seconds": 86400, # 最长1天
"openUpload": 1
}
```
### 内部服务配置
```python
{
"admin_token": "internal-secure-password",
"showAdminAddr": 1,
"uploadSize": 104857600, # 100MB
"uploadMinute": 5,
"uploadCount": 50,
"errorMinute": 1,
"errorCount": 5,
"expireStyle": ["day", "hour", "forever"],
"max_save_seconds": 0, # 不限制
"openUpload": 1
}
```
## 下一步
- [配置说明](/guide/configuration) - 了解所有配置选项
- [存储配置](/guide/storage) - 配置安全的存储后端
- [文件分享](/guide/share) - 了解文件分享功能
docs/guide/share.md
+341
View File
@@ -0,0 +1,341 @@
# 文件分享
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) - 了解如何管理分享的文件
docs/guide/storage.md
+383 -14
View File
@@ -1,26 +1,395 @@
# 阿里云设置
S3 AccessKeyId: `AccessKeyId`
# 存储配置
S3 SecretAccessKey: `SecretAccessKey`
FileCodeBox 支持多种存储后端，您可以根据需求选择合适的存储方式。本文档将详细介绍各种存储后端的配置方法。
S3 BucketName: `bucket-name`
## 存储类型概览
S3 EndpointUrl: `https://<bucket-name>.<region>.aliyuncs.com`
| 存储类型 | 配置值 | 说明 |
|---------|--------|------|
| 本地存储 | `local` | 默认存储方式，文件保存在服务器本地 |
| S3 兼容存储 | `s3` | 支持 AWS S3、阿里云 OSS、MinIO 等 |
| OneDrive | `onedrive` | 微软 OneDrive 云存储（仅支持工作/学校账户） |
| WebDAV | `webdav` | 支持 WebDAV 协议的存储服务 |
| OpenDAL | `opendal` | 通过 OpenDAL 集成更多存储服务 |
S3 Signature Version: `s3v4`
## 本地存储
S3 Region Name：`region`
本地存储是默认的存储方式，文件将保存在服务器的 `data/` 目录下。
# Minio设置
### 配置参数
S3 AccessKeyId: `AccessKeyId`
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `file_storage` | string | `local` | 存储类型 |
| `storage_path` | string | `""` | 自定义存储路径（可选） |
S3 SecretAccessKey: `SecretAccessKey`
### 配置示例
S3 BucketName: `bucket-name`
```bash
file_storage=local
storage_path=
```
S3 EndpointUrl: api接口地址
### 说明
S3 Signature Version: `s3v4`
- 文件默认存储在 `data/share/data/` 目录下
- 按日期自动创建子目录：`年/月/日/文件ID/`
- 建议在生产环境中将 `data/` 目录挂载到持久化存储
S3 Region Name：根据`configurations`里面设置的 `Server Location`
## S3 兼容存储
支持所有 S3 兼容的对象存储服务，包括 AWS S3、阿里云 OSS、MinIO、腾讯云 COS 等。
### 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `file_storage` | string | - | 设置为 `s3` |
| `s3_access_key_id` | string | `""` | Access Key ID |
| `s3_secret_access_key` | string | `""` | Secret Access Key |
| `s3_bucket_name` | string | `""` | 存储桶名称 |
| `s3_endpoint_url` | string | `""` | S3 端点 URL |
| `s3_region_name` | string | `auto` | 区域名称 |
| `s3_signature_version` | string | `s3v2` | 签名版本（`s3v2` 或 `s3v4`） |
| `s3_hostname` | string | `""` | S3 主机名（备用） |
| `s3_proxy` | int | `0` | 是否通过服务器代理下载（1=是，0=否） |
| `aws_session_token` | string | `""` | AWS 会话令牌（可选） |
### AWS S3 配置示例
```bash
file_storage=s3
s3_access_key_id=AKIAIOSFODNN7EXAMPLE
s3_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
s3_bucket_name=my-filecodebox-bucket
s3_endpoint_url=https://s3.amazonaws.com
s3_region_name=us-east-1
s3_signature_version=s3v4
```
### 阿里云 OSS 配置示例
```bash
file_storage=s3
s3_access_key_id=您的AccessKeyId
s3_secret_access_key=您的SecretAccessKey
s3_bucket_name=bucket-name
s3_endpoint_url=https://bucket-name.oss-cn-hangzhou.aliyuncs.com
s3_region_name=oss-cn-hangzhou
s3_signature_version=s3v4
```
::: tip 阿里云 OSS 端点格式
端点 URL 格式为：`https://<bucket-name>.<region>.aliyuncs.com`
常用区域：
- 杭州：`oss-cn-hangzhou`
- 上海：`oss-cn-shanghai`
- 北京：`oss-cn-beijing`
- 深圳：`oss-cn-shenzhen`
:::
### MinIO 配置示例
```bash
file_storage=s3
s3_access_key_id=minioadmin
s3_secret_access_key=minioadmin
s3_bucket_name=filecodebox
s3_endpoint_url=http://localhost:9000
s3_region_name=us-east-1
s3_signature_version=s3v4
```
::: warning MinIO 注意事项
- `s3_endpoint_url` 填写 MinIO 的 API 接口地址
- `s3_region_name` 根据 MinIO 配置中的 `Server Location` 设置
- 确保存储桶已创建且有正确的访问权限
:::
### 腾讯云 COS 配置示例
```bash
file_storage=s3
s3_access_key_id=您的SecretId
s3_secret_access_key=您的SecretKey
s3_bucket_name=bucket-name-1250000000
s3_endpoint_url=https://cos.ap-guangzhou.myqcloud.com
s3_region_name=ap-guangzhou
s3_signature_version=s3v4
```
### 代理下载
当 `s3_proxy=1` 时，文件下载将通过服务器中转，而不是直接从 S3 下载。这在以下情况下有用：
- S3 存储桶不允许公开访问
- 需要隐藏实际的存储地址
- 网络环境限制直接访问 S3
## OneDrive 存储
OneDrive 存储支持将文件保存到微软 OneDrive 云存储。
::: warning 重要限制
OneDrive 存储**仅支持工作或学校账户**，并且需要有管理员权限以授权 API。个人账户无法使用此功能。
:::
### 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `file_storage` | string | - | 设置为 `onedrive` |
| `onedrive_domain` | string | `""` | Azure AD 域名 |
| `onedrive_client_id` | string | `""` | 应用程序（客户端）ID |
| `onedrive_username` | string | `""` | 账户邮箱 |
| `onedrive_password` | string | `""` | 账户密码 |
| `onedrive_root_path` | string | `filebox_storage` | OneDrive 中的存储根目录 |
| `onedrive_proxy` | int | `0` | 是否通过服务器代理下载 |
### 配置示例
```bash
file_storage=onedrive
onedrive_domain=contoso.onmicrosoft.com
onedrive_client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
onedrive_username=user@contoso.onmicrosoft.com
onedrive_password=your_password
onedrive_root_path=filebox_storage
```
### Azure 应用注册步骤
要使用 OneDrive 存储，您需要在 Azure 门户中注册应用程序：
#### 1. 获取域名
登录 [Azure 门户](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade)，将鼠标置于右上角账号处，浮窗显示的**域**即为 `onedrive_domain` 的值。
#### 2. 注册应用
1. 点击左上角的 **+ 新注册**
2. 输入应用名称（如：FileCodeBox）
3. **受支持的帐户类型**：选择"任何组织目录(任何 Azure AD 目录 - 多租户)中的帐户和个人 Microsoft 帐户"
4. **重定向 URI**：选择 `Web`，输入 `http://localhost`
5. 点击**注册**
#### 3. 获取客户端 ID
注册完成后，在应用概述页面的**概要**中找到**应用程序(客户端)ID**，即为 `onedrive_client_id` 的值。
#### 4. 配置身份验证
1. 在左侧菜单选择**身份验证**
2. 找到**允许公共客户端流**，选择**是**
3. 点击**保存**
#### 5. 配置 API 权限
1. 在左侧菜单选择 **API 权限**
2. 点击 **+ 添加权限**
3. 选择 **Microsoft Graph** → **委托的权限**
4. 勾选以下权限：
- `openid`
- `Files.Read`
- `Files.Read.All`
- `Files.ReadWrite`
- `Files.ReadWrite.All`
- `User.Read`
5. 点击**添加权限**
6. 点击**代表 xxx 授予管理员同意**
7. 确认后，权限状态应显示为**已授予**
### 安装依赖
使用 OneDrive 存储需要安装额外的 Python 依赖：
```bash
pip install msal Office365-REST-Python-Client
```
### 验证配置
您可以使用以下代码测试配置是否正确：
```python
import msal
from office365.graph_client import GraphClient
domain = 'your_domain'
client_id = 'your_client_id'
username = 'your_username'
password = 'your_password'
def acquire_token_pwd():
authority_url = f'https://login.microsoftonline.com/{domain}'
app = msal.PublicClientApplication(
authority=authority_url,
client_id=client_id
)
result = app.acquire_token_by_username_password(
username=username,
password=password,
scopes=['https://graph.microsoft.com/.default']
)
return result
# 测试连接
client = GraphClient(acquire_token_pwd)
me = client.me.get().execute_query()
print(f"登录成功：{me.user_principal_name}")
```
## WebDAV 存储
WebDAV 存储支持将文件保存到任何支持 WebDAV 协议的服务，如 Nextcloud、ownCloud、坚果云等。
### 配置参数
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `file_storage` | string | - | 设置为 `webdav` |
| `webdav_url` | string | `""` | WebDAV 服务器 URL |
| `webdav_username` | string | `""` | WebDAV 用户名 |
| `webdav_password` | string | `""` | WebDAV 密码 |
| `webdav_root_path` | string | `filebox_storage` | WebDAV 中的存储根目录 |
| `webdav_proxy` | int | `0` | 是否通过服务器代理下载 |
### 配置示例
```bash
file_storage=webdav
webdav_url=https://dav.example.com/remote.php/dav/files/username/
webdav_username=your_username
webdav_password=your_password
webdav_root_path=filebox_storage
```
### Nextcloud 配置示例
```bash
file_storage=webdav
webdav_url=https://your-nextcloud.com/remote.php/dav/files/username/
webdav_username=your_username
webdav_password=your_app_password
webdav_root_path=FileCodeBox
```
::: tip Nextcloud 应用密码
建议在 Nextcloud 中创建应用密码，而不是使用主密码：
1. 登录 Nextcloud
2. 进入**设置** → **安全**
3. 在**设备与会话**中创建新的应用密码
:::
### 坚果云配置示例
```bash
file_storage=webdav
webdav_url=https://dav.jianguoyun.com/dav/
webdav_username=your_email@example.com
webdav_password=your_app_password
webdav_root_path=FileCodeBox
```
::: tip 坚果云应用密码
坚果云需要使用应用密码：
1. 登录坚果云网页版
2. 进入**账户信息** → **安全选项**
3. 添加应用密码
:::
## OpenDAL 存储
OpenDAL 是一个统一的数据访问层，支持多种存储服务。通过 OpenDAL，您可以使用 Google Cloud Storage、Azure Blob Storage 等更多存储服务。
### 配置参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `file_storage` | string | 设置为 `opendal` |
| `opendal_scheme` | string | 存储服务类型（如 `gcs`、`azblob`） |
| `opendal_<scheme>_<setting>` | string | 服务特定的配置参数 |
### 安装依赖
```bash
pip install opendal
```
### Google Cloud Storage 配置示例
```bash
file_storage=opendal
opendal_scheme=gcs
opendal_gcs_root=/filecodebox
opendal_gcs_bucket=your-bucket-name
opendal_gcs_credential=base64_encoded_credential
```
### Azure Blob Storage 配置示例
```bash
file_storage=opendal
opendal_scheme=azblob
opendal_azblob_root=/filecodebox
opendal_azblob_container=your-container
opendal_azblob_account_name=your_account
opendal_azblob_account_key=your_key
```
### 支持的服务
OpenDAL 支持众多存储服务，完整列表请参考 [OpenDAL 官方文档](https://opendal.apache.org/docs/rust/opendal/services/index.html)。
常用服务包括：
- `gcs` - Google Cloud Storage
- `azblob` - Azure Blob Storage
- `obs` - 华为云 OBS
- `oss` - 阿里云 OSS（通过 OpenDAL）
- `cos` - 腾讯云 COS（通过 OpenDAL）
- `hdfs` - Hadoop HDFS
- `ftp` - FTP 服务器
- `sftp` - SFTP 服务器
::: warning OpenDAL 注意事项
1. 通过 OpenDAL 集成的服务均通过服务器中转下载，会同时消耗存储服务和服务器的流量
2. 相比原生 S3/OneDrive 支持，OpenDAL 方式可能缺少一些调试信息
3. OpenDAL 采用 Rust 编写，性能较好
:::
## 存储选择建议
| 场景 | 推荐存储 | 原因 |
|------|----------|------|
| 个人/小型部署 | 本地存储 | 简单易用，无需额外配置 |
| 企业内网 | MinIO + S3 | 自建对象存储，数据可控 |
| 公有云部署 | 对应云厂商 S3 | 同区域访问快，成本低 |
| 已有 OneDrive | OneDrive | 利用现有资源 |
| 已有 WebDAV | WebDAV | 兼容性好 |
| 特殊存储需求 | OpenDAL | 支持更多存储服务 |
## 常见问题
### S3 上传失败
1. 检查 Access Key 和 Secret Key 是否正确
2. 确认存储桶名称和区域配置正确
3. 检查存储桶的访问权限设置
4. 确认签名版本（`s3v2` 或 `s3v4`）与服务商要求一致
### OneDrive 认证失败
1. 确认使用的是工作/学校账户，而非个人账户
2. 检查 Azure 应用是否已授予管理员同意
3. 确认 API 权限配置完整
4. 验证用户名和密码是否正确
### WebDAV 连接失败
1. 检查 WebDAV URL 格式是否正确
2. 确认用户名和密码（或应用密码）正确
3. 检查服务器是否支持 WebDAV 协议
4. 确认网络连接正常
docs/guide/upload.md
+379
View File
@@ -0,0 +1,379 @@
# 文件上传
FileCodeBox 提供了多种灵活的文件上传方式，支持普通上传和分片上传，满足不同场景的需求。
## 上传方式
FileCodeBox 支持以下几种上传方式：
### 拖拽上传
将文件直接拖拽到上传区域即可开始上传。这是最便捷的上传方式。
1. 打开 FileCodeBox 首页
2. 将文件从文件管理器拖拽到上传区域
3. 松开鼠标，文件开始上传
4. 上传完成后获取提取码
::: tip 提示
拖拽上传支持同时拖拽多个文件（取决于主题支持）。
:::
### 点击上传
点击上传区域，通过系统文件选择器选择文件。
1. 点击上传区域的「选择文件」按钮
2. 在弹出的文件选择器中选择要上传的文件
3. 确认选择后文件开始上传
4. 上传完成后获取提取码
### 粘贴上传
支持从剪贴板直接粘贴图片进行上传（部分主题支持）。
1. 复制图片到剪贴板（截图或复制图片）
2. 在上传区域使用 `Ctrl+V`（Windows/Linux）或 `Cmd+V`（macOS）粘贴
3. 图片自动开始上传
4. 上传完成后获取提取码
::: warning 注意
粘贴上传仅支持图片格式，不支持其他文件类型。具体支持情况取决于所使用的主题。
:::
## 文件大小限制
### 默认限制
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `uploadSize` | 10MB | 单文件最大上传大小 |
### 修改上传限制
管理员可以通过管理面板或配置文件修改上传大小限制：
```python
# 设置最大上传大小为 100MB
uploadSize = 104857600 # 100 * 1024 * 1024
```
::: info 说明
`uploadSize` 的单位是字节。常用换算：
- 10MB = 10485760
- 50MB = 52428800
- 100MB = 104857600
- 500MB = 524288000
- 1GB = 1073741824
:::
### 超出限制的处理
当上传文件超过大小限制时，系统会返回 403 错误：
```json
{
"detail": "大小超过限制,最大为10.00 MB"
}
```
## 普通上传 API
### 文件上传接口
**POST** `/share/file/`
Content-Type: `multipart/form-data`
**请求参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | file | 是 | 要上传的文件 |
| `expire_value` | int | 否 | 过期数值，默认 1 |
| `expire_style` | string | 否 | 过期方式，默认 `day` |
**过期方式选项：**
| 值 | 说明 |
|----|------|
| `day` | 按天过期 |
| `hour` | 按小时过期 |
| `minute` | 按分钟过期 |
| `forever` | 永不过期 |
| `count` | 按下载次数过期 |
**响应示例：**
```json
{
"code": 200,
"detail": {
"code": "654321",
"name": "example.pdf"
}
}
```
**cURL 示例：**
```bash
curl -X POST "http://localhost:12345/share/file/" \
-F "file=@/path/to/file.pdf" \
-F "expire_value=7" \
-F "expire_style=day"
```
## 分片上传 API
对于大文件，FileCodeBox 支持分片上传功能。分片上传将大文件分割成多个小块分别上传，支持断点续传。
::: warning 前提条件
分片上传功能需要管理员启用：`enableChunk=1`
:::
### 分片上传流程
```
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 初始化上传 │ ──▶ │ 上传分片 │ ──▶ │ 完成上传 │
│ /init/ │ │ /chunk/ │ │ /complete/ │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌───────────┐
│ 循环上传 │
│ 每个分片 │
└───────────┘
```
### 1. 初始化上传
**POST** `/chunk/upload/init/`
**请求参数：**
```json
{
"file_name": "large_file.zip",
"file_size": 104857600,
"chunk_size": 5242880,
"file_hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}
```
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `file_name` | string | 是 | - | 文件名 |
| `file_size` | int | 是 | - | 文件总大小（字节） |
| `chunk_size` | int | 否 | 5MB | 分片大小（字节） |
| `file_hash` | string | 是 | - | 文件的 SHA256 哈希值 |
**响应示例：**
```json
{
"code": 200,
"detail": {
"existed": false,
"upload_id": "abc123def456789",
"chunk_size": 5242880,
"total_chunks": 20,
"uploaded_chunks": []
}
}
```
| 字段 | 说明 |
|------|------|
| `existed` | 文件是否已存在（秒传） |
| `upload_id` | 上传会话 ID |
| `chunk_size` | 分片大小 |
| `total_chunks` | 总分片数 |
| `uploaded_chunks` | 已上传的分片索引列表 |
### 2. 上传分片
**POST** `/chunk/upload/chunk/{upload_id}/{chunk_index}`
**路径参数：**
| 参数 | 说明 |
|------|------|
| `upload_id` | 初始化时返回的上传会话 ID |
| `chunk_index` | 分片索引，从 0 开始 |
**请求体：**
Content-Type: `multipart/form-data`
| 参数 | 类型 | 说明 |
|------|------|------|
| `chunk` | file | 分片数据 |
**响应示例：**
```json
{
"code": 200,
"detail": {
"chunk_hash": "a1b2c3d4e5f6..."
}
}
```
**cURL 示例：**
```bash
# 上传第一个分片（索引为 0）
curl -X POST "http://localhost:12345/chunk/upload/chunk/abc123def456789/0" \
-F "chunk=@/path/to/chunk_0"
```
### 3. 完成上传
**POST** `/chunk/upload/complete/{upload_id}`
**路径参数：**
| 参数 | 说明 |
|------|------|
| `upload_id` | 上传会话 ID |
**请求参数：**
```json
{
"expire_value": 7,
"expire_style": "day"
}
```
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `expire_value` | int | 是 | 过期数值 |
| `expire_style` | string | 是 | 过期方式 |
**响应示例：**
```json
{
"code": 200,
"detail": {
"code": "789012",
"name": "large_file.zip"
}
}
```
### 断点续传
分片上传支持断点续传。当上传中断后：
1. 使用相同的 `file_hash` 重新调用初始化接口
2. 服务器返回 `uploaded_chunks` 列表，包含已上传的分片索引
3. 客户端只需上传不在列表中的分片
4. 所有分片上传完成后调用完成接口
**示例流程：**
```javascript
// 1. 初始化上传
const initResponse = await fetch('/chunk/upload/init/', {
method: 'POST',
body: JSON.stringify({
file_name: 'large_file.zip',
file_size: fileSize,
chunk_size: 5 * 1024 * 1024,
file_hash: fileHash
})
});
const { upload_id, uploaded_chunks, total_chunks } = await initResponse.json();
// 2. 上传未完成的分片
for (let i = 0; i < total_chunks; i++) {
if (!uploaded_chunks.includes(i)) {
const chunk = file.slice(i * chunkSize, (i + 1) * chunkSize);
await fetch(`/chunk/upload/chunk/${upload_id}/${i}`, {
method: 'POST',
body: chunk
});
}
}
// 3. 完成上传
await fetch(`/chunk/upload/complete/${upload_id}`, {
method: 'POST',
body: JSON.stringify({
expire_value: 7,
expire_style: 'day'
})
});
```
## 错误处理
### 常见错误
| HTTP 状态码 | 错误信息 | 原因 | 解决方案 |
|-------------|----------|------|----------|
| 403 | 大小超过限制 | 文件超过 `uploadSize` 限制 | 减小文件大小或联系管理员调整限制 |
| 403 | 上传频率限制 | 超过 IP 上传频率限制 | 等待限制时间窗口后重试 |
| 400 | 过期时间类型错误 | `expire_style` 值不在允许列表中 | 使用有效的过期方式 |
| 404 | 上传会话不存在 | `upload_id` 无效或已过期 | 重新初始化上传 |
| 400 | 无效的分片索引 | `chunk_index` 超出范围 | 检查分片索引是否正确 |
| 400 | 分片不完整 | 完成上传时分片数量不足 | 确保所有分片都已上传 |
### 频率限制
系统对上传操作有频率限制，防止滥用：
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| `uploadMinute` | 1 | 限制时间窗口（分钟） |
| `uploadCount` | 10 | 时间窗口内最大上传次数 |
当超过频率限制时，需要等待时间窗口过后才能继续上传。
### 错误响应格式
```json
{
"detail": "错误信息描述"
}
```
## 上传配置
### 相关配置项
| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `openUpload` | int | 1 | 是否开放上传（1=开放，0=关闭） |
| `uploadSize` | int | 10485760 | 最大上传大小（字节） |
| `enableChunk` | int | 0 | 是否启用分片上传（1=启用，0=禁用） |
| `uploadMinute` | int | 1 | 上传频率限制时间窗口（分钟） |
| `uploadCount` | int | 10 | 时间窗口内最大上传次数 |
| `expireStyle` | list | ["day","hour","minute","forever","count"] | 允许的过期方式 |
### 配置示例
```python
# 允许上传 100MB 文件，启用分片上传
uploadSize = 104857600
enableChunk = 1
# 放宽上传频率限制：每 5 分钟最多 50 次
uploadMinute = 5
uploadCount = 50
# 只允许按天和按次数过期
expireStyle = ["day", "count"]
```
## 下一步
- [文件分享](/guide/share) - 了解完整的分享流程
- [配置说明](/guide/configuration) - 了解所有配置选项
- [存储配置](/guide/storage) - 了解文件存储方式
- [安全设置](/guide/security) - 了解安全相关配置