Backup and migration of 3x-ui to another VPS without losing users

Effective 3x-ui migration to a new VPS without losing users and their configurations requires preserving the x-ui.db database, which contains all accounts and settings, as well as the directory with SSL certificates, usually located in /root/.acme.sh, followed by deployment on the new server.

Migrating infrastructure, especially critical services like 3x-ui, is a common task for system administrators and developers. Whether it's the need for more powerful hardware, a region change for improved latency, cost optimization, or increased fault tolerance, the process must be well-thought-out and seamless. 3x-ui, as a popular control panel for Xray servers, is actively used to create and manage proxy servers supporting various protocols such as VLESS, Reality, XTLS, VMess, Shadowsocks, and others. Loss of user data or incorrect configuration after migration can lead to serious service availability issues. In this article, we will detail each step, from preparation to final verification, to ensure the smoothest possible 3x-ui transfer to a new server.

Where does 3x-ui store its data and why is it important for backup?

For a successful 3x-ui backup and subsequent migration, it is crucial to understand where the panel stores its configurations, user data, and certificates. 3x-ui uses an SQLite database to store all operational information about users, their credentials, traffic statistics, and proxy server settings. Additionally, SSL certificates are required to ensure a secure TLS connection (including VLESS protocols with XTLS/Reality). These two components are key to preserving functionality after migration.

Key 3x-ui Data Components

• x-ui.db Database: This is the heart of your 3x-ui panel. It contains:
  • All created users with their UUIDs, ports, protocols, and additional settings.
  • Traffic usage statistics for each user.
  • Inbound and outbound connection settings (inbounds/outbounds).
  • General 3x-ui panel settings (port, admin login/password, limits).

  By default, x-ui.db is located in the directory where 3x-ui is installed. In most cases, with a standard installation, this will be /etc/x-ui/x-ui.db. However, if you installed 3x-ui manually or used a script that allows you to choose the path, it might differ. Always verify the file location before starting the backup.

• SSL Certificates: For protocols requiring TLS encryption (VLESS, VMess, Shadowsocks with TLS, Reality) to work, valid SSL certificates are necessary. Most often, they are issued using Let's Encrypt via the acme.sh script. The directory where acme.sh stores certificates and keys is usually located at /root/.acme.sh/. In this directory, you will find subdirectories named after your domains, inside which certificate files (fullchain.cer) and private key files (.key) are stored.
• 3x-ui Configuration Files (optional): Although the main configuration is stored in the database, some installation scripts might create additional configuration files or systemd service files. However, for most migration scenarios, backing up x-ui.db and certificates is sufficient.

Why is a full backup of x-ui.db and certificates so important?

Without x-ui.db, you will lose all your users, their UUIDs, settings, and statistics. In fact, this would be equivalent to a fresh 3x-ui installation, where you would have to recreate all users and send them new configurations. This is not only time-consuming but also extremely inconvenient for your clients.

Without SSL certificates, your proxy servers using TLS will stop working. Users will receive connection errors because the server will not be able to establish a secure connection. Although certificates can be reissued on a new server, this takes time and correct DNS configuration, and can also lead to temporary downtime. Preserving existing certificates minimizes downtime and avoids the need to reconfigure client devices if you are not changing the domain.

Understanding these key components allows for a precise action plan for 3x-ui migration, ensuring that all important data is preserved and correctly restored on the new server.

Full 3x-ui Backup: What to save before migration?

Before proceeding with the 3x-ui transfer, it is necessary to perform a full backup of all critical data from the current VPS. This process includes stopping the 3x-ui service, copying the database and SSL certificates, and then securely moving them to a local machine or cloud storage. Strict adherence to these steps guarantees data integrity and minimizes risks.

Stopping the 3x-ui service for backup integrity

Before copying the database, be sure to stop the 3x-ui service. This will prevent any write operations to x-ui.db during copying, eliminating the risk of corruption or an incomplete backup. If the database is in use during copying, you might get an inconsistent file that will be difficult or impossible to restore.

Connect to your old VPS via SSH and execute the following commands:

