# MinIO 迁移到 RustFS

> FastGPT Docker 部署的对象存储从 MinIO 迁移到 RustFS

Source: https://doc.fastgpt.cn/zh-CN/self-host/docker_minio_to_rustfs

`main` 版本的新部署默认使用 RustFS 作为对象存储。已有 MinIO 部署必须原地迁移，保留原有 Compose project、业务数据卷、数据库连接和密钥，只替换对象存储。

> 不要在另一个目录重新执行 `install.sh`，也不要更换 Compose project 名称。直接启动一套新安装会创建新的 MongoDB、Redis、PG 数据卷，并重新生成数据库密码、`ROOT_KEY` 和 `AES256_SECRET_KEY`，导致原业务数据不可见。

本文中的容器名、Compose 服务名、网络名和端口均为示例，执行前必须核对当前部署。`docker inspect` 使用容器名，`docker compose stop` / `up` 使用 Compose 文件中 `services` 下的服务名，两者可能不同。后续命令中的 `fastgpt-mongo`、`fastgpt-minio`、`fastgpt-app`、`fastgpt-plugin` 和网络 `data` 都要替换为实际名称。

## 1. 固定原部署身份并备份

以下命令均在现有 FastGPT 部署目录执行。先备份当前 Compose 文件；如果目录中存在 `config.json` 或其他本地配置，也一并保留，不要用新安装文件覆盖。

```bash
cd /path/to/current-fastgpt
cp docker-compose.yml docker-compose.yml.minio.bak
test ! -f config.json || cp config.json config.json.minio.bak
```

如果 FastGPT 在宿主机上运行，例如通过 `pnpm dev` 启动，同时备份应用实际读取的 `.env` / `.env.local` 等配置文件。

先列出当前 Compose 服务和容器，确认示例名称对应的实际名称：

```bash
docker compose config --services
docker compose ps
```

确认当前 Compose project 名称和业务数据卷。后续所有 `docker compose` 命令都必须在这个目录执行，或显式传入同一个 project 名称。

```bash
docker inspect -f '{{ index .Config.Labels "com.docker.compose.project" }}' fastgpt-mongo
docker volume ls --filter label=com.docker.compose.project=YOUR_PROJECT_NAME
docker inspect -f '{{ json .Mounts }}' fastgpt-minio
```

如果 project 名称为空，先用 `docker compose ls` 确认当前配置对应的 project，再继续操作。`docker volume ls` 只列出 Docker 卷；旧 MinIO 如果使用 bind mount，还要记录并保留 `.Mounts` 中的宿主机数据目录。

## 2. 在原 Compose 中加入 RustFS

在现有 `docker-compose.yml` 顶层、`x-share-db-config` 之前增加一组凭证锚点，确保锚点早于所有引用它的位置；YAML 不支持先引用、后定义锚点。然后把下面的服务加入 `services`。`fastgpt-rustfs` 会使用原 project 的命名卷前缀，稍后切换时继续复用同一个卷。

```yaml
x-rustfs-access-key: &x-rustfs-access-key 'YOUR_NEW_ACCESS_KEY'
x-rustfs-secret-key: &x-rustfs-secret-key 'YOUR_NEW_SECRET_KEY'
```

```yaml
  fastgpt-rustfs:
    image: rustfs/rustfs:1.0.4
    # 中国大陆网络可改为 docker.m.daocloud.io/rustfs/rustfs:1.0.4
    container_name: fastgpt-rustfs
    restart: always
    ports:
      - 9010:9000
      - 9011:9001
    networks:
      # 替换为原 Compose 中实际声明的网络名
      - data
    security_opt:
      - no-new-privileges:true
    environment:
      RUSTFS_ACCESS_KEY: *x-rustfs-access-key
      RUSTFS_SECRET_KEY: *x-rustfs-secret-key
      RUSTFS_VOLUMES: /data
      RUSTFS_ADDRESS: :9000
      RUSTFS_CONSOLE_ADDRESS: :9001
      RUSTFS_CONSOLE_ENABLE: "true"
      RUSTFS_OBS_LOGGER_LEVEL: error
      RUSTFS_OBS_LOG_DIRECTORY: /logs
    volumes:
      - fastgpt-rustfs:/data
    healthcheck:
      test: ['CMD-SHELL', 'curl -fsS http://127.0.0.1:9000/health && curl -fsS http://127.0.0.1:9001/rustfs/console/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

同时在 `volumes` 中声明新的数据卷。不要删除 `fastgpt-minio`，切换完成并验证前它仍用于回滚。

```yaml
volumes:
  fastgpt-rustfs:
