本地通过 Docker Compose 部署 Dify（社区版），并集成本地 Qwen3 大模型

Source

文章目录

这是一份基于官方文档梳理的本地部署记录，目标是用最少的步骤把 Dify 在本机跑起来，用于学习与功能体验。文中示例命令以 macOS/Linux 为主，Windows 可用 WSL2 环境配合 Docker Desktop。

1. 环境准备

基本要求（最低）：CPU ≥ 2 核、内存 ≥ 4 GiB。
macOS（推荐 Docker Desktop）：在 Docker Desktop 设置 VM 至少 2 vCPU、8 GiB 内存，否则可能启动失败。
Linux：确保 Docker ≥ 19.03，Docker Compose ≥ 1.28（或使用 Compose V2）。

建议先检查 Docker/Compose 版本：

docker --version
docker compose version  # Compose V2（推荐）
# 若为 Compose V1，则使用 `docker-compose version`

2. 获取 Dify 源码

按官方建议，克隆最新发布版本的分支：

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

进入 Docker 目录：

cd dify/docker

3. 初始化环境变量文件

复制示例环境配置为实际使用的 .env 文件：

cp .env.example .env

首次使用可以先保持默认配置；如需自定义端口、持久化卷、外部存储等，后续再改动并重启。

4. 启动服务

根据本机 Docker Compose 版本选择对应命令：

Compose V2（推荐）：

docker compose up -d

启动后，检查容器状态：

docker compose ps

正常情况下可以看到核心服务与依赖组件已就绪：

核心服务：api / worker / web
依赖组件：weaviate / db / redis / nginx / ssrf_proxy / sandbox

docker compose ps 运行状态
在这里插入图片描述

5. 首次访问与管理员初始化

首次访问需先进行管理员初始化：

注意：如果你在启动之前修改了 .env 文件中的 EXPOSE_NGINX_PORT 或者 EXPOSE_NGINX_SSL_PORT 应该根据实际情况修改 url，我这里修改了 EXPOSE_NGINX_PORT=8091 所有使用了如下 url

http://localhost:8091/install

在这里插入图片描述

6. 集成 Qwen3 模型

1）首先下载 ollama 插件(这里已经安装完成了)
在这里插入图片描述
添加 Qwen3 大模型(这里的大模型名称必须与实际模型的名称相同，不是随便定义的)

7. 常用运维操作

更新到最新版本（在 dify/docker 目录中）：

docker compose down
git pull origin main
docker compose pull
docker compose up -d

同步环境变量（重要）：

当上游示例文件 .env.example 有更新时，需比对并同步本地 .env 的新增或变更项，避免因缺失配置导致服务异常。

自定义配置并重启：

# 修改 .env 后
docker compose down
docker compose up -d

查看日志与排障：

docker compose logs -f          # 跟随查看所有服务日志
docker compose logs -f api      # 仅看 api 服务
docker compose logs -f web      # 仅看 web 服务

停止与清理：

docker compose down             # 停止并移除容器
docker compose down -v          # 同时移除卷（谨慎）

8. 常见问题与建议

资源不足导致启动失败：增大 Docker Desktop 的 vCPU/内存，参考前述建议（至少 2 vCPU、8 GiB 内存更稳妥）。
端口冲突：如本机已有 80/443/5432/6379 等占用，调整 .env 或相关服务映射端口后重启。
首次镜像拉取较慢：可切换镜像源或预先手动 docker compose pull。
服务健康检查未通过：先查看对应服务日志，再确认 .env 配置（例如数据库、向量库等环境变量）。

8. 安装中遇到的问题

1）因为我本地的 80 端口被占用，所以修改了 EXPOSE_NGINX_PORT 的默认端口
2）由于网络原因，在安装 ollama 插件的时候，无法安装成功

docker compose logs --no-log-prefix plugin_daemon | tail -n 200 | cat

输出日志

2025-08-11 15:04:22.763 ERROR [Dummy-9] [base.py:211] - Error in stream reponse for plugin {'code': -500, 'message': '{"message":"no available node, plugin not found","error_type":"PluginDaemonInternalServerError","args":null}', 'data': None}
2025-08-11 15:04:22.764 ERROR [Dummy-9] [app.py:875] - Exception on /console/api/workspaces/current/model-providers/langgenius/ollama/ollama/models [POST]
Traceback (most recent call last):
  File "/app/api/.venv/lib/python3.12/site-packages/flask/app.py", line 917, in full_dispatch_request
    rv = self.dispatch_request()
         ^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/.venv/lib/python3.12/site-packages/flask/app.py", line 902, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**view_args)  # type: ignore[no-any-return]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/.venv/lib/python3.12/site-packages/flask_restful/__init__.py", line 489, in wrapper
    resp = resource(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/.venv/lib/python3.12/site-packages/flask/views.py", line 110, in view
    return current_app.ensure_sync(self.dispatch_request)(**kwargs)  # type: ignore[no-any-return]
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/.venv/lib/python3.12/site-packages/flask_restful/__init__.py", line 604, in dispatch_request
    resp = meth(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/controllers/console/wraps.py", line 210, in decorated
    return view(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/libs/login.py", line 61, in decorated_view
    return current_app.ensure_sync(func)(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/controllers/console/wraps.py", line 31, in decorated
    return view(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/controllers/console/workspace/models.py", line 155, in post
    model_provider_service.save_model_credentials(
  File "/app/api/services/model_provider_service.py", line 237, in save_model_credentials
    provider_configuration.add_or_update_custom_model_credentials(
  File "/app/api/core/entities/provider_configuration.py", line 422, in add_or_update_custom_model_credentials
    provider_model_record, credentials = self.custom_model_credentials_validate(model_type, model, credentials)
                                         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/core/entities/provider_configuration.py", line 402, in custom_model_credentials_validate
    credentials = model_provider_factory.model_credentials_validate(
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/app/api/core/model_runtime/model_providers/model_provider_factory.py", line 191, in model_credentials_validate
    self.plugin_model_manager.validate_model_credentials(
  File "/app/api/core/plugin/impl/model.py", line 137, in validate_model_credentials
    for resp in response:
                ^^^^^^^^
  File "/app/api/core/plugin/impl/base.py", line 212, in _request_with_plugin_daemon_response_stream
    self._handle_plugin_daemon_error(error.error_type, error.message)
  File "/app/api/core/plugin/impl/base.py", line 248, in _handle_plugin_daemon_error
    raise PluginDaemonInternalServerError(description=message)
PluginDaemonInternalServerError: no available node, plugin not found

修改文件 docker-compose.override.yaml 中的 PIP_MIRROR_URL，重新部署即可。

services:
  plugin_daemon:
    image: langgenius/dify-plugin-daemon:0.2.0-local
    environment:
      PLUGIN_PYTHON_ENV_INIT_TIMEOUT: "900"
      PIP_MIRROR_URL: "https://pypi.tuna.tsinghua.edu.cn/simple"
      FORCE_VERIFYING_SIGNATURE: "false"

附录：常用命令速查

# 进入部署目录
cd dify/docker

# 首次启动
cp .env.example .env
docker compose up -d

# 查看状态与日志
docker compose ps
docker compose logs -f

# 升级
docker compose down
git pull origin main
docker compose pull
docker compose up -d

# 清理
docker compose down -v

参考

Dify 官方文档（Docker Compose 部署）