Upgrade steps
Important Note
Due to significant architectural changes between V1 and V2, direct online upgrade from V1 to V2 is NOT supported.
To ensure a safe and successful migration, please read the Upgrade Instructions carefully before proceeding.
1 Install 1panel-migrator¶
1.1 Obtain Installation Package¶
Visit the 1Panel GitHub Release Page to manually download the installation package matching your server architecture, then place it in the /tmp directory:
Installation packages for the following architectures are provided for each release (filename examples):
1panel-migrator-linux-amd641panel-migrator-linux-arm641panel-migrator-linux-arm1panel-migrator-linux-ppc64le1panel-migrator-linux-s390x
1.2 Installation Steps¶
The following steps use the amd64 architecture as an example:
# (1) Navigate to the temporary directory
cd /tmp
# (2) Add executable permissions
chmod +x 1panel-migrator-linux-amd64
# (3) Move to system PATH and rename
mv 1panel-migrator-linux-amd64 /usr/local/bin/1panel-migrator
2 Upgrade Instructions¶
The upgrade process consists of two steps: Upgrade Service and Upgrade Websites.
Important: Complete the service upgrade first, then proceed with the website upgrade.
Service upgrade has two roles:
- Master Node: Contains both
1panel-coreand1panel-agentservices, exposes external ports, and supports browser access. - Slave Node: Only contains the
1panel-agentservice, no external ports exposed, managed via the Node Management page of the master node.
2.1 Upgrade to Master Node¶
- Upgrade Service
1panel-migrator upgrade core
- Upgrade Websites
Important: Ensure the V2 service is running successfully before executing this command.
1panel-migrator upgrade website
2.2 Upgrade to Slave Node¶
- Upgrade Service
1panel-migrator upgrade agent
- Add Slave Node to Master Node
Go to the Node Management page of the master node and add this slave node. The system will automatically detect and process V1 historical data.
- Upgrade Websites
1panel-migrator upgrade website
Important
After adding the slave node, run the website upgrade command on the slave node server.
3 Rollback Instructions¶
If issues occur during upgrade, you can roll back to the previous 1Panel V1 version.
The rollback process also has two steps: Rollback 1Panel Service and Rollback Websites.
Important
Complete the service rollback first, then proceed with the website rollback.
3.1 Service Rollback¶
No distinction between master/slave nodes — run this command directly on the target server:
1panel-migrator rollback service
3.2 Website Rollback¶
Run this command on the target server as well:
1panel-migrator rollback website
Important
Ensure the V1 service is running successfully before executing this command.
Take 1Panel Further
Running 1Panel OSS? Pro Edition adds WAF protection, unlimited AI agents, multi-node management, and priority support — starting at $80/year.