sudo systemctl stop x-ui
sudo systemctl disable x-ui # Optional: prevents startup on reboot

Verify that the service is stopped:

sudo systemctl status x-ui

The output should show that the service is inactive (inactive (dead)).

Copying the x-ui.db database and SSL certificates

Now that the service is stopped, you can safely copy the necessary files.

1. Backup of x-ui.db database:
   Locate the x-ui.db file. In most cases, it is located at /etc/x-ui/x-ui.db. If you installed 3x-ui differently, the path might vary. You can use the command find / -name x-ui.db to search for it.
   Copy the file to a safe location, for example, to the user's home directory, to easily download it later:

   cp /etc/x-ui/x-ui.db ~/x-ui.db.bak
   

2. Backup of SSL certificates:
   The directory with certificates is usually located at /root/.acme.sh/. Copy it entirely. If you use multiple domains, this directory will contain all necessary certificates.
   

   If you did not use acme.sh or your certificates are located elsewhere, make sure you copy the fullchain.cer and the corresponding .key file for each domain you use. If you are using Reality, backing up certificates is not as critical as they are generated on the fly, but if you are using VLESS/VMess with TLS, it is mandatory.

   cp -r /root/.acme.sh/ ~/.acme.sh.bak
   

   Now you have two files/directories to download: ~/x-ui.db.bak and ~/.acme.sh.bak.

Downloading backup files to your local machine

Once the files are copied to the home directory, you can download them to your local machine using scp or an SFTP client (e.g., WinSCP, FileZilla).

Using scp:

# Open a terminal on your LOCAL machine
scp user@your_old_vps_ip:~/x-ui.db.bak .
scp -r user@your_old_vps_ip:~/.acme.sh.bak .

Replace user with your username (usually root or a user with sudo privileges), and your_old_vps_ip with the IP address of your old VPS.

After a successful download, ensure that the files are not corrupted and have a reasonable size. At this point, the backup is complete. You can now either delete the backup files from the old VPS or keep them as an additional precaution. If you plan to completely delete the old VPS, make sure you have a reliable copy of the backup.

Now that we have all the necessary data, we can proceed to prepare the new server for 3x-ui on the new server.

Preparing the new VPS for 3x-ui transfer

Before proceeding with data restoration, it is necessary to prepare the new VPS. This stage includes selecting a suitable server, its basic configuration, installing necessary dependencies, and, of course, installing the 3x-ui panel itself. Proper preparation of the new server will ensure stable operation and a seamless 3x-ui transfer.

Choosing the optimal VPS for 3x-ui: what to look for?

The choice of VPS depends on the anticipated load. For 3x-ui, the main factors are the number of active users, the volume of traffic transferred, and the protocols you plan to use (Reality, XTLS, TLS require more CPU resources). Valebyte.com offers various plans suitable for different tasks. For example, for a small number of users (up to 20-30) with moderate traffic, a basic plan with 1 vCPU, 1-2 GB RAM, and a 20-30 GB NVMe disk will be sufficient. For more demanding scenarios, such as Hiddify on VPS or Marzban on VPS, which can handle hundreds of users, it's better to consider plans with 2-4 vCPU, 4-8 GB RAM, and a faster disk.

Key parameters:

• Processor (vCPU): 1-2 cores for most cases, 2+ for high loads or Reality.
• Random Access Memory (RAM): 1-2 GB is sufficient for Xray/3x-ui, but 2-4 GB provides more buffer.
• Disk (SSD/NVMe): 20-40 GB NVMe will be more than enough. NVMe provides better I/O performance, which is important for databases and logs.
• Network Channel: 100 Mbps - 1 Gbps. The wider the channel, the better for the proxy.
• Server Location: Choose a location that provides minimal latency for your users.
• Operating System: Ubuntu 20.04/22.04 LTS, Debian 10/11/12, or CentOS 7/8. Ubuntu LTS versions are the most common choice.

Approximate VPS characteristics for 3x-ui:

