Dify 用 Docker Compose 私有化部署

这篇适合谁、读完能做到什么

适合想在自己的机器或服务器上运行 Dify，又不想一开始就折腾数据库和向量数据库的开发者和小团队。读完你应该能用 Docker Compose 在一台机器上把 Dify 跑起来，知道怎么修改部署的配置，上线前要替换哪些默认凭据，以及以后怎么安全地升级。

Dify 这套部署包含什么

默认的 Docker Compose 部署自带 PostgreSQL、Weaviate，以及 Dify 运行需要的其他服务。也就是说，你不需要事先准备数据库或向量数据库^[1]。这套方案的定位是在单台机器上运行 Dify，之后再做安全加固、自定义和升级^[1]。

部署前准备：硬件、软件和平台

硬件方面，至少需要 2 个 CPU 核心和 4 GiB 内存^[1]。

软件方面，需要 Docker 和 2.35.0 或更高版本的 Docker Compose，并确保 Docker 守护进程正在运行。此外还要装 Git 用来下载 Dify，装 OpenSSL 用来为 Agent 的本地沙箱生成令牌^[1]。

不同系统的安装方式略有差别^[1]：

• macOS：安装 Docker Desktop，并给它的虚拟机分配至少 2 个虚拟 CPU 和 8 GiB 内存。
• Linux：按发行版的说明安装 Docker Engine 和 Docker Compose。
• Windows：启用 WSL 2，安装 Docker Desktop，并把源代码和容器数据放在 Linux 文件系统里。

装好以后，先检查 Compose 版本：

docker compose version

上手：获取、配置和启动

在 Dify 的发行版页面选一个版本，把命令里的 <version> 换成对应的标签，然后克隆仓库并进入 docker 目录^[1]：

git clone --branch <version> --depth 1 https://github.com/langgenius/dify.git
cd dify/docker

接下来用模板创建配置文件 .env，再生成 Agent 本地沙箱用的令牌，并把它写进 DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN。Agent 后端和它的本地沙箱都需要这个共享令牌才能启动^[1]。

首次启动前，如果这是生产用途，先把安全加固一节列出的凭据设置好。另外，如果想用自己的外部向量数据库或 MySQL 代替默认的 Weaviate 和 PostgreSQL，也可以在 .env 里设置。注意，首次启动之后再切换，已有数据不会迁移^[1]。

在 dify/docker 目录里启动服务并检查状态^[1]：

docker compose up -d
docker compose ps --all

一直运行的服务应显示 Up 或 healthy。init_permissions 只运行一次，用来准备存储权限，完成后显示 Exited (0) 就是正常的^[1]。

访问和远程部署

启动后，在浏览器打开 http://localhost/install，创建管理员账户，再到 http://localhost 登录^[1]。

如果部署在远程服务器上，把 localhost 换成服务器的 IP 地址或域名。默认 HTTP 端口是 80，如果 80 端口已被占用，就在 docker/.env 里把 EXPOSE_NGINX_PORT 设为其他端口，访问地址里也要带上这个端口。需要远程实时协作时，在 docker/.env 中添加 NEXT_PUBLIC_SOCKET_URL，值为服务器的 WebSocket 地址，然后重新运行 docker compose up -d^[1]。

自定义：以修改 Nginx 上传上限为例

部署的全局设置，比如 Compose profile、对外端口、挂载路径、健康检查调度，以及共享凭据，都写在 docker/.env 里。其他设置按服务分开存放。大多数服务会加载 docker/envs/ 下自带的 .defaults 文件，这些文件不要直接改，修改写进注释里指明的本地 .env 文件即可。API、Worker 和定时任务共用的设置，放在 envs/core-services/api-worker.env 中^[1]。

下面以把 Nginx 的请求体大小上限提高到 200M 为例。如果 envs/infrastructure/nginx.env 还不存在，先从默认文件复制一份^[1]：

cp envs/infrastructure/nginx.defaults envs/infrastructure/nginx.env

然后在这个文件里写入^[1]：

