Dify本地化部署指南：Docker与镜像安装-开发者社区

Dify本地化部署指南：Docker与镜像安装

在AI应用开发日益普及的今天，如何快速、稳定地构建可落地的智能系统，成为开发者和企业面临的关键挑战。传统的LLM集成方式往往需要大量编码、调试与运维工作，而Dify的出现改变了这一局面——它是一个开源的可视化 AI Agent 与应用开发平台，将复杂的模型调用、提示工程、知识检索（RAG）和智能体编排整合进一个直观的图形界面中。

通过 Dify，你无需从零搭建后端服务或手动管理向量数据库，就能快速创建智能客服、内容生成器、知识库问答机器人等实用工具。更重要的是，它的微服务架构天然适配 Docker 部署，使得本地化安装变得简单可控，尤其适合对数据安全有要求的企业环境。

本文将带你一步步完成 Dify 在 CentOS 7 系统上的完整本地部署，涵盖Docker 安装、离线镜像导入、服务配置启动及常见问题排查，确保即使在网络受限的生产环境中也能顺利运行。

环境准备：安装 Docker Engine

Dify 由多个独立服务组成，包括 API 接口、前端界面、数据库、缓存、向量库等，使用 Docker + Docker Compose 是最推荐的部署方式。以下以CentOS 7为例进行说明。

⚠️ 注意事项：
- 系统架构需为 x86_64
- 内核版本建议 ≥ 3.10（可通过uname -r查看）
- 若为最小化安装系统，请提前启用网络连接并更新基础包

卸载旧版 Docker（如有）

部分系统可能预装了旧版本 Docker，容易引发冲突：

yum remove -y docker \ docker-client \ docker-client-latest \ docker-common \ docker-latest \ docker-latest-logrotate \ docker-logrotate \ docker-engine

安装必要依赖

yum install -y yum-utils device-mapper-persistent-data lvm2

其中yum-utils提供了yum-config-manager工具，用于添加远程仓库；device-mapper-persistent-data和lvm2支持 Docker 使用 devicemapper 存储驱动。

添加国内镜像源（推荐阿里云）

避免因官方源在国外导致下载缓慢：

yum-config-manager --add-repo http://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo

这一步会自动注册阿里云维护的 Docker CE 软件源，大幅提升后续安装速度。

安装 Docker 社区版

yum install -y docker-ce docker-ce-cli containerd.io

若遇到 GPG 密钥验证失败：

yum install -y --nogpgcheck docker-ce docker-ce-cli containerd.io

✅ 仅在确认源可信时使用--nogpgcheck，不建议长期关闭签名检查。

启动并设置开机自启

systemctl enable docker --now

该命令同时启用并立即启动 Docker 服务。

验证安装结果

首先查看服务状态：

systemctl status docker

正常情况下应显示active (running)。

再运行测试容器验证运行时是否正常：

docker run hello-world

如果输出欢迎信息，说明 Docker 已正确安装并可用。

获取 Dify 项目文件

Dify 的部署依赖两个核心文件：docker-compose.yml和.env。它们定义了所有服务的容器配置与环境变量。

根据网络条件不同，有两种获取方式：

方式一：在线克隆（适用于可访问 GitHub 的环境）

git clone https://github.com/langgenius/dify.git cd dify/docker cp .env.example .env

这是最直接的方式，适合开发测试或具备公网访问权限的服务器。

方式二：离线导入（适用于内网/隔离环境）

对于无法联网的生产服务器，建议采用“外网打包 → 内网加载”的流程。

核心服务镜像列表

服务名称	镜像名	功能说明
PostgreSQL	`postgres:15-alpine`	存储用户、应用、对话记录等元数据
Redis	`redis:6-alpine`	缓存会话、任务队列
Weaviate	`semitechnologies/weaviate:1.19.0`	向量数据库，支撑 RAG 检索
Dify-API	`langgenius/dify-api:0.15.3`	提供 RESTful 接口
Dify-Web	`langgenius/dify-web:0.15.3`	前端控制台
Sandbox	`langgenius/dify-sandbox:0.2.10`	安全执行 LLM 脚本
Plugin Daemon	`langgenius/dify-plugin-daemon:0.0.2-local`	插件运行时守护进程
Nginx	`nginx:latest`	反向代理与静态资源服务
Squid	`ubuntu/squid:latest`	可选 HTTP 缓存代理

