x4gKing/3x-ui-Upgrade: How One Port Becomes a VPN Panel, a Subscription Feed, and a Front Door

The One-Port Trick That Changes Everything

The headline feature here is not the panel itself. It is the way the repository makes a single public port act like three different services at once. A browser can land on a human-facing dashboard, a VPN client can fetch raw subscription data, and the proxy path can still carry tunnel traffic without another exposed port.

That matters on PaaS platforms, where the environment is often allergic to the usual VPN-panel pattern of “one port for the UI, another for subscriptions, more for inbounds.” This repo does not fight that constraint with more software. It narrows the problem until Nginx can classify traffic well enough to fake a larger system.

Why Nginx Is Doing the Heavy Lifting

The center of gravity is `nginx.conf.template`. It is not just a reverse proxy. It is a classifier. A `map` block looks at the User-Agent, path rules decide where requests go, and `/sub/` can mean different things depending on whether the caller is a browser or a VPN client.

That split is the project’s sharpest move. The same endpoint can serve a polished HTML page to humans and raw subscription data to client apps. The result feels less like routing and more like protocol translation at the edge.

The practical result is easy to miss: Nginx is acting as a traffic cop, a browser detector, and a branding layer at the same time. That is why the repo feels small in code but large in behavior.

The Wrapper Layer: Dockerfile and start.sh

The repository is mostly glue. The `Dockerfile` assembles the runtime, while `start.sh` performs the just-in-time setup that makes the whole thing usable in a constrained container environment. The panel binary is not being reinvented here. It is being surrounded.

#!/usr/bin/env bash
set -e

# Configure the panel at boot time
x-ui setting -username "$ADMIN_USER" -password "$ADMIN_PASS"
x-ui setting -webpath "/managepanel/"

# Expand environment variables into the Nginx template
envsubst '$PORT' < /etc/nginx/nginx.conf.template > /etc/nginx/nginx.conf

# Keep the container alive with Nginx in the foreground
nginx -g 'daemon off;' &
exec /usr/local/bin/x-ui

That boot sequence tells you what this repo really is. It is a deployment control plane wrapped around someone else’s application. The shell script sets credentials, injects the path, and binds the runtime to the platform’s assigned port. Everything else is orchestration.

The User Interface Is a Second Product

`sub-view.html` is the clearest sign that the repo is not only about infrastructure. It gives humans a cleaner surface for subscription management, with usage stats, expiration data, QR codes, and copy actions. That is a product decision, not just a deployment choice.

The neat part is that the UI exists alongside the raw machine endpoint instead of replacing it. Humans get readability. Clients get the exact payload they expect. The route decides which audience is being served.

• A browser-friendly dashboard instead of raw base64 text.
• Usage and expiration details presented in one glance.
• QR code and copy actions for quick client setup.

This is where the project stops looking like a private operator’s hack and starts looking like a polished service surface. The wrapper is trying to reduce user error as much as it is trying to reduce port count.

Rewriting a Binary Without Touching the Binary

The sharpest trick in the repository is the branding rewrite. `sub_filter` replaces upstream surface text on the fly, and injected client-side script can mutate the page after it loads. In other words, the panel can be re-skinned without forking the binary or rebuilding the app.

That is elegant and fragile at the same time. It works because the upstream HTML and script structure are predictable enough to patch live. It breaks if those assumptions change. This is configuration as surgery, and surgery is always sensitive to anatomy.

How It Compares to 3x-ui, Heimdall, and Marzban

Against upstream `3x-ui`, the difference is not feature breadth. It is deployment shape. The wrapper is built for a world where the platform gives you one slot and expects you to make it do more than one job.

Compared with Marzban, which leans more enterprise and generally carries more moving parts, this project is lighter and more opinionated. Compared with a plain panel install, it gives up simplicity in exchange for a single-port design that actually fits constrained hosting.

What the Project Gets Right, and What It Risks

The strongest thing about this repo is its discipline. It does one narrow job: make a constrained deployment look spacious. The path-based multiplexing is elegant, the UI split is humane, and the startup sequence is tight enough to fit in a small container story.

The risks are the same ones you would expect from a clever wrapper. It depends on a downloaded binary, it has little room for test coverage, and its live rewriting strategy can become brittle if upstream internals move. That is not a reason to dismiss it. It is the price of the trick.

• Use the repo when the real problem is platform limits, not protocol design.
• Treat Nginx as a routing and rewriting layer, not just a proxy.
• Expect elegance in the glue and trade-offs in long-term maintenance.