Dify-WSL2极速部署Dify实战和避坑与网络优化指南

关于Dify本地部署流程说明和本人遇到的坑点

0. 什么是 Dify？

Dify 是一款开源的 LLM（大语言模型）应用开发平台。它将 RAG（检索增强生成）、模型配置、提示词编排（Prompt Engineering）、工作流和插件系统高度集成。简单来说，它能让你通过可视化界面，像搭积木一样快速构建出属于自己的 AI 助手、知识库问答系统或自动化 Agent。

为什么选择本地部署？

• 数据隐私：所有私有文档和对话记录都存储在本地数据库，无需担心敏感信息上传云端。
• 成本控制：本地部署平台本身免费，且可以自由接入各种本地运行的模型（如通过 Ollama 运行 Llama 3 或 DeepSeek）。
• 深度定制：可以无限制地调用插件、修改源码，并根据个人需求灵活配置工作流。

官网流程

使用 Docker Compose 部署 Dify - Dify Docs

克隆 Dify

1

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

启动 Dify

1. 导航到 Dify 源代码中的 docker 目录：

   1
   

   cd dify/docker

2. 复制示例环境配置文件：

   1
   

   cp .env.example .env

   当前端和后端运行在不同子域名时，需要在 .env 文件中将 COOKIE_DOMAIN 设置为站点的顶级域名（例如 example.com），并将 NEXT_PUBLIC_COOKIE_DOMAIN 设置为 1。前端和后端必须位于同一顶级域名下才能共享认证 Cookie。

3. 根据你的 Docker Compose 版本选择相应命令启动容器：

   1
   

   docker compose up -d

   运行 docker compose version 检查你的 Docker Compose 版本。

   将启动以下容器：

   • 5 个核心服务：api、worker、worker_beat、web、plugin_daemon
   • 6 个依赖组件：weaviate、db_postgres、redis、nginx、ssrf_proxy、sandbox

   打开管理员初始化页面以设置管理员账户：

4. 1
   2
   3
   4
   5
   

   # 本地环境
   http://localhost/install
   
   # 服务器环境
   http://your_server_ip/install

5. 完成管理员账户设置后，在以下地址登录 Dify：

   1
   2
   3
   4
   5
   

   # 本地环境
   http://localhost  
   
   # 服务器环境
   http://your_server_ip

修改配置

修改本地 .env 文件中的环境变量值，然后重启 Dify 以应用更改：

1
2

docker compose down
docker compose up -d

一、 源码获取：从小工具开始

1. 解决 jq 命令缺失

在克隆 Dify 仓库时，我们通常使用一段 Shell 脚本自动获取 GitHub 最新 Release 版本号，以确保安装的是稳定版：

1

git clone --branch "$(curl -s https://api.github.com/repos/langgenius/dify/releases/latest | jq -r .tag_name)" https://github.com/langgenius/dify.git

遇到问题：报错 Command 'jq' not found。 解决办法：安装 JSON 处理利器 jq。

1

sudo apt update && sudo apt install jq -y

二、 环境排雷：Docker 的安装来源

遇到问题：尝试重启服务时报错 Unit docker.service not found，且 docker compose 频繁报权限拒绝（Permission Denied）。

原因分析：Ubuntu 默认通过 Snap 沙盒安装 Docker（路径为 /snap/bin/docker）。 这种安装方式与 WSL 2 的集成性较差，且传统的 systemctl 服务管理命令往往失效。

解决方案：换装官方标准版 Docker

1. 清理旧版：sudo snap remove docker

2. 一键安装标准版（自动配置路径并安装 Compose）：

   1
   

   curl -fsSL https://get.docker.com | bash -s docker --mirror Aliyun

3. 权限平权：将当前用户加入 docker 组，从此告别 sudo：

   1
   2
   

   sudo usermod -aG docker $USER
   newgrp docker

三、 突破网络屏障（核心痛点）

在 WSL 2 环境下，镜像拉取超时（net/http: request canceled）是部署失败的头号原因。

1. 开启 WSL 镜像网络模式（最佳实践）

