你在本地或内网部署了 RagFlow、Dify，想用自建 MinIO 统一存图片和附件，结果遇到两种情况：要么上传成功但预览白屏，要么重启后图片全没了，或者 URL 指向的还是容器内的临时目录。这篇不解释对象存储原理，只按「先定位谁在管存储、再对齐访问地址、最后验证读写」的顺序，把两套平台的 MinIO 配置点和常见坑讲清楚，让你照着改就能跑通。
你在本地或内网部署了 RagFlow、Dify，想用自建 MinIO 统一存图片和附件，结果遇到两种情况：要么上传成功但预览白屏，要么重启后图片全没了，或者 URL 指向的还是容器内的临时目录。这篇不解释对象存储原理，只按「先定位谁在管存储、再对齐访问地址、最后验证读写」的顺序，把两套平台的 MinIO 配置点和常见坑讲清楚，让你照着改就能跑通。
先给一个整体判断：RagFlow 和 Dify 都不会「自动发现」你的 MinIO，必须显式把存储类型切成 S3 兼容，并给出端点、桶名、访问密钥。两个平台的区别只在于配置项叫什么、改完要重启哪些容器、以及对外暴露的图片链接由谁生成。下面按平台拆开讲，最后给一条统一的排查顺序。
先分清谁在管图片：两套平台的存储职责边界
动手改配置之前，先确认「现在到底是谁在存图」。判断依据不是上传按钮，而是各自的环境变量或配置文件。如果存储类型还是默认的本地目录，你直接去 MinIO 里找对象，当然是空的；反过来，如果已经切到对象存储但图片仍丢，那问题多半在访问地址而不是存储本身。
- RagFlow 侧的图片
- 知识库解析阶段落盘的原图和切图，以及会话或文档预览引用的附件
- Dify 侧的图片
- 知识库上传的文件、对话中的图片输入，以及工具产生的临时文件
- MinIO 在这里的角色
- S3 兼容端点，所以两边的配置项本质都是端点、桶名、密钥、区域这几类
- 为什么先分边界
- 两套平台可能装在同一台机器上，但配置文件和重启范围不同，混着改会互相干扰
如果你只是想快速验证，先别动生产环境。用 MinIO 建一个专用桶，再分别改两边的配置，避免和已有的其它桶混用导致互相覆盖。这一步看起来多余，但能省掉后面「到底是谁把对象删了」的扯皮。
RagFlow 侧：把落盘目录指到 MinIO
RagFlow 的存储配置集中在部署时的环境变量文件里。需要把存储类型切成对象存储，并填端点、桶名、访问密钥。改完必须重启服务容器，热改不生效。这一点很多人踩过：改完配置文件以为立刻生效，其实旧进程还抱着老配置在跑。
- 端点别写公网域名，也别写 localhost。容器视角下 localhost 指的是容器自己，连不到宿主机上的 MinIO
- 先单独验证桶和密钥：用命令行工具对同一个端点、同一个桶做一次写入和读取，能通再进平台
- 确认桶已提前建好，且权限策略至少给了写权限。只给读权限时，表现是上传直接报错，而不是白屏
- 改完拿一份带图的文档跑一次解析，然后回到 MinIO 控制台确认真的出现了新对象
还有一个容易被忽略的点：如果 RagFlow 和 MinIO 不在同一台机器，中间又挂了反向代理或防火墙，端点的端口和路径要按实际可达的写。判断标准很简单——进到 RagFlow 的容器里，用命令行能访问到端点，那这个值才算填对。
Dify 侧：文件存储与「对外可见 URL」是两件事
Dify 的存储配置同样走部署环境变量，切换到 S3 兼容并填端点、桶、密钥。这里有两个要分开理解的配置：一个决定后端往哪写，一个决定前端拿到的图片链接长什么样。它们经常不是同一个值，别用一个套两处。
| 配置关注点 | 作用 | 填错的典型表现 |
|---|---|---|
| 存储端点 | 后端实际读写对象的位置 | 上传报错或写入超时 |
| 桶与密钥 | 决定能否写入与读取 | 权限不足，上传直接失败 |
| 对外访问地址 | 平台返回的图片链接前缀 | 图片接口通，但浏览器 404 |
| 反向代理放行 | 决定外部能否取到对象 | 接口正常，图片加载失败 |
切换存储后，新上传的文件才走新存储，历史文件不会自动迁移。这是设计如此，不是 bug。如果你需要历史文件也进 MinIO，得自己写迁移脚本，并按桶和前缀规划好目录结构，别一股脑塞进同一层。
- 跨容器或跨机部署时，读写端点和对前端展示的地址分开配，不要图省事用同一个值
- 确认前面挂的反向代理有没有放行对象存储的路径，否则表现就是接口通、图片打不开
- 如果图片链接指向的是内网地址或旧域名，浏览器端一定取不到，先改对外地址再看效果
改完怎么验：一条从上传到取图的排查顺序
不要东改一下西改一下。按下面四步走，每一步都有明确的现象可以对照，能快速把问题锁定在存储侧还是展示侧。
- 看桶里有没有对象没有对象就是写入侧问题，回到端点、密钥、桶权限；这一步没通，后面都白搭
- 看对象大小是否正常大小为 0 说明是流式写入被截断，常见于超时设置太短或代理做了缓冲，先把超时和缓冲配置查一遍
- 看平台返回的图片链接能否在浏览器直接打开打不开就是对外地址或反向代理问题，跟存储本身无关，改地址或放行路径即可
- 重启一次全部服务再看重启后丢图，基本是配置没落到持久化的环境变量里，或者容器重建时把配置文件覆盖了
如果你在排查中需要对比不同中转站或直连方案的表现差异，可以先到站内的对比页面看当时的测试口径和数字，别凭单次速度下结论。
什么情况下别急着上 MinIO
MinIO 不是必选项。它解决的是多实例共享文件、备份和扩容的问题，代价是多了一个要维护的服务。下面几种情况，可以先不上，等条件具备了再切。
- 单人、单机、数据量很小的场景，平台自带的本地存储更省事，多一层对象存储只是多一个故障点
- 团队还没有稳定的内网域名和证书时，先把访问地址这块理顺，否则图片在浏览器端会持续报错
- 需要多环境共用一套存储时，务必用不同桶或不同前缀隔离，否则测试数据会混进生产桶
- 没有明确的备份和生命周期策略前，别把唯一一份数据直接压上去
常见问题
为什么配置改完，之前上传的图片还是打不开？
切换存储只影响新上传的文件，历史文件仍指向原来的位置。要么保留旧存储可读，要么手动把旧文件搬到新桶并让记录里的路径对齐。先确认平台里存的是相对路径还是完整 URL，改起来方式不一样。
图片能上传，但页面预览是空白，先查哪？
先直接访问平台返回的图片链接，能在浏览器打开就说明存储没问题，问题在前端或代理；打不开就回到对外访问地址和桶权限。多数情况是后端能连、前端拿到的地址容器外访问不到。
桶一定要单独建吗，能不能和别的数据共用一个桶？
能共用，但要按前缀或目录隔离，避免清理策略误删。更稳的做法是给这套平台单独一个桶，权限只开这一个桶，出问题时排查范围也小。
