Introduction to Nginx Caching: Practical Tips for Improving Website Access Speed

I. What is Nginx Caching and Why Do We Need It?¶

Imagine going to a library to borrow a book and having to search from the bottom shelf every time—it’s very time-consuming. Nginx caching is like the library’s “frequently read bookshelf”—it temporarily stores frequently accessed content in fast storage (such as memory or disk). When a user requests the same content again, Nginx reads it directly from the cache instead of repeatedly asking the backend server (e.g., PHP, Java services).

Why use Nginx caching?
- Faster access speed: Users don’t need to wait for the backend server to process requests; data is fetched directly from the cache, making page loads faster.
- Reduced server load: Fewer repeated requests lower the backend server’s load, enabling it to support more concurrent users.
- Bandwidth savings: Cached content doesn’t need to be transmitted repeatedly, reducing traffic consumption from the server to the user.

II. Main Types of Nginx Caching (Simplified for Beginners)¶

Nginx offers various caching methods, with different types suitable for different scenarios. Beginners should first master the two most common types:

1. Proxy Caching (Reverse Proxy Scenario)¶

Applicable Scenario: Nginx acts as a reverse proxy (e.g., proxying backend PHP, Python services) to cache static resources or response content requested by users.
Principle: User request → Nginx proxy → Nginx checks the cache first; if available, it returns directly. If not, it fetches from the backend server and stores the result in the cache.

2. Webpage Caching (HTTP Caching)¶

Applicable Scenario: Caches front-end resources (HTML, CSS, JS, images, etc.) so that browsers can load content directly from local cache without even requesting Nginx.
Principle: The backend server returns a response with a Cache-Control header (e.g., max-age=3600 means cache for 1 hour). After receiving it, the browser uses the local cache for subsequent requests for the same resource.

What Not to Cache (Must-Know for Beginners)¶

Dynamic content: Pages with user login information (/user/profile) or real-time data (/api/weather), as these differ with each request and caching would result in users seeing outdated data.
Frequently changing content: E.g., product inventory, real-time counters. Caching should be disabled for these.

III. Quick Start: Configuring Nginx Proxy Caching (Most Common Scenario)¶

Step 1: Define Cache Path and Parameters¶

In nginx.conf or the site configuration file (e.g., /etc/nginx/sites-available/your-site), define the cache storage location and rules:

# Define cache path: /var/cache/nginx/proxy_cache is the directory for cache files
# levels=1:2 specifies cache directory hierarchy (e.g., first level a-z, second level 0-9)
# keys_zone=my_cache:10m is a shared memory area (10MB) for storing cache keys and metadata
# max_size=10g: Maximum cache disk usage is 10GB; old caches are deleted using LRU when exceeded
# inactive=30m: Cache entries not accessed within 30 minutes are automatically deleted (avoids "zombie" caches)
proxy_cache_path /var/cache/nginx/proxy_cache levels=1:2 keys_zone=my_cache:10m max_size=10g inactive=30m use_temp_path=off;

Note: The Nginx user (usually www-data) must have read/write permissions to the proxy_cache_path directory, otherwise caching will fail. Fix with:
chown -R www-data:www-data /var/cache/nginx/proxy_cache

Step 2: Enable Caching in Location Block¶