```

为两个新凭证生成随机值，替换上面的 `YOUR_NEW_ACCESS_KEY` 和 `YOUR_NEW_SECRET_KEY`：

```bash
openssl rand -hex 16
openssl rand -hex 16
```

在当前旧部署目录只启动 RustFS。临时端口 `9010/9011` 用于避开旧 MinIO 的 `9000/9001`。

```bash
docker compose up -d fastgpt-rustfs
docker compose ps fastgpt-rustfs
curl -fsS http://127.0.0.1:9010/health
```

记录 RustFS 数据卷名称，迁移过程中和最终切换都必须使用这个卷：

```bash
docker volume ls --filter label=com.docker.compose.project=YOUR_PROJECT_NAME
```

## 3. 复制初始对象数据

在宿主机安装 [MinIO Client](https://github.com/minio/mc#install-from-source)。如果 Homebrew 或旧二进制下载地址返回 HTTP 410，可以在已安装 Go 的环境中，从官方固定版本源码安装：

```bash
go install github.com/minio/mc@RELEASE.2025-08-13T08-35-41Z
export PATH="$(go env GOPATH)/bin:$PATH"
mc --version
```

使用旧 MinIO 和新 RustFS 的凭证创建别名。不要交换 `old`、`new` 的地址或凭证。

```bash
mc alias set old http://127.0.0.1:9000 YOUR_OLD_ACCESS_KEY YOUR_OLD_SECRET_KEY
mc alias set new http://127.0.0.1:9010 YOUR_NEW_ACCESS_KEY YOUR_NEW_SECRET_KEY
mc alias list
```

如果旧部署改过 MinIO 的 `9000` 端口，请使用实际端口；如果改过 `STORAGE_PUBLIC_BUCKET` / `STORAGE_PRIVATE_BUCKET`，下面所有命令都要使用实际桶名。

```bash
mc mb --ignore-existing new/fastgpt-public new/fastgpt-private
mc mirror --overwrite old/fastgpt-public new/fastgpt-public
mc mirror --overwrite old/fastgpt-private new/fastgpt-private
```

这一步可以保持旧 FastGPT 运行。初次复制完成后，等待一个观察窗口，让切换到 RustFS 之前的正常读写都落到旧 MinIO。

## 4. 冻结写入并做最终同步

在同一旧部署目录停止所有可能写入对象存储的应用。若还有外部脚本或客户端直接写入旧 MinIO，也必须先停止。

```bash
docker compose stop fastgpt-app fastgpt-plugin
```

如果应用通过 `pnpm dev`、systemd 或其他方式运行，使用对应方式停止实际应用进程；只停止 Compose 中的依赖服务不能冻结宿主机应用的写入。还要排查其他机器、开发工作区和后台任务中连接同一套数据库及对象存储的实例，包含知识库训练消费者；它们也必须停止，并在切换后更新凭据再启动，避免旧凭据实例抢到新任务后读取失败。

确认源和目标别名、桶名无误后执行最终同步。最终同步必须包含 `--remove`，把旧 MinIO 中已删除、但目标 RustFS 中仍存在的对象一并删除。

```bash
set -euo pipefail
mc mirror --overwrite --remove old/fastgpt-public new/fastgpt-public
mc mirror --overwrite --remove old/fastgpt-private new/fastgpt-private
```

任何一条同步命令失败时都不要切换。随后对两个桶执行 dry-run；只有目标与源无差异，dry-run 的汇总才应为 `"total":0` 和 `"transferred":0`。

```bash
mc mirror --dry-run --overwrite --remove --json old/fastgpt-public new/fastgpt-public
mc mirror --dry-run --overwrite --remove --json old/fastgpt-private new/fastgpt-private
mc du old/fastgpt-public new/fastgpt-public
mc du old/fastgpt-private new/fastgpt-private
```

如果 dry-run 仍有差异、`mc du` 的结果不符合预期，或者无法确认源和目标桶，立即停止迁移并继续保留旧部署，不要启动新版应用。

## 5. 原地切换对象存储

最终同步完成后，先停止旧 MinIO 容器以释放 `9000/9001` 端口，但不要删除它的数据卷：

```bash
docker compose stop fastgpt-minio
```

继续修改当前目录中的同一个 `docker-compose.yml`：

1. 将 `fastgpt-rustfs` 的端口改回 `9000:9000` 和 `9001:9001`。
2. 在 `x-share-db-config` 中使用 RustFS 凭证和 Endpoint。
3. 将 `fastgpt-app`、`fastgpt-plugin` 的 `depends_on` 从 `fastgpt-minio` 改为 `fastgpt-rustfs`。
4. 将 `NO_PROXY` / `no_proxy` 中的 `fastgpt-minio` 替换为 `fastgpt-rustfs`。
5. 删除或注释旧 `fastgpt-minio` 服务定义，避免 `docker compose up -d` 再次启动它；保留 `fastgpt-minio` 数据卷。

共享存储配置应与下面一致：

```yaml
  STORAGE_ACCESS_KEY_ID: *x-rustfs-access-key
  STORAGE_SECRET_ACCESS_KEY: *x-rustfs-secret-key
  STORAGE_S3_ENDPOINT: http://fastgpt-rustfs:9000
