必须源码编译安装Dify并严格使用Python 3.12，通过pip或Poetry安装backend依赖，配置.env密码一致后启动db/redis/weaviate，最后运行healthcheck验证。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要在本地完整运行 Dify 的最新功能（如 Agent 工作流编排、知识库向量化检索、多模型路由），必须基于源码完成编译安装并精确管理 Python 依赖，不能仅靠 pip install dify 或 Docker 快速启动——后者默认跳过本地构建、不加载自定义插件、且无法调试 backend 核心逻辑。
准备系统环境与 Python 运行时
使用 Ubuntu 22.04 LTS 或更新版本，确保系统级工具就绪：执行 sudo apt update && sudo apt install -y git curl wget build-essential python3-dev python3-venv。
Python 版本必须为 【3.12】，Dify 0.6.0 明确不兼容 3.11 及以下；若系统自带 Python 3.10，请用 pyenv 安装并设为全局版本：pyenv install 3.12.4 && pyenv global 3.12.4。验证命令 python --version 输出必须为 Python 3.12.4，否则后续 pip 安装会静默失败。
这一步不可跳过——实测在 Python 3.11 环境下，pip install -r requirements.txt 会因 typing_extensions >=4.8.0 与 langchain-core==0.3.1 的类型注解冲突而中断，报错信息被 pip 默认隐藏，只显示 “Failed to build xxx”。
获取源码并初始化项目结构
执行 git clone https://github.com/langgenius/dify.git，进入 dify/ 目录后，先确认是否存在 backend/ 子目录；若缺失，说明克隆不完整，需删掉整个文件夹重试。
切换到 backend/ 目录：cd backend。此处是 Python 后端服务根路径，所有 requirements*.txt 文件均位于此，不是项目根目录或 dify/docker/ 下。
复制环境模板：cp .env.example .env，然后用 nano .env 手动填写 POSTGRES_PASSWORD 和 REDIS_PASSWORD——这两个值必须与后续 Docker Compose 启动的数据库服务密码严格一致，否则 API 服务启动后立即报 ConnectionRefusedError。
安装核心依赖与可选组件
方法一：使用 pip 直接安装（适合调试）
创建虚拟环境：python -m venv venv → 激活：source venv/bin/activate（Linux/macOS）或 venv\Scripts\activate（Windows）→ 升级 pip：pip install --upgrade pip setuptools wheel → 安装主依赖：pip install -r requirements.txt -r requirements.dev.txt。
方法二：使用 Poetry（推荐用于二次开发）
先安装 Poetry：curl -sSL https://install.python-poetry.org | python3 - → 进入 backend/ 后执行：poetry env use 3.12 → poetry install。Poetry 会自动解析 pyproject.toml 中的依赖图谱，比 pip 更精准处理 langchain 与 llama-index 的版本锁死问题。
注意：若网络受限，pip 安装时务必加国内镜像源，例如：pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple；Poetry 则需提前配置 poetry source add -r https://pypi.tuna.tsinghua.edu.cn/simple。
启动基础服务与验证依赖完整性
第一步：启动 PostgreSQL、Redis、Weaviate 等底层服务
返回项目根目录（即含 docker-compose.yml 的位置），执行：docker compose up -d db redis weaviate。
第二步：检查容器状态
运行 docker ps --filter "status=running" --format "{{.Names}}" | grep -E "db|redis|weaviate"，输出应包含三个容器名；若缺失，说明 .env 中的密码未生效或端口被占用，需先 docker compose down 再重试。
第三步：验证 Python 环境健康度
重新进入 backend/，确保虚拟环境已激活，执行：python -m dify_cli healthcheck。该命令会依次测试数据库连接、Redis 健康、模型 API 密钥格式（若配置了 OPENAI_API_KEY）、以及 SQLAlchemy 初始化能力。只有全部通过，才表示依赖安装真正成功。