在 Windows 用户目录下（C:\Users\用户名\）创建或修改 .wslconfig 文件：

1
2

[wsl2]
networkingMode=mirrored

该模式让 WSL 共享 Windows 的 127.0.0.1，直接解决了跨系统访问代理的问题。

2. 配置 Docker 引擎代理

创建 /etc/systemd/system/docker.service.d/http-proxy.conf，让 Docker 守护进程走你的主机代理端口（例如 7897）：

1
2
3
4
5
6
7
8

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf <<-'EOF'
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

1
2
3

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7897"
Environment="HTTPS_PROXY=http://127.0.0.1:7897"

配置后记得刷新：sudo systemctl daemon-reload && sudo systemctl restart docker

3. 配置 Dify 容器内部代理

为了让 Dify 在网页端能顺利下载 DeepSeek 等插件，需编辑 dify/docker/.env：

1

nano ~/dify/docker/.env

按 Ctrl + W 搜索 PROXY，或使用快捷键 Alt + / 快速跳至末尾

1
2
3
4
5

HTTP_PROXY=http://127.0.0.1:7897
HTTPS_PROXY=http://127.0.0.1:7897
# 注意：一定要配置 NO_PROXY 避免内部容器通信中断
NO_PROXY=localhost,127.0.0.1,api,db,redis,weaviate

四、 常用状态排查命令

部署完成后，你需要确认这些服务是否真的“活”了：

• 查看容器列表：sudo docker compose ps（确认所有 11 个服务状态均为 Up 或 healthy）。
• 查看端口占用：安装 net-tools 后使用 sudo netstat -ntpl 或现代化的 sudo ss -ntpl 确认 3000 (前端) 和 5001 (API) 端口已开启。

结语

部署 Dify 不只是跑通一个命令，更是一次对 Linux 权限管理、WSL 网络架构和 Docker 服务的深度梳理。只要解决了权限隔离和网络连通性，本地 AI 开发的大门就正式为你敞开了。

五、更多了解

1 架构图

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

┌─────────────────────────────────────────────────────────┐
│                      用户浏览器                           │
│              https://dify.tangyuxian.com               │
└────────────────────┬────────────────────────────────────┘
                     │ HTTPS
                     ↓
┌─────────────────────────────────────────────────────────┐
│                    Nginx 反向代理                         │
│  ├── 端口 443 (HTTPS)                                    │
│  ├── SSL 证书                                            │
│  └── 路由分发                                            │
└────────┬────────────────────────┬───────────────────────┘
         │                        │
         ↓                        ↓
    ┌─────────┐            ┌──────────┐
    │ Web     │            │ API      │
    │ (3000)  │            │ (5001)   │
    │ 前端界面 │            │ 后端服务  │
    └─────────┘            └────┬─────┘
                                │
                    ┌───────────┼───────────┐
                    ↓           ↓           ↓
            ┌──────────┐ ┌──────────┐ ┌──────────┐
            │PostgreSQL│ │  Redis   │ │ Weaviate │
            │  (5432)  │ │  (6379)  │ │    │
            │ 关系数据库│ │   缓存   │ │ 向量数据库│
            └──────────┘ └──────────┘ └──────────┘
                    ↑
                    │
            ┌──────────┐
            │ Worker   │
            │ 后台任务  │
            └──────────┘

2 流程

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

1. 用户问："产品有什么功能？"
   ↓
2. Web 前端 → API 服务
   ↓
3. API 调用 DeepSeek Embedding
   └── 问题 → 向量
   ↓
4. API 查询 Weaviate
   ├── 用问题向量搜索
   └── 找到最相似的 3 段内容
   ↓
5. API 组合上下文
   ├── 相关文档内容
   ├── 对话历史（从 PostgreSQL）
   └── 系统提示词
   ↓
6. API 调用 DeepSeek Chat API
   └── 基于上下文生成回答
   ↓
7. API 保存对话历史到 PostgreSQL
   ├── 用户消息
   ├── AI 回复
   └── Token 消耗
   ↓
8. 返回结果给前端
   ↓
9. 前端显示 AI 回答