Usage Category	vCPU	RAM	Disk (NVMe)	Network Channel	Approximate Price (Valebyte.com)
Small (up to 20-30 users)	1 core	1-2 GB	20 GB	100 Mbps	$5 - $8/month
Medium (up to 50-100 users)	2 cores	2-4 GB	30-40 GB	250-500 Mbps	$8 - $15/month
High (100+ users, Reality/XTLS)	4+ cores	4-8 GB	50+ GB	500 Mbps - 1 Gbps	$15 - $30+/month

Basic setup of the new VPS and 3x-ui installation

After activating the new VPS (many providers, including Valebyte.com, offer VPS with instant activation), connect to it via SSH.

1. System Update:
   Always start by updating the package manager and installed packages.

   sudo apt update && sudo apt upgrade -y # For Debian/Ubuntu
   # sudo yum update -y # For CentOS/RHEL
   

2. Install necessary utilities:
   Install curl, wget, git, and unzip if they are not already installed. These might be needed for 3x-ui installation and file operations.

   sudo apt install -y curl wget git unzip # For Debian/Ubuntu
   # sudo yum install -y curl wget git unzip # For CentOS/RHEL
   

3. 3x-ui Installation:
   Use the official script to install 3x-ui. This ensures that all dependencies are installed correctly and the panel will work with the correct paths.

   bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
   

   Follow the script instructions. After installation, 3x-ui will start with an empty database. You do not need to configure users or ports at this stage, as we will restore data from the backup. Just ensure that the panel is installed and the x-ui service is present in the system.

4. Stopping the new 3x-ui service:
   As on the old server, we need to stop 3x-ui to safely replace the database.

   sudo systemctl stop x-ui
   sudo systemctl disable x-ui # Optional, but recommended
   

Your new VPS is now ready to receive data from the backup. You have a clean copy of 3x-ui installed, but it does not yet contain your users and settings. The next step is data restoration.

Step-by-step 3x-ui migration: restoring data and users

The most critical stage of 3x-ui migration is restoring the saved data on the new server. This process involves uploading backup files to the new VPS, replacing the 3x-ui database, and restoring SSL certificates. It is important to follow the instructions precisely to avoid data loss or incorrect service operation.

Uploading backup files to the new VPS

Transfer the x-ui.db.bak and .acme.sh.bak files, which you previously downloaded to your local machine, to your new VPS. You can use scp or an SFTP client.

Using scp:

# Open a terminal on your LOCAL machine
scp ~/x-ui.db.bak user@your_new_vps_ip:/tmp/
scp -r ~/.acme.sh.bak user@your_new_vps_ip:/tmp/

Replace user with the username (usually root), and your_new_vps_ip with the IP address of your new VPS. The files will be uploaded to the temporary directory /tmp/ on the new server.

Restoring the 3x-ui database

Connect to the new VPS via SSH. Now we will replace the empty 3x-ui database with the one you backed up.

1. Moving the database:
   Move the backup file x-ui.db.bak from /tmp/ to the target 3x-ui directory, replacing the existing empty x-ui.db file. The default 3x-ui directory is /etc/x-ui/.

   mv /tmp/x-ui.db.bak /etc/x-ui/x-ui.db
   

2. Setting permissions:
   Ensure that the database file has the correct permissions and owner so that 3x-ui can work with it. This is usually root:root and permissions 0600 or 0640.

   chown root:root /etc/x-ui/x-ui.db
   chmod 600 /etc/x-ui/x-ui.db
   

Restoring SSL certificates

If you used TLS or Reality, you need to restore the certificates.

