OpenIMSDKDocs

Type at least two characters to search titles and routes.

EN

Language

ENEnglishEnglish docs简中简体中文中文文档
Browse OpenIMSDK Guides
GUIDESOpenIMSDK Guides

OpenIMSDK guides organized by implementation stage, from product concepts and deployment to integration, extension, operations, and reliability.

Guides

Object Storage Migration

Plan configuration, data migration, and access checks when changing storage.

Copy

Migrate S3 object storage

When switching your OpenIMServer object storage provider (for example, migrating from MinIO to an enterprise cloud S3 provider), use the built-in s3convert utility to update database object references without losing existing data.

Clone the repository

Clone the latest OpenIMServer repository:

git clone https://github.com/openimsdk/open-im-server.git
cd open-im-server

Update configuration files

Modify configuration files in the config/ directory to configure the new S3 target:

  1. Edit openim-rpc-third.yml:
  2. Update the configuration block for your new S3 provider with valid credentials and endpoint URLs.
  3. Set object.enable to the name of the new target provider (e.g., oss, cos, kodo, or aws).
  4. Review minio.yml:
  5. If your deployment does not use MinIO, ignore this file.
  6. If migrating to or from MinIO, verify the connection parameters match the intended environment.

Compile the migration tool

  1. Navigate to the S3 tools directory:
   cd tools/s3
  1. Compile the migration binary:
   go build -o s3convert main.go

Execute the migration

To guarantee data consistency, follow these operational best practices:

  1. Pre-migration preparation:
  2. Stop services: Stop OpenIMServer instances to prevent concurrent writes and race conditions during migration.
  3. Back up MongoDB: Create a full backup of the s3 collection in MongoDB before executing the migration tool to allow rapid rollback if needed.
  4. Migration behavior:
  5. The migration utility does not delete source objects in the legacy S3 bucket; it updates corresponding object locator records in MongoDB's s3 collection.
  6. Validate data integrity and verify file accessibility after the migration command completes.
  7. Run the migration command:
   ./s3convert -config <config-dir-path> -name <old-s3-name>
  • <config-dir-path>: Path to the directory containing configuration YAML files.
  • <old-s3-name>: Identifier of the source S3 provider being migrated away from (e.g., minio).
  1. Example command:

If your configuration files reside in ../../config and you are migrating from minio:

   ./s3convert -config ./../../config -name minio

When the output prints success, the database records have been successfully updated. Restart OpenIMServer to resume message and media processing.