在外部机器上导出镜像

假设已在一台能上网的机器上拉取了上述镜像：

# 将所有镜像保存为 tar 包 docker save -o postgres.tar postgres:15-alpine docker save -o redis.tar redis:6-alpine docker save -o weaviate.tar semitechnologies/weaviate:1.19.0 docker save -o dify-api.tar langgenius/dify-api:0.15.3 docker save -o dify-web.tar langgenius/dify-web:0.15.3 docker save -o sandbox.tar langgenius/dify-sandbox:0.2.10 docker save -o plugin-daemon.tar langgenius/dify-plugin-daemon:0.0.2-local docker save -o nginx.tar nginx:latest # squid 可选

然后将这些.tar文件拷贝至目标主机（如通过U盘、SCP等方式）。

批量加载离线镜像

进入存放镜像的目录，执行批量加载脚本：

for image in ./docker-images/*.tar; do echo "Loading $image..." docker load -i "$image" done

完成后可通过docker images | grep langgenius快速确认关键镜像是否已导入。

解压 Dify 主程序

将提前下载好的dify.tar.gz解压并复制配置文件：

tar -xf dify.tar.gz cd dify/docker cp .env.example .env

🔐 安全提醒：.env文件包含数据库密码、密钥等敏感信息，部署后请限制文件读取权限（如chmod 600 .env），避免泄露。

配置与启动 Dify 服务

修改`.env`环境变量（按需调整）

虽然默认配置即可运行，但建议根据实际需求修改以下参数：

# 管理员账户 ADMIN_EMAIL=admin@company.com ADMIN_PASSWORD=StrongPass123! # 主机监听端口（避免与现有服务冲突） HOST_PORT=80 # 数据库密码（必须与 postgres 容器一致） POSTGRES_PASSWORD=MyPostgresSecret123 # 是否启用 HTTPS（通常由反向代理处理） ENABLE_HTTPS=false # 前端访问地址（影响 Cookie 和跨域策略） CONSOLE_URL=http://localhost NEXT_PUBLIC_API_BASE=http://localhost/api

💡 生产建议：
- 更改默认管理员邮箱和强密码
- 如需外网访问，将CONSOLE_URL改为实际域名
- 若配合 Nginx 或 Traefik 做 SSL 终止，此处仍可保留 HTTP

启动服务集群

确保当前目录下存在docker-compose.yml和.env后，执行：

docker compose up -d

该命令会在后台启动所有服务容器。首次运行会触发数据库初始化和表结构创建，耗时约 1~2 分钟。

查看服务状态

docker compose ps

预期输出示例：

NAME SERVICE STATUS PORTS dify-api-1 api running 5001/tcp dify-web-1 web running 0.0.0.0:80->80/tcp dify-db-1 db running 5432/tcp dify-redis-1 redis running 6379/tcp dify-weaviate-1 vector-db running 8080/tcp ...

若发现某个容器处于exited或反复重启状态，可通过日志定位问题：

docker logs dify-api-1

也可以动态跟踪日志流：

docker logs -f dify-api-1

访问 Dify 平台

当所有服务状态均为running后，打开浏览器访问：

👉 http://localhost 或 http://<你的服务器IP>

首次访问时，Dify 会自动完成数据库迁移和初始用户创建。稍等片刻后跳转至登录页面。

使用你在.env中设置的ADMIN_EMAIL和ADMIN_PASSWORD登录，即可进入主界面，开始构建你的第一个 AI 应用。

常见问题排查与解决方案

❌ 问题1：`docker compose`命令不存在

现象：执行docker compose报错 “command not found”

原因：Docker Compose V2 虽然已集成到 CLI，但部分系统未自动安装插件。

解决方法：

手动安装docker-compose插件：

mkdir -p /usr/libexec/docker/cli-plugins curl -SL https://github.com/docker/compose/releases/latest/download/docker-compose-linux-x86_64 \ -o /usr/libexec/docker/cli-plugins/docker-compose chmod +x /usr/libexec/docker/cli-plugins/docker-compose

验证是否成功：

docker compose version

✅ 成功后应返回类似Docker Compose version v2.23.0的信息。

❌ 问题2：Weaviate 启动失败，提示`permission denied`

典型错误日志：

mkdir: permission denied for '/var/lib/weaviate'

根本原因：Weaviate 容器以非 root 用户（UID 1000）运行，宿主机挂载目录权限不足。

修复步骤：

mkdir -p volumes/weaviate chown 1000:1000 volumes/weaviate # 或简化操作： chmod 777 volumes/weaviate

然后重启服务：

docker compose down && docker compose up -d

❌ 问题3：前端白屏或资源加载失败

表现：页面空白、JS/CSS 加载报 404、控制台报错Failed to fetch

排查方向：

检查dify-web日志是否有构建或路由错误：

bash docker logs dify-web-1

确认.env中的 URL 配置正确：

env CONSOLE_URL=http://localhost NEXT_PUBLIC_API_BASE=http://localhost/api

若通过域名访问，请替换为实际地址（如https://dify.company.com）。

清除浏览器缓存或使用无痕模式重试。
检查 Nginx 容器是否正常运行：

bash docker compose ps nginx

❌ 问题4：API 无法连接数据库

典型日志：

psql: FATAL: password authentication failed for user "postgres"

或：

connection refused

解决思路：

确保.env中POSTGRES_PASSWORD与docker-compose.yml中定义的一致
检查dify-db-1是否正在运行且无异常退出：

bash docker logs dify-db-1

初次启动时数据库需时间初始化（尤其是首次创建 volume），等待 1~2 分钟观察 API 是否自动重连成功
若怀疑密码错误，可临时修改.env并重建服务：

bash docker compose down docker compose up -d

后续运维建议

1. 定期备份关键数据卷

以下目录存储着核心业务数据，务必定期备份：

volumes/postgres：用户账号、应用配置、对话历史
volumes/weaviate：向量化知识库内容
volumes/uploads：上传的文档、图片等资源文件

可编写定时脚本压缩打包并异地存储：

tar -czf backup_dify_$(date +%Y%m%d).tar.gz volumes/postgres volumes/weaviate volumes/uploads

2. 版本升级流程

当新版本发布时，可通过以下步骤平滑升级：

# 停止当前服务 docker compose down # 更新代码（在线环境） git pull origin main cd docker # 加载新版镜像（离线环境） docker load -i dify-api-v0.16.0.tar docker load -i dify-web-v0.16.0.tar # 启动新版本 docker compose up -d

⚠️ 升级前务必查阅 Release Notes，关注数据库迁移脚本兼容性，必要时先在测试环境验证。

3. 集成外部大模型

Dify 支持多种主流 LLM 接入，可在 Web 控制台 →Model Provider中配置：

OpenAI GPT-3.5 / GPT-4
Anthropic Claude 系列
百度文心一言
阿里通义千问
讯飞星火
自建 Ollama、vLLM、TGI 等私有部署模型

只需填写对应 API Key 和 Endpoint 地址，即可在 Prompt 编辑器中自由切换模型进行测试。

这种灵活性让企业既能利用公有云的强大能力，也可逐步过渡到私有模型，实现成本与安全的平衡。

Dify 的价值不仅在于其强大的功能集成，更体现在它对开发者体验的深度优化。通过可视化的流程设计、模块化的组件拼接以及开箱即用的部署方案，它真正实现了“低代码构建高智能应用”的愿景。

无论你是想快速验证一个 AI 创意，还是为企业搭建稳定的智能化服务平台，Dify 都是一个值得信赖的选择。结合 Docker 的容器化部署能力，即使是复杂的多服务架构，也能在几分钟内完成本地落地。

现在就动手部署属于你的 Dify 实例，开启高效构建 AI Agent 的新篇章吧！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

Dify本地化部署指南：Docker与镜像安装