Update Xray-core & Panel on VPS Without Losing Users

To safely update Xray-core and 3x-ui on a VPS without losing users, you must perform several key steps, including thorough configuration and database backups, and version compatibility checks, which typically takes 15 to 45 minutes of active work depending on your installation's complexity and user count.

Keeping Xray-core and control panels like 3x-ui up-to-date on your Virtual Private Server (VPS) is not just a recommendation; it's a critical necessity for ensuring the stability, security, and efficiency of your services. In an environment of constantly evolving blocking methods and emerging vulnerabilities, timely updating Xray-core on your server is essential for uninterrupted access and protecting your users' data. For administrators managing dozens or hundreds of connections, the process to update 3x-ui without losing user data requires special attention and strict adherence to a proven methodology. This article from Valebyte.com provides a comprehensive guide to safe updating, minimizing risks and guaranteeing the integrity of your infrastructure.

Why Update Xray-core and 3x-ui on Your VPS? New Features and Enhanced Security

Updating server software might seem like a routine task that's easy to postpone. However, when it comes to critical components like Xray-core and the 3x-ui panel, delaying updates can lead to severe consequences. Current versions not only offer new features but also patch vulnerabilities that could be actively exploited by malicious actors.

Strengthening Anti-Censorship Mechanisms

One of the key benefits of regular xray update vps is the integration of new and improved anti-censorship mechanisms. Xray-core developers constantly work on new protocols and obfuscations that allow traffic to remain undetected by Deep Packet Inspection (DPI) systems. For example, recent Xray versions may include new transport protocols like Vision or enhanced XTLS-Reality, which significantly improve resistance to detection and blocking. Without these updates, your server can quickly become ineffective in regions with strict censorship, leading to lost connections and user dissatisfaction. These improvements often include performance optimization, reduced latency, and increased throughput, which is especially important for users requiring high-speed connections for video streaming or online gaming. You can learn more about how to set up an effective VPN in our article VPN on Your Own VPS: A Complete Guide 2026.

Patching Critical Vulnerabilities and Improving Stability

Software, like any complex product, is not immune to bugs and vulnerabilities. Xray-core and 3x-ui are actively developed, and various bugs and vulnerabilities are discovered and fixed during the development process. These vulnerabilities can range from minor errors affecting operational stability to critical security flaws allowing unauthorized access to your server or data interception. For instance, vulnerabilities related to handling specific traffic types or incorrect authentication, which could lead to Denial of Service (DoS) attacks or information leaks, have been found in the past. Timely updating Xray-core on your server ensures you are using a version with the latest security fixes, thereby protecting your VPS from potential threats. This also enhances overall operational stability, preventing unpredictable service failures and restarts, which is crucial for maintaining continuous service delivery to users.

Preparing for Xray and 3x-ui Update: Safety First

Before proceeding with updating Xray-core or the 3x-ui panel, thorough preparation is crucial. Lack of proper preparation is the most common cause of problems leading to data loss or server downtime. This is especially true during a panel version migration or Xray updates, where changes in data structure can be significant.

Choosing the Right VPS for Your Xray Server

The efficiency and stability of your Xray server directly depend on your VPS's hardware resources. Insufficient RAM, a slow CPU, or a slow disk can lead to reduced performance, latency, and even crashes under high load. For successful updates and subsequent stable operation of Xray-core and 3x-ui, especially considering the use of more resource-intensive anti-censorship protocols, you must ensure your VPS meets the minimum requirements. Valebyte.com offers a wide range of VPS plans optimized for various workloads. Below is a table with recommendations for choosing a VPS based on the expected number of users and traffic.

For 50 concurrent users, 4 vCPU, 8 GB RAM, and an 80 GB NVMe disk are sufficient.

Users	vCPU	RAM	Disk	Port	Price (from, $/mo)
1-10	1	1 GB	20 GB NVMe/SSD	1 Gbps	$5
10-25	2	2 GB	40 GB NVMe	1 Gbps	$10
25-50	4	4 GB	60 GB NVMe	1 Gbps	$15
50-100	4	8 GB	80 GB NVMe	1 Gbps	$25
100-200+	6-8+	16 GB+	120 GB+ NVMe	10 Gbps	$40+

Choosing NVMe disks is a priority, as they provide significantly higher read/write speeds compared to traditional SSDs, which is critical for working with 3x-ui databases and fast Xray-core traffic processing.

Full Xray-core and 3x-ui Data Backup: Key to Updating Without User Loss

The most important step before any update is creating a full backup. This is your insurance against unforeseen problems. Without a backup, you risk losing all configurations, user data, and statistics. The 3x-ui backup process involves saving the SQLite database, which stores all user data, configurations, and settings. For Xray-core, you need to save its configuration files.

Steps for creating a backup:

