im_server/docs/third/IM-文件安全第三方接入记录.md

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。

对象路径规则：

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. 增加后台查询与人工处置接口，用于查看任务、重试、放行、下架。