Tengine Tips & Troubleshooting

Use Tengine as load balancer for multiple backend servers

2026-09-29

Once your backend outgrows one server — two Spring Boot nodes, or a web box plus a worker — Tengine can sit in front and spread traffic between them with zero extra software. This is the setup I run for a small microservice deployment, and it handles failover automatically when a node dies.

Step 1 — Define the upstream group

In the http block, declare all backend nodes:

upstream backend_pool {
    server 10.0.0.11:8080 weight=3;
    server 10.0.0.12:8080 weight=1;
    server 10.0.0.13:8080 backup;
}

• weight=3 — node 11 gets three times more traffic than node 12
• backup — node 13 only receives traffic when the others fail

Default behavior is round-robin across the healthy nodes.

Step 2 — Proxy to the pool

server {
    location / {
        proxy_pass http://backend_pool;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

The keepalive headers matter here — without them every request opens a fresh TCP connection to a backend, which eats throughput.

Step 3 — Failover and health checks

When a backend is unreachable, Tengine automatically marks it down and routes around it — no manual intervention. If your build includes the upstream_check module (Tengine-specific), you get active health checks too:

upstream backend_pool {
    server 10.0.0.11:8080;
    server 10.0.0.12:8080;
    check interval=3000 rise=2 fall=3 timeout=1000 type=http;
    check_http_send "HEAD /health HTTP/1.0\r\n\r\n";
    check_http_expect_alive http_2xx http_3xx;
}

What to watch out for

• Sessions: default round-robin sends a user to different nodes between requests. Add ip_hash; inside the upstream if your app is not stateless.
• One dead node: with weights, a down server is skipped automatically, but max_fails=3 fail_timeout=30s tunes how fast Tengine gives up on it.
• This is exactly where Tengine’s dynamic upstreams shine over stock Nginx.

Summary

One upstream block plus a proxy_pass turns Tengine into a load balancer with weights and failover. If a node goes down and you start seeing 502s instead of failover, my 502 guide walks through the usual causes.

← Back to home