filecodebox/docs/en/guide/management.md

Admin Panel

FileCodeBox provides a fully-featured admin panel that allows administrators to conveniently manage files, view system status, and modify configurations. This document introduces the various features and usage of the admin panel.

Accessing the Admin Panel

Login Method

The admin panel is located at the /admin path. Access method:

1. Visit http://your-domain.com/admin in your browser
2. Enter the admin password (the value of the admin_token configuration)
3. Click the login button

::: tip Tip The default admin password is FileCodeBox2023. Be sure to change this password in production environments. See Security Settings for details. :::

Show Admin Entry

By default, the admin panel entry is not shown on the homepage. You can control whether to show it via configuration:

Setting	Type	Default	Description
showAdminAddr	int	0	Show admin entry on homepage (1=show, 0=hide)

::: warning Security Recommendation For public services, it's recommended to keep showAdminAddr at 0 and access the admin panel directly via the /admin path to reduce the risk of malicious scanning. :::

Authentication Mechanism

The admin panel uses JWT (JSON Web Token) for authentication:

1. After successful login, the server returns a Token containing admin identity
2. Subsequent requests carry the Token via Authorization: Bearer <token> header
3. Token is used to verify admin identity, ensuring only authorized users can access admin functions

Dashboard

After logging in, you first see the dashboard page, which displays the overall system status.

Statistics

The dashboard displays the following key metrics:

Metric	Description
Total Files (totalFiles)	Total number of files stored in the system
Storage Used (storageUsed)	Total storage space occupied by all files (bytes)
System Uptime (sysUptime)	Time when the system was first started
Yesterday's Uploads (yesterdayCount)	Number of files uploaded yesterday
Yesterday's Upload Size (yesterdaySize)	Total size of files uploaded yesterday (bytes)
Today's Uploads (todayCount)	Number of files uploaded today so far
Today's Upload Size (todaySize)	Total size of files uploaded today (bytes)

Metric Notes

• Total Files: Includes all unexpired files and text shares
• Storage Used: Shows actual storage space occupied by files, excluding database and other system files
• Yesterday/Today Statistics: Calculated based on file creation time, useful for understanding system usage trends

::: tip Tip Storage usage is displayed in bytes. For example, 10485760 represents approximately 10MB. :::

File Management

File List

The file management page displays all shared files in the system, supporting pagination and search.

List information includes:

• File ID
• Extraction code (code)
• Filename prefix (prefix)
• File extension (suffix)
• File size
• Creation time
• Expiration time
• Remaining download count

Search Files

Use the search function to quickly find specific files:

1. Enter keywords in the search box
2. System performs fuzzy matching based on filename prefix (prefix)
3. Search results update in real-time

Search examples:

• Enter report to find all files with "report" in the filename
• Enter .pdf to find all PDF files (if the filename contains this string)

Pagination

The file list supports paginated display:

Parameter	Default	Description
page	1	Current page number
size	10	Items per page

Delete Files

Administrators can delete any file:

1. Find the file to delete in the file list
2. Click the delete button
3. Confirm the delete operation

::: danger Warning Delete operations are irreversible! Files will be permanently deleted from the storage backend, and database records will also be removed. :::

Delete process:

1. System first deletes the actual file from the storage backend (local/S3/OneDrive, etc.)
2. Then deletes the file record from the database
3. After deletion, the corresponding extraction code becomes invalid

Download Files

Administrators can directly download any file:

1. Find the target file in the file list
2. Click the download button
3. File will be downloaded via browser

For text shares, the system returns text content directly instead of downloading a file.

Modify File Information

Administrators can modify some information of shared files:

Modifiable Field	Description
code	Extraction code (must be unique, cannot duplicate other files)
prefix	Filename prefix
suffix	File extension
expired_at	Expiration time
expired_count	Remaining download count

Modify extraction code:

Original code: abc123
New code: myfile2024

::: warning Note When modifying extraction codes, the system checks if the new code is already in use. If an identical extraction code exists, the modification will fail. :::

Local File Management

In addition to managing shared files, the admin panel also provides local file management functionality for managing files in the data/local directory.

View Local Files

The local file list displays all files in the data/local directory:

Information	Description
Filename	Complete filename
Creation Time	File creation time
File Size	File size (bytes)

Share Local Files

You can quickly share local files:

1. Select the file to share in the local file list
2. Set expiration method and value
3. Click the share button
4. System generates extraction code

Share parameters:

Parameter	Description
filename	Filename to share
expire_style	Expiration method (day/hour/minute/forever/count)
expire_value	Expiration value (days/hours/minutes/download count)

