april.a digital gardenAPRILNOTE!
↖ 全部笔记
April

dify本地源码部署启动

# Dify

本文整理并重排了在本地从源码启动 Dify 的完整流程，覆盖后端、Worker 以及前端（建议在 WSL2 Ubuntu 中运行）三部分，并补充在 Windows 环境下的常见问题与规避建议。

概览

  • 后端与中间件：Windows（或 WSL2）上运行 Docker 与 Python 服务
  • Worker：与后端同机运行（使用 Celery）
  • 前端：建议在 WSL2 Ubuntu 中构建与启动（Next.js）

环境准备

  • 操作系统：Windows 10/11 或 WSL2 Ubuntu
  • 基础软件：Git、Docker Desktop（启用 WSL2 集成）、Conda（Python 3.12）、OpenSSL
  • C/C++ 构建工具（如依赖需要编译）：Visual Studio 2022 生成工具（含 C++ 工作负载）
  • Node.js 与包管理：nvm、npm、pnpm

克隆仓库

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

中间件启动（Docker）

  1. 进入中间件配置目录并复制示例配置：

    1
    2
    cd docker
    cp middleware.env.example middleware.env

  2. 启动中间件容器：

    1
    docker compose -f docker-compose.middleware.yaml up -d

后端 API 启动（Python / uv / Flask）

  1. 创建并激活 Conda 环境：

    1
    2
    conda create -n dify312 python=3.12
    conda activate dify312

  2. 进入后端目录并准备环境变量：

    1
    2
    cd api
    cp .env.example .env

  3. 生成并设置 Flask SECRET_KEY：

    1
    openssl rand -base64 42

    将生成的结果填入 .env 文件中的 SECRET_KEY 字段。

    示例（截图）：

    image

  4. 安装 uv 并同步依赖：

    • 安装 uv 请参考官方文档（Windows/WSL2 均可）。
    • 在 api 目录执行：
    1
    uv sync

    若安装过程中提示 C++ 构建链缺失（常见于编译型依赖），请安装 Visual Studio 2022 生成工具：

    参考截图：

    image
    image

  5. 数据库迁移与服务启动：

    1
    2
    3
    4
    5
    # 迁移数据库
    uv run flask db upgrade

    # 启动 API 服务
    uv run flask run --host 0.0.0.0 --port=5001 --debug

Worker 启动（Celery）

在后端同环境下启动 Celery Worker：

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

前端启动（WSL2 Ubuntu / Next.js）

建议在 WSL2 的 Ubuntu 中准备前端环境并构建启动。

  1. 安装 npm 并设置国内镜像：

    1
    2
    sudo apt update && sudo apt install -y npm
    npm config set registry https://registry.npmmirror.com

  2. 安装 nvm（国内镜像脚本示例）：

    1
    2
    3
    curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash
    chmod +x ~/.nvm/nvm.sh
    source ~/.bashrc

  3. 安装 Node.js 22 并检查版本：

    1
    2
    nvm install 22
    node -v

  4. 安装 pnpm 并配置镜像源：

    1
    2
    npm install -g pnpm --registry=https://registry.npmmirror.com
    pnpm config set registry https://registry.npmmirror.com/

  5. 进入前端目录并安装依赖、构建：

    1
    2
    3
    cd web
    pnpm install --frozen-lockfile
    pnpm build

关于 Windows 绝对路径构建问题（Next.js standalone）

在 Windows 下构建后，web/.next/standalone 目录可能包含带有项目绝对路径的层级（例如 \github\dify_gat\dify\web）。这会影响 pnpm start 的启动路径。

可在 web/package.json 中调整 start 脚本，在拷贝目标路径前加入 standalone 下的完整目录层级。例如（仅供参考，需替换为你实际的绝对路径层级）：

1
2
3
4
5
{
  "scripts": {
    "start": "cp -r .next/static .next/standalone/github/dify_gat/dify/web/.next/static && cp -r public .next/standalone/github/dify_gat/dify/web/public && cross-env PORT=$npm_config_port HOSTNAME=$npm_config_host node .next/standalone/github/dify_gat/dify/web/server.js"
  }
}

示例截图：

image

完成上述调整后：

1
2
pnpm dev   # 启动测试环境（开发模式）
pnpm start # 启动正式环境（生产模式）

常见问题与提示

  • C++ 构建工具缺失：uv sync 或某些包安装时报 C++ 相关错误，请安装 Visual Studio 2022 生成工具（含 C++ 工作负载）。
  • Docker 未启动或端口占用：确保 Docker Desktop 运行，必要时修改中间件或 API 端口设置。
  • WSL 路径与 Windows 路径差异：前端在 WSL 中构建，注意与 Windows 端共享目录的路径映射与权限。
  • Next.js standalone 绝对路径：如出现绝对路径嵌套，调整 package.json 的 start 脚本指向 standalone 真实路径。
  • 环境变量：请根据 .env.example 完整配置后端所需的密钥与第三方服务参数。

命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# 克隆仓库
git clone https://github.com/langgenius/dify.git

# 中间件
cd docker
cp middleware.env.example middleware.env
docker compose -f docker-compose.middleware.yaml up -d

# 后端（api）
conda create -n dify312 python=3.12
conda activate dify312
cd api
cp .env.example .env
openssl rand -base64 42  # 复制到 SECRET_KEY
uv sync
uv run flask db upgrade
uv run flask run --host 0.0.0.0 --port=5001 --debug

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

# 前端（web，在 WSL2 Ubuntu 中）
sudo apt update && sudo apt install -y npm
npm config set registry https://registry.npmmirror.com
curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh | bash
chmod +x ~/.nvm/nvm.sh && source ~/.bashrc
nvm install 22 && node -v
npm install -g pnpm --registry=https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com/
cd web
pnpm install --frozen-lockfile
pnpm build
pnpm dev
pnpm start

查找笔记