Complete Guide to Preserving Original Request URLs in Nginx Proxy

Analysis of Nginx Proxy Request URL Handling Mechanism

In web application architecture, when Nginx functions as a reverse proxy server, it typically modifies the client's request URL by default. When using the proxy_pass http://my_app_upstream; directive, Nginx forwards the request to the specified upstream server, but the upstream application receives a URL that has been altered to the proxy target's address.

Root Cause of Original URL Loss

The Nginx proxy module determines how to forward the URI based on the configuration of the proxy_pass directive. When the directive includes a URI portion, Nginx uses that URI to replace the original request URI. For example, configuring proxy_pass http://backend/app; causes all requests to be rewritten to paths starting with /app.

Preserving Original URL with proxy_set_header

The key to preserving the original request URL lies in correctly setting HTTP header information. The proxy_set_header directive ensures that the upstream server can identify the original request's domain and path.

location / {
    proxy_pass http://my_app_upstream;
    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;
}

In this configuration, the proxy_set_header Host $host; directive is crucial. It passes the original request's Host header to the upstream server, enabling the application to construct correct URLs based on the original domain.

Configuration Examples and Best Practices

For typical scenarios involving Ruby on Rails applications with Thin or Unicorn servers, a complete Nginx configuration should include the following key elements:

upstream my_app_upstream {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

server {
    listen 80;
    server_name example.com;
    
    location / {
        proxy_pass http://my_app_upstream;
        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;
        proxy_redirect off;
    }
}

Practical Application Scenario Validation

In the case described in the reference article, users need to proxy http://example.com/some/path to http://192.168.1.24 while maintaining the original URL in the browser address bar. Through the above configuration, it can be ensured that:

• When users access http://example.com/some/path, requests are transparently proxied to the backend server
• All internal links and redirects are generated based on the original domain example.com
• The backend application can correctly identify the original path information of the request

In-depth Technical Principle Analysis

Nginx's proxy behavior is influenced by multiple factors. When the proxy_pass directive does not include a URI portion, Nginx passes the complete original URI to the upstream server. Combined with correct header information settings, a complete proxy environment can be constructed.

This configuration is particularly important for applications that rely on complete URL information (such as Rails applications using URL helpers). Incorrect proxy configurations can cause applications to generate wrong links, damaging user experience and SEO effectiveness.

Common Issues and Solutions

In actual deployments, the following typical problems may be encountered:

• Redirect Loops: Usually caused by improper proxy_redirect configuration; it is recommended to use proxy_redirect off for debugging in test environments
• SSL Certificate Issues: When using HTTPS, ensure the X-Forwarded-Proto header is correctly set to https
• Application Framework Compatibility: Different frameworks may handle proxy header information differently; adjustments should be made according to specific framework documentation

Performance and Security Considerations

While implementing URL preservation functionality, performance and security must also be considered:

• Reasonably set proxy_buffer_size and proxy_buffers to optimize performance
• Verify the authenticity of X-Forwarded-For headers to prevent IP spoofing
• Consider using the realip module to obtain real client IP addresses in production environments

Through proper Nginx proxy configuration, web applications can operate normally in proxy environments while maintaining complete URL information, providing users with a consistent experience.