Docker MongoDB Migration (Dump Mode)

How to use mongodump to migrate FastGPT's MongoDB from Environment A to Environment B.

Prerequisites:

Environment A: Your existing FastGPT deployment (e.g., on Alibaba Cloud) that needs to be migrated.
Environment B: The new FastGPT deployment (e.g., on Tencent Cloud, or a NAS like Synology/QNAP). Note: NAS deployments may require MongoDB 4.2 or 4.4, while cloud deployments support the default FastGPT MongoDB version.
Environment C: Your local machine, used as a staging area to hold files and coordinate the transfer.

1. Prepare: Access Docker MongoDB [Environment A]

docker exec -it mongo sh
mongo -u 'username' -p 'password'
>> show dbs

Confirm you can see the fastgpt database and note the database name for export.

Preparation:

Create a temporary directory for import/export on both the container and the host, e.g., data/backup [Environment A + Environment C].

Create the directory in [Environment A] for the dump operation

Enter the FastGPT Docker container:

docker exec -it fastgpt sh
mkdir -p /data/backup

Once created, exported MongoDB data will appear in the data/backup directory under your local FastGPT installation folder (auto-synced via volume mount). If it doesn't sync automatically, you can manually create the directory and use docker cp to copy files out (this rarely happens).

Then set up the [Environment C] host directory for syncing uploaded files into the container.

Navigate to the FastGPT directory, go into the mongo folder, and create a backup subdirectory:

mkdir -p /fastgpt/data/backup

Also create a directory in the new [Environment B]:

mkdir -p /fastgpt/mongobackup

###2. Export Data from [Environment A] Enter Environment A and use mongodump to export the MongoDB database.

2.1 Export

Run mongodump to export data files to the temporary directory (data/backup).

[The export path is set to /data/backup in the command. Since the FastGPT config already has data persistence set up, the exported files will sync to the host's fastgpt/mongo/data/backup directory.]

Single command to export (run on the host, no need to enter the container):

docker exec -it mongo bash -c "mongodump --db fastgpt -u 'username' -p 'password' --authenticationDatabase admin --out /data/backup"

You can also enter the container and combine directory creation with the export:

1.docker exec -it fastgpt sh

2.mkdir -p /data/backup

3. mongodump --host 127.0.0.1:27017 --db fastgpt -u "username" -p "password" --authenticationDatabase admin --out /data/backup

Fallback: if files don't auto-sync, manually copy them to the host [Environment A]:

docker cp mongo:/data/backup   [local-fastgpt-dir]:/fastgpt/data/backup>

2.2 For beginners, it's recommended to compress the directory and download it to your local staging environment [A -> C] for verification. This ensures you have a backup and can check file counts. Experienced users can transfer directly to the new server [A -> B].

2.2.1 Navigate to the [Environment A] source system's local fastgpt/mongo/data directory:

cd /usr/fastgpt/mongo/data

Compress the files:

tar -czvf ../fastgpt-mongo-backup-$(date +%Y-%m-%d).tar.gz ./

Download the archive to your local machine [A -> C] for verification. Experienced users can sync directly to Environment B's fastgpt data directory.

scp  -i /Users/path/[your-pem-file] root@[cloud-server-ip]:/usr/fastgpt/mongo/fastgptbackup-2024-05-03.tar.gz /[local-path]/Downloads/fastgpt

Experienced users can transfer directly to the new environment:

scp  -i /Users/path/[your-pem-file]  root@[old-server-ip]:/usr/fastgpt/mongo/fastgptbackup-2024-05-03.tar.gz    root@[new-server-ip]:/Downloads/fastgpt2

2.2 [Environment C] Verify the archive is complete. If not, re-export. Cross-environment scp transfers can occasionally lose data.

After downloading the archive to Environment C, extract it to a custom directory, e.g., user/fastgpt/mongobackup/data:

tar -xvzf fastgptbackup-2024-05-03.tar.gz -C user/fastgpt/mongobackup/data

The extracted files should be .bson files. Verify the file count matches the source. If they don't match, the new FastGPT environment will have no data after import.

If everything looks good, upload the archive to Environment B's designated directory (e.g., /fastgpt/mongobackup). Do not place it in fastgpt/data/ -- that directory will be cleared later, and having extra files there will cause import errors.

scp  -rfv [local-path]/Downloads/fastgpt/fastgptbackup-2024-05-03.tar.gz  root@[new-server-ip]:/Downloads/fastgpt/backup

3. Import and Restore

3.1. Extract the archive on the new FastGPT environment

tar -xvzf fastgptbackup-2024-05-03.tar.gz -C user/fastgpt/mongobackup/data

Verify the file count again against your earlier check.

Experienced users can use tar to verify archive integrity. The above steps are for beginners to facilitate comparison.

3.2 Manually copy files into the new FastGPT Docker container [Environment C]

Since the files aren't in the data/ directory, they won't auto-sync into the container. Also ensure the container's data directory is clean, or the import will fail.

docker cp user/fastgpt/mongobackup/data mongo:/tmp/backup

3.3 Initialize docker compose -- run it once to create the new mongo/data persistence directory

If the mongo/db directory isn't freshly initialized, mongorestore may fail. If you encounter errors, try initializing mongo.

Commands:

cd /fastgpt-install-dir/mongo/data
rm -rf *

Restore with mongorestore [Environment C] Run this from the host to import in one command (you can also run it inside the container):

docker exec -it mongo mongorestore -u "username" -p "password" --authenticationDatabase admin /tmp/backup/ --db fastgpt

Note: if the imported file count seems too low, the import likely failed. A failed import means you can log in to FastGPT but see no data.

Restart containers [Environment C]

docker compose restart
docker logs -f mongo  # Strongly recommended: check mongo logs before logging in. If mongo has errors, the web UI will also show errors.

If mongo starts normally, you should see output like this (not "mongo is restarting" -- that indicates an error):

Error state:

After starting the FastGPT container, log in to the web UI. If all your original data is displayed, the migration was successful.

Author

Overview