Dify本地化部署全流程指南-平芜编程栈

Dify本地化部署全流程指南

在企业级AI应用开发日益普及的今天，如何快速、安全地构建基于大语言模型（LLM）的应用成为技术团队关注的核心问题。Dify 作为一款开源的可视化 AI 应用开发平台，凭借其对 Prompt 工程、RAG 系统和 Agent 编排的全面支持，正在被越来越多组织用于搭建智能客服、知识库问答、自动化内容生成等系统。

更重要的是，Dify 支持全组件本地化部署，这意味着你可以将整个系统运行在私有服务器上，彻底掌控数据流与访问权限——这对于金融、政务、医疗等高合规要求场景尤为关键。

本文将带你从零开始，在一台 CentOS 7 服务器上完成 Dify 的完整部署。我们会覆盖 Docker 安装、镜像预加载（含离线方案）、服务启动与故障排查等关键环节，特别适配国内网络环境限制，确保即使在无法直连外网的情况下也能顺利完成部署。

系统准备：确认基础环境是否就绪

在动手之前，请先确认你的目标服务器满足以下条件：

操作系统：CentOS Linux 7（x86_64），内核版本建议不低于 3.10
内存：至少 8GB，Weaviate 向量数据库对内存较敏感
存储空间：预留 ≥20GB 可用空间，用于容器镜像和持久化数据卷
网络能力：可选择性支持公网访问；若为内网环境，则需具备离线传输文件的能力

⚠️ 提示：强烈建议在独立虚拟机或物理机中部署，避免与其他业务争抢资源。特别是 PostgreSQL 和 Weaviate 对 I/O 性能有一定要求。

如果你使用的是云主机，记得提前开放防火墙端口3000（前端入口），否则后续无法通过浏览器访问。

安装 Docker：构建容器运行时基础

Dify 采用多容器架构，依赖docker compose进行服务编排。因此第一步是安装并配置好 Docker 引擎。

清理旧版本（如有）

某些系统可能预装过旧版 Docker，存在兼容性风险，建议先卸载：

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

这条命令会清除所有已知的旧包，为新安装扫清障碍。

安装必要工具链

接下来安装一些核心依赖，它们是启用 Docker 存储驱动的基础：

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

其中device-mapper-persistent-data和lvm2是 Device Mapper 驱动所必需的模块，也是 Docker 推荐的标准配置。

添加阿里云镜像源加速下载

由于官方源在国外，直接访问经常超时。我们改用阿里云提供的镜像仓库来提升稳定性：

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

这一步注册了阿里云维护的 Docker CE 软件源，后续所有安装都将从此获取 RPM 包。

安装 Docker 社区版

现在可以正式安装运行时组件：

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

安装完成后，Docker 服务并不会自动启动，也不会设置开机自启。

启动并启用守护进程

执行以下命令激活服务：

systemctl enable docker --now

该命令等价于分两步操作：

systemctl enable docker systemctl start docker

至此，Docker 已经准备好接收指令。

验证安装状态

首先检查服务是否正常运行：

systemctl status docker

输出中应包含active (running)字样。

再运行一个测试容器验证功能完整性：

docker run --rm hello-world

如果能看到欢迎信息"Hello from Docker!"，说明环境已就绪。

获取部署资源：在线 vs 离线两种路径

Dify 的标准部署由多个微服务组成，主要包含以下几个核心组件：

组件	作用
`dify-web`	前端界面（React 构建）
`dify-api`	后端逻辑（FastAPI 实现）
`dify-sandbox`	安全执行 LLM 输出的 Python 脚本
`dify-plugin-daemon`	插件运行时守护进程
`postgres:15-alpine`	主数据库，存储用户、应用、会话等元数据
`redis:6-alpine`	缓存与任务队列（Celery + Redis）
`semitechnologies/weaviate`	向量数据库，支撑 RAG 功能
`nginx`	反向代理，统一路由入口

根据网络状况不同，推荐两种部署策略：

方案一：在线部署（适合网络通畅环境）

如果你的服务器可以直接访问 GitHub 和 Docker Hub，这是最简单的部署方式。

