PuppyIP Resource Center
Network & Connection Troubleshooting 10 min Published 2026-11-17

Migrating an x-ui Domain with Caddy: Separate Reverse Proxying, Certificates and SNI

Before moving an x-ui domain, confirm whether TLS terminates at Caddy or x-ui, then update DNS, routing and certificate renewal for the selected design.

x-ui Caddy Domain migration Reverse proxy TLS certificate SNI

Service eligibility and regional restrictions

PuppyIP serves only compliant overseas businesses and their authorized personnel. Proxy services are not available in mainland China. The service may only be used for lawful business activities outside mainland China. Use of this service within mainland China is prohibited.

Hosting a proxy IP or server overseas does not change these restrictions. The service must not be provided to end users in mainland China through relaying, forwarding, sharing or resale. Before use, read the Terms of Service.

Key Takeaways

  • A domain change can involve DNS, Caddy site addresses, upstream routing, the x-ui listener and a separately installed certificate; changing one setting may not be enough.
  • Choose the TLS termination design first: public HTTPS at Caddy or direct client TLS to x-ui.
  • Caddy-managed certificates and certificates installed in x-ui are separate deployments with separate paths and renewal hooks.
  • Verify the public and any direct x-ui endpoint with the actual domain SNI without exposing a management port.

Map the two TLS designs before changing the domain

First decide where TLS terminates. If Caddy terminates public HTTPS, it needs a certificate for the new domain and should reverse-proxy to a restricted x-ui upstream. If clients connect directly to x-ui's TLS listener, x-ui itself must bind and load a certificate for the new name. Both designs can coexist, but each entry point needs a clearly identified owner.

Changing only the Caddyfile does not update x-ui's listener, panel URL or certificate path. Putting a certificate in x-ui does not create a Caddy site. Record the old domain's use, public entry, upstream port and renewal method before the change so the migration does not expose the panel or continue serving an old certificate.

Read-only checks for DNS, listeners and current configuration

Confirm that the new domain's A/AAAA records point to the expected entry, then inspect public 80/443 listeners and the x-ui management listener. Read Caddyfile and x-ui certificate settings locally; redact real domains, upstream addresses, panel paths, accounts and keys before sharing. The caddy validate command checks selected configuration syntax, but success does not prove DNS or upstream reachability.

Identify whether Caddy proxies to loopback, a Unix socket or another restricted address, and confirm the destination port belongs to x-ui. If the TLS port owner is unclear, inspect listeners first; do not change the firewall or add a public port.

Check listeners and validate the Caddy configuration

sh
ss -ltnp | grep -E ':(80|443)([[:space:]]|$)'
caddy validate --config /PATH/TO/Caddyfile
On the server, inspect listeners on ports 80 and 443, then validate the selected Caddyfile. Validation does not print the full adapted configuration and does not prove DNS or upstream reachability. Replace the config path.

Update routing and certificates for the selected design

Before editing, back up the Caddyfile, x-ui public URL setting and certificate configuration. If Caddy terminates TLS, add the new site and limit its upstream to the necessary network. If x-ui handles direct TLS, install a certificate for the new SNI in its management interface and bind it to the correct listener. Never copy a private key into a public directory or expose an admin port just to test it.

If the DNS TTL has not expired or several backends exist, migrate in stages and retain the old entry until the new name passes verification. Validate the Caddy configuration before reloading it; changing x-ui certificates may also require a controlled reload. Either service reload may interrupt existing connections, so schedule maintenance for the actual design.

Make renewal cover the service that actually uses the certificate

Certificate renewal depends on which service terminates TLS, the ACME challenge type and deployment hooks. A Caddy-managed certificate does not inherit renewal settings for a certificate installed into x-ui through acme.sh. With standalone HTTP-01, TCP 80 must reach the challenge service. If Caddy owns the port, use a supported proxy challenge, stop/start hooks or another validated method, and ensure the service comes back after a failed attempt.

Check the actual scheduled task's user, config directory, Caddy service name, certificate installation target and reload command. A one-time command-line renewal does not prove cron is correct. Do not delete old certificates or reset accounts to solve a site-routing issue. Redact task output before giving it to a maintainer.

Verify public and upstream endpoints using the target SNI

After migration, inspect the certificate SAN, validity and chain returned on public 443 with the new domain as SNI, then load the HTTPS page and confirm Caddy reaches the intended x-ui upstream. If x-ui has a separate TLS listener, inspect its certificate separately; Caddy's certificate does not prove a direct x-ui certificate was updated.

Also confirm that the management page still requires authentication, only necessary public ports remain open, and the old domain is retained or redirected as planned. If the local test passes but users still receive an old certificate, check DNS, CDN/load-balancer and caches. If the certificate is correct but the page returns 502, check the Caddy upstream protocol, address and x-ui service state.

Use SNI to verify the entry's certificate chain and hostname

sh
DOMAIN='EXAMPLE.NEW.HOST'
CONNECT_ADDRESS='EXAMPLE.NEW.HOST'
PORT='443'
openssl s_client -connect "$CONNECT_ADDRESS:$PORT" -servername "$DOMAIN" -verify_hostname "$DOMAIN" -verify_return_error </dev/null
Set the address, port and domain to the actual entry being checked. 127.0.0.1 checks only the local listener; test a public site from the intended external network. Requires an OpenSSL build that supports verify_hostname.

Rollback and completion criteria

If the new site is inaccessible, the certificate name is wrong or the upstream fails, restore the saved Caddyfile and x-ui certificate settings, validate the configuration and only then reload. DNS changes may not reach every resolver immediately, so keep the old entry and a safe management path as part of the rollback plan.

A complete migration has the new domain resolving to the intended entry, the selected TLS terminator serving the correct certificate, the proxy reaching x-ui, administrator authentication working, renewal ownership clear and the old domain handled as planned. Replace all example domains, certificates and ports for the deployment; this is not a reason to expose the x-ui panel port.

Sources

Frequently Asked Questions

Is adding the new domain to Caddyfile enough?

Not always. Confirm the TLS terminator, DNS, proxy upstream, x-ui's own certificate binding and whether renewal tasks also need changes.

Will Caddy's automatic certificate renew x-ui's certificate too?

Do not assume that. Caddy and x-ui may use different certificate paths and renewal mechanisms. Verify each service's actual TLS listener.

How can I tell a certificate problem from a proxy problem?

Check the certificate with the target SNI first. If it is correct but the page returns 502, inspect Caddy's upstream address, protocol and service state.

Should I expose the x-ui management port during migration?

Do not open extra ports for testing. Prefer the protected Caddy entry and expose only ports required by the chosen deployment.