1. Moving the .acme.sh directory:
   Move the backed-up .acme.sh.bak directory to the /root/ home directory, replacing it if it exists (though it likely won't on a new server).

   mv /tmp/.acme.sh.bak /root/.acme.sh
   

2. Setting permissions:
   Ensure that the directory and the files within it have the correct permissions and owner.

   chown -R root:root /root/.acme.sh
   chmod -R 700 /root/.acme.sh
   

After performing these steps, all your data and certificates will be in place on the new VPS. Now you can start the 3x-ui service.

Starting 3x-ui and checking functionality

Start the 3x-ui service and ensure it has started successfully:

sudo systemctl start x-ui
sudo systemctl enable x-ui # To ensure the service starts on system boot
sudo systemctl status x-ui

If everything went successfully, the status should be active (running). Try accessing the 3x-ui control panel via a web browser using your new VPS's IP address and the panel port (default 2053). You should see all your users and their configurations. Check the 3x-ui logs for errors:

journalctl -u x-ui -f

In case of problems, this will help identify their cause. Common issues include incorrect file permissions or database errors (if the backup was made incorrectly, which is unlikely when the service is stopped).

At this point, the main restoration process is complete. The next step is to verify configurations and, if necessary, change the domain.

Domain change after 3x-ui migration: certificates and configuration

In some cases, when transferring 3x-ui to a new VPS, it may be necessary to change the domain name used to access the proxy servers. This could be due to the old domain being tied to the old IP address, or simply a desire to use a new domain. Changing the domain necessitates reissuing SSL certificates and updating user configurations.

When is a domain change needed?

• IP address change and inability to re-bind the old domain: If your old domain is strictly tied to the old VPS or you cannot update DNS records for any reason.
• Desire to use a new, more suitable domain: Perhaps you want to improve branding or simply use a more convenient name.
• Issues with the current domain: The domain has been blacklisted, blocked, or has other problems.

If you have simply migrated the VPS but kept the domain name and updated its DNS A-record to the new IP address, reissuing certificates is not always mandatory if the old certificates are still valid and were successfully transferred. However, for maximum reliability and currency, it is recommended to reissue them.

Reissuing SSL certificates for a new domain

Suppose your old domain was old.example.com, and the new one will be new.example.com.

1. Update DNS A-record:
   Ensure that the A-record for new.example.com points to the IP address of your new VPS. This is critically important for Let's Encrypt to work and for the proxy server to function correctly. Wait for full DNS propagation (this can take from a few minutes to several hours).
2. Deleting old certificates (optional, but recommended for cleanliness):
   You can remove old entries for old.example.com from /root/.acme.sh/ if they are no longer needed, or simply allow acme.sh to handle the new domain.
3. Issuing a new certificate using acme.sh:
   Stop 3x-ui if it uses port 80/443 to obtain the certificate (by default, 3x-ui uses other ports for the panel, but Xray might listen on 443).

   Execute the command to issue a new certificate. Ensure that acme.sh is installed (it usually comes with 3x-ui installation or can be installed manually).

   # Ensure 3x-ui is stopped if it conflicts with port 80/443
   sudo systemctl stop x-ui
   
   # Issue a certificate for the new domain (using webroot or standalone)
   # Webroot:
   acme.sh --issue -d new.example.com --webroot /var/www/html/ # if you have a web server on port 80
   # Standalone (simplest if port 80 is free):
   acme.sh --issue -d new.example.com --standalone
   
   # After issuing, install the certificate to the correct paths.
   # Xray usually requires fullchain.cer and .key files.
   # 3x-ui can automatically pick them up from .acme.sh,
   # but it's better to explicitly specify paths in inbound settings.
   acme.sh --install-cert -d new.example.com \
   --key-file       /etc/x-ui/new.example.com.key  \
   --fullchain-file /etc/x-ui/new.example.com.pem \
   --reloadcmd     "sudo systemctl restart x-ui"
   

   After successfully issuing and installing the certificate, start 3x-ui:

   sudo systemctl start x-ui
   

Updating configurations in the 3x-ui panel

After obtaining the new certificate, you need to update all inbound connections in the 3x-ui panel that used the old domain and old certificates. Access the 3x-ui web interface:

1. Go to the "Inbounds" section.
2. For each inbound that used the old domain:
   
   • Edit it.
   • In the "Domain" (or "Host", "SNI") field, specify new.example.com.
   • In the "SSL Certificate" and "SSL Private Key" fields, specify the new paths to the certificate and key files you obtained (e.g., /etc/x-ui/new.example.com.pem and /etc/x-ui/new.example.com.key).
   • Save changes.
3. If you are using Reality, ensure that the correct dest (the target domain you are cloning) and serverNames (SNI domains to be used) are specified in the inbound settings. These do not depend on your certificate but must be configured correctly.

After updating all inbounds, 3x-ui will automatically reload the Xray configuration. Your users will now need to update their client applications, specifying the new domain new.example.com and, possibly, new ports if you changed them. Make sure you provide them with up-to-date configurations.

Effective certificate management and timely configuration updates are key to the successful and secure operation of your proxy server. If you are looking for alternatives to 3x-ui that also offer advanced features and ease of management, consider sing-box on VPS, which is a universal server for VLESS, Reality, and Hysteria.

Verification and testing after 3x-ui migration

After completing all steps for 3x-ui migration to the new server, it is crucial to perform thorough functionality verification. This will ensure that all users can connect, traffic flows without issues, and all settings are preserved and functioning correctly. Ignoring this stage can lead to unexpected downtimes and user complaints.

Key stages of functionality verification

1. Access to 3x-ui panel:
   Try to access the 3x-ui web interface using the new IP address or domain (if you changed it) and port (default 2053). Ensure that you can log in, see all your users and their settings. Check the panel logs for errors ("Logs" section in 3x-ui).
2. Checking Xray server operation:
   Ensure that the Xray server, managed by 3x-ui, is running and listening on the correct ports. You can use the command ss -tulnp (or netstat -tulnp) to check open ports.

   sudo ss -tulnp | grep xray
   

   You should see the ports you configured for your inbounds in 3x-ui (e.g., 443, 80, 2053).

3. Testing client connections:
   
   • Connect from a test device: Take one of your client devices (e.g., a smartphone with v2rayNG or Hiddify) and try to connect to the new server.
   • Check all protocols: If you are using VLESS, Reality, VMess, Shadowsocks, Hysteria2, or other protocols, test each one.
   • Check statistics: After a few minutes of use, check the traffic statistics in the 3x-ui panel for the test user. Ensure that traffic is being accounted for.
4. Checking SSL certificates (for TLS/Reality):
   If you are using protocols with TLS encryption, ensure that the certificates are valid. You can use online SSL checking tools or the openssl command on the server.

   # Check certificate on port 443 for your domain
   echo | openssl s_client -servername your_domain.com -connect your_vps_ip:443 2>/dev/null | openssl x509 -noout -dates
   

   Ensure that the certificate's start and end dates are correct.

5. Checking performance and latency:
   Run speed tests and check the latency (ping) to the new VPS. Compare them with the old server's metrics. The new VPS should demonstrate improved or similar characteristics, especially if you migrated due to performance issues. For optimizing latency and bypassing blocks, consider articles on zapret on VPS and router or VPS for bypassing blocks in Iran.

Troubleshooting potential issues

If you encountered problems, here are some common solutions:

• Cannot connect to 3x-ui panel:
  • Check if the x-ui service is running (sudo systemctl status x-ui).
  • Ensure that the 3x-ui panel port (default 2053) is open in the VPS firewall (ufw status or iptables rules).
  • Check for port conflicts with other running services (sudo ss -tulnp).
• Clients cannot connect to the proxy:
  • Ensure that Xray is running and listening on the correct ports (see above).
  • Check the VPS firewall: are the ports used by your inbounds open (e.g., 443)?
  • If using a domain, ensure its A-record points to the new IP address and DNS has fully updated.
  • Check Xray logs via 3x-ui or with the command journalctl -u x-ui -f for errors related to SSL certificates, ports, or configuration.
  • Ensure that the client application has the correct parameters (IP address/domain, port, UUID, SNI, etc.).
• SSL certificate issues:
  • Ensure that the fullchain.cer and .key files exist at the specified paths in the 3x-ui inbound settings.
  • Check file permissions for certificates (they should be accessible by the user under which Xray runs, usually nobody or root, but nobody is better).
  • Try reissuing the certificate if it has expired or is corrupted.

Thorough testing and prompt troubleshooting will ensure a smooth transition and minimal inconvenience for your users. If everything works stably, you have successfully completed your 3x-ui migration!

3x-ui Successful Migration Checklist

To ensure the smoothest and most painless 3x-ui transfer, it's helpful to have a checklist at hand. By following this checklist, you will minimize risks and ensure that no important step is missed.

Preparation Stage (Old VPS)

1. ☐ Notify users (if applicable) about upcoming work and possible brief downtime.
2. ☐ Stop 3x-ui service: sudo systemctl stop x-ui.
3. ☐ Create a backup of the x-ui.db database: cp /etc/x-ui/x-ui.db ~/x-ui.db.bak.
4. ☐ Create a backup of the SSL certificates directory: cp -r /root/.acme.sh/ ~/.acme.sh.bak.
5. ☐ Download backup files (x-ui.db.bak and .acme.sh.bak) to your local machine using scp or SFTP.
6. ☐ Verify the integrity of the downloaded files (e.g., file size).

New VPS Setup

1. ☐ Choose a suitable VPS plan (Valebyte.com offers various options for cheap VPS with hourly billing or with instant activation).
2. ☐ Install the chosen operating system (Ubuntu 20.04/22.04 LTS or Debian 11/12 recommended).
3. ☐ Connect to the new VPS via SSH.
4. ☐ Update the system: sudo apt update && sudo apt upgrade -y.
5. ☐ Install 3x-ui using the official script: bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh).
6. ☐ Stop the 3x-ui service on the new VPS: sudo systemctl stop x-ui.