Delete Local Files

You can delete files in the data/local directory:

1. Find the file to delete in the local file list
2. Click the delete button
3. Confirm deletion

::: tip Use Cases Local file management is useful for:

• Sharing files after batch uploading to the server
• Managing files uploaded to the server through other means
• Cleaning up unnecessary local files :::

System Settings

View Configuration

On the system settings page, you can view the current values of all configuration items. Configuration items are grouped by category:

• Basic settings (site name, description, etc.)
• Upload settings (file size limits, rate limits, etc.)
• Storage settings (storage type, path, etc.)
• Theme settings (theme selection, opacity, etc.)
• Security settings (admin password, error limits, etc.)

Modify Configuration

Administrators can modify most configurations through the admin panel:

1. Go to the system settings page
2. Find the configuration item to modify
3. Enter the new value
4. Click the save button

Modifiable configuration items:

Category	Example Settings
Basic Settings	name, description, keywords, notify_title, notify_content
Upload Settings	uploadSize, uploadMinute, uploadCount, openUpload, enableChunk
Expiration Settings	expireStyle, max_save_seconds
Theme Settings	themesSelect, opacity, background
Security Settings	admin_token, showAdminAddr, errorMinute, errorCount
Storage Settings	file_storage, storage_path and storage backend-specific configurations

::: warning Note

• admin_token (admin password) cannot be set to empty
• themesChoices (theme list) cannot be modified through the admin panel
• After modifying storage settings, existing files will not be automatically migrated :::

Configuration Effect

Configuration changes take effect immediately without restarting the service. Configurations are saved in the database and persist after restart.

Configuration storage location:

• Database: data/filecodebox.db
• Table name: keyvalue
• Key name: settings

API Endpoints

All admin panel functions are implemented through REST APIs. Here are the main endpoints:

Authentication Endpoint

Login

POST /admin/login
Content-Type: application/json

{
    "password": "your-admin-password"
}

Response:

{
    "code": 200,
    "detail": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "Bearer"
    }
}

Dashboard Endpoint

Get Statistics

GET /admin/dashboard
Authorization: Bearer <token>

File Management Endpoints

Get File List

GET /admin/file/list?page=1&size=10&keyword=
Authorization: Bearer <token>

Delete File

DELETE /admin/file/delete
Authorization: Bearer <token>
Content-Type: application/json

{
    "id": 123
}

Download File

GET /admin/file/download?id=123
Authorization: Bearer <token>

Modify File Information

PATCH /admin/file/update
Authorization: Bearer <token>
Content-Type: application/json

{
    "id": 123,
    "code": "newcode",
    "expired_at": "2024-12-31T23:59:59"
}

Local File Endpoints

Get Local File List

GET /admin/local/lists
Authorization: Bearer <token>

Delete Local File

DELETE /admin/local/delete
Authorization: Bearer <token>
Content-Type: application/json

{
    "filename": "example.txt"
}

Share Local File

POST /admin/local/share
Authorization: Bearer <token>
Content-Type: application/json

{
    "filename": "example.txt",
    "expire_style": "day",
    "expire_value": 7
}

Configuration Endpoints

Get Configuration

GET /admin/config/get
Authorization: Bearer <token>

Update Configuration

PATCH /admin/config/update
Authorization: Bearer <token>
Content-Type: application/json

{
    "admin_token": "new-password",
    "uploadSize": 52428800
}

Common Issues

Forgot Admin Password

If you forgot the admin password, you can reset it through the following methods:

1. Stop the FileCodeBox service
2. Open data/filecodebox.db using an SQLite tool
3. Query the record with key='settings' in the keyvalue table
4. Modify the admin_token value in the JSON
5. Restart the service

-- View current configuration
SELECT * FROM keyvalue WHERE key = 'settings';

-- Or delete configuration to restore default password
DELETE FROM keyvalue WHERE key = 'settings';

File Deletion Failed

If an error occurs when deleting files, possible reasons:

1. Storage backend connection failed: Check if storage configuration is correct
2. File no longer exists: File may have been manually deleted
3. Insufficient permissions: Check write permissions for storage directory

Configuration Changes Not Taking Effect

If configuration changes don't take effect:

1. Check if you clicked the save button
2. Refresh the page to see if configuration was saved
3. Check browser console for error messages
4. Confirm configuration value format is correct (e.g., don't enter strings for numeric types)

Next Steps

• Configuration Guide - Learn detailed descriptions of all configuration options
• Security Settings - Learn how to enhance system security
• Storage Configuration - Configure different storage backends