Dify离线安装指南：从零部署AI应用平台

Li Siyuan

1397人浏览 · 2025-12-15 16:51:46

Li Siyuan · 2025-12-15 16:51:46 发布

Dify离线安装指南：从零部署AI应用平台

在企业级 AI 应用落地过程中，一个常见的挑战是：如何在无法访问公网的内网环境中部署像 Dify 这样的现代化 LLM 开发平台？金融、政务、医疗等行业对数据安全要求极高，服务器往往被严格隔离。此时，标准的在线安装方式行不通，必须依赖一套完整的离线部署流程。

Dify 作为开源的可视化大模型应用开发平台，集成了 Prompt 编排、RAG 检索增强、Agent 工作流和 API 服务能力，已成为许多团队构建智能系统的首选工具。但它的多服务架构（前端、后端、数据库、缓存、反向代理）也意味着离线部署时需要处理更多依赖项——尤其是 Docker 镜像与配置的一致性。

本文将带你一步步完成 Dify 的全链路离线部署，涵盖从联网环境准备到目标服务器启动的全过程，并提供常见问题的排查思路，确保你在无网络条件下也能顺利搭建生产可用的 AI 平台。

构建离线包：在联网环境中预下载所有依赖

要实现真正的“断网部署”，核心在于提前把所有运行时所需的组件打包成一个自包含的离线包。这个过程不能跳过任何一步，哪怕只是少导出一个镜像，都可能导致后续启动失败。

准备一台临时联网主机

选择一台用于构建离线包的云服务器或本地虚拟机，操作系统建议使用 Ubuntu 20.04 或 CentOS 7+，并确保安装以下基础工具：

Git
Docker ≥ 20.10
Docker Compose v2.23+
至少 4GB 内存、20GB 磁盘空间

验证环境是否就绪：

docker --version
docker compose version
git --version

如果尚未安装 Docker 和 Compose，可参考官方文档快速配置。注意，某些系统中 docker-compose 命令已被弃用，应使用 docker compose（带空格）的新语法。

克隆源码并拉取全部容器镜像

Dify 使用 Docker Compose 管理多个微服务，因此我们先获取项目代码并触发镜像下载：

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

打开 .env 文件，建议显式指定版本号以避免后期不一致：

TAG=0.6.10
POSTGRES_PASSWORD=your_secure_password
REDIS_PASSWORD=your_redis_password

接着执行一次启动命令，强制拉取所有依赖镜像：

docker compose up -d

虽然你并不打算长期运行这个实例，但这一步至关重要——它会自动下载 dify-api、dify-web、PostgreSQL、Redis、Nginx 等所有必需镜像。等待几分钟，直到所有容器状态为 running：

docker ps

⚠️ 小贴士：如果你只导出了部分镜像而遗漏了某个服务（比如 vector 日志收集器），即使该服务不是必选，也可能因 docker-compose.yml 中声明了对应服务而导致启动失败。要么完整导出，要么修改 compose 文件移除相关服务。

导出所有 Docker 镜像为 tar 包

列出当前已加载的 Dify 相关镜像，确认关键组件都在其中：

docker images | grep -E "(dify|postgres|redis|nginx|vector)"

你应该看到类似如下输出：

镜像名称	用途
`langgenius/dify-api:0.6.10`	后端逻辑处理
`langgenius/dify-web:0.6.10`	前端界面
`postgres:15`	数据持久化存储
`redis:7-alpine`	缓存与任务队列
`nginx:alpine`	静态资源代理
`vectordev/vector:0.27-alpine`	可选日志采集

将这些镜像统一打包成一个 .tar 文件：

docker save \
  langgenius/dify-api:0.6.10 \
  langgenius/dify-web:0.6.10 \
  postgres:15 \
  redis:7-alpine \
  nginx:alpine \
  vectordev/vector:0.27-alpine \
  -o ../images.tar

💡 如果你明确禁用了日志模块，可以省略 Vector 镜像以减小体积。否则建议保留完整集合。

打包项目文件与配置

回到上级目录，将整个 docker 子目录连同刚刚生成的镜像包一起压缩：

cd ..
tar -czf dify-offline-package.tar.gz \
  docker/.env \
  docker/docker-compose.yml \
  docker/overrides/ \
  images.tar

这样就得到了一个完整的离线部署包：dify-offline-package.tar.gz。你可以通过 U 盘、内网 FTP、scp 或其他安全传输方式将其送入目标服务器。

在目标服务器上完成离线部署

现在切换到没有互联网连接的目标机器，开始真正的部署操作。

上传并解压离线包

假设你已将包传至 /opt/ 目录下：

cd /opt
tar -xzf dify-offline-package.tar.gz

解压后结构应如下：

/opt/
├── dify-offline-package.tar.gz
├── images.tar
└── docker/
    ├── .env
    ├── docker-compose.yml
    └── overrides/

