• Published:

1Panel V2 reached stable release on June 10, 2025, and it is not a cosmetic update. V1 was the first pass at a control panel; V2 is the architectural cleanup that follows. The official position is clear: because V2 changed the architecture significantly, there is no direct online upgrade from V1. Existing V1 users need the official migration tool for a staged move.

Before starting, back up your sites. The migration stops services and resets several pieces of state.

Get the migration tool

The tool is 1panel-migrator. For amd64, download 1panel-migrator-linux-amd64 from the release page, rename it to 1panel-migrator, and place it in /usr/local/bin/. The final path should be:

/usr/local/bin/1panel-migrator

Migrate the core

Run:

1panel-migrator upgrade core

The command prints a set of warnings before it touches anything:

  • V1 license information is cleared and migrated to the community edition.
  • All V1 website, application, and database backup records are cleared.
  • Scheduled task execution records are not retained, though the V1 scheduled task definitions remain.
  • V1 snapshot records cannot be migrated because the version mechanisms differ.
  • V1 services stop during migration.

After you confirm, the migrator downloads the V2 package, initializes core.db and agent.db, migrates V1 data, and backs it up. When it finishes, it reports that the version is now v2.0.0 and tells you to run the website migration command.

Migrate websites

Run:

1panel-migrator upgrade website

This step also comes with warnings that matter:

  • After migration, all site configuration is stored under {1Panel install directory}/www.
  • OpenResty is upgraded to 1.27.1.2-0-1-focal.
  • The main OpenResty configuration is reset. Back up custom changes first.
  • 00.default.conf is reset, removing the default default_server. You can replace it with the V1 file after the upgrade if needed.
  • PHP runtime environments are removed. Existing PHP containers in created sites are not deleted, but those sites are migrated as static sites.
  • Once V2 migration succeeds, you can switch a migrated static site back to PHP in the site settings.
  • The reverse proxy cache mechanism was rebuilt, so all site reverse proxy caches are turned off. Re-enable them after upgrading.

Sites are unavailable during this step. After confirmation, the migrator pulls 1panel/openresty:1.27.1.2-0-1-focal, backs up V1 OpenResty to /opt/1panel/backup/openresty, moves the www directory to /opt/1panel/www, migrates conf.d, and starts OpenResty.

When that finishes, log in to the panel and continue updating from v2.0.0 to v2.0.2.

Reinstall the runtime

V2 changed the runtime structure, so a V1 installation needs its runtime reinstalled after migration. PHP sites are switched to static during the move. Old runtime containers may still exist and sites may keep running, but the runtime page will not show them. Even so, creating a new runtime is the safer route.

Install the PHP extensions you need. One usable set is:

exif,imagick,intl,zip,opcache,redis,mysqli,gd

After the extensions are installed, go to the website panel and switch the static site back to the PHP environment. Then open App Store > Installed, stop the old PHP runtime container, and delete it.

Old image: 1panel-php:8.4.6

New image: 1panel-php-fpm:8.4.6

Enable HTTP/3

In the website panel, go to HTTPS > HTTP3 and enable it. Remember to open UDP port 443 in the firewall.

Useful checks:

  • HTTP/3 service check: https://http3check.net/ or https://http3.wcode.net/
  • Browser support check: https://quic.nginx.org/, https://http3.is, or https://cloudflare-quic.com/

For a local curl test, download curl from https://curl.se/download.html. On Windows, get the build from https://curl.se/windows/, enter the bin directory, and run:

curl.exe --http3-only https://http3.is

The HTTP/3 problem

At some point HTTP/3 stopped working properly on the panel. A request with --http3-only failed with:

curl: (55) ngtcp2_conn_handle_expiry returned error: ERR_HANDSHAKE_TIMEOUT

Refreshing in the latest Chrome still did not show HTTP/3. iOS Safari sometimes failed to connect at all to sites with HTTP/3 enabled.

After digging around, the first workaround was to edit the OpenResty configuration and add reuseport after listen 443 quic:

server {
    listen 80 ;
    listen 443 ssl ;
    listen 443 quic reuseport;
....

There is a catch: each nginx instance can define reuseport only once. If one site defines it, other sites cannot define it again. One solution is to add reuseport in the top-level nginx http block. Later, it turned out that once one site had reuseport, other sites could enable HTTP/3 from the panel and work normally without adding it individually. Odd behavior, but it worked.

The likely cause is containerized nginx workers having trouble listening on UDP. That is not certain, especially since switching images had previously forced HTTP/3 to work on 1Panel. The exact reuseport behavior deserves a more careful write-up later.

The cleaner fix

After discussing the issue with 1Panel developers, tracked as issue #9525, the recommended fix was to uninstall and reinstall the OpenResty container. The root cause was that the OpenResty configuration still came from V1.

You can also avoid a full reinstall and overwrite the V2 configuration directly at:

/opt/1panel/apps/openresty/openresty/conf/default/00.default.conf

Use:

server {
    listen 80 ;
    listen [::]:80 ;
    listen 443 ssl ;
    listen [::]:443 ssl ;
    listen 443 quic reuseport ;
    listen [::]:443 quic reuseport ;
    server_name _;
    index 404.html;
    root /usr/share/nginx/html;
    include /usr/local/openresty/nginx/conf/ssl/root_ssl.conf;
    http2 on;
}

The reuseport edit is a workaround. Reinstalling or replacing the OpenResty configuration is the clean fix.

Related Posts