Skip to main content

Download Deployment Options

Lost-MSth5/29/26About 2 min

Note

Because the backend uses Flask, which is a synchronous framework, the default deployment setup cannot handle a large number of simultaneous downloads when thread count is limited. The following deployment suggestions are provided for users who need to improve download performance.

Single-host Deployment

NGINX X-Accel-Redirect

nginx is a well-known high-performance HTTP server that supports reverse proxying, load balancing, and more. By using the X-Accel-Redirect feature, the backend can return a special response header that tells nginx to serve the file directly from a specified path. This greatly improves download throughput and concurrency. Meanwhile, other requests are also forwarded to nginx.

If all requests are proxied through nginx, nginx should listen on port 80 and the backend should use a different port to avoid conflicts. If you need SSL/TLS, refer to nginx documentation and use port 443 or another appropriate port.

config.py
class Config:

    HOST = '0.0.0.0'
    PORT = 81
    # USE_CORS = True
    USE_PROXY_FIX = True
    # DEPLOY_MODE = 'waitress'

    DOWNLOAD_LINK_PREFIX = ''  # http(s)://host(:port)/download/
    BUNDLE_DOWNLOAD_LINK_PREFIX = ''  # http(s)://host(:port)/bundle_download/

    DOWNLOAD_USE_NGINX_X_ACCEL_REDIRECT = True
    NGINX_X_ACCEL_REDIRECT_PREFIX = '/nginx_download/'
    BUNDLE_NGINX_X_ACCEL_REDIRECT_PREFIX = '/nginx_bundle_download/'

Tips

If USE_PROXY_FIX is enabled and nginx is configured accordingly, DOWNLOAD_LINK_PREFIX and BUNDLE_DOWNLOAD_LINK_PREFIX do not need to be set manually; the address and port can be detected automatically. Otherwise, configure them explicitly.

It is highly recommended to enable DEPLOY_MODE to achieve better performance.

The backend configuration above is followed by an nginx example configuration for Windows:

nginx.conf
server {
    listen       80;
    server_name  _;

    location / {
        proxy_pass http://127.0.0.1:81;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Prefix /;
    }

    location /nginx_download/ {
        internal;
        alias "E:/arcaea_server/database/songs/";  # change to your actual path
        # NOTE: slash at the end of alias is important
    }

    location /nginx_bundle_download/ {
        internal;
        alias "E:/arcaea_server/database/bundle/";  # change to your actual path
        # NOTE: slash at the end of alias is important
    }
}

Tips

In the example above, the alias path must be changed to your actual path, and it must end with a slash /. The alias directive replaces the request path /nginx_download/ with the specified directory.

Remote Deployment

Remote deployment means the main server and the download server are not on the same machine. This is useful when you need to offload download traffic or when the main server has limited uplink bandwidth. Currently, the client is redirected to the remote URL with a 302 redirect, and compatibility may vary.

nginx is a high-performance HTTP server that supports reverse proxying, load balancing, and more. Using the secure_link feature, the backend can generate a signed download URL and redirect the client to nginx for download via 302. This method works for both remote and single-host deployments. For more details, refer to the ngx_http_secure_link_module documentation.

On the main server, configure the backend as follows. Adjust download_link_host and bundle_download_link_host to match your download server address and port:

config.py
class Config:

    HOST = '0.0.0.0'
    PORT = 81
    # USE_CORS = True
    # USE_PROXY_FIX = True
    DEPLOY_MODE = 'waitress'

    REMOTE_DOWNLOAD_MODE = 'nginx'
    REMOTE_DOWNLOAD_OPTIONS = {
        'nginx': {
            # nginx secure_link
            'download_link_host': 'http(s)://<host>:<port>',  # change to your actual address
            'download_link_prefix': '/arcaea_server_download',
            'bundle_download_link_host': 'http(s)://<host>:<port>',  # change to your actual address
            'bundle_download_link_prefix': '/arcaea_server_bundle_download',
            'secret_key': 'nginx_secure_link_md5_secret_key',
        }
    }

Although nginx is not required on the main server for this mode, it is still recommended. The main server nginx configuration is omitted here; below is an example nginx configuration for the download server:

nginx.conf
server {
    listen       80;
    server_name  _;
    
    # ......

    location /arcaea_server_download/ {
        secure_link $arg_md5,$arg_expires;
        secure_link_md5 "$secure_link_expires|$uri nginx_secure_link_md5_secret_key";
        if ($secure_link = "") { return 403; }
        if ($secure_link = "0") { return 410; }

        alias "E:/arcaea_server/v0.updating/database/songs/";  # change to your actual path
        # NOTE: slash at the end of alias is important
    }

    location /arcaea_server_bundle_download/ {
        secure_link $arg_md5,$arg_expires;
        secure_link_md5 "$secure_link_expires|$uri nginx_secure_link_md5_secret_key";
        if ($secure_link = "") { return 403; }
        if ($secure_link = "0") { return 410; }

        alias "E:/arcaea_server/v0.updating/database/bundle/";  # change to your actual path
        # NOTE: slash at the end of alias is important
    }

}

Tips

In the example above, the alias path must be changed to your actual path, and it must end with a slash /. The alias directive replaces the request path /arcaea_server_download/ with the specified directory.

For security reasons, in production it is recommended to change secret_key to a random and sufficiently strong string, and synchronize the same value into the download server nginx configuration at nginx_secure_link_md5_secret_key so the generated download links can be verified correctly.

Copyright © 2026 Lost-MSth