Skip to main content

S3 Storage Integration

  • OpenIMSDK supports integration with multiple S3 storage services, including: MinIO, Alibaba Cloud OSS, Tencent Cloud COS, Qiniu KODO, and AWS, providing developers with a wide range of choices.

  • Files are uploaded directly from the SDK to S3 storage, bypassing the API server, which significantly improves server-side performance.

  • The API address called during access only redirects requests to the actual S3 storage address. Business-related permission checks can be added at this stage to ensure data security and business flexibility.

  • When using an Nginx proxy for the API, you need to add proxy_set_header X-Request-Api $scheme://$host/api;. See: Nginx Configuration

  • Integration with other S3 storage types is also fully supported. You only need to implement the corresponding interface on the server side — no SDK modifications required. Interface Source

  • Modify object.enable: <name> in the config/openim-rpc-third.yml file to minio, oss, cos, kodo, or aws. Default is minio.

object:
  enable: minio

MinIO

  1. Edit externalAddress in config/minio.yml to your application's access address. The server does not need to be able to access this address.
  2. For MinIO with Nginx, see: https://docs.openim.io/guides/gettingStarted/nginxDomainConfig
# Bucket name for storing and managing files.
bucket: openim
# Access key ID for authentication.
accessKeyID: root
# Secret access key for authentication.
secretAccessKey: openIM123
# Session token, required if using temporary credentials.
sessionToken:
# Internal server address, used only for internal server calls, typically a LAN address.
internalAddress: localhost:10005
# External server address, accessible from outside, supports HTTP and HTTPS with domain names. Ensure this address is accessible by clients. The server does not need to access this address — it is only used for signing.
externalAddress: http://external_ip:10005
# Whether to enable public read access for the bucket. When set to true, the bucket will be automatically changed to public read. Setting it back to false will NOT revert to private.
publicRead: false

Alibaba Cloud OSS

  1. OSS bucket creation: https://oss.console.aliyun.com/bucket
  2. AccessKey generation: https://ram.console.aliyun.com/profile/access-keys
  3. Official documentation: https://help.aliyun.com/zh/oss/developer-reference/overview-25/?spm=a2c4g.11186623.0.i3
  4. Edit object.oss in config/openim-rpc-third.yml.
# OSS data center endpoint, e.g., http://oss-cn-hangzhou.aliyuncs.com
endpoint:
# Bucket name for storing and managing files.
bucket:
# Bucket's external access URL, typically an accelerated access address.
bucketURL:
# Access key ID for authentication.
accessKeyID:
# Secret access key for authentication.
accessKeySecret:
# Session token, required if using temporary credentials.
sessionToken:
# Public read mode. Recommended to set to false, otherwise Content-Type and filename cannot be set for downloads. If set to true, configure these in the OSS management console.
publicRead: false

Tencent Cloud COS

  1. COS bucket creation: https://console.cloud.tencent.com/cos5/bucket
  2. AccessKey generation: https://console.cloud.tencent.com/cam/capi
  3. Official documentation: https://cloud.tencent.com/document/product/436/7751
  4. Edit object.cos in config/openim-rpc-third.yml.
# Bucket URL Endpoint, e.g., https://temp-1252357374.cos.ap-chengdu.myqcloud.com
bucketURL:
# Secret ID for authentication.
secretID:
# Secret key for authentication.
secretKey:
# Session token, required if using temporary credentials.
sessionToken:
# Public read mode. Recommended to set to false, otherwise Content-Type and filename cannot be set for downloads. If set to true, configure these in the COS management console.
publicRead: false

Qiniu KODO

  1. KODO bucket creation: https://portal.qiniu.com/kodo/bucket
  2. AccessKey generation: https://portal.qiniu.com/developer/user/key
  3. Official documentation: https://developer.qiniu.com/kodo/1644/security
  4. Edit object.kodo in config/openim-rpc-third.yml.
# Qiniu KODO endpoint, e.g., http://s3.cn-south-1.qiniucs.com
endpoint:
# Bucket name for storing and managing files.
bucket: kodo-bucket-test
# Bucket URL Endpoint, e.g., http://kodo-bucket-test-oetobfb.qiniudns.com
bucketURL:
# Access key ID for authentication.
accessKeyID:
# Secret access key for authentication.
accessKeySecret:
# Session token, required if using temporary credentials.
sessionToken:
# Public read mode. Recommended to set to false, otherwise Content-Type and filename cannot be set for downloads. Configure these in the KODO management console.
publicRead: false

AWS

  1. Region documentation: http://docs.aws.amazon.com/general/latest/gr/rande.html
  2. AWS S3 bucket creation: https://s3.console.aws.amazon.com/s3/home
  3. AccessKey generation: https://console.aws.amazon.com/iam/home?#/security_credentials
  4. Official documentation: https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html
  5. AWS does not currently support generating thumbnails via URL parameters. Edit object.aws in config/openim-rpc-third.yml.
# Region for sending requests, see: http://docs.aws.amazon.com/general/latest/gr/rande.html
region:
# Bucket name for storing and managing files.
bucket:
# Access key ID for authentication.
accessKeyID:
# Secret access key for authentication.
secretAccessKey:
# Session token, required if using temporary credentials.
sessionToken:
# Public read mode. Currently does not support setting to true.
publicRead: false