记录Dify 安装与使用过程

本文总结Dify的安装、启动和本地使用方式，适合首次运行Dify或者日常开发和排查启动问题时快速查阅。

运行方式选择

推荐按目标选择启动方式：

只是体验或自托管整套 Dify：使用 Docker Compose 全量启动。
需要改前端或后端代码：使用源码开发模式，Docker 只启动数据库、Redis、Weaviate 等中间件。
需要处理异步任务、知识库导入、工作流后台执行：源码开发模式下额外启动 worker。

环境要求

最低运行要求：

CPU >= 2 Core
RAM >= 4 GiB
Docker
Docker Compose

源码开发模式还需要：

Node.js >= 24
pnpm
uv

建议通过 Corepack 管理 pnpm：

bash 复制代码

npm install -g corepack
corepack enable

方式一：Docker Compose 全量启动

这是最简单的方式，会一次性启动 Web、API、worker、数据库、Redis、向量数据库、nginx 等服务。

bash 复制代码

cd dify/docker
cp .env.example .env
docker-compose up -d

如果 docker/.env 已经存在，不要直接覆盖。可以先打开对照 docker/.env.example，只补充新增变量或修改需要的配置。

登录dify

启动后访问：

text 复制代码

http://localhost/install

安装ollama插件

集成qwen3大模型

http://localhost/app/9732aa5e-0776-45cf-9e49-88982a303ddc/workflow?action=showSettings\&tab=provider

Dify → 模型提供方 → Ollama：

Base URL

http://localhost:11434

docker环境使用这个：

http://host.docker.internal:11434

Ollama

https://ollama.com/

常用命令

bash 复制代码

# 查看服务状态
docker compose ps

# 查看所有服务日志
docker compose logs -f

# 查看单个服务日志，例如 api
docker compose logs -f api

# 停止并保留数据卷
docker compose down

# 重新拉起
docker compose up -d

如果本机 80 端口被占用，修改 docker/.env：

env 复制代码

EXPOSE_NGINX_PORT=8080

然后重新启动：

bash 复制代码

docker compose up -d

访问地址改为：

text 复制代码

http://localhost:8080/install

方式二：源码开发模式

源码开发模式下，本地运行 API 和 Web，Docker 只负责中间件。仓库提供了 dev 脚本，优先使用脚本启动。

第一次初始化：

bash 复制代码

cd dify
./dev/setup

./dev/setup 会执行这些事情：

复制 api/.env.example 到 api/.env
复制 web/.env.example 到 web/.env.local
复制 docker/middleware.env.example 到 docker/middleware.env
安装 API 依赖：uv sync --group dev
安装 Web 依赖：pnpm install

注意：如果这些环境文件已经存在并且你改过配置，运行前先备份，避免被覆盖。

启动中间件

在第一个终端运行：

bash 复制代码

cd dify
./dev/start-docker-compose

该脚本会使用 docker/docker-compose.middleware.yaml 启动本地开发需要的中间件，默认包括 PostgreSQL、Redis、Weaviate、sandbox、ssrf_proxy 和 plugin daemon。

启动后端 API

在第二个终端运行：

bash 复制代码

cd dify
./dev/start-api

该脚本会先执行数据库迁移：

bash 复制代码

uv run flask db upgrade

然后启动 API：

bash 复制代码

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

后端默认地址：

text 复制代码

http://localhost:5001

启动前端 Web

在第三个终端运行：

bash 复制代码

cd dify
./dev/start-web

该脚本会进入 web 目录并运行：

bash 复制代码

pnpm install
pnpm dev:inspect

前端默认地址：

text 复制代码

http://localhost:3000

首次初始化 Dify 时，访问：

text 复制代码

http://localhost:3000

可选：启动 worker

如果要处理知识库索引、工作流、邮件、插件、清理任务等异步队列，需要额外启动 worker：

bash 复制代码

cd dify
./dev/start-worker

也可以指定队列、并发和 worker 池：

bash 复制代码

./dev/start-worker --queues dataset,workflow --concurrency 2 --pool gevent

可选：启动 Celery Beat

如果要运行定时任务：

bash 复制代码

cd dify
./dev/start-beat

