diff --git a/docs/config_specification.md b/docs/config_specification.md
new file mode 100644
index 0000000..526f6c0
--- /dev/null
+++ b/docs/config_specification.md
@@ -0,0 +1,95 @@
+# 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`（存储类型）