Dify 运维手册：从 Docker 部署到数据迁移的实践指南

本文将详细介绍如何使用 Docker 和 Docker Compose 来部署、更新、迁移开源 LLM 应用开发平台 Dify (v0.6.14)。内容涵盖从快速部署到数据备份，再到从源码构建镜像等高级操作，旨在为开发者和运维人员提供一份清晰实用的操作指南。

使用 Docker Compose 快速部署 Dify

对于大多数用户而言，使用官方提供的 Docker Compose 文件是部署 Dify 最快捷、最推荐的方式。

步骤 1：获取 Dify 部署文件

首先，从 Dify 的官方仓库获取 docker 部署目录。

步骤 2：配置环境变量

Dify 的所有配置都通过环境变量进行管理。部署前，需要将配置模板文件 .env.example 复制为 .env 文件，然后根据实际需求修改。

# 进入 docker 部署目录
cd dify/docker
# 复制环境变量配置文件
cp .env.example .env

之后，可以使用文本编辑器打开 .env 文件，根据其中的注释修改数据库密码、SECRET_KEY 等关键配置。

步骤 3：启动服务

完成配置后，执行以下命令即可在后台启动 Dify 的所有服务。

docker-compose up -d

该命令会自动拉取所需的 Docker 镜像并按顺序启动所有容器。

更新 Dify 服务

当 Dify 发布新版本时，可以按照以下步骤进行安全更新。

1. 停止并移除旧版容器:

   cd dify/docker
   docker-compose down
   

2. 备份数据 (重要):
   在进行任何更新操作前，强烈建议备份 docker 目录，特别是其中的 volumes 子目录。这是保证数据安全的关键。
3. 获取新版文件:
   下载或拉取最新版本的 Dify 源码，用新的 docker 目录替换旧的。
4. 导入新版镜像:
   如果是在离线环境，需要提前将新版镜像文件导入。
5. 更新配置文件:
   对比新旧 .env 文件，将自定义的配置迁移到新的 .env 文件中。
6. 启动新版服务:

   docker-compose up -d
   

数据迁移与备份

数据迁移是运维中的常见需求。Dify 使用两种方式进行数据持久化：本地目录映射和 Docker 命名数据卷，因此它们的迁移方法也不同。

迁移映射到本地的卷目录

Dify 的 docker-compose.yaml 文件中，部分服务通过“本地目录映射”来持久化数据。这意味着容器的某个目录直接对应宿主机上的 ./volumes 目录。

这种方式的迁移非常直接，本质上就是文件拷贝。

1. 停止 Dify 服务
   在操作文件前，必须停止所有容器，防止数据写入冲突。

   docker-compose down
   

2. 打包卷目录
   将 volumes 目录打包成一个压缩文件。

   tar -czvf dify-volumes.tar.gz ./volumes
   

3. 在新服务器上解压
   将压缩包传输到新服务器的目标位置后，解压缩即可。

   tar -xzvf dify-volumes.tar.gz
   

迁移 Docker 命名数据卷

对于 PostgreSQL 等关键服务，Dify 采用了 Docker 的“命名数据卷”进行数据持久化。这种卷由 Docker 统一管理，其物理文件存储在 /var/lib/docker/volumes/ 目录下，直接拷贝相对繁琐且可能存在权限问题。

以 oradata 和 dify_es01_data 这两个数据卷为例，以下是推荐的迁移方法。

说明: 如果部署时使用了 docker-compose -p dify 指定项目名，Docker 会自动为卷名称加上前缀，例如 dify_oradata。

方法 1：使用临时容器进行备份与恢复 (推荐)

这种方法无需 root 权限，也无需关心卷在宿主机上的具体物理路径，是安全和标准化的做法。

1. 备份数据卷
   创建一个临时的 alpine 容器，同时挂载需要备份的数据卷和本地的一个备份目录，然后在容器内执行打包命令。

   # 确保当前目录下有 backup 子目录
   mkdir -p backup
   # 备份 oradata 数据卷
   docker run --rm -v oradata:/source -v $(pwd)/backup:/backup alpine sh -c "cd /source && tar czf /backup/oradata.tar.gz ."
   # 备份 dify_es01_data 数据卷
   docker run --rm -v dify_es01_data:/source -v $(pwd)/backup:/backup alpine sh -c "cd /source && tar czf /backup/es_data.tar.gz ."
   