进入 docker 目录进行后续操作：

cd docker

加载预先导出的 Docker 镜像

使用 docker load 命令恢复所有镜像：

docker load -i ../images.tar

完成后检查是否成功导入：

docker images | grep -E "(dify|postgres|redis|nginx)"

确保每个服务都有对应的镜像存在，且标签（tag）与 .env 中定义的 TAG 一致。例如，若 .env 设置的是 TAG=0.6.10，但实际镜像标签是 latest，就会导致找不到镜像而启动失败。

配置环境变量文件

.env 文件已经随包一起传输，但仍需根据内网环境做适当调整。常见修改项包括：

# Web 访问端口（默认 80）
WEB_PORT=80

# 数据库存储路径（推荐挂载外部持久化目录）
PG_DATA_DIR=/data/dify/postgres

# Redis 密码（必须与 compose 文件中保持一致）
REDIS_PASSWORD=ChangeThisToAStrongPassword!

# API 监听地址
API_HOST=0.0.0.0
API_PORT=5001

# 明确指定版本标签
TAG=0.6.10

特别提醒：务必确保 PG_DATA_DIR 所指向的路径存在且具有写权限。PostgreSQL 容器默认以 UID 999 用户运行，因此建议提前创建并授权：

mkdir -p /data/dify/postgres
chown -R 999:999 /data/dify/postgres

否则可能出现 “Permission denied” 错误导致数据库无法初始化。

启动服务并验证状态

一切就绪后，启动所有服务：

docker compose up -d

查看各容器运行状态：

docker compose ps

正常情况下你会看到：

NAME                   SERVICE             STATUS              PORTS
dify-api-1           api                 running             5001/tcp
dify-web-1           web                 running             3000/tcp
dify-redis-1         redis               running             6379/tcp
dify-postgres-1      postgres            running             5432/tcp
dify-nginx-1         nginx               running             0.0.0.0:80->80/tcp

如果某些容器显示 Restarting 或 Exited，说明存在问题，需进一步排查。

常见问题诊断与解决方案

即便准备充分，离线部署仍可能遇到各种意料之外的问题。以下是我们在实际交付中总结出的高频故障及应对策略。

页面空白或静态资源加载失败

现象：浏览器打开 IP 地址后页面白屏，F12 控制台报错如 Failed to load /index.html 或 404 Not Found。

原因分析：
- Nginx 未正确代理 / 路径到前端资源
- dify-web 容器未成功启动
- 浏览器缓存了旧版本资源

解决步骤：

首先查看 web 服务日志：

docker compose logs web

若发现编译错误或资源缺失，尝试重建容器：

docker compose down web
docker compose up -d web

同时清除浏览器缓存或使用隐身模式访问。若问题依旧，检查 docker-compose.yml 中 nginx 是否正确挂载了 web 容器的静态目录。

数据库连接失败（Connection refused）

典型错误信息：

psycopg2.OperationalError: could not connect to server: Connection refused

这通常发生在 API 服务尝试连接 PostgreSQL 时。

排查流程：

检查数据库容器是否运行：

bash docker compose ps postgres

查看其日志输出：

bash docker compose logs postgres

若出现 could not access directory "/var/lib/postgresql/data"，说明数据目录权限不足。

修复权限（假设你映射到了 /data/dify/postgres）：

bash chown -R 999:999 /data/dify/postgres

bash rm -rf /data/dify/postgres/*

因为 Postgres 第一次启动会在数据目录初始化结构，已有内容可能导致冲突。

Redis 认证失败（NOAUTH Authentication required）

错误提示：

NOAUTH Authentication required.

这是典型的密码不匹配问题。

根本原因：.env 文件中的 REDIS_PASSWORD 与 Redis 实际设置的密码不一致。

修复方法：

确保 .env 中设置了正确的密码。
若不确定当前 Redis 密码，可进入容器重置：

```bash
docker exec -it dify-redis-1 redis-cli

CONFIG SET requirepass “your_new_password”
AUTH default your_new_password
```

然后更新 .env 文件中的 REDIS_PASSWORD，并重启服务：

bash docker compose down && docker compose up -d

容器反复重启（Restarting）

表现为 docker compose ps 输出中某容器持续处于 Restarting 状态。

通用排查命令：

# 查看具体哪个服务异常
docker compose ps

# 查看日志定位根本错误
docker compose logs api     # 或 web, postgres, redis

常见诱因包括：

端口占用：80（Nginx）、5432（PostgreSQL）、6379（Redis）被其他进程占用。可通过 netstat -tuln | grep <port> 检查。
磁盘空间不足：特别是数据库写入大量日志时。运行 df -h 查看剩余空间。
配置文件语法错误：如 .env 中含有非法字符或换行符。
镜像版本不匹配：.env 中 TAG=0.6.10，但实际镜像不存在该标签。