Configuration Guide

FileCodeBox provides rich configuration options. Prefer the admin panel; directly editing the database can introduce invalid types or break security settings.

Configuration Methods

FileCodeBox supports two configuration methods:

1. Admin Panel Configuration (Recommended): Access /admin to enter the admin panel and modify settings on the settings page
2. Database Configuration: Configuration is stored in the data/filecodebox.db database

Note

On first startup, the system uses default configuration from core/settings.py. Modified configurations are saved to the database.

Basic Settings

Site Information

Setting	Type	Default	Description
name	string	文件快递柜 - FileCodeBox	Site name, displayed in page title and navigation bar
description	string	开箱即用的文件快传系统	Site description, used for SEO
keywords	string	FileCodeBox, 文件快递柜...	Site keywords, used for SEO
serverHost	string	0.0.0.0	Service listening address
serverPort	int	12345	Service listening port
serverWorkers	int	1	Worker count; keep one worker for SQLite deployments

Notification Settings

Setting	Type	Default	Description
notify_title	string	系统通知	Notification title
notify_content	string	Welcome message	Notification content, supports HTML
page_explain	string	Legal disclaimer	Footer explanation text
robotsText	string	User-agent: *\nDisallow: /	robots.txt content

Upload Settings

File Upload Limits

Setting	Type	Default	Description
openUpload	int	1	Enable upload functionality (1=enabled, 0=disabled)
uploadSize	int	10485760	Maximum single file upload size (bytes), default 10MB
enableChunk	int	0	Enable chunked upload (1=enabled, 0=disabled)
allowed_file_types	list	["*"]	Allowed extensions; * allows every file type

Note

uploadSize is in bytes. 10MB = 10 * 1024 * 1024 = 10485760 bytes

Upload Rate Limiting

Setting	Type	Default	Description
uploadMinute	int	1	Upload limit time window (minutes)
uploadCount	int	10	Maximum uploads allowed within the time window

Example: Default configuration allows up to 10 uploads per minute.

File Expiration Settings

Setting	Type	Default	Description
expireStyle	list	["day","hour","minute","forever","count"]	Available expiration methods
max_save_seconds	int	0	Maximum file retention time (seconds), 0 means no limit

Expiration methods explained:

• day - Expire by days
• hour - Expire by hours
• minute - Expire by minutes
• forever - Never expire
• count - Expire by download count

Theme Settings

Theme Selection

Setting	Type	Default	Description
themesSelect	string	themes/2024	Currently active theme
themesChoices	list	See below	Available themes list

Default available themes:

[
  {
    "name": "2023",
    "key": "themes/2023",
    "author": "Lan",
    "version": "1.0"
  },
  {
    "name": "2024",
    "key": "themes/2024",
    "author": "Lan",
    "version": "1.0"
  }
]

Interface Style

Setting	Type	Default	Description
opacity	float	0.9	Interface opacity (0-1)
background	string	""	Custom background image URL, empty uses default background

Admin Settings

Setting	Type	Default	Description
admin_token	string	Set during setup	Admin login password
showAdminAddr	int	0	Show admin panel entry on homepage (1=show, 0=hide)
adminSessionExpire	int	2592000	Admin session lifetime in seconds (30 days)

Security Warning

The setup page is shown automatically while the system is uninitialized. Complete setup before exposing a production service to the public internet.

Security Settings

Error Rate Limiting

Setting	Type	Default	Description
errorMinute	int	1	Error limit time window (minutes)
errorCount	int	10	Maximum errors allowed within the time window
trustedProxies	list	[]	Trusted reverse-proxy IPs used to resolve client addresses

This setting prevents brute-force attacks on extraction codes.

Storage Settings

Storage Type

Setting	Type	Default	Description
file_storage	string	local	Storage backend type
storage_path	string	""	Custom storage path
storageLimit	int	0	Total storage quota in bytes; 0 means unlimited

Supported storage types:

• local - Local storage
• s3 - S3-compatible storage (AWS S3, Aliyun OSS, MinIO, etc.)
• onedrive - OneDrive storage
• webdav - WebDAV storage
• opendal - OpenDAL storage

For detailed storage configuration, see Storage Configuration.

Configuration Examples

Example 1: Small Personal Use

Suitable for personal or small team use with relaxed limits:

{
    "name": "My File Share",
    "uploadSize": 52428800,        # 50MB
    "uploadMinute": 5,             # 5 minutes
    "uploadCount": 20,             # Max 20 uploads
    "expireStyle": ["day", "hour", "forever"],
    "showAdminAddr": 1
}

Example 2: Public Service

Suitable for public services requiring stricter limits:

{
    "name": "Public File Box",
    "uploadSize": 10485760,        # 10MB
    "uploadMinute": 1,             # 1 minute
    "uploadCount": 5,              # Max 5 uploads
    "errorMinute": 5,              # 5 minutes
    "errorCount": 3,               # Max 3 errors
    "expireStyle": ["hour", "minute", "count"],
    "max_save_seconds": 86400,     # Max retention 1 day
    "showAdminAddr": 0
}

Example 3: Enterprise Internal Use

Suitable for enterprise internal use with large file and chunked upload support:

{
    "name": "Enterprise File Transfer",
    "uploadSize": 1073741824,      # 1GB
    "enableChunk": 1,              # Enable chunked upload
    "uploadMinute": 10,            # 10 minutes
    "uploadCount": 100,            # Max 100 uploads
    "expireStyle": ["day", "forever"],
    "file_storage": "s3",          # Use S3 storage
    "showAdminAddr": 1
}

Configuration examples

These dictionaries illustrate combinations of values; they are not editable configuration files. Set the admin password through first-run setup or the admin panel.

Next Steps

• Storage Configuration - Learn how to configure different storage backends
• Security Settings - Learn how to enhance system security
• File Sharing - Learn about file sharing features