[dify]Dify 文件下载问题排查:Word 文件已生成,浏览器却无法下载

在本地电脑远程访问服务器上部署的 Dify 运行工作流时，我想实现输出可下载文件的效果，但实际测试中发现：通过 Word文档操作工具插件生成了 Word 文件，无法正常下载。

这里把这次排查过程整理下来，作为一篇实践记录，供后续参考。

一、环境说明

本次实践环境如下：

• Dify 版本：1.13.2
• 部署环境：CentOS 7 虚拟机

我搭建的是一个比较简单的 Dify 工作流，一共只有 3 个节点：

1. 开始节点：用于设置文件输入
2. Word文档操作工具插件节点：用于生成 Word 文件
3. 输出节点：用于将结果返回前端

但实际测试时发现，文件虽然生成了，浏览器却无法正常下载。

二、修改环境变量配置

首先，在 Dify 的 .env 配置文件中，可以看到这样一段与文件访问相关的说明：

# File preview or download Url prefix.# used to display File preview or download Url to the front-end or as Multi-model inputs;# Url is signed and has expiration time.# Setting FILES_URL is required for file processing plugins.#   - For https://example.com, use FILES_URL=https://example.com#   - For http://example.com, use FILES_URL=http://example.com#   Recommendation: use a dedicated domain (e.g., https://upload.example.com).#   Alternatively, use http://<your-ip>:5001 or http://api:5001,#   ensuring port 5001 is externally accessible (see docker-compose.yaml).FILES_URL=

这段说明其实已经给出了几个关键信息：

一是，文件处理类插件依赖 FILES_URL 配置； 二是，这个地址会作为文件预览或下载的访问前缀； 三是，如果使用 5001 端口，那么这个端口必须能够被外部访问。

看到这里，基本可以判断：问题主要出在文件下载地址配置不正确，或者相关端口没有打通。

三、第一次尝试：将 FILES_URL 配置为容器服务名

根据配置说明，我先做了第一步尝试，把 .env 中的 FILES_URL 改成：

FILES_URL=http://api:5001

修改完成后，重启 Dify，再重新执行工作流。

结果还是不行，浏览器依然无法在本地正常下载文件。

如果是在服务器本机直接访问本机部署的 Dify，这种写法有时可能可以正常使用；但当前场景是本地电脑远程访问服务器上的 Dify，情况就不一样了。

分析这个配置，问题其实比较清楚。 api 是 Docker Compose 中的服务名，这种写法更适合容器内部服务之间访问。也就是说，Dify 各个容器之间可能可以识别 api 这个地址，但外部浏览器并不知道 api 代表什么。

因为我是从本地电脑远程访问服务器上的 Dify，浏览器访问下载链接时，实际上是从本地去请求这个地址。此时 http://api:5001 对浏览器来说并不是一个可解析、可访问的外部地址，所以下载自然无法成功。

也就是说，这种配置方式虽然看起来符合说明，但只适用于内部访问，不适合直接给本地浏览器使用。

四、第二次尝试：改成真实 IP 地址

既然容器服务名不行，那下一步就改成服务器真实 IP。

我将 FILES_URL 修改为：

FILES_URL=http://{服务器IP}:5001

按理说，这一步已经更接近正确答案了。因为对于本地浏览器来说，服务器真实 IP 是可以识别的，访问路径也更合理。

但是测试之后发现，还是不行。

继续往下分析，如果地址本身没有问题，那问题会不会出在端口没有真正开放出来？

也就是说，虽然我写了 http://{服务器IP}:5001，但如果宿主机并没有对外暴露 5001 端口，那么本地浏览器仍然无法访问到对应的文件服务。

五、继续排查：检查 5001 端口是否开放

接下来，检查服务器上的 5001 端口监听情况，使用的命令如下：

netstat -tuln | grep 5001

这一步的目的很明确，就是确认 5001 端口是否真正处于监听状态，是否已经被暴露出来供外部访问。

如果没有监听结果，或者只是容器内部启用了服务、宿主机却没有做端口映射，那么即使 FILES_URL 配置成了真实 IP，外部依然访问不到。

检查到这里，基本可以把排查重点放到 Docker Compose 配置上了。

六、问题定位：docker-compose.yaml 中没有映射 5001 端口

继续查看 Dify 的 docker-compose.yaml，最终发现问题出在这里： api 服务并没有配置 5001 端口映射。

这意味着什么？

意味着即使 Dify 内部文件服务监听了 5001 端口，宿主机也没有把这个端口开放出来，外部浏览器当然就无法通过 http://{服务器IP}:5001 访问文件。

所以需要修改 docker-compose.yaml，在 api 服务中增加 5001 端口映射。例如：

api:image:langgenius/dify-api:1.13.2restart:alwaysports:-"5001:5001"

这里最关键的就是这一行：

-"5001:5001"

它的作用是把容器内部的 5001 端口映射到宿主机的 5001 端口。这样一来，外部浏览器就可以通过服务器 IP 加 5001 端口访问对应的文件下载地址。

七、修改完成后重启 Dify

在完成以下两项修改后：

1. 将 .env 中的 FILES_URL 改为真实可访问的 IP 地址
2. 在 docker-compose.yaml 中为 api 服务增加 5001:5001 端口映射

再重启 Dify，重新运行工作流。

这次测试结果就正常了： Word文档操作工具插件生成的 Word 文件可以正常显示，并且能够下载。

到这里，问题就解决了。

八、总结

这次问题的解决，核心就是两步：

1. 修改 .env

FILES_URL=http://{服务器IP}:5001

2. 修改 docker-compose.yaml

api:image:langgenius/dify-api:1.13.2restart:alwaysports:-"5001:5001"

完成上述修改后，重启 Dify，再运行工作流，文件即可正常生成并下载。

从这次排查看，像这种“文件已经生成，但浏览器无法下载”的问题，排查思路可以重点放在两个方面： 一是文件访问地址是否配置正确，二是对应端口是否真正对外开放。