Upgrade from V3.x.x

Warning

The current upgrade tool is still in testing phase. Please make backups before proceeding and be prepared to revert to the original version in case of upgrade failure.

When upgrading from V3.x.x to V4.0.x, the following data will be lost:

• Remote download and other background task records;
• Order records;
• Report abuse records;
• User-customized sidebar;
• User's hardware authenticators;
• Theme color configurations;
• Thumbnails from non-local storage policy generated by thumbnail proxy;
• Other configuration items no longer supported in V4.

After the upgrade, V3 share links and direct links will remain valid.

1. Preparation

Check Current Version

The V3 to V4 upgrade tool was developed based on Cloudreve V3.8.x. Other older versions have not been tested. It is recommended to upgrade Cloudreve to V3.8.x first before proceeding with the upgrade to V4.

Close the Site

Please close the current site and Cloudreve V3 process first to prevent new data from being written to the database.

Backup Database

Please backup your existing database version first. You can use third-party tools such as mysqldump to create database backups. For SQLite databases, you can directly backup the cloudreve.db file.

The upgrade tool will only read the V3 database and convert it to V4 format without modifying the data in the V3 database. However, there is still a possibility of V3 database corruption due to operational errors or program defects. Please make sure you have a backup before proceeding with subsequent operations.

Backup Configuration File

Please backup the existing V3 version configuration file conf.ini.

2. Convert Database

2.1 Obtain V4 Executable

Refer to Quick Start to obtain the V4.0.x version of the main program. Name it cloudreve_v4 and place it in the same directory as the current cloudreve.

Warning

In future versions of V4, this upgrade tool will be removed. Please upgrade to version V4.0.x first, then proceed with subsequent upgrades.

# Rename the current Cloudreve V3 executable to cloudreve_v3
mv cloudreve cloudreve_v3

# Rename the V4 main program to cloudreve
mv cloudreve_v4 cloudreve

# Create a data directory for storing V4 configuration files and data
mkdir data

2.2 Prepare V4 Configuration File and Database

Refer to Configuration File to prepare a configuration file conf.ini for V4 use, and place it in the data directory created in the previous step. In the V4 configuration file, please specify the database connection information for V4 in the Database configuration item. Please create a new database separate from V3.

You can also directly copy the V3 configuration file conf.ini to the data directory and modify the database connection information in it, changing the Name in the Database configuration item to the name of the V4 database, or specify a new SQLite database file location through the DBFile configuration item.

TIP

In V4, specifying the table prefix TablePrefix configuration item is no longer supported, so it is recommended here to specify a new database for V4, separate from V3.

# Copy the V3 configuration file `conf.ini` to the data directory created in the previous step
cp conf.ini data/conf.ini

# Modify the database connection information in the V4 configuration file
# Please create a new database separate from V3
nano data/conf.ini

2.3 Run the Upgrade Tool

# Run the upgrade tool
./cloudreve migrate --v3-conf conf.ini -c data/conf.ini

Specify the V4 configuration file path with the -c parameter and the V3 configuration file path with the --v3-conf parameter. The upgrade tool will read the data from the V3 database, convert it to V4 format, and write it to the V4 database.

Depending on the amount of data, the upgrade tool may take from several minutes to several hours to run.

3. Start V4

After the upgrade tool has finished running, you can start the V4 site.

# Start V4
./cloudreve

4. Subsequent Steps

1. If you still see the V3 page when accessing the site after the upgrade is complete, please delete your browser cache and make sure you are not using a custom frontend.
2. After checking that the V4 site is running normally, the database data used by V3 can be deleted.

Common Issues

If the upgrade process is interrupted abnormally, how do I retry?

Simply re-run the upgrade tool. Cloudreve will save the upgrade progress to the migration_state.json file and continue from where it was interrupted when started again. If you need to start the upgrade from scratch:

1. Delete all data tables and data already generated in the V4 database;
2. Delete the migration_state.json file, or use the --force-reset parameter to restart the upgrade.

Upgrade failed with hash ID salt is not set, please set it from v3 conf file

Please check if the HashIDSalt configuration item is configured in the V3 configuration file conf.ini. This configuration affects all share links and direct links. By default, V3 will automatically generate and fill in this value when it starts, but you may have manually deleted this value. The solution is:

1. Add the HashIDSalt configuration item to the [System] configuration item in the V3 configuration file conf.ini, and fill in a random value;
2. Retry the upgrade program.
3. After the upgrade is complete, all share links and direct links from V3 will be invalid. If you want to avoid this situation, please manually go to the database and set the hash_id_salt field in the settings table to an empty string.

Upgrade failed with Failed to migrate: failed creating schema resources: sql/schema: copy rows from old table "xxx" to new temporary table "new_xxx"

This error indicates that V4 and V3 are using the same database, and the data tables have conflicted. Please specify a new database in the V4 configuration file.