Data Restoration

1. ☐ Upload backup files (x-ui.db.bak and .acme.sh.bak) from your local machine to the new VPS (e.g., to /tmp/).
2. ☐ Move x-ui.db.bak to /etc/x-ui/x-ui.db: mv /tmp/x-ui.db.bak /etc/x-ui/x-ui.db.
3. ☐ Set correct permissions for x-ui.db: chown root:root /etc/x-ui/x-ui.db && chmod 600 /etc/x-ui/x-ui.db.
4. ☐ Move .acme.sh.bak to /root/.acme.sh/: mv /tmp/.acme.sh.bak /root/.acme.sh.
5. ☐ Set correct permissions for .acme.sh/: chown -R root:root /root/.acme.sh && chmod -R 700 /root/.acme.sh.

Post-Operation Actions and Verification

1. ☐ Start the 3x-ui service: sudo systemctl start x-ui && sudo systemctl enable x-ui.
2. ☐ Check the status of the 3x-ui service: sudo systemctl status x-ui (should be active (running)).
3. ☐ Log in to the 3x-ui web panel using the new IP address/domain and port (default 2053).
4. ☐ Verify the presence of all users and their settings in the panel.
5. ☐ Update the domain's DNS A-record to the new VPS IP address (if you are keeping the same domain).
6. ☐ Reissue SSL certificates for the new domain (if you changed the domain, or to update existing ones).
7. ☐ Update certificate paths and domain names in 3x-ui inbound settings (if domain or certificate paths were changed).
8. ☐ Check open Xray ports: sudo ss -tulnp | grep xray.
9. ☐ Test connections from several client devices for all used protocols.
10. ☐ Check traffic statistics in the 3x-ui panel.
11. ☐ Check 3x-ui/Xray logs for errors.
12. ☐ Open necessary ports in the new VPS firewall (if not configured automatically).
13. ☐ Final notification to users about the completion of migration and, if necessary, provision of new settings.

With this checklist, you can confidently perform your 3x-ui migration, maintaining control over each stage and minimizing potential issues.

Conclusion

Successful 3x-ui migration to a new VPS without losing users is a multi-stage but entirely achievable process that requires careful attention to detail. Key steps include a thorough backup of the x-ui.db database and SSL certificates, as well as their correct restoration on a pre-prepared new server. Choosing a reliable VPS, such as those offered by Valebyte.com, with suitable characteristics and a stable network channel, is critically important for ensuring uninterrupted operation after the transfer. By following the detailed instructions and checklist, you will be able to easily transfer your 3x-ui panel, preserving all user data and configurations, while ensuring improved service performance and reliability.