NGINX_CLIENT_MAX_BODY_SIZE=200M

改完之后，先验证配置，再重建受影响的容器。这里要用 up -d，不能用 restart，因为 restart 会沿用容器原有的环境变量^[1]：

docker compose config --quiet
docker compose up -d

最后检查 Nginx 实际生效的配置。输出中应包含 client_max_body_size 200M;。如果显示的是别的值，先检查 docker/.env 有没有覆盖，因为这个值还可能来自其他位置^[1]：

docker compose exec -T nginx nginx -T 2>&1 | grep client_max_body_size

上线前的安全加固

在把服务开放给其他人之前，先配置 HTTPS，并替换 docker/.env 里自带的开发凭据。需要替换的包括数据库和 Redis 的密码，即 DB_PASSWORD 和 REDIS_PASSWORD；代码执行沙箱的 SANDBOX_API_KEY 和 CODE_EXECUTION_API_KEY，两者应设为同一个强密钥^[1]。

向量数据库 Weaviate 也要处理：把 WEAVIATE_API_KEY 设为强密钥，加入 WEAVIATE_AUTHENTICATION_APIKEY_ALLOWED_KEYS，并把 WEAVIATE_AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED 设为 false，强制要求身份认证。插件守护进程的 PLUGIN_DAEMON_KEY 和 PLUGIN_DIFY_INNER_API_KEY 则要使用两个不同的强密钥^[1]。

默认部署栈不会把数据库、Redis、代码执行沙箱或 Weaviate 的端口发布到宿主机。即使在内网，也应该限制对这些服务的访问^[1]。

另外要注意 SECRET_KEY。如果没有设置，Dify 会在首次启动时生成一个随机密钥，并和数据一起保存。之后再设置或修改它，用旧密钥签名的令牌和文件链接都会失效^[1]。

升级

升级前，先在 Dify 的发行版页面选定目标版本，并阅读它的升级说明^[1]。之后的每条 Compose 命令，都要沿用部署原来的项目名和 Compose 文件，包括 -p、-f 选项或 COMPOSE_PROJECT_NAME，这样原有的命名卷才会继续挂载^[1]。

备份时，先在 dify/docker 中执行 docker compose stop，避免复制数据库文件时它还在写入。然后备份 docker/.env、本地的 .env 文件、自定义的 Compose 文件，以及 docker/volumes/ 等持久化数据^[1]。

切换版本时，本地的 .env 文件和 docker/volumes/ 不受 Git 跟踪，检出新版本后仍然保留。如果你改过 docker-compose.yaml 等被 Git 跟踪的文件，先暂存这些修改，在仓库根目录执行^[1]：

git stash
git fetch --tags origin
git checkout <version>

然后对比 docker/.env.example 和你现有的 docker/.env，并把每个本地服务文件和对应的模板对比。更新所需的设置时，应改现有文件，而不是直接用模板覆盖，否则你的覆盖值会丢失。现有的数据库和仍在使用的向量数据库，连同它们的连接设置和 Compose profile，都要保留。修改 DB_TYPE 或 VECTOR_STORE 不会迁移数据^[1]。

最后拉取新镜像，重新启动并检查状态^[1]：

docker compose pull
docker compose up -d
docker compose ps --all

升级后，持续运行的服务应显示 Up 或 healthy，init_permissions 应显示 Exited (0)。然后打开 Dify，试一下依赖你自定义设置的功能^[1]。

限制和常见问题

• 这套方案是单机部署。页面没有讨论多机高可用，如有这方面需求，需要另外规划^[1]。
• 页面没有给出费用，也没有给出云服务器的具体型号。硬件要求只写到 2 核 4 GiB 这个下限^[1]。
• 切换数据库或向量数据库不会自动迁移数据，这一点在首次启动和升级时都要记住^[1]。

下一步

想了解全部环境变量及优先级规则，可以阅读页面链接的环境变量配置说明^[1]。

本文改编自 Dify 官方文档中的《使用 Docker Compose 部署 Dify》一页^[1]，原文以 CC BY 4.0 许可证发布。