Reverse Proxy Setup (Nginx)
Relevant source files
The following files were used as context for generating this wiki page:
The zheng project utilizes Nginx as a reverse proxy to act as a single entry point for multiple backend Java web applications. This setup simplifies the architecture by routing incoming HTTP requests on port 80 to the appropriate backend service based on the URL path. It also handles serving static assets directly for improved performance.
The core components of this setup are the main Nginx configuration, upstream service definitions, and specific server block configurations for routing. A Windows batch script is also provided for managing the Nginx service.
Architecture Overview
Nginx listens for all incoming traffic on port 80. Based on the request's location path, it forwards the request to one of the backend services, each running on a different port. Static assets like CSS, JavaScript, and images are served directly by Nginx from the filesystem.
The following diagram illustrates the request flow from the user to the backend services through the Nginx reverse proxy.
Main Nginx Configuration
The main configuration file, nginx.conf, defines global settings, logging formats, and upstream server groups.
Sources: project-tools/nginx/nginx.conf
Global Settings
The http block contains several global directives:
| Directive | Value | Description | Source |
|---|---|---|---|
worker_processes | 1 | Sets the number of worker processes. | nginx.conf:3 |
worker_connections | 1024 | Sets the maximum number of simultaneous connections for each worker process. | nginx.conf:6 |
log_format | main | Defines a custom log format named main. | nginx.conf:12 |
access_log | logs/access.log main | Specifies the path and format for the access log. | nginx.conf:14 |
sendfile | on | Enables the use of sendfile() for direct copying of data between file descriptors. | nginx.conf:16 |
keepalive_timeout | 65 | Sets the timeout during which a keep-alive client connection will stay open. | nginx.conf:18 |
gzip | on | Enables gzip compression of responses. | nginx.conf:20 |
include | servers/*.conf | Includes all .conf files from the servers directory to load server block configurations. | nginx.conf:43 |
Upstream Services
Upstream blocks define pools of backend servers that Nginx can proxy requests to. Each upstream corresponds to a specific Java web application running on its own port, as defined in its respective pom.xml.
| Upstream Name | Backend Server | Purpose | Source File & Port Confirmation |
|---|---|---|---|
zheng-cms-admin | 127.0.0.1:2222 | The CMS administration backend. | nginx.conf:29-31, zheng-cms-admin/pom.xml:97 |
zheng-cms-web | 127.0.0.1:2224 | The public-facing CMS web application. | nginx.conf:32-34, zheng-cms-web/pom.xml:97 |
zheng-api-server | 127.0.0.1:6666 | The main API server. | nginx.conf:35-37, zheng-api-server/pom.xml:96 |
zheng-oss-admin | 127.0.0.1:7772 | The Object Storage Service administration backend. | nginx.conf:38-40, zheng-oss-admin/pom.xml:96 |
zheng-ui | 127.0.0.1:1111 | A UI service. Note: This port does not correspond to a Jetty port in the analyzed pom.xml files. | nginx.conf:23-25 |
zheng-upms-server | 127.0.0.1:1112 | The User Permission Management System backend. | nginx.conf:26-28 |
Request Routing (zheng-ui.conf)
The file zheng-ui.conf defines the main server block that listens on port 80 and handles request routing.
Sources: project-tools/nginx/servers/zheng-ui.conf
Server Definition
The server is configured to listen on port 80 for requests to www.zheng.com.
server {
listen 80;
server_name www.zheng.com;
# ... location blocks
}
Sources: project-tools/nginx/servers/zheng-ui.conf:1-3
Location-Based Proxying
Nginx uses location blocks to match URL paths and proxy the requests to the correct upstream service.
| Location Path | Proxied to Upstream | Description |
|---|---|---|
/ | http://zheng-cms-web | The default route for all requests, serving the main CMS content. |
/manage | http://zheng-cms-admin | Routes requests for the admin interface to the CMS admin service. |
/api | http://zheng-api-server | Routes all API calls to the API server. |
/oss | http://zheng-oss-admin | Routes requests for the object storage service to its admin backend. |
Sources: project-tools/nginx/servers/zheng-ui.conf:4-27
All proxied locations set the following HTTP headers to pass client information to the backend services:
Host: The original host requested by the client.X-Real-IP: The real IP address of the client.X-Forwarded-For: A list of IP addresses the request has been forwarded through.
# Example for the /api location
location /api {
proxy_pass http://zheng-api-server;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
Sources: project-tools/nginx/servers/zheng-ui.conf:16-21
Static Asset Handling
Requests for static files (CSS, JS, images) are handled directly by Nginx to offload the backend applications. It serves files from a hardcoded local directory path and sets a 30-day browser cache expiry.
location ~* ^/(css|js|images)/ {
root D:/work/zheng/zheng-ui/zheng-cms-web;
expires 30d;
}
Note: The root path is an absolute local path, which may require changes depending on the deployment environment.
Sources: project-tools/nginx/servers/zheng-ui.conf:28-31
Management Script (nginx.bat)
A simple Windows batch script, nginx.bat, is provided to manage the Nginx process. It must be run from within the project-tools directory.
The script supports the following commands:
| Command | Action |
|---|---|
nginx.bat start | Starts the Nginx server in the background. |
nginx.bat stop | Performs a fast shutdown of the Nginx server. |
nginx.bat quit | Performs a graceful shutdown of the Nginx server. |
nginx.bat reload | Reloads the Nginx configuration without downtime. |
@echo off
cd nginx
if "%1" == "start" (
start nginx.exe
)
if "%1" == "stop" (
nginx.exe -s stop
)
if "%1" == "quit" (
nginx.exe -s quit
)
if "%1" == "reload" (
nginx.exe -s reload
)
cd ..
Sources: project-tools/nginx.bat