im_server/docs/third/IM-MinIO存储切换说明.md

IM 文件存储切换（OSS / MinIO）

IM Server 继续提供 /v0/file/u/ 上传和 /v0/file/s/ 鉴权下载接口。客户端不直连对象存储。后台 hotgo.hg_sys_config 的 im_third_party.media_handler 是存储开关：oss 写阿里云 OSS，minio 写自建 MinIO。部署配置中的 media.use_handler 必须为 sys_config（server/meetingim.conf 已如此配置）；开关在服务启动时读取，修改后滚动重启 IM Server。

后台配置

先在 hotgo 执行 IM-MinIO存储配置.sql，再通过后台填写：

配置 key	值或用途
media_handler	oss / minio，默认保留现有值
minio_endpoint	https://minio.118im.com；容器内如有可达的 HTTPS 内网地址，可改用内网地址
minio_bucket	xgjs，需预先创建
minio_region	us-east-1
minio_access_key_id	MinIO Access Key，后台敏感配置
minio_secret_access_key	MinIO Secret Key，后台敏感配置

阿里云 OSS 的 oss_* 配置需继续保留，用于读取切换前的文件。回切 OSS 后，MinIO 的配置也需保留。新写入的 MinIO 对象在文件记录中保存为 minio://<bucket>/<key>；原有 OSS 文件位置不改。下载和清理按文件位置选择存储后端，不会因为切换开关迁移已有对象。

上线顺序

1. 确认 IM Server Pod 能访问 MinIO S3 API，且 xgjs 桶及访问密钥可用；不要使用 Console URL 作为 API endpoint。
2. 执行配置 SQL 并在后台填写密钥；保留 media_handler=oss，发布包含 MinIO handler 的 IM Server。
3. 将 media_handler 改为 minio，滚动重启 IM Server，在客户端做小文件上传、下载、Range 下载、删除和历史 OSS 文件下载验证。
4. 回切时将 media_handler 改为 oss 并滚动重启；已有 MinIO 文件继续从 MinIO 读取。

MinIO 对象默认按私有文件处理。示例中的直连公网 URL 只有在桶策略允许公开读取时才可访问；IM 客户端应使用服务返回的文件 URL。当前阿里云内容安全接口接受阿里云 OSS 对象参数，MinIO 文件的第三方审核任务需另行接入可用的文件提交方式，不能把 MinIO 对象直接当 OSS 对象提交。

2026-10-17：本地和测试环境的 hotgo 均已加入 MinIO 字典与配置项，凭据已分别填入数据库，media_handler 仍为 oss。MinIO 公网 S3 API 的独立上传、读取、删除冒烟测试已通过；切换后仍需从测试环境 IM Server Pod 验证完整客户端上传链路。