```

`STORAGE_VENDOR` 仍保持 `minio`，这里只替换 S3 兼容实现的地址与凭证。

宿主机上运行的 FastGPT 还需要同步更新其 `.env` / `.env.local` 中的 `STORAGE_ACCESS_KEY_ID`、`STORAGE_SECRET_ACCESS_KEY` 和 `STORAGE_S3_ENDPOINT`。如果主站、Pro 后台或其他进程分别读取不同的环境文件，需要逐一更新所有连接这套对象存储的配置。Endpoint 使用该应用可访问的宿主机地址和映射端口，例如 `http://127.0.0.1:9000`；不要直接使用仅在 Compose 网络内解析的 `fastgpt-rustfs`。如果应用在另一台机器上运行，使用对象存储宿主机的实际可访问地址。

校验并启动原部署。由于仍在原目录、原 Compose project 中运行，MongoDB、Redis、PG、应用密钥和原配置都会保持不变。

```bash
docker compose config --quiet
docker compose up -d
docker compose ps
curl -fsS http://127.0.0.1:9000/health
```

宿主机应用也要通过原来的启动方式重新启动，确保读取更新后的存储配置。

确认文件上传、下载、知识库文件访问和公开桶匿名读取正常后，再考虑删除旧 `fastgpt-minio` 数据卷。不要执行 `docker compose down -v`。

## 回滚

如果切换后应用无法正常工作，停止新对象存储和 FastGPT，再恢复备份的 Compose 文件并启动原部署：

```bash
docker compose stop fastgpt-app fastgpt-plugin fastgpt-rustfs
cp docker-compose.yml.minio.bak docker-compose.yml
docker compose up -d
```

宿主机应用需要同时恢复备份的 `.env` / `.env.local`，再通过原来的方式重新启动。

回滚后旧 MinIO 数据仍然可用。如果切换到 RustFS 后已经产生新的文件，需要先把这些新对象反向同步回 MinIO，否则它们不会出现在回滚后的部署中。

> `fastgpt-public` 的匿名只读策略会在 FastGPT 启动时自动设置。迁移完成后、FastGPT 启动前公开文件会返回 403；`fastgpt-private` 始终保持私有。
