跳到主要内容

Dify Docker Compose 部署:环境配置、初始化与模型接入

按官方 Compose 目录部署 Dify,修改环境文件,完成管理员初始化与模型提供方设置。

Dify 要同时运行多个服务

Dify 包含应用、任务处理、数据库和相关组件,不能按单个 API 容器的配置购买服务器。官方起步要求至少 2 核 CPU、4GiB 内存,磁盘还要容纳镜像、数据库和上传文件。准备已安装 Docker 与 Compose 的 Linux VPS。

取得官方发行版

打开 Dify 官方 Releases,选择要部署的正式版本并记录标签。下列 TAG 必须换成所选版本,不能把占位符原样运行。

bash;使用前请核对本文前提。
git clone --branch TAG https://github.com/langgenius/dify.git
cd dify/docker
cp .env.example .env

如果服务器没有 Git,先用系统软件包管理器安装。保留版本标签和 .env,后续更新与恢复都会用到。

修改 .env 后再启动

编辑 .env 中的密码、密钥和对外地址。服务器已有网站占用 80 或 443 时,调整官方配置的 EXPOSE_NGINX_PORT 等入口参数,或接入现有反向代理,不要让两个服务争用端口。

bash;使用前请核对本文前提。
sudo docker compose config --quiet
sudo docker compose up -d
sudo docker compose ps

初始化相关的一次性服务完成后退出可能是预期行为;持续运行的组件报错,则查看对应服务日志。不要仅凭所有行都出现过容器名就认定安装正常。

初始化管理员与模型提供方

通过部署入口打开 /install,创建管理员。进入工作区后配置模型提供方和凭据,先用一个简单聊天应用确认模型调用可用,再增加知识库和复杂工作流。

如果界面能打开但模型调用失败,查看提供方地址、模型名称、凭据与额度。上传文档后的处理还涉及后台任务,前端能登录并不表示文档处理组件已经正常。

保存数据库、上传文件和环境配置

备份 Compose 的持久化数据、数据库和 .env。文件和数据库之间有关联,恢复时应来自同一轮备份。版本升级遵循官方迁移说明,先保存旧版本数据再切换。

同一台机器计划运行更多应用时,观察内存、任务队列和磁盘增长,再决定扩容;不要把官方起步配置当成所有工作流的固定上限。

每个目标版本单独核对迁移要求

Dify 升级步骤随版本变化。先记录当前 Git 标签、Compose 文件、镜像与 .env,再阅读目标版本以及跨过的版本发行说明。官方当前要求 Docker Compose 2.24.0 或更新;运行 docker compose version 确认环境满足条件。

保存数据库、上传文件、向量存储、插件数据、密钥和自定义代理配置。持久化位置以自己的 Compose 和外部存储配置为准,不能只备份一个 volumes 目录就假定外部 PostgreSQL、S3 或向量数据库已经包含在内。停写后取得相互对应的备份。

合并新配置,不覆盖旧 .env

在单独目录取得目标发行版,将旧配置与目标模板比较。官方当前配置包括 docker/.env 和 docker/envs 下的可选配置模板;逐份核对所使用的 .env.example,加入新变量并保留原密码、密钥和对外地址。

改过 docker-compose.yaml 时,把必要改动应用到新版本文件,而不是一直沿用旧文件。新发行版可能增加必需服务;按其说明处理一次性初始化任务,不将全部 Exited 状态统一当成故障。

完成官方要求的迁移步骤后执行 docker compose config --quiet,再启动该版本。数据库与向量服务有专门升级路径时,按对应文档执行,不直接拉取一个 latest 镜像替换所有组件。

检查模型、知识库和插件,再恢复业务

升级后检查管理员登录、原模型凭据和应用发布地址。用一份小文档验证上传、后台索引与知识库检索,再执行一个使用原插件的工作流;同时看 worker、API、插件和所使用存储组件的日志。前端能打开不表示任务队列已经恢复。

失败时保留新数据和日志,停止业务写入。在隔离环境恢复升级前的数据库、文件、向量与插件数据,以及原密钥和配置,再用原版本验证。数据库迁移后的实例不能只切回旧应用镜像;恢复点之后的新上传和调用记录需要另行处理。