Dify工作流文件URL不完整？FILES_URL配置排查与解决指南

最近有朋友跑过来问我说他在 Dify 工作流里用“开始节点”接收用户上传的图片后面接了一个代码节点想把文件 URL 拿出来做二次处理。结果在代码节点里打印出来一看文件地址要么是/api/v1/files/xxx/access?...这种相对路径要么直接是http://localhost:80/api/v1/files/xxx/access?...拿到浏览器里根本打不开整个工作流直接被卡在这一步。我跟他讲这大概率不是 Dify 的 bug而是部署的时候FILES_URL这个环境变量没有配好。这篇文章就围绕这个问题把原因、定位思路、解决办法、以及几类容易踩的坑完整梳理一遍。内容主要针对 Docker Compose 方式本地部署 Dify、并且用工作流处理文件上传的同学Dify 1.x 版本都适用老版本思路也大同小异。1. 先定位开始节点的文件变量到底长什么样1.1 用代码节点把文件变量完整打印出来遇到文件 URL 不完整的问题我建议第一步别急着改代码先在 Dify 工作流里搭一个最简单的“调试链路”把文件变量的真实结构打出来看。操作很简单开始节点里拖一个文件类型变量比如叫my_file类型选“文件”或“图片”接着接一个代码节点输入变量绑定sys.files.my_file代码直接原样输出 JSON。import json def main(file_var: dict) - dict: return { result: json.dumps(file_var, ensure_asciiFalse, indent2) }运行一次工作流手工上传一个测试图片然后看代码节点的输出。不同 Dify 版本的字段结构会有一点差异但核心通常长这样{ dify_model_plugin: { file_type: image, transfer_method: local_file, type: image, url: /api/v1/files/9b185436-xxxx-xxxx-xxxx/access?timestamp1700000000nonceabcsignxxx }, filename: test.png, transfer_method: local_file, type: image, url: http://localhost:80/api/v1/files/9b185436-xxxx-xxxx-xxxx/access?timestamp1700000000nonceabcsignxxx }重点看两个字段url和remote_url。url是 Dify 内部生成的文件访问地址remote_url一般只在用户通过外链方式上传文件时才会有值本地文件上传时基本上用不到。如果你看到url是以/api/v1/...开头或者写的是http://localhost:80/...甚至出现http://nginx:80/...那就说明 Dify 在生成这个地址的时候没有拿到正确的外部访问域名或者压根没配置采用了默认值。后面的所有排查都是围绕这个问题展开的。1.2 为什么 URL 会拼成相对路径或 localhostDify 的文件默认不是直接把服务器上的存储路径暴露给你的。它会把文件存在本地存储目录然后通过一个 API 路由对外提供访问。工作流里文件变量里的url本质上就是一个动态拼接出来的访问地址。拼接的时候Dify 会依赖一个基础地址前缀这个前缀的配置项就是FILES_URL。关键点在于Dify 工作流内部传递变量时是没有经过外部网关或者 Nginx 反代的。如果你没有在环境变量里显式指定FILES_URLDify 只能按默认值去拼。默认值通常就是http://localhost有些 Docker 部署场景下还可能是容器内部的服务名比如http://nginx:80。于是你拿到的 URL 要么是相对路径要么是 localhost要么是容器内部地址。这就是为什么同样一个工作流你在本机部署时感觉一切正常因为浏览器就在 localhost 上拿到的http://localhost/...能直接打开一旦换到服务器上通过域名访问别人上传的文件打出来的 URL 还是 localhost那肯定 404。问题不在工作流逻辑而在“文件访问的基础地址”没有跟着部署环境一起变。2. 最快解决路径配置 FILES_URL 并正确重启2.1 修改 .env 文件的具体操作Docker Compose 部署的 Dify环境变量基本都集中在部署目录下的docker/.env里面。找到这个文件搜索FILES_URL没有就手动加一行。FILES_URLhttps://dify.example.com这里有几个细节要注意FILES_URL要填用户实际访问你 Dify 服务时使用的地址。如果你用域名反代就填https://dify.example.com如果你只是用服务器 IP 加端口访问就填http://服务器IP:端口。结尾不要带斜杠https://dify.example.com/这种写法容易导致后面拼接时出现双斜杠虽然 Dify 有的版本能容错但没必要给自己埋坑。如果你的服务是 HTTPS这里一定也要写 HTTPS。否则 Dify 生成的图片地址还是 HTTP浏览器会把 HTTP 资源直接拦截掉表现就是“图片加载不出来”这个问题容易和文件 URL 不完整混在一起。如果你在.env里找不到FILES_URL不要慌手动新增一行即可。Dify 的 docker-compose.yaml 里通常会引用这个变量并且有默认值兜底你新增后就会覆盖默认值。2.2 改完环境变量后容器必须这样重建才生效这是整个排查过程里最容易踩的坑我见过太多人改完.env后只跑了一句docker compose up -d然后发现文件 URL 还是老样子于是怀疑 Dify 是不是缓存了什么。实际上docker compose up -d在容器已经存在、只有环境变量变化的时候默认不会重新创建容器。你必须强制让它重建一次新环境变量才会真正注入到容器进程里。docker compose up -d --force-recreate api worker web如果你不确定服务名就直接全部重建docker compose up -d --force-recreate重建完成后建议进容器里确认一下环境变量是否真的生效docker ps | grep api docker exec -it api容器名 env | grep FILES_URL看到输出的FILES_URL是你设置的值再重新运行工作流打印文件变量url字段应该就变成完整的外部地址了。提示如果你是在 Dify 的源码目录用docker/docker-compose.yaml启动的记得确认你改的是docker/.env不是项目根目录下的某个无关.env文件别问我是怎么知道的。3. 配好 FILES_URL 之后工作流里怎么安全使用文件 URL3.1 代码节点里做一次兜底拼接最省心全局配置FILES_URL是首选方案但不少人在实际项目里会遇到一种情况代码节点运行环境是沙箱拿到的文件变量结构依然带有相对路径。这时候不要慌可以在代码节点里做一个兜底拼接避免下游节点拿到非法 URL。核心思路很简单判断url字段是否以http://或https://开头如果不是就手动拼上你的文件访问基础地址。import json FILES_BASE_URL https://dify.example.com def main(file_var: dict) - dict: url file_var.get(url, ) or if url.startswith(/): url FILES_BASE_URL.rstrip(/) url return { complete_url: url }这个方案的优点是稳定不依赖代码节点里能不能读到环境变量。缺点也很明显域名是写死的以后换域名要改工作流。所以我一般是把它作为“临时补救措施”长期方案还是把FILES_URL配置好让 Dify 自动生成完整地址。3.2 HTTP 请求节点里动态拼接文件地址如果你需要在 HTTP 请求节点里把文件 URL 传给第三方服务建议不要直接拖文件变量作为完整 URL也不要手动拼一个可能重复的地址。正确做法是让代码节点先输出一个完整的complete_url然后在 HTTP 节点的 URL 输入框里引用这个变量。比如代码节点输出了complete_urlHTTP 节点 URL 栏写成{{#complete_url#}}这样最干净。如果确实需要手动拼接只需要注意一点先判断文件变量里的url是不是已经带http前缀。否则容易出现https://your-domain.comhttp://localhost/...这种奇怪地址。还有一点特别容易忽略Dify 文件 URL 后面通常会带签名参数比如timestamp、nonce、sign。这些参数是访问校验的一部分拼接和转发的时候一定要原样保留不要觉得看着碍眼就删掉。没有签名文件接口会直接拒绝访问。3.3 LLM 读图和外部服务拉取文件时为什么也受这个配置影响有些同学会问我把文件传给 LLM 节点是不是就不需要管FILES_URL这个要看情况。Dify 内部处理文件时如果是走本地文件流转它会自己读取文件内容转换成模型需要的格式这时候FILES_URL配不配影响不大。但如果你集成的模型供应商要求图片必须通过公网 URL 传入或者你在工作流里把文件 URL 交给了外部服务去拉取那么FILES_URL没配好直接影响就是模型读图失败或者外部服务 403。我遇到过一个实际案例工作流里把图片 URL 传给一个第三方图像处理服务第三方服务收到地址后去拉取图片拿到的 URL 是http://localhost:80/...对方自然访问不到。排查到最后就是FILES_URL没有配外部地址。改完之后图片 URL 变成公网可访问地址问题立刻解决。所以结论是哪怕你现在只做内部文件处理我也建议把FILES_URL规范配置好因为你不知道哪天会加一个外部服务调用到时候再排查会非常被动。4. 常见问题与排查技巧实录4.1 本地正常、线上文件 URL 打不开现象本地部署时一切正常上传图片后 URL 能打开部署到服务器后同样的工作流代码节点打印出来的 URL 还是http://localhost:80/...外部访问必然失败。原因很直接.env里的FILES_URL没有跟着部署环境改仍然是默认值。Dify 本身不会自动感知你当前是通过什么域名访问的它只知道你配置的基础地址。排查步骤我一般是这样在代码节点打印文件变量的完整 JSON确认url到底是什么。在服务器上执行docker exec -it api容器名 env | grep FILES_URL看容器里的实际值。如果容器里的FILES_URL是http://localhost或空值直接改.env并强制重建容器。这组操作基本能把九成以上的问题定位出来。4.2 改了 FILES_URL 仍然不生效怎么办这种现象通常有三个原因。第一个原因是容器没有重建。我在前面强调过docker compose up -d不会因为环境变量变化就自动重建容器必须加--force-recreate。很多人改完没重启或者只重启了一半服务导致 api 容器生效了worker 容器还是旧环境变量而处理文件任务的可能正好是 worker。第二个原因是改错了.env文件。Docker Compose 部署的 Dify.env文件在docker目录下。如果你同时有源码目录和部署目录注意别混淆。第三个原因是容器内环境变量被 docker-compose.yaml 中的引用方式限制住了。如果你手动维护过docker-compose.yaml要确认 api 和 worker 服务里确实引用了${FILES_URL}。官方编排一般都会引用但如果你从老版本升级过来或者自己改过编排可能会漏掉。检查完这三个地方基本都能解决。4.3 文件 URL 带签名参数过期后访问 403这也是一个高频疑惑。代码节点里打印出来的 URL 很长带有timestamp、nonce、sign参数。这个不是 URL 不完整而是 Dify 的文件访问签名机制。这些签名参数是用来校验请求合法性的防止未授权的人通过拼接 URL 访问文件。带签名的链接通常是有时效的超过一定时间后Dify 会返回 403。如果你的下游服务需要长期保存文件不要把它返回的临时 URL 直接存到数据库里长期使用。正确做法是让服务端把文件下载下来转存到自己的对象存储或者文件系统里保存你自己生成的新地址。这个思路适用于任何使用 Dify 文件 URL 做二次分发的场景。4.4 用了 Nginx 反代之后文件 URL 变成内部地址Dify 用 Docker Compose 部署后大多数人会在前面套一层 Nginx 做反向代理。这时候如果FILES_URL没配好文件 URL 可能变成http://nginx:80/...或者容器内部 IP。原因是容器内生成 URL 时Dify 只能根据它能拿到的信息来拼。虽然 Nginx 反代时会传递一些 header但 Dify 内部生成文件 URL 的逻辑不一定依赖于这些 header最可靠的还是直接配置外部访问地址。配置建议和前面一样FILES_URL写成用户实际访问的域名。另外如果域名是 HTTPSFILES_URL必须用 HTTPS否则会出现页面是 HTTPS、文件资源是 HTTP 的混合内容问题浏览器一样会拦截。5. 别忽略工作流发布为 API 时返回文件 URL 同样依赖 FILES_URL5.1 外部系统通过 API 拿到的文件地址长什么样开始节点上传的文件问题不只出现在工作流画布里。当你把工作流发布成 API第三方系统调用接口、上传文件、拿到返回结果时返回数据里的文件变量同样会走FILES_URL拼接逻辑。之前有个做业务对接的同事踩过这个坑外部系统调用 Dify 工作流 API工作流跑通了返回的文件字段看起来也有 URL但对方点开就是打不开。我让他去查了一下部署环境果然FILES_URL没配置返回的地址是内网地址。配置好之后外部系统才能正常下载文件。所以如果你把 Dify 工作流 API 暴露给第三方系统使用检查清单里一定要有这一项确认FILES_URL是外部可访问的域名。否则对方拿到文件也访问不了你还得排查半天。5.2 对外提供文件访问的配置建议这里给一个比较稳妥的配置习惯FILES_URL统一在docker/.env里配置不要写死在具体某个工作流里。如果 Dify 是给多个环境共用建议每个环境单独维护一份.env避免测试环境配置被带到生产环境。对外文件访问的域名最好和后台管理域名保持一致或者是一个专门的文件子域名方便后续做 CDN 或者迁移存储。另外一个细节是如果文件量大、访问频繁建议考虑把 Dify 的本地文件存储切换到对象存储比如 S3、OSS这样文件访问地址可以走对象存储的域名FILES_URL的配置指向也会更清晰。不过这是另一个话题了本次先聚焦在 URL 不完整这个眼前的问题上。最后再分享一个我个人常用的调试习惯遇到 Dify 文件相关的问题第一步永远是先把文件变量完整打印出来看结构而不是直接改代码逻辑。因为你只有看到url到底是什么才能判断是环境变量问题、签名过期问题还是字段用错了。排查文件 URL 不完整这件事只要抓住FILES_URL、容器是否重建、URL 是否带全签名这三个点基本就能把所有相关坑都趟平。