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

文章目录

• • • 1. 环境准备
    • 2. 获取 Dify 源码
    • 3. 初始化环境变量文件
    • 4. 启动服务
    • 5. 首次访问与管理员初始化
    • 6. 集成 Qwen3 模型
    • 7. 常用运维操作
    • 8. 常见问题与建议
    • 8. 安装中遇到的问题
    • 附录：常用命令速查
    • 参考

这是一份基于官方文档梳理的本地部署记录，目标是用最少的步骤把 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. 常用运维操作

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 部署）