dify多媒体文件需统一存至腾讯云cos以解决磁盘爆满、提速访问及跨环境备份问题；须同步配置服务端存储逻辑、密钥权限、域名解析与对象路径规则，并严格按步骤设置多租户媒体库、最小权限策略及.env环境变量，确保上传、读取与ai解析链路全通。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要把Dify平台生成的图片、音频、用户上传的PDF和视频等多媒体文件，统一存到腾讯云COS里，避免本地磁盘爆满、提升访问速度、实现跨环境一致性备份。这要求你不能只改一个配置项，必须同步调整Dify服务端存储逻辑、密钥权限、域名解析和对象路径规则。
准备COS媒体库与密钥
登录腾讯云智能媒资托管控制台，创建新媒体库时【务必选择“多租户模式”】，否则Dify后续无法为不同用户隔离文件路径。单击“查看密钥”，完整复制三项：媒体库访问域名（形如 https://xxx-1300000000.cos.ap-shanghai.myqcloud.com）、媒体库ID（纯数字，如 1300000000）、媒体库密钥（含SecretId和SecretKey）。这三项将直接填入Dify环境变量，不可混淆或截断。
在COS控制台进入该媒体库 → 存储桶管理 → 点击对应存储桶 → 权限管理 → Bucket Policy，粘贴以下最小权限策略（仅允许Dify写入指定前缀）：
{ "Statement": [{ "Action": ["name/cos:PutObject","name/cos:GetObject","name/cos:HeadObject","name/cos:DeleteObject"], "Effect": "Allow", "Principal": { "QCS": ["qcs::cam::uin/100000000000:uin/100000000000"] }, "Resource": ["qcs::cos:ap-shanghai:uid/1300000000:xxx-1300000000/*"], "Condition": { "StringLike": { "qcs:delimiter": "/" } } }] }
配置Dify环境变量启用COS
进入Dify项目根目录，执行 cp .env.example .env 创建配置文件。用文本编辑器打开 .env，找到存储相关区块，按顺序填写：
第一步：关闭本地存储开关 → STORAGE_TYPE=cos
第二步：填入COS基础参数 → COS_BUCKET_NAME=xxx-1300000000（注意不带地域后缀）、COS_REGION=ap-shanghai（必须与控制台地域一致）、COS_SECRET_ID=你的SecretId、COS_SECRET_KEY=你的SecretKey
第三步：设置访问域名与路径前缀 → COS_ENDPOINT=https://xxx-1300000000.cos.ap-shanghai.myqcloud.com（必须与控制台“媒体库访问域名”完全一致）、COS_PATH_PREFIX=dify-media（所有文件将存于COS根目录下的 dify-media/ 文件夹内，不可为空）
⚠️ 注意：COS_ENDPOINT 若漏掉 https:// 或多加斜杠，会导致Dify启动后所有文件上传返回403错误且无明确日志提示。
验证文件上传与AI读取链路
方法一：通过Dify Web界面上传测试
登录Dify控制台 → 进入任意应用 → 点击“知识库” → “添加文档” → 上传一张PNG图片。等待状态变为“已处理”后，打开浏览器开发者工具（F12）→ Network标签页 → 筛选 api 请求 → 查看最近一条 /files/upload 响应体中的 url 字段。该URL应以你配置的 COS_ENDPOINT 开头，且路径包含 dify-media/ 前缀。
方法二：命令行直连校验
在服务器终端执行：curl -X GET "$COS_ENDPOINT/dify-media/test.txt?acl" -H "Authorization: <strong>【此处需用临时Token或预签名URL，不可暴露SecretKey】</strong>"。若返回 AccessDenied 是正常现象（因未授权ACL读取），但返回 NoSuchBucket 则说明 COS_BUCKET_NAME 或 COS_REGION 填错。
方法三：触发AI对话读取
在知识库中上传一份PDF → 新建对话 → 输入“总结这份PDF的前三段”。若Dify能正确返回摘要内容，说明COS文件不仅成功上传，还能被Dify后台服务实时拉取、解析并送入大模型上下文。
