# Docker MongoDB Migration (Dump Mode)

> Logical MongoDB backup, isolated restoration, and FastGPT migration checks

Source: https://doc.fastgpt.io/self-host/migration/docker_mongo
Last Updated: 2026-11-12

## Author

The original community example was contributed by [samqin123](https://github.com/samqin123); see [PR 1426](https://github.com/labring/FastGPT/pull/1426). These steps retain the logical-backup approach and clarify the current migration scope.

## Overview

`mongodump` exports MongoDB business data. A complete FastGPT migration also needs the vector database, object storage, configuration, and secrets. See the [complete migration inventory](https://doc.fastgpt.io/self-host/migration/docker_db). A is the source, B is the target, and C is your local backup location.

Verify compatibility between FastGPT, MongoDB, and MongoDB Database Tools before migrating. Stop FastGPT and other writers for a consistent backup. Rehearse restoration in an isolated target instance with new persistent volumes, keeping the source environment and original volumes available for rollback.

## 1. Prepare the Source and Backup Directory

The examples use the official template's default MongoDB container name `fastgpt-mongo` and database name `fastgpt`; replace them if customized in your deployment. Confirm that a compatible `mongodump` is installed in the container and the backup account has export permissions. The commands omit the password parameter so the tool prompts interactively.

```bash
docker exec fastgpt-mongo mongodump --version
docker exec fastgpt-mongo mkdir -p /tmp/fastgpt-backup
mkdir -p ./fastgpt-backup
```

Copy the archive explicitly to the host. Inspect deployment configuration for actual volume mounts.

## 2. Export and Transfer

Run on the source host A:

```bash
docker exec -it fastgpt-mongo mongodump --db fastgpt --username BACKUP_USER --authenticationDatabase admin --archive=/tmp/fastgpt-backup/fastgpt.archive.gz --gzip
docker cp fastgpt-mongo:/tmp/fastgpt-backup/fastgpt.archive.gz ./fastgpt-backup/fastgpt.archive.gz
```

Check the command exit status and export logs, then calculate a SHA-256 checksum. Use `sha256sum` on Linux or `shasum -a 256` on macOS. Copy the archive and checksum to C and B, and compare a newly calculated checksum after transfer. If `MONGODB_LOG_URI` is configured for a separate logging database, run `mongodump` for that database separately.

```bash
sha256sum ./fastgpt-backup/fastgpt.archive.gz
scp ./fastgpt-backup/fastgpt.archive.gz operator@target-host:/path/to/backup/
```

## 3. Restore in Isolation

Initialize the target MongoDB accounts and replica set according to the selected template. Keep FastGPT business services stopped. Check MongoDB logs and replica-set health, then copy the archive into the target MongoDB container:

```bash
docker cp /path/to/backup/fastgpt.archive.gz fastgpt-mongo:/tmp/fastgpt.archive.gz
docker exec -it fastgpt-mongo mongorestore --username RESTORE_USER --authenticationDatabase admin --archive=/tmp/fastgpt.archive.gz --gzip --nsInclude='fastgpt.*'
```

Use an account with restore permissions. Check successful and failed record counts in restoration logs. Restore into a clean, isolated database. If duplicate keys or namespace conflicts occur, preserve the state and inspect the target and backup. When renaming databases, first verify Database Tools namespace-mapping options.

## 4. Start and Validate

Restore the corresponding vector data, object storage, and original configuration secrets before starting the target FastGPT. Run `docker compose ps`, check readiness and FastGPT/MongoDB logs, and confirm the expected replica-set state with `rs.status()`.

Validate account login, Apps, Dataset Collections and chunks, file downloads, retrieval results, chat history, and new chats. Schedule traffic cutover only after archive checks and business acceptance pass. Retain the source backups and a rollback window.
