Nginx Reverse Proxy Guide: Elegantly Routing Specific Subdirectories to Docker Containers

In daily DevOps and development, we often need to deploy multiple different services under the same domain (e.g., `wiki.lib00.com`). For instance, pointing the root path `/` to the main website, while routing a specific subdirectory `/ais` to a backend AI application container, without affecting other paths (like `/xxxx`). This article, presented by DP@lib00, will detail how to elegantly achieve this requirement using Nginx. ## Core Nginx Configuration For routing specific paths, the most critical points are the trailing slash at the end of the `proxy_pass` target address and how the path prefix is handled. Below is the optimized Nginx configuration. In this example, we reverse proxy `hub.wiki.lib00.com/ais` to an internal Docker container at `172.18.0.14:7860`: ```nginx server { listen 443 ssl; server_name hub.wiki.lib00.com; # ... Other SSL and logging configs ... # Specific routing rules for /ais location ^~ /ais/ { # Core trick: The trailing / strips the "/ais/" from the request path before forwarding # Example: Accessing hub.wiki.lib00.com/ais/test -> Forwards to 172.18.0.14:7860/test proxy_pass http://172.18.0.14:7860/; 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; # WebSocket support (Essential for AI WebUIs) proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "Upgrade"; # Optimization for AI streaming output proxy_buffering off; proxy_read_timeout 600s; } # Default handling for other paths (e.g., /xxxx) location / { # Processing logic for the default site proxy_pass http://127.0.0.1:8080; } } ``` --- ## In-Depth Analysis of Key Configurations ### 1. The "Magic Slash" in `proxy_pass` This is the most common pitfall in Nginx reverse proxy configurations: * **With a trailing slash** (`http://172.18.0.14:7860/`): Nginx will **strip** the part of the URI that matches the `location`. A request to `/ais/api` will be forwarded as `/api`. For most AI tools (like Gradio, Streamlit, etc.) that default to running on the root path, this is **highly recommended**. * **Without a trailing slash** (`http://172.18.0.14:7860`): Nginx will append the full request path to the backend. A request to `/ais/api` will be forwarded as `/ais/api`. If your backend service does not recognize the `/ais` prefix, it will throw an error. ### 2. Priority Control with `location` Using the `^~ /ais/` prefix elevates the matching priority. `^~` tells Nginx that if this prefix matches, it should stop searching for other regular expressions (like `location ~ \.php$`), ensuring that requests targeting this subdirectory are accurately intercepted without interference from global rules. ### 3. WebSocket and LLM Streaming Optimization Modern AI applications (such as ChatGPT UI, Stable Diffusion WebUI) rely heavily on WebSockets for bidirectional communication. Therefore, the `Upgrade` and `Connection` headers are indispensable. Furthermore, if you are connecting to a Large Language Model (LLM), its responses are usually generated word-by-word (streaming output). In this case, you must set `proxy_buffering off;` to disable Nginx's buffering mechanism. If buffering is not disabled, Nginx will wait until the backend has generated the entire content before sending it to the client, causing the frontend page to freeze. ### 4. Troubleshooting: Static Resource 404 Errors After configuring the proxy as above, you might find that while the page layout loads when accessing `hub.wiki.lib00.com/ais`, static resources like CSS/JS return 404 errors. **Reason**: The backend application uses absolute paths (e.g., `/assets/style.css`) internally to load resources. After being parsed by the browser, the request becomes `hub.wiki.lib00.com/assets/style.css` under the root directory, thereby escaping the `/ais/` matching rule. **Solution**: In such scenarios, you usually need to explicitly specify the base path in the startup parameters or environment variables of the backend AI application. For example, configure `root_path="/ais"` in FastAPI, or set `root_path` in Gradio's startup parameters. This lets the application know it is running under a subdirectory, enabling it to generate correct relative links for static resources.