1. Stop Services: Before backing up, it's recommended to stop the Xray and 3x-ui services to ensure data integrity. This prevents new data from being written during the copy process.

   systemctl stop xray
   systemctl stop 3x-ui

2. Backup 3x-ui Database: The 3x-ui database is typically located at `/etc/3x-ui/3x-ui.db`. Copy this file to a safe location.

   cp /etc/3x-ui/3x-ui.db /root/3x-ui_backup_$(date +%Y%m%d_%H%M%S).db

3. Backup 3x-ui Configuration (if any): Sometimes 3x-ui stores additional settings in files. Check the `/etc/3x-ui/` directory for other important files.

   cp -r /etc/3x-ui /root/3x-ui_config_backup_$(date +%Y%m%d_%H%M%S)

4. Backup Xray-core Configuration: The Xray configuration file is usually located at `/usr/local/etc/xray/config.json`.

   cp /usr/local/etc/xray/config.json /root/xray_config_backup_$(date +%Y%m%d_%H%M%S).json

5. Start Services: After creating backups, you can restart the services.

   systemctl start xray
   systemctl start 3x-ui

6. Upload Backups to Remote Storage: It is crucial to save these files not only on the VPS but also to upload them to remote storage (e.g., cloud storage, local computer). This protects you in case of a complete VPS failure. Use scp or sftp for this.

For more detailed information on backup and migration, we recommend reading our article Backup and Migration of 3x-ui to Another VPS Without User Loss.

Testing on a Second VPS: The ideal scenario is to have a second, test VPS where you can first perform the update. This allows you to identify any potential problems and ensure the new version works correctly before applying changes to your production server. If you don't have a second VPS, make sure you thoroughly check all steps and create reliable backups.

Step-by-Step Xray-core and 3x-ui Update on VPS: How to Update 3x-ui Without Losing Users

Once you have completed all preparatory steps, including creating a full backup, you can proceed with the update process itself. It is important to follow the instructions carefully to avoid errors and ensure a safe VPN update without losing user data.

Updating Xray-core

Updating Xray-core is typically done using the official installation script, which is designed to update existing installations. This method is preferable to manual compilation as it handles dependencies and correctly replaces binary files.

Xray-core update procedure:

1. Check Current Xray Version: Before updating, it's useful to know which version of Xray-core you have installed.

   xray -version

2. Stop Xray Service: This is critically important to prevent file conflicts during the update.

   systemctl stop xray

3. Run Xray Installation Script: Most Xray installations on a VPS use a script, for example, from Project X. Execute it with the update option. If you used a different script, refer to its documentation.

   bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install --version 1.8.10 # Replace 1.8.10 with the actual version

   Or, if you are using a more general script that simply reinstalls the latest version:

   bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)"

   The script will automatically detect that Xray is already installed and offer to update it. It will replace the Xray binary files with new ones. Your configuration files in /usr/local/etc/xray/ usually remain untouched, but it's always worth checking them after an update, especially if you are moving between major versions.

4. Check Configuration (if necessary): After updating, especially when moving to a new major Xray version, changes to config.json may be required. Check the official changes in the Xray GitHub repository to ensure your current configuration is compatible. If you are using 3x-ui, the panel usually adapts the Xray configuration itself.
5. Start Xray Service: After a successful update, start the service.

   systemctl start xray

6. Check Xray Status: Ensure the service is running without errors.

   systemctl status xray

   Look for Active: active (running) messages and no errors in the logs.

7. Verify New Version:

   xray -version

   Ensure the new version is displayed.

Updating the 3x-ui Panel

The 3x-ui panel also has its own update script, which allows you to update 3x-ui without losing user data. It's important to use this script specifically, as it correctly handles database migration and updates the panel files.

3x-ui update procedure:

1. Check Current 3x-ui Version: Log into the 3x-ui web interface and check the version in the "About" or "Settings" section.
2. Stop 3x-ui Service:

   systemctl stop 3x-ui

3. Run 3x-ui Installation/Update Script:

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

   This script will automatically detect that 3x-ui is already installed and offer options: "Install" or "Update". Select the update option. It will download the latest version, update the files, and, most importantly, migrate your 3x-ui.db database if necessary for the new version. This ensures that all your users and their settings are preserved.

4. Start 3x-ui Service:

   systemctl start 3x-ui

5. Check 3x-ui Status:

   systemctl status 3x-ui

   Ensure the service is actively running.

6. Log in to the Web Interface: Open your browser and try to log into the 3x-ui panel. Verify that all users and their configurations are in place and that Xray-core successfully launches through the panel. If you encounter problems, you may need to regenerate configurations for some protocols via the web interface.

Important Note: When updating Xray-core and 3x-ui, always update Xray-core first, then 3x-ui. This is because 3x-ui is a wrapper around Xray and may depend on specific Xray-core features or versions. Updating 3x-ui to a newer version than Xray-core can lead to incompatibility and errors.

