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

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

在 AI 应用开发日益普及的今天，如何快速搭建一个支持 RAG、Agent 编排和 Prompt 工程的可视化平台，成为许多开发者关心的问题。Dify 正是为此而生——它不仅开源、功能完整，还提供了灵活的部署方式，无论是用于本地调试还是生产上线，都能轻松应对。

本文将带你从零开始，在本地完整部署 Dify 平台。我们将覆盖源码模式和Docker 模式两种主流部署路径，涵盖前后端配置、中间件依赖、常见问题排查等关键环节，确保你能在不同场景下顺利运行这套强大的 LLM 开发工具链。

环境准备与核心组件概览

在动手之前，先确认你的开发环境满足以下基本要求：

• Git（代码拉取）
• Docker & Docker Compose（容器化部署）
• Python 3.10（后端运行时）
• Node.js 16+（前端构建）
• Poetry（Python 依赖管理）

如果你打算走源码路线，这些工具都得装好；如果选择 Docker 部署，则只需保证 Docker 环境可用即可。

接下来，克隆官方仓库：

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

Dify 的架构依赖几个关键中间件服务，它们各自承担重要角色：

• PostgreSQL：存储用户信息、应用配置、会话记录等结构化数据
• Redis：作为缓存层和 Celery 异步任务队列的消息代理
• Weaviate：向量数据库，支撑知识库的语义检索能力（RAG 核心）

幸运的是，项目内置了docker-compose配置文件，可以一键拉起所有依赖服务。

进入docker目录并启动中间件栈：

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

这条命令会在后台启动 PostgreSQL、Redis 和 Weaviate 容器，并自动创建所需的网络和持久卷。你可以通过以下命令检查服务状态：

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

看到所有服务处于running状态后，说明基础环境已就绪。

⚠️ 提示：Weaviate 对内存比较敏感，建议主机至少有 8GB 内存，其中为 Weaviate 预留不少于 4GB，否则可能出现 OOM 或启动缓慢的问题。

后端服务部署：源码模式详解

Dify 的后端基于 Flask 构建，负责处理 API 请求、执行工作流调度、管理模型调用以及同步向量数据到 Weaviate。如果你想深入定制逻辑或参与贡献，源码模式是首选。

进入后端目录并配置环境变量

cd ../api cp .env.example .env

.env文件中包含多个关键配置项，需要根据实际环境调整：

特别注意：不要使用默认的SECRET_KEY，这会带来安全风险。

自动生成 SECRET_KEY

推荐使用 OpenSSL 生成一个强随机密钥写入.env：

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

这个小脚本会精准替换.env中的SECRET_KEY行，避免手动编辑出错。

安装依赖与初始化虚拟环境

Dify 使用 Poetry 管理依赖，首次运行前需初始化环境：

poetry env use 3.10 poetry install

如果你还没安装 Poetry，可以通过官方脚本快速获取：

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

安装完成后记得将其加入 PATH。

执行数据库迁移

第一次部署必须执行数据库 Schema 初始化：

poetry shell flask db upgrade

这一步会自动在 PostgreSQL 中创建用户表、应用表、对话历史、知识库索引映射等相关结构。如果提示连接失败，请先确认DATABASE_URL是否正确指向容器内的服务名（例如postgresql://postgres:postgres@postgres:5432/dify），而不是localhost。

启动 Flask 服务

一切就绪后，启动开发服务器：

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

成功启动后你会看到类似输出：

* Running on http://0.0.0.0:5001 * Debugger is active!

此时后端 API 已监听http://localhost:5001，你可以用curl测试版本接口：

curl http://localhost:5001/api/version

返回 JSON 即表示服务正常。

✅ 小技巧：若想让服务在后台持续运行，可结合nohup或使用supervisor这类进程管理工具。

后端服务部署：Docker 模式实践

对于希望跳过环境配置、追求稳定一致部署体验的用户，Docker 是更优解。

构建镜像

在api目录下执行：

docker build -t dify-api .

该过程会依据Dockerfile自动安装依赖、复制代码、设置启动命令，最终生成一个轻量级镜像。

启动容器

运行容器并暴露端口：

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

这里的关键参数包括：

• -p 5001:5001：映射宿主机端口
• --env-file .env：加载环境变量
• --network=dify-network：确保能访问由docker-compose.middleware.yaml创建的中间件服务

🔁 注意事项：

如果你在docker目录下启动了中间件，其默认创建了一个名为dify-network的自定义桥接网络。新容器必须加入同一网络才能通信，否则会出现“connection refused”。

查看日志排查问题

实时查看容器日志：

docker logs -f dify-api

常见错误如数据库连接失败，通常源于以下原因：

• .env中的DATABASE_URL写成了localhost而非服务名（应为postgres）
• 容器未加入正确的 Docker 网络
• PostgreSQL 尚未完成初始化（稍等片刻再试）

前端服务部署：源码模式快速上手

Dify 的前端采用 React + TypeScript 技术栈，提供直观的拖拽式流程编排界面，支持 Prompt 调试、知识库上传、Agent 设计等功能。

进入前端目录并安装依赖

cd ../../web npm install

配置 API 接口地址

创建.env.local文件（或修改已有）：

REACT_APP_API_BASE_URL=http://localhost:5001

