Nginx Cache Issues and Solutions: From sendfile Configuration to Cache Clearing

Problem Background and Phenomenon Analysis

In web development, it's common to encounter situations where Nginx continues to serve old versions of CSS files after modifications. This issue is particularly prevalent in virtualized environments, especially when using virtualization software like VirtualBox. Users typically attempt to restart Nginx services or delete cache directories, but often fail to resolve the problem.

Core Issue: Impact of sendfile Configuration

Based on case studies, the root cause often relates to Nginx's sendfile configuration. When sendfile is set to on, Nginx uses the operating system's sendfile system call for file transmission, which may have compatibility issues in virtualized environments.

In VirtualBox environments, the sendfile functionality has known compatibility issues with the virtualization layer. Specifically, after file modifications, Nginx continues to serve old versions through caching mechanisms, even when explicit cache configurations have been cleared.

Solution: Disabling sendfile

The most direct solution is to set sendfile to off in the Nginx configuration file:

http {
    sendfile off;
    # Other configuration items...
}

After modifying the configuration, reload the Nginx configuration:

sudo systemctl reload nginx

With sendfile disabled, Nginx will use traditional read/write methods for file transmission, which is more stable in virtualized environments and ensures immediate effect after file modifications.

Technical Principle Deep Analysis

The sendfile system call was originally designed for efficient data transmission between file descriptors, avoiding multiple data copies between user space and kernel space. However, in virtualized environments, this optimization may backfire.

VirtualBox's shared folder mechanism has compatibility issues with the sendfile system call, specifically manifesting as delayed file metadata updates. When CSS files are modified, VirtualBox may not immediately notify the Nginx process within the virtual machine of file changes, causing Nginx to continue using cached file handles.

Alternative Cache Management Solutions

Manual Cache File Clearing

If Nginx caching is explicitly configured, cache directories can be cleared using the following commands:

sudo find /var/cache/nginx -type f -delete
sudo systemctl reload nginx

It's important to note that Nginx only creates cache directories when proxy_cache_path or fastcgi_cache_path are explicitly configured.

Request-Based Cache Bypass

For production environments, the proxy_cache_bypass directive can be used for on-demand cache refresh:

location / {
    proxy_cache_bypass $http_secret_header;
    add_header X-Cache-Status $upstream_cache_status;
}

Refresh cache by sending requests with specific headers:

curl http://example.com/style.css -H "secret-header:true"

Best Practice Recommendations

In development environments, it's recommended to always disable sendfile functionality to avoid compatibility issues caused by virtualization. In production environments, the decision to enable sendfile should be based on actual requirements, but must ensure robust cache refresh mechanisms.

For cache configuration, it's advisable to use proxy_cache_path to explicitly specify cache directories and set appropriate inactive parameters to ensure automatic cache expiration.

Troubleshooting Process

When encountering file update issues, follow these troubleshooting steps:

1. Check sendfile settings in Nginx configuration
2. Confirm if explicit caching is configured
3. Verify VirtualBox shared folder configuration
4. Check file permissions and ownership
5. Test file access using tools like curl

Through systematic troubleshooting methods, the root cause can be quickly identified and effective solutions implemented.