2. 传输备份文件
   将 backup 目录下的 oradata.tar.gz 和 es_data.tar.gz 文件传输到新服务器。
3. 在新服务器上恢复数据
   首先在新服务器上创建同名的数据卷，然后用类似的方法将数据恢复进去。

   # 在新服务器上创建空的命名数据卷
   docker volume create oradata
   docker volume create dify_es01_data
   # 从备份文件恢复数据到 oradata 卷
   docker run --rm -v oradata:/target -v /path/to/backup:/backup alpine sh -c "cd /target && tar xzf /backup/oradata.tar.gz"
   # 从备份文件恢复数据到 dify_es01_data 卷
   docker run --rm -v dify_es01_data:/target -v /path/to/backup:/backup alpine sh -c "cd /target && tar xzf /backup/es_data.tar.gz"
   

方法 2：直接操作宿主机卷目录 (需要 root 权限)

如果拥有服务器的 root 权限，也可以直接备份卷的物理目录。

1. 查找卷的物理路径

   docker volume inspect oradata dify_es01_data
   

   该命令会输出卷的 Mountpoint，即物理存储路径。

2. 直接打包

   # 获取路径并打包
   ORADATA_PATH=$(docker volume inspect -f '{{.Mountpoint}}' oradata)
   ES_DATA_PATH=$(docker volume inspect -f '{{.Mountpoint}}' dify_es01_data)
   sudo tar -czf oradata_backup.tar.gz -C $ORADATA_PATH .
   sudo tar -czf es_data_backup.tar.gz -C $ES_DATA_PATH .
   

高级操作：从源码构建与管理镜像

在需要二次开发、应用安全补丁或离线部署等场景下，需要从源码手动构建 Dify 的 Docker 镜像。

构建 API 和 Web 镜像

Dify 的核心服务分为 api 和 web 两部分，需要分别构建。

1. 构建 API 镜像 (dify/dify-api)

   cd api && docker build . -t dify/dify-api:0.6.14
   

2. 构建 Web 镜像 (dify/dify-web)

   cd web && docker build . -t dify/dify-web:0.6.14
   

导出与导入镜像 (用于离线环境)

构建或拉取镜像后，可将其导出为 .tar 文件，以便在无法访问外部网络的服务器上导入使用。

1. 导出镜像
   使用 docker save 命令将一个或多个镜像打包。

   # 导出 Dify 核心镜像
   docker save -o dify_dify_api_0.6.14.tar dify/dify-api:0.6.14
   docker save -o dify_dify_web_0.6.14.tar dify/dify-web:0.6.14
   # 导出其它依赖镜像
   docker save -o postgres_15_alpine.tar postgres:15-alpine
   docker save -o redis_6_alpine.tar redis:6-alpine
   

2. 导入镜像
   在新服务器上，使用 docker load 命令从 .tar 文件中加载镜像。

   docker load -i dify_dify_api_0.6.14.tar
   docker load -i dify_dify_web_0.6.14.tar
   docker load -i postgres_15_alpine.tar
   docker load -i redis_6_alpine.tar
   

核心概念解析

理解以下几个关键概念有助于更好地维护和使用 Dify。

docker 与 docker-legacy 目录

在 Dify 源码中存在两个部署目录。docker-legacy 是旧版的部署方式，而 docker 目录是当前推荐的、结构更清晰的部署方案。新用户应始终选择使用 docker 目录。

SECRET_KEY 的作用

在 dify-api 服务的 .env 配置文件中，SECRET_KEY 是一个至关重要的安全配置。它是一个长随机字符串，用于加密和签发用户的会话 cookie，防止会话被篡改。请务必将其设置为一个无人能猜到的复杂值。

构建时忽略 storage 目录

Dify 的 Dockerfile 在构建镜像时，会通过 .dockerignore 文件明确忽略 storage 目录。这是因为 storage 目录用于存放租户上传的文件、密钥对等敏感或隐私信息，这些信息不应该被打包进通用的 Docker 镜像中，而应通过数据卷在运行时动态挂载。

解析 docker run --rm 备份命令

在数据迁移部分推荐的备份命令模板，其各个参数的含义如下：

docker run --rm -v <volume_to_backup>:/source -v <host_backup_dir>:/backup <image> sh -c "<commands>"