Troubleshooting and Rolling Back Server Updates: What to Do If Something Goes Wrong

Even with the most careful preparation, problems can arise. This is especially true during a panel version migration or Xray updates, where changes in logic or data structure may be incompatible with your current configuration. It's important to know how to quickly diagnose a problem and, if necessary, perform a server update rollback.

Common Issues During Panel and Xray Version Migration

When updating Xray-core and 3x-ui, you might encounter several common problems:

• Xray or 3x-ui Service Fails to Start: This is the most common issue. Causes can include incompatible configuration changes, missing dependencies, or corrupted binary files.
  • Diagnosis: Check service logs:

    journalctl -u xray -f
    journalctl -u 3x-ui -f

    Errors in the logs often point to a specific problem, such as "config error" or "port already in use".
• Loss of Users or Settings in 3x-ui: If the 3x-ui.db database was corrupted or not correctly migrated, you might find an empty panel or missing users.
  • Diagnosis: Check the size of the /etc/3x-ui/3x-ui.db file. If it's too small (e.g., a few KB), this might indicate corruption or the creation of a new, empty database.
• Client Connection Issues: Services are running, but clients cannot connect or experience slow speeds.
  • Diagnosis: Check firewall settings (ufw status or firewall-cmd --list-all). Ensure that the ports used by Xray are open. Verify that addresses or ports in the Xray configuration haven't changed after the update. Also, check if routing rules or DNS settings on the VPS have changed.
• Protocol Incompatibility: New Xray versions may change or deprecate certain protocol parameters, rendering old client configurations inoperable.
  • Diagnosis: Try creating a new user in 3x-ui with default settings and check if it works. If so, the problem is likely with older configurations.

Server Update Rollback Procedure

Thanks to pre-created backups, the update rollback procedure can be relatively simple. It involves restoring old files and, possibly, reinstalling a previous version of Xray-core or 3x-ui.

Steps for rollback:

1. Stop All Services:

   systemctl stop xray
   systemctl stop 3x-ui

2. Restore 3x-ui Database: Copy your backup of the 3x-ui.db file back to its original location.

   cp /root/3x-ui_backup_$(date +%Y%m%d_%H%M%S).db /etc/3x-ui/3x-ui.db

   Replace 3x-ui_backup_$(date +%Y%m%d_%H%M%S).db with the name of your actual backup file.

3. Restore Xray-core Configuration: Copy your backup of the config.json file back.

   cp /root/xray_config_backup_$(date +%Y%m%d_%H%M%S).json /usr/local/etc/xray/config.json

   Replace xray_config_backup_$(date +%Y%m%d_%H%M%S).json with the name of your actual backup file.

4. Reinstall Previous Xray-core Version (if necessary): If the problem is related to the new Xray-core version itself, you may need to install a previous stable version. To do this, use the installation script specifying the exact version that worked previously.

   bash -c "$(curl -L https://github.com/XTLS/Xray-install/raw/main/install-release.sh)" @ install --version 1.8.9 # Replace 1.8.9 with your previous version

5. Reinstall Previous 3x-ui Version (if necessary): If the problem is with 3x-ui, and restoring the database didn't help, or if the new panel version is incompatible with your old Xray version, you might need to install a previous 3x-ui version. This is more complex, as the official script usually installs the latest. You'll need to find instructions for installing a specific version or restore the entire 3x-ui directory from a backup if you made one.
6. Start Services and Verify:

   systemctl start xray
   systemctl start 3x-ui
   systemctl status xray
   systemctl status 3x-ui

   Check the logs and the 3x-ui web interface to ensure everything has returned to a working state.

It's important to understand that a rollback is a temporary solution. After a successful rollback, you need to analyze the cause of the failure and prepare for a repeated, more secure update. You may need to review the changelogs of both programs to understand what changes caused the conflict.

Automating Xray and 3x-ui Updates: Risks and Benefits for a Secure VPN Upgrade

The idea of automatic updates sounds appealing: no need to spend time on manual intervention, the system will always be up-to-date. However, when it comes to critical services like Xray-core and 3x-ui, serving real users, automation is not always the best solution. This is especially true for a safe VPN update infrastructure.

When is Auto-Update Justified?

Automatic updates can be justified in the following scenarios:

• Test or Non-Critical Environments: If you have a test server that doesn't serve real users, or if the losses from downtime are insignificant, auto-updates can be useful for quickly getting the latest features and fixes. This allows developers or administrators to quickly evaluate new versions in a controlled environment.
• Highly Specialized Installations with Minimal Customization: If your Xray and 3x-ui installation uses standard configurations and has no complex settings or integrations, the risk of conflicts during updates is reduced. In such cases, if you are prepared for potential manual intervention to resolve issues, auto-updates can save time.
• Using Specialized Panels with Their Own Auto-Update Mechanisms: Some comprehensive control panels for Xray, such as Marzban, may offer more reliable and tested auto-update mechanisms that account for component compatibility. However, even in this case, it's always recommended to check the documentation and be prepared for potential issues. You can learn about Marzban installation in our article Marzban on VPS: Xray Panel Installation and Multi-User Setup.