这是前端发起请求的目标地址。开发环境下建议保留此配置，便于调试。

启动开发服务器

npm start

启动成功后浏览器会自动打开http://localhost:3000，显示登录页面。

💡 提示：开发服务器支持热重载，修改代码后页面会自动刷新，极大提升迭代效率。

前端服务部署：Docker 模式用于生产

当你要将 Dify 部署到测试或生产环境时，推荐使用 Docker 打包静态资源。

构建生产资源

npm run build

该命令会将打包结果输出至build/目录，包含压缩后的 JS、CSS 和 HTML 文件。

构建前端镜像

确保当前位于web目录，并存在Dockerfile：

docker build -t dify-web .

典型的Dockerfile内容如下：

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

也可以在构建时注入 API 地址（适用于多环境部署）：

ARG REACT_APP_API_BASE_URL=http://localhost:5001 ENV PUBLIC_URL=${REACT_APP_API_BASE_URL}

运行前端容器

docker run \ --name dify-web \ -p 3000:3000 \ --network=dify-network \ -d dify-web

容器内运行 Nginx，托管静态文件，并可通过反向代理统一处理 API 请求，避免跨域问题。

验证部署是否成功

完成部署后，进行以下几步验证：

1. 访问前端界面
   打开 http://localhost:3000
   → 应能正常加载登录页

2. 检查 API 连通性
   打开浏览器开发者工具，观察 Network 请求
   →/api/version应返回类似：
   json { "version": "0.6.0", "current_user": null }

3. 注册账号并创建应用
   → 尝试使用“文本生成”或“Agent”模板新建一个应用

4. 测试 RAG 功能
   在知识库中上传一份文档（如 PDF 或 TXT）
   → 触发查询，观察 Weaviate 是否成功建立向量索引

5. 验证数据持久化
   登录 PostgreSQL 和 Redis 容器，查看是否有数据写入：
   bash docker exec -it dify-postgres psql -U postgres -c "SELECT * FROM users LIMIT 1;" docker exec -it dify-redis redis-cli keys "*"

全部通过即表明部署成功。

常见问题与实战解决方案

❌ 数据库迁移失败：“Connection refused”

典型表现：flask db upgrade报错无法连接 PostgreSQL。

根本原因：
- PostgreSQL 容器未完全启动
- 网络隔离导致无法解析服务名
-.env中DATABASE_URL错误地用了localhost

解决方法：
- 使用docker ps确认dify-postgres处于运行状态
- 检查.env中是否为postgresql://postgres:postgres@postgres:5432/dify
- 若使用 Docker 模式，确保容器加入dify-network

❌ Weaviate 启动慢或崩溃

现象：容器反复重启，日志显示 OOM 或 timeout。

原因分析：Weaviate 是内存密集型服务，尤其在处理大批量文档嵌入时，对 JVM 堆内存要求较高。

优化建议：
- 提升 Docker Desktop 内存限制至 8GB 以上
- 在docker-compose.middleware.yaml中显式设置资源限制：

weaviate: image: semitechnologies/weaviate:v1.19 deploy: resources: limits: memory: 4G # 其他配置...

❌ 前端无法调用后端 API

症状：浏览器报 CORS 错误，或 404/502。

可能原因：
-REACT_APP_API_BASE_URL配置错误
- 生产环境中未配置反向代理
- 后端未开启跨域支持

修复策略：
- 开发环境确保.env.local正确设置 API 地址
- 生产环境推荐使用 Nginx 统一代理前端和 API 请求
- 临时调试可在后端.env添加：
env FLASK_ENV=development
（仅限测试，禁止用于生产）

❌ OpenAI 调用超时或认证失败

错误类型：Invalid API key或Request timeout

主要原因：
- 未设置有效的OPENAI_API_KEY
- 国内网络无法直连 OpenAI 接口
- 密钥权限不足或已被封禁

应对方案：
- 在.env中正确填写密钥：
env OPENAI_API_KEY=sk-xxxxxxxxxxxxxx
- 如在国内，建议配置代理，或切换为本地模型（后续可通过 Model Provider 接入 Ollama、HuggingFace、Qwen 等）

总结与延伸方向

通过本文的详细指导，你应该已经能够在本地完整部署 Dify 平台，无论选择源码调试还是 Docker 快速启动，都能顺利运行前后端服务并与中间件协同工作。

Dify 的真正价值在于其低代码构建 LLM 应用的能力。你无需编写复杂逻辑，就能通过图形化界面实现：

• 智能客服问答系统
• 自动生成营销文案
• 多步骤 Agent 协作流程
• 私有知识库增强检索

下一步，你可以尝试：

• 接入私有大模型（如 Qwen、ChatGLM、Llama3），摆脱对公有云 API 的依赖
• 配置 SSO 单点登录，集成企业身份系统
• 使用 CI/CD 实现自动化构建与部署流水线
• 扩展插件系统，接入自定义工具或外部 API

Dify 正在快速发展，社区活跃，文档完善。欢迎访问其 GitHub 仓库 获取最新特性、参与讨论，甚至贡献代码。

现在，你已经拥有了独立部署和运维 Dify 的能力。是时候动手打造属于你自己的 AI 应用工厂了。