dify项目结构说明与win11本地部署

后续会深度研究下dify，智能体的应用要更广泛一些。我也会根据自己的需求，在dify中中的功能进行增强。

项目结构

api - 后端API服务
web - 前端Web应用
sdks - SDK库
docker - Docker相关配置
dev - 开发相关工具，主要是同步脚本等
images - 项目说明的的图片资源

我先让codeBuddy帮我分析下这个工程，看下如何运行。

中间件依赖

dify的启动，一来一堆中间件

shell 复制代码

cd docker
# 拷贝中间件的环境变量
cp middleware.env.example middleware.env
# 我在docker-compose.middleware.yaml 第一行增加
name: 'dify-middleware'

# 挂在
PGDATA_HOST_VOLUME
REDIS_HOST_VOLUME
WEAVIATE_HOST_VOLUME

# 启动
docker compose -f docker-compose.middleware.yaml up -d

api项目

uv环境安装

从1.3开始dify的python环境使用uv管理了。

shell 复制代码

#安装uv
pip install uv
# 安装python 3.12
uv python install 3.12

准备配置文件

shell 复制代码

cd dify/api
# 复制出一个.env
cp .\.env.example .env

替换SECRET_KEY

生成随机密钥并替换 .env 文件中的 SECRET_KEY 值

shell 复制代码

#替换秘钥，官方的是linux版本，我改成了win
$key = [Convert]::ToBase64String((1..42 | ForEach-Object { Get-Random -Maximum 256 }))
(Get-Content .env) -replace '^SECRET_KEY=.*', "SECRET_KEY=$key" | Set-Content temp_env
Move-Item temp_env .env -Force

安装依赖

shell 复制代码

# 同步uv.lock中的一来到本地
uv sync

设置python interpreter

打开setting
选择dify的项目的Python Interpreter
2 通过Add Interpreter 的Add Local Interpreter
3 选择已经存在的
4 选择路径
最后点击ok

执行数据库迁移

执行数据库迁移到最新版本：

shell 复制代码

uv run flask db upgrade

启动api服务

shell 复制代码

# 在dify目录下执行该命令
uv --directory api run  flask run --host 0.0.0.0 --port=5001 --debug

# 等价于 进入api目录后执行
uv run flask run --host 0.0.0.0 --port=5001 --debug

命令解释

--directory 指定工作目录为api

启动worker服务

shell 复制代码

# linux 或mac
uv run celery -A app.celery worker -P gevent -c 1 --loglevel INFO -Q dataset,generation,mail,ops_trace

# win11
uv run celery -A app.celery worker -P solo --without-gossip --without-mingle -Q dataset,generation,mail,ops_trace --loglevel INFO

需要注意的是，在.env中LOG_TZ默认时区为 UTC，改成中国地区LOG_TZ=Asia/Shanghai

前端项目

dify要求前端的环境是：Node.js v22 + Pnpm v10

看了下我本地的，版本比官方的要低

shell 复制代码

PS C:\Users\yxkong> node -v
v20.15.1
PS C:\Users\yxkong> pnpm -v
9.15.4

直接执行报：

text 复制代码

pnpm install --frozen-lockfile  WARN  Unsupported engine: wanted: {"node":">=v22.11.0"} (current: {"node":"v20.15.1","pnpm":"9.15.4"}) Lockfile is up to date, resolution step is skipped Packages: +1781 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ ╭───────────────────────────────────────────────────────────────────╮ │ │ │ Update available! 9.15.4 → 10.11.1. │ │ Changelog: https://github.com/pnpm/pnpm/releases/tag/v10.11.1 │ │ Run "pnpm add -g pnpm" to update. │ │ │ ╰───────────────────────────────────────────────────────────────────╯

先升级下，以前用mac的时候，很简单，直接执行下面的命令即可。

shell 复制代码

npm install -g n

在win上没法执行，直接从官网下载一个覆盖安装。 nodejs.org/zh-cn/downl...

