FileRelay/docs/config_specification.md

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（存储类型）