📋 Migration Guide: Upgrading from 2.x to 3.x

January 16, 2026 · View on GitHub

Version 3.x is a major release! The core architecture has been completely refactored, transitioning from Next.js to Vite for bundling, and the backend has been rebuilt with GORM + Gin architecture.

Upgrade Steps

1. Export Master Control Data

  • In the 2.x version's master control list, use the export function to save all master control configuration data

2. Update Docker Configuration

  • Obtain the latest docker-compose.yml configuration file from the repository

3. Pull the Latest Image

docker pull ghcr.io/nodepassproject/nodepassdash:latest

4. Restart Container

# Run in the directory containing the compose file
docker compose down && docker compose up -d

5. Re-import Data

  • Access the new version interface and recreate master control configurations
  • Import the previously exported master control data
  • Verify that all functions are working properly

⚠️ Important Notes

This version is not backward compatible. Please backup/export your master control data before upgrading. It is recommended to create a fresh master control setup to avoid issues with legacy data!

  • Database Incompatibility: Version 3.x uses a completely new database table structure and cannot directly migrate 2.x data
  • Configuration Format Changes: Master control configuration format has been adjusted; manual reconfiguration of important tunnels is recommended
  • Feature Changes: Some function interfaces and operation methods have changed; please refer to the new version documentation

FAQ

Q: Can I upgrade directly without losing data?

A: No. Due to the complete database structure refactoring, data must be migrated through the export/import process.

Q: What does the exported data contain?

A: The exported data includes all master control configuration information, including master control addresses, ports, credentials, and other settings.

Q: Can I rollback to version 2.x after upgrading?

A: Yes, but you need to use the data backed up before the upgrade. It is recommended to make a complete backup before upgrading.

Technical Support

If you encounter problems during migration: