# 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](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 验证完整客户端上传链路。