当前位置：首页 > news >正文

Dify本地部署指南：源码与Docker双模式启动

news 2026/3/26 18:56:10

Dify 本地部署实战：从源码到容器的完整搭建路径

在 AI 应用开发日益普及的今天，如何快速构建一个稳定、可扩展且支持复杂逻辑的 LLM 工具平台，成为开发者面临的核心挑战。Dify 正是为此而生——它不仅提供可视化编排界面，还深度整合了 Prompt 工程、RAG 检索增强生成和 Agent 编排能力，让开发者可以用低代码方式实现企业级 AI 应用。

但再强大的平台，也得先跑起来才算数。本文不讲概念，只聚焦一件事：手把手带你把 Dify 在本地真正“启动”。无论是想调试源码、做二次开发，还是只想快速验证功能，下面这套流程都能帮你避开常见坑点，稳稳落地。

我们采用分步推进的方式，先拉取代码，再逐个启动中间件、后端和前端服务。过程中会穿插实际问题的应对策略，毕竟真实环境从来不会按文档完美运行。

准备工作：环境齐了吗？

别急着敲命令，先确认你机器上有没有这些基础组件：

git—— 拉代码用
docker和docker-compose（建议 v2.20+）—— 跑中间件和容器化服务
Python 3.10—— 源码模式下后端依赖
Node.js 18+与npm—— 前端构建要用
OpenSSL—— 生成安全密钥的关键工具

都装好了？那就开始。

git clone https://github.com/langgenius/dify.git cd dify

这一步看似简单，但如果你在国内，GitHub 下载慢或频繁断连，可以考虑使用镜像站点或配置代理。另外建议保留.git目录，方便后续跟踪上游更新。

中间件不是配角，而是地基

很多部署失败，其实败在中间件没搭好。Dify 的三大支柱是 PostgreSQL、Redis 和 Weaviate，它们分别负责结构化数据存储、缓存队列和向量检索。少了任何一个，后面的服务都会报错。

项目已经贴心地准备了docker/docker-compose.middleware.yaml，我们可以直接用 Docker 启动这三个服务：

cd docker cp middleware.env.example middleware.env docker compose -f docker-compose.middleware.yaml up -d

这个middleware.env文件里定义了数据库密码、Weaviate 持久化路径等关键配置，复制后可以根据需要修改，比如改数据库名或调整持久化目录。

启动完成后，检查一下是否都在运行：

docker ps | grep -E "(postgres|redis|weaviate)"

正常情况下你会看到三个容器处于running状态。如果某个没起来，比如 Weaviate 卡住了，先别慌，看日志：

docker logs weaviate

常见问题是内存不足（尤其是 macOS 默认 2GB 的 Docker Desktop 配置），Weaviate 至少要 3~4GB 才能顺利启动。解决办法也很直接：去 Docker Desktop 设置里调高内存限制，或者在 compose 文件中加资源约束：

services: weaviate: image: semitechnologies/weaviate:v1.23.0 mem_limit: 4g # ...

至于网络访问，这里默认用了 bridge 网络，宿主机可以通过localhost访问这些服务：

PostgreSQL:localhost:5432
Redis:localhost:6379
Weaviate:localhost:8080

你可以分别测试连通性：

# 测试 Redis redis-cli ping # 应返回 PONG # 查看 Weaviate 元信息 curl http://localhost:8080/v1/meta # 连接 PostgreSQL（需安装 psql 客户端） psql -h localhost -U postgres -p 5432 -d postgres -c "SELECT 1"

只要这几项通了，你的地基就算打牢了。

后端启动：两种选择，不同用途

现在轮到 API 服务登场。Dify 的后端基于 Flask 构建，处理所有核心逻辑，包括用户认证、应用编排、Agent 调度和 LLM 对接。

方式一：源码启动（适合开发调试）

进入api/目录：

cd ../api

复制配置文件：

cp .env.example .env

.env是整个系统的“中枢神经”，里面一堆变量，最不能忽略的是SECRET_KEY。千万别留默认值，否则有安全风险。用 OpenSSL 生成一个强随机密钥：

awk -v key="$(openssl rand -base64 42)" '/^SECRET_KEY=/ {sub(/=.*/, "=" key)} 1' .env > temp_env && mv temp_env .env

这行命令的意思是：找到.env中以SECRET_KEY=开头的行，把它后面的值替换成 42 字节的 Base64 随机串。简洁高效，一行搞定。

接下来安装依赖。Dify 使用 Poetry 管理 Python 包，如果你还没装，先装上：

curl -sSL https://install.python-poetry.org | python3 -

然后创建虚拟环境并安装依赖：

poetry env use 3.10 poetry install

注意版本要求：强烈建议使用 Python 3.10。虽然可能也能跑 3.11 或 3.12，但官方主要测试和支持的是 3.10，避免因依赖兼容性问题浪费时间。

安装完之后，进入 shell 环境执行数据库迁移：

poetry shell flask db upgrade

这条命令会自动执行migrations/目录下的脚本，在数据库中创建所需的表结构，比如用户、应用、会话记录等。第一次部署必须运行，否则登录页面都打不开。

最后启动服务：

flask run --host 0.0.0.0 --port=5001 --debug

加上--debug参数后，代码改动会自动热重载，非常适合边改边测。此时服务监听在http://localhost:5001，打开浏览器访问/health接口：

curl http://localhost:5001/health # 返回 {"status": "ok"}

看到ok，说明后端已就绪。

