162 lines
6.3 KiB
Markdown
162 lines
6.3 KiB
Markdown
# 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 配置 |
|
||
|
||
当前 `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. 增加后台查询与人工处置接口，用于查看任务、重试、放行、下架。
|