Files
vastsa 381a539c92 fix: resolve OSS chunk cleanup and legacy download issues
Use compatible S3 checksum settings, retry failed cleanup without reusing completed uploads, and include legacy attachment filenames. Correct admin-page URLs in both documentation languages.

Refs #556, #531, #502
2026-10-27 16:08:35 +08:00

9.5 KiB

Security Settings

FileCodeBox provides multiple layers of security mechanisms to protect your file sharing service. This document explains how to properly configure security options to ensure secure system operation.

Admin Password

First-Run Setup

::: danger Important Security Warning FileCodeBox does not ship with a default admin password. Open the site in your browser on first run and set the admin password on the setup page. :::

Change the admin password through the admin panel:

  1. Access /#/admin to enter the admin panel
  2. Log in with the current password
  3. Go to the "System Settings" page
  4. Find the admin_token configuration item
  5. Enter a new secure password and save

admin_token is stored as a password hash. Do not write a plaintext password to the database, or admin login will stop working.

Password Security Recommendations

  • Use a strong password with at least 16 characters
  • Include uppercase and lowercase letters, numbers, and special characters
  • Avoid common words or personal information
  • Change password regularly
# Recommended password format example
"admin_token": "Xk9#mP2$vL5@nQ8&wR3"

Hide Admin Entry

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

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

::: tip Recommendation For public services, it's recommended to keep show_admin_addr at 0 and access the admin panel directly via /#/admin. :::

IP Rate Limiting

FileCodeBox has built-in IP-based rate limiting mechanisms to effectively prevent abuse and attacks.

Upload Rate Limiting

Limit the number of uploads from a single IP within a specified time:

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

How it works:

  • System records upload requests from each IP
  • When an IP's upload count reaches upload_count within upload_minute minutes
  • Subsequent upload requests from that IP will be rejected with HTTP 423 error
  • Counter resets after the time window expires

Configuration examples:

# Relaxed configuration: Max 20 uploads in 5 minutes
{
    "upload_minute": 5,
    "upload_count": 20
}

# Strict configuration: Max 3 uploads in 1 minute
{
    "upload_minute": 1,
    "upload_count": 3
}

Error Rate Limiting

Limit the number of error attempts from a single IP to prevent brute-force attacks on extraction codes:

Setting Type Default Description
error_minute int 1 Error limit time window (minutes)
error_count int 10 Maximum errors allowed within the time window

How it works:

  • When a user enters an incorrect extraction code, the system records the error count for that IP
  • When error count reaches error_count, that IP will be temporarily locked
  • Lock duration is error_minute minutes
  • During lockout, all extraction requests from that IP will be rejected

Configuration example:

# Anti-brute-force configuration: Max 3 errors in 5 minutes
{
    "error_minute": 5,
    "error_count": 3
}

::: warning Note The default allows up to 10 errors per IP each minute. Public services can tighten this limit while accounting for users behind shared network addresses. :::

Upload Restrictions

File Size Limit

Setting Type Default Description
upload_size int 10485760 Maximum single file upload size (bytes), default 10MB
open_upload int 1 Enable upload functionality (1=enabled, 0=disabled)

Common size conversions:

  • 10MB = 10 * 1024 * 1024 = 10485760
  • 50MB = 50 * 1024 * 1024 = 52428800
  • 100MB = 100 * 1024 * 1024 = 104857600
  • 1GB = 1024 * 1024 * 1024 = 1073741824

File Expiration Settings

Through file expiration mechanisms, you can automatically clean up expired files, reducing storage usage and security risks:

Setting Type Default Description
expire_style 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 (requires alphanumeric extraction code)
  • count - Expire by download count

Security recommendations:

For public services, it's recommended to:

  1. Remove the forever option to avoid permanent file storage
  2. Set max_save_seconds to limit maximum retention time
  3. Prefer using count method for automatic deletion after download
# Recommended configuration for public services
{
    "expire_style": ["hour", "minute", "count"],
    "max_save_seconds": 86400  # Max retention 1 day
}

Disable Upload Functionality

In some cases, you may need to temporarily disable upload functionality:

{
    "open_upload": 0  # Disable upload functionality
}

Reverse Proxy Security Configuration

In production environments, Nginx or other reverse proxy servers are typically used. Here are security configuration recommendations:

Nginx Configuration Example

server {
    listen 80;
    server_name your-domain.com;
    
    # Force HTTPS redirect
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;
    
    # SSL certificate configuration
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers on;
    
    # Security headers
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    
    # Limit request body size (match upload_size configuration)
    client_max_body_size 100M;
    
    # Pass real IP
    location / {
        proxy_pass http://127.0.0.1:12345;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # Static resource caching
    location /assets {
        proxy_pass http://127.0.0.1:12345;
        proxy_cache_valid 200 7d;
        add_header Cache-Control "public, max-age=604800";
    }
}

Key Security Configuration Notes

1. Pass Real IP

FileCodeBox's IP limiting functionality depends on obtaining the client's real IP. The system obtains IP in the following order:

  1. X-Real-IP request header
  2. X-Forwarded-For request header
  3. Direct client connection IP

Ensure the reverse proxy correctly sets these headers:

proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

2. Request Body Size Limit

Nginx's client_max_body_size should match or be slightly larger than FileCodeBox's upload_size configuration:

client_max_body_size 100M;  # Allow max 100MB uploads

3. HTTPS Encryption

It's strongly recommended to enable HTTPS in production environments:

  • Protect uploaded file content
  • Protect admin login credentials
  • Prevent man-in-the-middle attacks

Caddy Configuration Example

your-domain.com {
    reverse_proxy localhost:12345
    
    header {
        X-Frame-Options "SAMEORIGIN"
        X-Content-Type-Options "nosniff"
        X-XSS-Protection "1; mode=block"
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
    }
}

Security Checklist

Before deploying FileCodeBox, confirm the following security configurations:

  • Completed first-run setup and set the admin password admin_token
  • Hidden admin entry show_admin_addr: 0
  • Configured appropriate upload rate limiting
  • Configured error rate limiting to prevent brute-force attacks
  • Set reasonable file size limits
  • Configured file expiration policy
  • Enabled HTTPS encryption
  • Reverse proxy correctly passes real IP
  • Set security response headers

Public Service Configuration

{
    "admin_token": "your-very-secure-password",
    "show_admin_addr": 0,
    "upload_size": 10485760,           # 10MB
    "upload_minute": 1,
    "upload_count": 5,
    "error_minute": 5,
    "error_count": 3,
    "expire_style": ["hour", "minute", "count"],
    "max_save_seconds": 86400,        # Max 1 day
    "open_upload": 1
}

Internal Service Configuration

{
    "admin_token": "internal-secure-password",
    "show_admin_addr": 1,
    "upload_size": 104857600,          # 100MB
    "upload_minute": 5,
    "upload_count": 50,
    "error_minute": 1,
    "error_count": 5,
    "expire_style": ["day", "hour", "forever"],
    "max_save_seconds": 0,            # No limit
    "open_upload": 1
}

Next Steps