# IM 文件安全第三方接入记录

更新时间：2026-08-23

## 1. 接入范围

本次记录三条文件与安全链路：

1. 阿里云 OSS：用于文件对象存储和签名下载，media handler 标识为 `oss`。
2. 阿里云内容安全增强版：用于文件内容审核，当前 provider 标识为 `aliyun_green`，任务类型为 `content`。
3. 阿里云云安全中心恶意文件检测：用于病毒、木马、WebShell、勒索等恶意文件检测，当前 provider 标识为 `aliyun_sas`，任务类型为 `malware`。

密钥、账号、Bucket 等敏感信息不写入本文档，也不写入源码。运行环境应通过配置中心或部署环境注入。

## 2. 阿里云 OSS 接入

新增媒体 handler：`server/media/oss`。

当前支持：

- `Upload`：上传文件到 OSS Bucket，并把 OSS object key 写入 `FileDef.Location`。
- `Headers`：对 GET/HEAD 生成 OSS 签名 URL，并返回 `308 Permanent Redirect`。
- `Delete`：按 object key 批量删除 OSS 对象。
- `GetIdFromUrl`：从 Tinode 文件 URL 中解析文件 ID。

对象路径规则：

```text
tenants/{tenantID}/{yyyy}/{mm}/{fileID}
```

配置字段：

| 字段 | 说明 |
| --- | --- |
| `access_key_id` | 阿里云 AccessKey ID，部署环境注入 |
| `access_key_secret` | 阿里云 AccessKey Secret，部署环境注入 |
| `endpoint` | OSS 普通 Bucket endpoint |
| `bucket` | OSS Bucket 名称 |
| `region_id` | OSS Bucket 所属地域 |
| `serve_url` | Tinode 对外文件 URL 前缀，默认 `/v0/file/s/` |
| `presign_ttl` | 签名 URL 有效秒数，默认 `120` |
| `cache_control` | 下载缓存头 |
| `cors_origins` | CORS 允许来源 |
| `verify_bucket` | 启动时是否联网校验 Bucket 存在 |
| `use_sys_config` | 为 `true` 时从 `hotgo.hg_sys_config` 读取 OSS 配置 |

OSS endpoint 填写 `https://oss-cn-shenzhen.aliyuncs.com`。IM Server 初始化 OSS handler 时也会给裸域名补 HTTPS，并将阿里云 OSS 的显式 HTTP endpoint 改为 HTTPS。修改后台 `im_third_party.oss_endpoint` 后需重启 IM Server；发布后用真实文件上传验证 `POST /v0/file/u/`，确认 Pod 到 OSS 走 443 端口且不再出现 TCP 写超时。若 HTTPS 仍超时，继续检查 Pod 到 OSS 的出网链路。

当前 `server/tinode.conf` 仍默认使用 `fs`。切换 OSS 时，将 `media.use_handler` 改为 `oss`，并在 `media.handlers.oss` 中设置 `use_sys_config=true` 后，运行时会从后台库 `hotgo.hg_sys_config` 的 `im_third_party` 分组读取 OSS 配置。

代码入口：

- Handler 实现：`server/media/oss/oss.go`
- 后台配置读取：`store.ThirdPartyConfig.Get("im_third_party", ...)`
- Handler 注册：`server/main.go`
- 单元测试：`server/media/oss/oss_tenant_test.go`

注意事项：

- 不使用 AccessPoint endpoint，当前按普通 Bucket endpoint 接入。
- 不在源码或文档中保存真实 AK/SK。
- 下载链路采用签名 URL 重定向，不由 Tinode 代理大文件内容。

## 3. 数据库状态机

新增租户业务库表：`im_file_review_tasks`。

独立租户库方案下，该表不包含 `tenant_id`。每个租户库保存本租户自己的文件审核任务。

核心字段：