In these cases, auto-updates can be configured via cron jobs that periodically run update scripts. For example, for 3x-ui, you can add the following command to crontab:

0 3 * * * bash <(curl -Ls https://raw.githubusercontent.com/MHSanaei/3x-ui/master/install.sh) update >/dev/null 2>&1

This command will attempt to update 3x-ui every day at 03:00. However, as shown below, this is extremely risky for production environments.

Why is Auto-Update Risky for Production Environments with Users?

For production servers serving active users, automatic updating Xray-core on your server or 3x-ui poses significant risks:

• Unpredictable Failures and Downtime: New software versions, especially major ones, can contain bugs or incompatible changes that cause service failures. Automatic updates can lead to sudden downtime, depriving users of VPN access.
• Loss of User Data: Although 3x-ui update scripts try to preserve the database, there is always a risk of data corruption or incorrect migration, especially with significant changes in the database structure. Without manual control and prior backup, this data can be irrevocably lost.
• Xray Configuration Changes: Xray-core updates can introduce changes to configuration file syntax or deprecate certain parameters. If 3x-ui cannot correctly adapt to these changes, or if you use a custom Xray configuration, it can lead to service inoperability.
• Anti-Censorship Bypass Issues: Sometimes, new Xray versions may be less effective at bypassing censorship in certain regions due to unforeseen changes or bugs. Manual updating allows you to test the new version before deploying it.
• Lack of Control and Rollback Capability: With automatic updates, you lose control over the process. If something goes wrong, you won't be able to intervene quickly, back up the problematic version, or perform a controlled rollback.
• Version Mismatch: If you use multiple components, such as Xray-core and 3x-ui, automatically updating one without updating the other can lead to incompatibility.

Overall, for production servers with users, the safest and most recommended approach is manual, controlled updating. This allows for preliminary testing, creating reliable backups, and minimizing the risks of downtime and data loss. The process described in this article is designed precisely for this approach, ensuring maximum reliability and a safe VPN update.

Frequently Asked Questions

Should I Update Xray-core and 3x-ui Simultaneously?

Yes, it is recommended to update Xray-core and 3x-ui sequentially, first Xray-core, then 3x-ui. This is because 3x-ui is a control panel for Xray-core and may have dependencies on its version. Updating only one component can lead to incompatibility and errors, so always follow this order to ensure correct operation. The entire process usually takes no more than 30 minutes.

How Often Should I Update Xray and 3x-ui?

The frequency of updates depends on the criticality of your service and the release of new versions. For production servers, it's recommended to check for Xray-core and 3x-ui updates at least once every 1-2 months. If critical vulnerabilities or significant anti-censorship improvements are released, updates should be performed immediately, without waiting for the planned cycle. For example, Xray version 1.8.10 was released with important fixes.

What if Clients Can't Connect After an Update?

First, check the status of the Xray and 3x-ui services using systemctl status xray and systemctl status 3x-ui. If they are not running, examine the logs via journalctl -u xray -f. Ports may have changed, or the firewall might be blocking new connections. Ensure that ports (e.g., 443, 80) are open. If all services are active, try regenerating the configuration for one user in 3x-ui and test the connection with a new key. As a last resort, roll back to the previous version using your backups.

Can I Use Docker to Update Xray and 3x-ui?

Yes, using Docker significantly simplifies the update process, as you can simply update the Docker image to the latest version. This provides isolation and environmental predictability. However, even when using Docker, it is crucial to back up data volumes (volumes) where configurations and the 3x-ui database are stored to avoid data loss when updating the container. For example, the 3x-ui image is updated with the command docker pull x-ui/x-ui.

How Do I Verify That Xray-core and 3x-ui Have Been Updated?

After running the update scripts, check the Xray-core version by executing xray -version in the terminal. For 3x-ui, log into the panel's web interface and find the version information in the "Settings" or "About" section. Ensure that the displayed versions match what you expected to install. If different versions are used, for example, Xray 1.8.10 and 3x-ui 2.1.0, this will be indicated.

Conclusion

Regular and controlled updating Xray-core on your server and the 3x-ui panel is a mandatory condition for maintaining the security, stability, and efficiency of your VPN service. Always start with a full backup of configurations and the database, then strictly follow the step-by-step instructions to update 3x-ui without losing users. Avoid automatic updates on production servers to minimize risks and ensure uninterrupted service for your clients.