# 克隆项目代码 git clone https://github.com/langgenius/dify.git # 进入 Docker 配置目录 cd dify/docker # 复制默认环境变量模板 cp .env.example .env

然后一键拉起所有服务：

docker compose up -d

Docker 将自动从远程仓库拉取所需镜像，并创建数据卷、网络等基础设施。

✅优点：操作简洁，版本同步及时
❌缺点：受网络波动影响大，可能出现拉取失败或中断

方案二：离线部署（适用于内网/弱网场景）

当目标服务器处于封闭网络时，必须预先在外网机器上导出镜像包，再手动传输过去。

第一步：在外网机器导出镜像

以 v0.15.3 版本为例，依次拉取并打包所有依赖镜像：

# 拉取最新镜像 docker pull langgenius/dify-web:0.15.3 docker pull langgenius/dify-api:0.15.3 docker pull langgenius/dify-sandbox:0.2.10 docker pull langgenius/dify-plugin-daemon:0.0.2-local docker pull postgres:15-alpine docker pull redis:6-alpine docker pull semitechnologies/weaviate:1.19.0 docker pull nginx:latest docker pull ubuntu:squid # 导出为 tar 文件 docker save langgenius/dify-web:0.15.3 > langgenius_dify-web_0.15.3.tar docker save langgenius/dify-api:0.15.3 > langgenius_dify-api_0.15.3.tar docker save langgenius/dify-sandbox:0.2.10 > langgenius_dify-sandbox_0.2.10.tar docker save langgenius/dify-plugin-daemon:0.0.2-local > langgenius_dify-plugin-daemon_0.0.2-local.tar docker save postgres:15-alpine > postgres_15-alpine.tar docker save redis:6-alpine > redis_6-alpine.tar docker save semitechnologies/weaviate:1.19.0 > semitechnologies_weaviate_1.19.0.tar docker save nginx:latest > nginx_latest.tar docker save ubuntu:squid > ubuntu_squid_latest.tar

将这些.tar文件打包压缩后，通过 U盘、SCP 或内部文件共享系统传送到目标服务器。

第二步：在目标服务器加载镜像

登录到目标机器，创建专用目录存放镜像：

mkdir -p /opt/dify-images cp *.tar /opt/dify-images/ cd /opt/dify-images

批量加载所有镜像：

for image in $(ls *.tar); do echo "Loading $image..." docker load -i "$image" done

完成后可通过docker images查看是否全部导入成功。

第三步：获取并配置 Dify 源码

同样可以通过离线方式获取主程序代码：

# 若已提前打包上传 tar -xf dify-source.tar.gz -C /opt/ cd /opt/dify/docker # 或者在线克隆（仅当临时通网时） git clone https://github.com/langgenius/dify.git && cd dify/docker

初始化环境配置：

cp .env.example .env

此时可根据实际需求调整.env中的关键参数，例如：

COMPOSE_PROJECT_NAME=dify-prod POSTGRES_PASSWORD=MySecurePass123! WEAVIATE_ENABLED=true

🔧 建议修改项：
POSTGRES_PASSWORD：不要使用默认密码，防止安全隐患
API_BASE_URL：若通过域名访问，需填写正确后端地址
SANDBOX_SERVICE_MODE：生产环境建议设为remote，提高隔离性

第四步：启动服务集群

一切就绪后，启动全部容器：

docker compose up -d

首次运行会自动创建以下持久化卷：
-pg_data：PostgreSQL 数据
-redis_data：Redis 缓存
-weaviate_data：向量数据库存储

数据库结构也会在api服务启动时自动初始化。

验证部署结果：确认各服务正常运行

查看容器状态

使用如下命令检查所有服务是否处于运行中：

docker compose ps

预期输出类似：

NAME COMMAND SERVICE STATUS dify-dify-api-1 "python app.py" api running dify-dify-web-1 "nginx -g 'daemon ..." web running dify-dify-sandbox-1 "/bin/sh -c 'exec ..." sandbox running dify-postgres-1 "docker-entrypoint..." postgres running dify-redis-1 "redis-server /etc..." redis running dify-weaviate-1 "/bin/weaviate --sc..." weaviate running dify-nginx-1 "/docker-entrypoin..." nginx running

