
自建 Dify 的人大多踩过同一件事:升级或重建容器之后,之前传的知识库文档不见了,登录也报加密数据无效。原因是 Dify 默认把上传文件、知识库内容和 .dify_secret_key 这类引导状态写在容器本地磁盘,容器一换这些就跟着没了。RustFS 官方集成目录用 Dify 1.18.0 验证过一条路子:把存储后端从本地盘切到 S3,指向 RustFS 桶,上传的文档、租户私钥、引导密钥全都落进桶里,容器里不再留需要保留的状态。这篇按官方那份 Compose 配置走一遍,重点是 OpenDAL 那几个环境变量、Docker bridge 之间的网络隔离、以及改完 .env 必须重建而不是重启。流程是本地集成验证,不适用于生产环境。
把 OpenDAL 切到 s3 scheme
Dify 的存储是通过 STORAGE_TYPE 选后端的,官方这份配置把它设成 opendal,再把 scheme 指定为 s3。OpenDAL 是 Dify 用的统一存储抽象层,底层具体接到哪种对象存储由 scheme 决定,选 s3 就是走 S3 协议,这正是 RustFS 能对接的原因。配置文件在 docker/.env 里,从 .env.example 复制过来,要改的是这一组变量。
STORAGE_TYPE=opendal
OPENDAL_SCHEME=s3
OPENDAL_S3_ENDPOINT=http://<your-rustfs-endpoint>:9000
OPENDAL_S3_BUCKET=dify
OPENDAL_S3_ACCESS_KEY_ID=<your-access-key>
OPENDAL_S3_SECRET_ACCESS_KEY=<your-secret-key>
OPENDAL_S3_REGION=us-east-1
OPENDAL_S3_ENABLE_PATH_STYLE=true
OPENDAL_S3_ROOT=/
OPENDAL_S3_ENABLE_PATH_STYLE=true 不能漏。路径样式是桶名进 URL 路径,形如 http://host:9000/dify/key;不开的话组件按虚拟主机样式把桶名拼进主机名,RustFS 不认这个地址。region 填 us-east-1 是签名需要的值,跟连不连 AWS 没关系。
启动栈之前要把桶先建好,Dify 不会自己建桶。用任意 S3 客户端指向 RustFS 端点建一个名叫 dify 的桶就行。
aws s3 mb s3://dify --endpoint-url http://<your-rustfs-endpoint>:9000
这组配置把三类数据一起挪进桶:上传的文档、知识库文件,还有 .dify_secret_key 和工作区私钥这类引导状态。这正是重建容器后最容易丢的那部分,挪走之后容器本身就可以随时弃掉。
Docker 的 bridge 网络互相看不到
这是整套配置中最容易浪费时间的一处。Dify 的 Compose 栈跑在它自己的 bridge 网络里,Docker 对不同的 bridge 做了隔离。在宿主机上能通的 http://172.17.0.2:9000 这类地址,到了 api 容器里就是连接超时,启动日志报 tcp connect error: Connection timed out。
官方的解法是把 RustFS 容器用别名接进 Compose 那个网络,端点主机写成别名:
docker network connect --alias rustfs <compose-network> <rustfs-container>
这样 api 和 worker 容器用 http://rustfs:9000 就能解析到,不用去猜容器 IP。容器 IP 在重建之后会变,别名不会,这也是不用 IP 的实际理由。<compose-network> 和 <rustfs-container> 两个占位符分别换成实际的网络名和 RustFS 容器名,Network 名字可以用 docker network ls 查到。
还有一个容易反复踩的点。改完 .env 之后,docker compose restart 不会重读环境变量,旧实例还是拿的旧存储配置,表现就是上传仍落在本地盘。要用 docker compose up -d --force-recreate 把整个栈重建,让每个服务都读到新值。只重启 api 一个容器也不够,worker 同样持有旧配置,两个都得换掉。
启动后先看桶里多了什么
栈起来、api 健康检查通过之后,去 Web UI(http://localhost:80)创建管理员账号。这一步会立刻往桶里写引导状态:
aws s3 ls s3://dify/ --recursive \
--endpoint-url http://<your-rustfs-endpoint>:9000
能看到 65 字节的 .dify_secret_key 和租户目录下的 private.pem。看到这两个对象,就说明密钥已经不在容器磁盘上了。这里顺带记一个排障点。登录报 Invalid encrypted data,多半是绕开 Web UI 直接给 console API 发明文密码,前端那边对密码字段做了 Base64 编码,账号操作走 UI 就不会撞这个。密钥进了桶还有个附带好处,多副本部署时几个 api 实例读到的是同一份 .dify_secret_key,不会出现各存一份、加密状态对不上的情况。
接着在 UI 里建知识库、传文档,上传会落到 upload_files/<tenant-id>/ 前缀下,对象在上传完成的瞬间就出现在桶里。索引流程直接针对桶内那份副本跑,不会先在本地盘落一遍。<tenant-id> 是每个工作区的标识,不同工作区共用同一个桶时靠这个前缀隔开,查看对象时按它区分归属。要是建文档时报 Default model not found for text-embedding,那是索引模式的问题。high-quality 需要先在 Dify 里配 embedding 模型供应商,纯存储测试用 economy 模式就够,跟 RustFS 这侧无关。
重置时 bind mount 要单独清
演示结束,docker compose down 拆掉栈,桶里的对象会留着。要连数据一起删:
aws s3 rm s3://dify --recursive \
--endpoint-url http://<your-rustfs-endpoint>:9000
有个细节官方专门提醒了。Dify 的 Compose 文件把数据库和存储 bind-mount 在 docker/volumes/ 下,docker compose down -v 并不会删 bind mount。-v 只清理 Compose 声明的匿名卷和命名卷,对宿主机上的目录挂载无能为力,这也是它被误用最多的地方。想要一个干净环境,得显式删掉 docker/volumes/,否则旧的管理员账号和加密状态还会残留,下次启动又是一堆对不上的报错。
从本地验证到能长期跑还差几步
官方把这套明确标成本地集成测试,Compose 栈是单机编排,凭证写死在 .env 里。长期跑之前有几处要改,尤其是数据库那部分还留在本地卷里,这份配置只把文件存储挪到了 RustFS,并没有把数据库也迁走。
凭证换成只授权 dify 这一个桶的专用账号,创建步骤在 RustFS 的访问密钥管理页。.env 里的密钥明文存放,生产环境要接到密钥管理方案里,别跟着配置文件一起进版本库。
知识库规模上来之前,先把 RustFS 的 S3 兼容性说明过一遍,确认索引流程会用到的分段上传行为跟预期一致。Dify 的环境变量参考里还有插件守护进程独立的 S3 设置和同一桶上的分段调优,那些在这份演示里没覆盖,扩到插件场景之前要单独配置。
排障按这个顺序走:网络超时先查 Compose 网络别名,上传还落本地盘先查是不是用 --force-recreate 重建过,登录报加密错误先查是不是走了 Web UI,建文档报模型错误先确认索引模式。这几处对应官方列出的全部典型故障,不用在存储配置上来回改。