nodejs.org/en/download

pnpm安装升级到是简单。

shell 复制代码

# 升级 pnpm 到最新版
npm install -g pnpm@latest

# 验证版本
pnpm -v
10.11.1

建议大家把缓存目录都改下，要不然c盘越来越大。

安装依赖

shell 复制代码

pnpm install --frozen-lockfile

准备配置

在web目录下，直接从.env.example复制出一个.env文件，正常不用改

shell 复制代码

cp .env.example .env

构建web服务

直接执行pnpm build即可

shell 复制代码

(dify-api) PS E:\ai\code\dify\web> pnpm build
> dify-web@1.4.1 build E:\ai\code\dify\web
> next build

   ▲ Next.js 15.2.3
   - Environments: .env

   Creating an optimized production build ...
 ✓ Compiled successfully
   Skipping validation of types
   Skipping linting
 ✓ Collecting page data
 ✓ Generating static pages (26/26)
 ✓ Collecting build traces
 ✓ Finalizing page optimization

启动web服务

在linux或mac中，启动直接执行pnpm start 即可，在win中报错

shell 复制代码

(dify-api) PS E:\ai\code\dify\web> pnpm start

> dify-web@1.4.1 start E:\ai\code\dify\web
> cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public && cross-env PORT=$npm_config_port HOSTNAME=$npm_config_host node .next/standalone/server.js

      0 [main] us 0 init_cheap: VirtualAlloc pointer is null, Win32 error 487
AllocationBase 0x0, BaseAddress 0x71690000, RegionSize 0x80000, State 0x10000
C:\Users\yxkong\scoop\apps\coreutils\current\bin\cp.exe: *** Couldn't reserve space for cygwin's heap, Win32 error 0
 ELIFECYCLE  Command failed with exit code 1.

win11上无法执行，我直接让codebuddy给我创建了一个兼容模式

关键点：

使用fs-extra 屏蔽操作系统之间的差异性，添加依赖

shell 复制代码

cd web && pnpm add fs-extra@11 --save-exact

新增start.js

shell 复制代码

const fs = require('fs-extra');  
const { spawn } = require('child_process');  
  
async function main() {  
  try {  
    // 复制.next/static目录  
    await fs.copy('.next/static', '.next/standalone/.next/static');  
    console.log('Copied .next/static successfully');  
  
    // 复制public目录  
    await fs.copy('public', '.next/standalone/public');  
    console.log('Copied public directory successfully');  
  
    // 获取环境变量  
    const port = process.env.npm_config_port || process.env.PORT || 3000;  
    const hostname = process.env.npm_config_host || process.env.HOSTNAME || 'localhost';  
  
    // 启动服务器  
    const server = spawn('node', ['.next/standalone/server.js'], {  
      env: {  
        ...process.env,  
        PORT: port,  
        HOSTNAME: hostname  
      },  
      stdio: 'inherit'  
    });  
  
    server.on('error', (err) => {  
      console.error('Failed to start server:', err);  
      process.exit(1);  
    });  
  
  } catch (err) {  
    console.error('Error during startup:', err);  
    process.exit(1);  
  }  
}  
  
main();

codebuddy修改了启动脚本最后启动成功。

如果启动失败，把node_modules删除，然后重新走一遍即可。

后记

修改的脚本在win11上验证通过，还未在mac和linux上验证，等验证了，我提交一个pr
dify官方的文档还是比较健全的，照着操作，遇到的问题不太多
整体上dify的代码清晰度，对于javaer来说，还是比较友好的

系列文章

uv配置环境

dify项目结构说明与win11本地部署

项目结构

中间件依赖

api项目

uv环境安装

准备配置文件

替换SECRET_KEY

安装依赖

设置python interpreter

执行数据库迁移

启动api服务

启动worker服务

前端项目

安装依赖

准备配置

构建web服务

启动web服务

后记

系列文章

dify应用

dify源码

ragflow相关

mcp