Suppose you want to cache static resources (images, CSS) from a backend server (e.g., http://127.0.0.1:8080). Add caching configuration in the corresponding location block:

server {
    listen 80;
    server_name your-site.com;

    # Cache all requests starting with /static/ (frontend static resources)
    location /static/ {
        proxy_pass http://127.0.0.1:8080/static/;  # Backend static resource address
        proxy_cache my_cache;  # Enable caching, associated with the previously defined cache zone
        proxy_cache_key "$scheme$request_method$host$request_uri";  # Cache key (URL + request method)
        proxy_cache_valid 200 304 12h;  # Cache status codes 200/304 (success/not modified) for 12 hours
        proxy_cache_valid any 1m;  # Other status codes (e.g., 404) cached for 1 minute
        add_header X-Proxy-Cache $upstream_cache_status;  # Response header shows cache status (HIT/MISS/EXPIRED, etc.)
        proxy_cache_use_stale error timeout http_500 http_502 http_503;  # Use expired cache when backend errors occur
    }
}

Step 3: Verify Configuration and Restart Nginx¶

After modifying the configuration, check for syntax errors first:

nginx -t  # Check if there are configuration errors

If the output is nginx: configuration file /etc/nginx/nginx.conf test is successful, restart Nginx:

nginx -s reload

IV. Cache Management: How to Clear and Optimize?¶

1. View Cache Status (Essential for Debugging)¶

Add statistical configuration in nginx.conf to check cache hit rates:

http {
    # Proxy cache path definition (same as before)
    proxy_cache_path /var/cache/nginx/proxy_cache ...;  

    # Log format to record cache status
    log_format cache_log '$remote_addr [$time_local] "$request" '
                         '$status $body_bytes_sent '
                         'cache_status:$upstream_cache_status';  

    server {
        access_log /var/log/nginx/cache_access.log cache_log;  # Path to cache logs
        # ...other configurations
    }
}

After restarting, check cache_access.log. Each line will end with cache_status:HIT (hit) or MISS (miss).

2. Clear Cache (Two Methods)¶

Method 1: Manually Delete Cache Files
Cache files are stored in the directory specified by proxy_cache_path (e.g., /var/cache/nginx/proxy_cache). They are organized into subdirectories based on the cache key’s hash (e.g., MD5 of the URL). Delete the target files or directories directly:

  rm -rf /var/cache/nginx/proxy_cache/*  # Clear all caches

Method 2: Fast Cache Clear with Third-Party Module (Advanced)
Use the ngx_cache_purge module to clear caches via HTTP requests (e.g., access /purge/URL). First, install the module:

  location ~ /purge(/.*) {
      proxy_cache_purge my_cache "$scheme$request_method$host$1";  # Clear cache for the specified URL
      allow 127.0.0.1;  # Only allow local or specified IPs to access
      deny all;
  }

Then access http://your-site.com/purge/static/xxx.jpg to delete the corresponding cache.

3. Optimization Tips (Must-Read for Beginners)¶

Cache dynamic content? Never! Only cache static resources (images, CSS, JS). Disable caching for dynamic content (e.g., PHP-generated pages):

  location ~ \.php$ {
      proxy_pass http://backend;
      proxy_cache off;  # Disable caching for dynamic content
  }

Set reasonable cache times: Static resources (e.g., images) can use 12h, CSS/JS 1d, and frequently updated content 10m. Control via proxy_cache_valid (see Step 2 example).
Avoid caching user-specific content: For personalized content (e.g., user logins), exclude user IDs from the cache key:

  proxy_cache_key "$scheme$request_method$host$uri";  # Exclude User-Agent to avoid duplicate caching for the same URL with different parameters

V. Common Issues: Why Isn’t Caching Working? Troubleshooting!¶

1. Cache Not Hit (MISS)?¶

Check configuration: Did you add proxy_cache my_cache in the location block? Did you forget to set proxy_pass?
Check backend headers: Does the backend return Cache-Control: max-age=3600? Nginx does not generate this header automatically—ensure the backend includes it.
Permission issues: Is the cache directory /var/cache/nginx/proxy_cache writable by the Nginx user (usually www-data)? Fix with:
chown -R www-data:www-data /var/cache/nginx

2. Outdated Cache Content (Users See Old Data)?¶

Check Cache-Control headers: Does the backend set max-age or Expires? For example, Cache-Control: no-cache will prevent Nginx from caching.
Manually update cache: After nginx -s reload, the cache updates automatically. For long-unupdated content, manually clear the cache (see above).

VI. Summary: Key Points for Nginx Caching Beginners¶

Core Purpose: Trade space for time—reduce repeated requests and improve website speed.
Configuration Focus: Cache only static resources and set proxy_cache_valid and cache paths reasonably.
Essential Tools: Check cache logs, clear caches manually or via modules, and monitor hit rates.
Pitfall Guide: Never cache dynamic content; prioritize permission checks and ensure correct backend headers.

Nginx caching is not difficult—with practice, you’ll master it quickly! For complex scenarios (e.g., CDN integration), explore advanced topics later, but the above content is sufficient for most entry-level use cases.