方式二：Docker 启动（适合快速部署）

如果你不想折腾本地 Python 环境，或者希望更接近生产部署形态，可以直接构建镜像运行。

仍在api/目录下：

docker build -t dify-api .

构建成功后，启动容器：

docker run \ --name dify-api \ -p 5001:5001 \ --env-file .env \ --network host \ -d \ dify-api

这里有几个细节要注意：

--env-file .env加载配置，确保数据库地址、密钥等正确
--network host使用主机网络，这样容器可以直接访问宿主机上的中间件（PostgreSQL、Redis 等）。不过这种方式在某些系统（如旧版 Docker for Mac）上不支持，替代方案是使用自定义 bridge 网络
-d后台运行，便于持续观察日志

查看日志确认启动状态：

docker logs -f dify-api

如果出现连接数据库失败，大概率是网络不通。这时可以把中间件也放进同一个 Docker 网络中统一管理：

docker network create dify-net # 启动中间件时指定网络 docker compose -f docker/docker-compose.middleware.yaml up -d --network dify-net # 修改 .env 中的 POSTGRES_HOST=postgres （即服务别名） # 再重启 API 容器，并加入同一网络 docker run --network dify-net --name dify-api -p 5001:5001 --env-file .env -d dify-api

这种做法更规范，也更适合未来迁移到 Kubernetes。

前端服务：让用户看得见的操作台

Dify 的前端基于 React 构建，提供了直观的应用编排界面。没有它，你就只能对着 API 文档发呆。

源码启动（推荐用于开发）

cd ../web npm install npm run start

几秒后，浏览器自动打开http://localhost:3000，但你会发现页面加载失败——因为前端找不到后端 API。

默认情况下，前端请求的是/api路径，通过代理转发到5001端口。但如果后端不在本地，或者你想换地址，就得改配置。

编辑.env.local文件：

REACT_APP_API_BASE=http://localhost:5001/api

保存后重启即可生效。注意这个文件不会被提交到 Git，适合本地个性化设置。

Docker 启动（适合预览或 CI/CD）

如果你想打包成静态服务发布，可以走 Docker 构建流程。

先构建前端资源：

npm run build

生成的文件放在build/目录下。接着用 Nginx 托管这些静态文件，Dockerfile 很轻量：

FROM nginx:alpine COPY build /usr/share/nginx/html COPY nginx.conf /etc/nginx/nginx.conf EXPOSE 80

构建镜像：

docker build -t dify-web .

运行容器：

docker run --name dify-web -p 3000:80 -d dify-web

现在访问http://localhost:3000，应该能看到登录页了。

⚠️ 注意：如果 API 地址变了，而你又没做动态配置，可能需要在构建前手动替换build/config.json中的 API 地址，或者使用构建参数注入。

最后的验证：不只是“能打开”

部署完成的标准，不是“页面出来了”，而是功能可用、链路通畅。

打开浏览器，访问：

前端：http://localhost:3000
健康检查：http://localhost:5001/health

你应该能进入注册页面，创建第一个工作空间和管理员账号。试着新建一个应用，配置 Prompt，上传一份文本作为知识库，看看 RAG 是否生效。

此外，可以手动验证各组件连通性：

组件	验证方法
PostgreSQL	`psql -h localhost -U postgres -d dify -c "SELECT datname FROM pg_database;"`
Redis	`redis-cli ping`→`PONG`
Weaviate	`curl http://localhost:8080/v1/meta`→ 返回 JSON 元信息
API	`curl http://localhost:5001/api/version`→ 获取版本号
Web UI	打开开发者工具，Network 面板中`/api`请求应全部 2xx

如果一切正常，恭喜你，已经拥有了一个完整的 Dify 开发环境。

那些你可能会遇到的问题

现实总比文档复杂一点。以下是几个高频问题及应对方式：

❌ Weaviate 启动失败，提示 OOM（内存溢出）

原因：Weaviate 默认占用较高内存，Docker Desktop 默认 2GB 不够用。

解决方案：
- 提升 Docker 内存至 4GB+
- 在docker-compose.middleware.yaml中显式设置mem_limit: 4g

❌`flask db upgrade`报 “Connection refused”

排查步骤：
1. 确认 PostgreSQL 容器正在运行：docker ps | grep postgres
2. 检查.env或middleware.env中POSTGRES_HOST是否为localhost（源码模式）或postgres（容器网络模式）
3. 用telnet localhost 5432测试端口是否可达

❌ 前端报 CORS 错误

原因：后端未允许来自http://localhost:3000的跨域请求。

修复：在.env中添加：

CORS_ALLOW_ORIGINS=http://localhost:3000

开发阶段可以放开，生产环境务必严格控制来源。

❌ 容器之间无法通信

典型表现：API 容器连不上postgres主机名。

解决方法：使用自定义 Docker 网络：

docker network create dify-net

然后将中间件和 API 容器都加入该网络，并在.env中将POSTGRES_HOST=postgres。

总结：选对方式，事半功倍

Dify 的本地部署并不难，关键是理清组件关系和网络拓扑。下面是两种主流方式的适用场景对比：

部署方式	适用场景	优点	缺点
源码启动	开发调试、二次开发	可实时修改代码，调试方便	环境依赖多，配置较繁琐
Docker 启动	快速部署、CI/CD 预演	环境隔离，一键运行，易于复制	构建时间长，定制灵活性低

对于大多数开发者来说，推荐组合是：