In-place Upgrade from Haozi Panel 2.x to AcePanel 3.0
This document describes how to upgrade Haozi Panel 2.x to AcePanel 3.0 without reinstalling the operating system. The overall approach is: perform “partial uninstallation without deleting data” (remove systemd services, command entry points, etc.) for some key applications on the old panel, then install the new panel and deploy a consistent runtime environment, and finally migrate the old panel’s data and website content to the new panel.
This tutorial is for in-place upgrade. If this tutorial is not suitable, consider migration upgrade:
Glossary
- In-place Upgrade: Complete the upgrade without reinstalling the operating system.
- Migration Upgrade: Migrate data to a new server to complete the upgrade.
- Old Panel: Haozi Panel 2.x (the panel to be upgraded).
- New Panel: AcePanel 3.0 (the target panel).
Operation Notes (Must Read)
- Extremely High Risk: You must take a snapshot/full backup of the server before starting, and confirm that rollback is possible.
- Long Downtime: You need to stop websites and the environment during the upgrade. Please reserve an upgrade window in advance and notify relevant business parties.
- Path Conflict Restriction: The old panel must not be installed in the
/opt/acedirectory (to avoid conflicts with the default directory of the new panel). - Inapplicable Scenarios: This solution is not applicable if the data disk is mounted in the old panel installation directory; you need to purchase/mount an additional new data disk to deploy the new panel (or adjust the mounting scheme before proceeding).
Pre-Upgrade Preparation
1) Confirm that the old panel environment is running normally
Log in to the old panel, check applications such as OpenResty, Percona, PHP in sequence, ensure they are running normally, and record the current version/configuration (for verification after migration).
2) Stop websites and environment operations
- Go to Websites and stop all running websites.
- Go to Applications and stop all running applications (OpenResty / Database / PHP / other services) until all are stopped.
3) Take a server snapshot/backup
Go to the server console, perform the snapshot/backup operation on the server to be upgraded, and be sure to wait for the backup to complete before proceeding with the subsequent steps.
Old Panel Preparation
Overview of the upgrade path:
- Perform partial uninstallation for some key applications on the old panel: only remove systemd services, executable entrances or soft links, etc., do not delete data directories.
- Install AcePanel 3.0 and deploy a runtime environment consistent with the old panel.
- Migrate the old panel’s application data and website files to the new panel’s directory structure.
- After starting and verifying that the full link is available, consider uninstalling the old panel.
Key Application “Partial Uninstallation” Instructions
Note: The commands in the table below are used to remove service files/command entrances to avoid conflicts with the services/commands installed with the new panel; data directories are not included in these commands.
Replace${mysql_path}and${postgresql_path}with the actual installation paths of the corresponding applications on the old panel (examples:/www/server/mysql,/www/server/postgresql).
| Application Name | Partial Uninstallation Method |
|---|---|
| OpenResty | rm -rf /etc/systemd/system/nginx.service /usr/local/bin/nginx |
| Percona | rm -rf /etc/systemd/system/mysqld.service && find /usr/local/bin/ -type l -lname "${mysql_path}/bin/*" -exec rm {} \; |
| PostgreSQL | rm -rf /etc/systemd/system/postgresql.service && find /usr/local/bin/ -type l -lname "${postgresql_path}/bin/*" -exec rm {} \; |
| PHP | rm -rf /lib/systemd/system/php-fpm-*.service /usr/local/bin/php* /usr/local/bin/pear /usr/local/bin/pecl |
| Docker/Podman | No uninstallation required |
| Gitea | rm -rf /usr/local/bin/gitea /etc/systemd/system/gitea.service |
| MinIO | rm -rf /usr/local/bin/minio /etc/systemd/system/minio.service |
For other non-critical applications, it is recommended to uninstall them directly on the old panel and reinstall them on the new panel as needed to reduce migration complexity.
Install the New Panel
After completing the “partial uninstallation” of the old panel applications, start installing the new panel.
Run the following command and follow the prompts to complete the installation:
bash <(curl -sSLm 10 https://dl.acepanel.net/helper.sh)
After the installation is complete, log in to the new panel and install the same environment as the old panel (such as OpenResty, Percona, PostgreSQL, PHP versions and related components).
Wait for the environment installation to complete before proceeding to the next step.
Migrate Application Data
Goal of this stage: Migrate the application data that was “partially uninstalled” on the old panel to the directory structure of the new panel, and ensure that permissions and configurations are correct.
OpenResty
- Skip this step if you have not modified the OpenResty configuration.
- If you have custom configurations: Export/copy the relevant configurations from the old panel to the new panel, and check the loading paths and include relationships on the new panel.
Percona (MySQL)
- Stop the new panel’s Percona.
- In the new panel’s Files, go to:
/opt/ace/server/mysqland delete thedatadirectory. - Go to the old panel’s Percona directory (example:
/www/server/mysql) and migrate thedatadirectory to the new panel:/opt/ace/server/mysql/. - Set the directory permissions to 700 and the owner to mysql.
PostgreSQL
- Stop the new panel’s PostgreSQL.
- In the new panel’s Files, go to:
/opt/ace/server/postgresqland delete thedatadirectory. - Go to the old panel’s PostgreSQL directory (example:
/www/server/postgresql) and migrate thedatadirectory to the new panel:/opt/ace/server/postgresql/. - Set the directory permissions to 700 and the owner to postgres.
PHP
- Install the PHP extensions/modules required for the business on the new panel.
- Refer to the old panel, adjust the PHP configuration files (such as
php.ini, php-fpm related configurations) as needed to ensure consistency with the original business operating parameters.
Gitea
- Stop the new panel’s Gitea.
- In the new panel’s Files, go to:
/opt/ace/server/giteaand delete all files in the directory. - Go to the old panel’s Gitea directory (example:
/www/server/gitea) and migrate all files in the directory to:/opt/ace/server/gitea. - Modify all paths involved in the Gitea configuration file (including data directories, log directories, repository directories, etc.) to ensure consistency with the new panel’s directory.
MinIO
- Stop the new panel’s MinIO.
- In the new panel’s Files, go to:
/opt/ace/server/minioand delete all files in the directory. - Go to the old panel’s MinIO directory (example:
/www/server/minio) and migrate all files in the directory to:/opt/ace/server/minio. - Modify all paths involved in the MinIO configuration file to ensure consistency with the new panel’s directory.
Startup and Verification
After completing the above migration, return to the new panel, start each application in sequence and confirm that they are running normally; if some applications fail to start, first check the corresponding error logs and fix them.
Note: After starting Percona / PostgreSQL, you need to change the password once in the panel, otherwise the panel’s database management function may not work properly.
Migrate Websites
After the application environment migration is completed, you need to re-create sites on the new panel and migrate the site files.
- Return to the old panel, go to Websites to view the site list and configurations.
- Open the new panel in a new tab and go to Websites.
- Refer to the old panel, create all websites one by one on the new panel.
- In the new panel’s Files, migrate all files in each website directory of the old panel to the corresponding website directory on the new panel.
- Complete the site configuration on the new panel: such as enabling HTTPS, setting pseudo-static, rewrite rules, reverse proxy, scheduled tasks, etc.
Note: The default website directory structure of the new panel is different, the default is:
/opt/ace/sites/[Site Name]/public
After all sites are migrated, visit and verify them one by one (homepage, API, backend, static resources, upload/download, etc.) to ensure that the business is operating normally.
Uninstall the Old Panel (Optional)
You can consider uninstalling the old panel after the new panel runs stably, the business verification is completed, and you confirm that rollback is not needed.
Run the following command to uninstall the old panel and delete the installation directory:
bash <(curl -sSLm 10 https://dl.cdn.haozi.net/panel/uninstall.sh)