任何显示为exited或频繁重启的服务都需要立即排查。

查阅日志定位异常

比如查看 API 层的日志：

docker compose logs api

常见错误包括：

数据库连接失败：检查.env中POSTGRES_HOST,POSTGRES_DB,POSTGRES_USER是否匹配
Weaviate 初始化失败：可能是磁盘权限不足或内存不够（见下文 Q2）
Sandbox 启动超时：SELinux 或防火墙拦截可能导致通信中断

建议逐个服务查看日志，尤其是api和weaviate，这两个组件最容易因配置问题卡住。

访问平台：登录并完成初始设置

部署成功后，默认可通过以下地址访问：

前端界面：http://<your-server-ip>:3000
API 文档：http://<your-server-ip>:3000/api-docs
Weaviate 控制台（可选）：http://<your-server-ip>:8080/v1/metastore

打开浏览器访问http://<your-server-ip>:3000，你应该看到 Dify 的登录页面。

首次启动时，系统会自动生成管理员账户：

邮箱：admin@dify.ai
密码：admin

登录后请立即修改密码，并创建专属工作空间。同时建议禁用默认账号或为其更换强密码，以防未授权访问。

常见问题与实战建议

❓ Q1：执行`docker compose`报错 “command not found”

这通常是因为缺少docker-compose-plugin。请补装插件：

yum install -y docker-compose-plugin

注意命令写法差异：
- 新版：docker compose（中间是空格）
- 旧版：docker-compose（带短横线）

推荐统一使用前者，它是当前 Docker 官方主推的 CLI 格式。

❓ Q2：Weaviate 启动失败，提示 OOM 或 Segmentation Fault

Weaviate 对内存非常敏感，尤其在向量维度较高时容易触发 OOM（Out of Memory）。即便主机有 8GB 内存，也建议单独为其分配不少于 4GB。

临时缓解方案是在docker-compose.yml中添加资源限制：

services: weaviate: # ... mem_limit: 3g

但更合理的做法是：
- 升级服务器内存至 16GB 以上
- 或切换为 PGVector 方案（需修改配置关闭 Weaviate）

此外，确保/var/lib/docker所在分区有足够的磁盘空间和读写权限。

❓ Q3：网页空白或 Nginx 返回 502 Bad Gateway

这种问题多半是上游服务（web 或 api）未能正常响应。先查日志：

docker compose logs web docker compose logs api

可能原因包括：
-.env中API_BASE_URL指向错误（如用了 localhost）
-api无法连接 PostgreSQL（检查密码、端口、网络）
- 静态资源挂载失败（确认volumes映射路径正确）

有时前端构建产物缺失也会导致白屏，可尝试重建dify-web容器。

❓ Q4：如何安全升级 Dify 版本？

跨版本升级存在一定风险，务必遵循以下流程：

备份重要数据：
bash cp -r /var/lib/docker/volumes/dify-pg_data/_data /backup/pg_data_backup
拉取新版代码或镜像
替换docker/目录下的配置文件（保留原有.env）
执行docker compose down && docker compose up -d

🔄 注意：部分版本之间存在数据库 Schema 变更，请务必查阅 GitHub Release Notes 中的迁移说明。

写在最后：本地化部署的价值不止于“可控”

Dify 的本地化部署不仅仅是为了应对网络限制或满足合规要求，它更代表了一种工程理念上的转变——让 AI 应用开发回归基础设施自主权。

当你能在自己的服务器上完全掌控模型输入、数据流向和访问权限时，才真正具备构建企业级智能系统的底气。无论是对接内部知识库、集成私有模型，还是实现细粒度审计日志，本地部署都提供了无可替代的灵活性。

而通过本文介绍的这套标准化流程，即使是初次接触容器化部署的开发者，也能在几十分钟内搭建起一个稳定可用的 Dify 平台。未来你还可以进一步结合 Nginx SSL、CI/CD 自动化脚本、监控告警体系，将其打造成团队专属的 AI 开发中枢。

这才是低代码平台不该丢失的“高可控”本质。

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

Dify本地化部署全流程指南