Ops & troubleshooting / 2026-09-30
3x-ui Panel: Pinning a Version, Random Credentials, Automatic Certificate Renewal
From a clean Debian 13: why not to install "latest", why the installer's random port and path get lost, and handing renewal to cron with acme.sh.
Panel tools are the easiest thing to burn through as a "one-click script" — until one day the certificate expires, the panel path is forgotten, the port conflicts, and only then do you notice that nobody wrote down what that one command printed.
This machine is a Lightsail instance in AWS Tokyo, Debian 13, clean install. What follows is what actually ended up on disk after this install.
Don't install latest directly
3x-ui iterates fast, and latest occasionally ships a panel that won't open. The safe approach is to look at the release list first, pick a version number the community reports as stable, then install it using the @version form:
# Example: check available versions first, then install a specific one
bash <(curl -Ls https://raw.githubusercontent.com/MHSanaei/3x-ui/master/install.sh)
After installing, check the version and the listening port once:
x-ui status
ss -lntp | grep -E 'x-ui|2053'
If the install script printed a custom port and a custom webBasePath, both are randomly generated and printed only once, at install time. Miss it and the only option is to edit the config file:
# Change webPort / webBasePath in /usr/local/x-ui/config.json, then restart
x-ui restart
What I do is redirect the install output straight into a log file on a local machine and archive the log when it's done. Panel login details are credentials: they don't go into notes, they don't go into a repo, they go into a separate secrets file and nowhere else.
Certificates: use acme.sh, not the panel's built-in
The panel's built-in certificate issuance sometimes gets stuck on DNS validation. Going through acme.sh with DNS-01 is more reliable and better suited to automation:
curl https://get.acme.sh | sh -s email=<email>
export CF_Token="<Cloudflare API Token>"
acme.sh --issue --dns dns_cf -d <domain> --keylength ec-256
Once issued, install the certificate where the panel reads it and register automatic renewal:
acme.sh --install-cert -d <domain> --ecc \
--key-file /root/cert/<domain>.key \
--fullchain-file /root/cert/<domain>.crt \
--reloadcmd "x-ui restart"
--reloadcmd is the crucial part. If the certificate files change but the process isn't reloaded, the browser still sees the old certificate — the symptom being "renewal clearly succeeded, yet it still reports expired".
Verify renewal, don't assume it
acme.sh --list # check the next renewal time
acme.sh --renew -d <domain> --force # run it manually once
Running it through by hand once before handing it to cron saves you a lot of "found out on expiry day" incidents. The cron entry is written automatically when acme.sh installs, in the user crontab; don't mix it in with hand-written backup jobs when editing.
Two things left
- Firewall: the panel port, node port and SSH port each need their own opening policy; don't leave the panel port open to the public internet long-term.
- Snapshots: Lightsail supports instance snapshots — take one as soon as this setup is done. If future tinkering breaks something, a rollback is a matter of minutes, a reinstall is a matter of hours.
Why a certificate "expires by itself" in the panel
3x-ui stores certificate paths as absolute paths in the panel config. After acme.sh renews, the files are updated, but:
- The panel has cached the certificate contents (the Xray process wasn't restarted)
- The renewal wrote to a different path
- The file permissions changed (
600changed to644, and Xray can't read it)
All three look like "certificate expired", but only the third one reports permission denied explicitly in the log.
The correct renewal hook
The key is that --reloadcmd must restart Xray, not just reload the panel. Reload the panel only and Xray still holds the old certificate.
The verification chain
openssl x509 -in /root/cert/node.crt -noout -dates
systemctl status x-ui | head -5
# verify from outside which certificate the handshake actually uses
echo | openssl s_client -connect node.example.com:443 -servername node.example.com 2>/dev/null | openssl x509 -noout -dates
The third one is the only trustworthy check — it sees the certificate actually served to clients.
One time window
Let's Encrypt certificates are valid for 90 days, and acme.sh renews 30 days before expiry by default. If you change DNS for the domain inside that renewal window, renewal fails and then goes into a 7-day retry. Before changing DNS, check the expiry date in acme.sh --list and stay out of the window.
One sentence to sum up: writing down "where it goes wrong" together with "how to verify it" is more useful than writing down only the config — config can be copied, the order of judgement cannot.