手动源码启动命令

如果不使用 dev 脚本，可以按下面顺序手动执行。

启动中间件：

bash 复制代码

cd dify
cp docker/middleware.env.example docker/middleware.env
docker compose -f docker/docker-compose.middleware.yaml --profile postgresql --profile weaviate -p dify up -d

准备环境文件：

bash 复制代码

cp api/.env.example api/.env
cp web/.env.example web/.env.local

安装后端依赖：

bash 复制代码

cd dify/api
uv sync --group dev

安装前端依赖：

bash 复制代码

cd dify/web
pnpm install

启动后端：

bash 复制代码

cd dify/api
uv run flask db upgrade
uv run flask run --host 0.0.0.0 --port=5001 --debug

启动前端：

bash 复制代码

cd dify/web
pnpm dev:inspect

常用配置文件

Docker 全量部署：

docker/.env：全量 Docker Compose 部署配置。
docker/docker-compose.yaml：全量服务编排。

源码开发：

api/.env：后端 API 配置。
web/.env.local：前端配置。
docker/middleware.env：本地开发中间件配置。
docker/docker-compose.middleware.yaml：中间件服务编排。

前端本地开发时，重点确认 web/.env.local：

env 复制代码

NEXT_PUBLIC_DEPLOY_ENV=DEVELOPMENT
NEXT_PUBLIC_EDITION=SELF_HOSTED
NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api
NEXT_PUBLIC_COOKIE_DOMAIN=

后端需要强随机 SECRET_KEY，可以在 api/.env 中生成并替换。

macOS：

bash 复制代码

secret_key=$(openssl rand -base64 42)
sed -i '' "/^SECRET_KEY=/c\\
SECRET_KEY=${secret_key}" api/.env

Linux：

bash 复制代码

secret_key=$(openssl rand -base64 42)
sed -i "/^SECRET_KEY=/c\\SECRET_KEY=${secret_key}" api/.env

基本使用流程

启动成功后，首次访问页面会进入初始化流程：

打开 http://localhost/install，或源码开发模式下打开 http://localhost:3000。
创建管理员账号。
进入控制台。
配置模型供应商或 OpenAI 兼容接口。
创建应用、工作流或知识库。
如使用知识库、工作流后台任务或插件能力，确保 worker 正在运行。

开发常用命令

后端：

bash 复制代码

cd dify/api
uv run flask db upgrade
uv run pytest tests/unit_tests/
uv run ruff check --fix ./
uv run ruff format ./
uv run basedpyright .

前端：

bash 复制代码

cd dify/web
pnpm dev
pnpm lint:fix
pnpm type-check:tsgo
pnpm test
pnpm storybook

仓库根目录也提供后端质量检查快捷命令：

bash 复制代码

make lint
make type-check
make test

常见问题

端口被占用

常见端口：

Docker 全量部署：80、443、5002、5003
源码开发：3000、5001
中间件：5432、6379、8080、8194、3128

可以在对应的 .env 文件中修改 EXPOSE_* 变量，或停止占用端口的本地服务。

前端访问不到后端

检查 web/.env.local：

env 复制代码

NEXT_PUBLIC_API_PREFIX=http://localhost:5001/console/api
NEXT_PUBLIC_PUBLIC_API_PREFIX=http://localhost:5001/api

同时确认后端 API 已启动：

bash 复制代码

curl http://localhost:5001/health

数据库或 Redis 连接失败

源码开发模式下先检查中间件：

bash 复制代码

cd dify/docker
docker compose --env-file middleware.env -f docker-compose.middleware.yaml -p dify ps

如果中间件没有启动，回到仓库根目录运行：

bash 复制代码

./dev/start-docker-compose

依赖安装失败

后端确认 uv 可用：

bash 复制代码

uv --version

前端确认 Node.js 和 pnpm 版本：

bash 复制代码

node --version
pnpm --version

当前前端要求 Node.js >= 24。

修改 `.env.example` 后如何同步

Docker 部署可使用环境变量同步脚本保留已有配置并补齐新增变量：

bash 复制代码

cd dify/docker
chmod +x dify-env-sync.sh
./dify-env-sync.sh

记录Dify 安装与使用过程