| 字段 | 说明 |
| --- | --- |
| `task_id` | 服务端生成的审核任务 ID |
| `file_id` | 对应 `im_fileuploads.id` |
| `user_id` | 上传用户 |
| `task_type` | `content` 或 `malware` |
| `provider` | `aliyun_green` 或 `aliyun_sas` |
| `object_name` | OSS 对象名快照 |
| `mime_type` | 文件 MIME 快照 |
| `file_size` | 文件大小快照 |
| `provider_task_id` | 第三方返回的任务 ID |
| `status` | `pending`、`running`、`clean`、`risky`、`failed` |
| `risk_level` | 第三方风险等级 |
| `risk_labels` | 命中的风险标签 JSON |
| `result_json` | 第三方原始结果 JSON |
| `attempts` / `next_retry_at` | 重试控制 |
| `completed_at` | 审核完成时间 |

唯一约束：

- `task_id` 全局唯一。
- `file_id + task_type + provider` 唯一，避免同一文件重复创建同类任务。

## 4. 当前代码入口

文件上传完成后，在数据库事务内自动创建审核任务：

- 普通/独立库路径：`server/db/mysql/adapter.go` 的 `FileFinishUpload`
- 共享库兼容路径：`server/db/mysql/tenant_adapter.go` 的 `TenantFileFinishUpload`
- 建表逻辑：`server/db/mysql/file_review_schema.go`
- 任务插入：`server/db/mysql/file_review_tasks.go`
- 状态常量和结构：`server/store/types/safety.go`

当前策略是异步审核：上传成功后先生成 `pending` 任务，不阻塞上传响应。

## 5. 阿里云内容安全接入

新增封装包：`server/filesafety/aliyun`。

当前支持：

- `SubmitOSSFile`：提交同账号 OSS 文件审核任务。
- `PollOSSFile`：轮询文件审核结果。
- 默认服务：`document_detection`。
- 支持参数：`ossBucketName`、`ossObjectName`、`ossRegionId`、`dataId`。

文件安全配置通过 `server/filesafety.LoadConfig` 从后台库 `hotgo.hg_sys_config` 的 `im_third_party` 分组读取。内容安全启用后，`server/filesafety.NewGreenClientFromConfig` 可直接构建阿里云内容安全客户端；恶意文件检测当前先落配置和任务状态，具体云安全中心 API worker 后续补充。

结果映射：

| 阿里云风险等级 | 内部状态 |
| --- | --- |
| 空 | `running` |
| `none` / `low` | `clean` |
| 其他风险等级 | `risky` |

后续 worker 需要读取 `provider=aliyun_green,status=pending/running` 的任务，调用提交和轮询接口，并回写 `provider_task_id/status/risk_level/risk_labels/result_json`。

## 6. 阿里云恶意文件检测接入

当前已完成状态机和任务落库，上传成功会创建：

- `task_type=malware`
- `provider=aliyun_sas`
- `status=pending`

后续还需要补云安全中心恶意文件检测 SDK/HTTP client，并实现 worker 提交、轮询和结果映射。

建议映射：

| 三方结果 | 内部状态 |
| --- | --- |
| 未完成 / 排队中 | `running` |
| 无风险 | `clean` |
| 命中恶意类型 | `risky` |
| 调用失败且可重试 | `pending`，更新 `attempts/next_retry_at` |
| 调用失败且不可重试 | `failed` |

## 7. 本地库变更

已在本地 `tinode` 业务库创建并更新 `im_file_review_tasks` 表。

后续新库或已有库启动时，会通过 MySQL adapter 的 ensure 流程自动补表。

## 8. 后续待办

1. 实现文件安全 worker：批量领取 `pending` 任务、提交第三方、轮询结果、回写状态。
2. 接入阿里云云安全中心恶意文件检测 client。
3. 增加审核策略：是否阻断下载、是否只告警、是否对高风险文件自动下架。
4. 在文件下载授权处读取审核结果，按策略限制 `risky/failed/running` 文件访问。
5. 增加后台查询与人工处置接口，用于查看任务、重试、放行、下架。