# FileRelay 配置项详细说明文档

本文档整理了 FileRelay 系统 `config.yaml` 配置文件中各字段的含义、类型及示例，供前端配置页面开发参考。

## 1. 站点设置 (site)
用于定义前端展示的站点基本信息。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `name` | string | 站点名称，显示在网页标题和页头 | `文件暂存柜` |
| `description` | string | 站点描述，显示在首页或元标签中 | `临时文件中转服务` |

## 2. 安全设置 (security)
涉及系统鉴权、取件保护相关的核心安全配置。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `admin_password_hash` | string | 管理员密码的 bcrypt 哈希值 | `$2a$10$...` |
| `pickup_code_length` | int | 自动生成的取件码长度（已包含在公共配置接口中） | `6` |
| `pickup_fail_limit` | int | 单个 IP 对单个取件码尝试失败的最大次数，超过后将被临时封禁 | `5` |
| `jwt_secret` | string | 用于签发管理端 JWT Token 的密钥，建议设置为复杂随机字符串 | `file-relay-secret` |

## 3. 上传设置 (upload)
控制文件上传的限制和策略。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `max_file_size_mb` | int64 | 单个文件的最大允许大小（单位：MB） | `100` |
| `max_batch_files` | int | 一个取件批次中允许包含的最大文件数量 | `20` |
| `max_retention_days` | int | 文件在服务器上的最长保留天数（针对 time 类型的过期策略） | `30` |
| `require_token` | bool | 是否强制要求提供 API Token 才能进行上传操作 | `false` |

## 4. 存储设置 (storage)
定义文件的实际物理存储方式。系统支持多种存储后端。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `type` | string | 当前激活的存储类型。可选值：`local`, `webdav`, `s3` | `local` |

### 4.1 本地存储 (local)
当 `type` 为 `local` 时生效。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `path` | string | 文件存储在服务器本地的相对或绝对路径 | `storage_data` |

### 4.2 WebDAV 存储 (webdav)
当 `type` 为 `webdav` 时生效。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `url` | string | WebDAV 服务器的 API 地址 | `https://dav.example.com` |
| `username` | string | WebDAV 登录用户名 | `user` |
| `password` | string | WebDAV 登录密码 | `pass` |
| `root` | string | WebDAV 上的基础存储根目录 | `/file-relay` |

### 4.3 S3 存储 (s3)
当 `type` 为 `s3` 时生效。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `endpoint` | string | S3 服务端点 | `s3.amazonaws.com` |
| `region` | string | S3 区域 | `us-east-1` |
| `access_key` | string | S3 Access Key | `your-access-key` |
| `secret_key` | string | S3 Secret Key | `your-secret-key` |
| `bucket` | string | S3 存储桶名称 | `file-relay-bucket` |
| `use_ssl` | bool | 是否强制使用 SSL (HTTPS) 连接 | `false` |

## 5. API Token 设置 (api_token)
控制系统对外开放的 API Token 管理功能。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `enabled` | bool | 是否启用 API Token 功能模块 | `true` |
| `allow_admin_api` | bool | 是否允许具备 `admin` 权限的 API Token 访问管理接口 | `true` |
| `max_tokens` | int | 系统允许创建的 API Token 最大总数限制 | `20` |

## 6. 数据库设置 (database)
系统元数据存储配置。

| 字段名 | 类型 | 含义 | 示例 |
| :--- | :--- | :--- | :--- |
| `path` | string | SQLite 数据库文件的路径 | `file_relay.db` |

---

## 附录：公共配置接口 (/api/config)

为了方便前端展示和交互约束，系统提供了 `/api/config` 接口，该接口不需要鉴权，返回以下非敏感字段（结构与完整配置保持一致）：

- **site**: 完整内容（`name`, `description`）
- **security**: 仅包含 `pickup_code_length`
- **upload**: 完整内容（`max_file_size_mb`, `max_batch_files`, `max_retention_days`, `require_token`）
- **api_token**: 仅包含 `enabled` 开关
- **storage**: 仅包含 `type`（存储类型）