Dify的备份还原

1. 备份范围清单

数据类型	存储位置	备份必要性	说明
PostgreSQL（业务库）	Docker 卷 `dify_db_data`	★★★ 必须	账号、应用、Prompt、知识库元数据
Weaviate（向量库）	Docker 卷 `dify_weaviate_data`	★★★ 必须	知识库分段向量
Redis（缓存 + 异步任务）	Docker 卷 `dify_redis_data`	★☆☆ 可选	可冷启动重建，仅排队任务丢失
上传文件（文本/图片/音频）	Docker 卷 `dify_storage_data`	★★★ 必须	知识库原始文件、对话上传
环境变量（.env）	宿主机 `docker/.env`	★★☆ 建议	含密钥、模型地址，泄露风险
nginx/ssl 证书	宿主机自定义路径	★★☆ 建议	生产环境开启 HTTPS 时

本文默认采用 官方 Docker Compose 卷名称，如自定义过 COMPOSE_PROJECT_NAME，请将 dify_ 前缀替换为实际前缀。

2. 零依赖一键备份脚本

保存为 dify-backup.sh，chmod +x dify-backup.sh 即可用。

#!/usr/bin/env bash
set -euo pipefail

############################ 用户可改区域 ############################
BACKUP_ROOT="/data/backup/dify"        # 备份落盘目录
RETENTION_DAYS=7                       # 保留天数
COMPOSE_PROJECT_NAME="dify"            # 与 .env 里保持一致
DOCKER_COMPOSE_FILE="docker-compose.yaml"
#####################################################################

DATE=$(date +%F_%H-%M-%S)
DEST="${BACKUP_ROOT}/${DATE}"
mkdir -p "${DEST}"

echo "========== 1. 备份 PostgreSQL =========="
docker compose -f "${DOCKER_COMPOSE_FILE}" exec -T db \
  pg_dump -U postgres -d dify -F c -b -v \
  > "${DEST}/dify.pgdump"

echo "========== 2. 备份 Weaviate =========="
# Weaviate 官方 CLI 备份（在线热备）
docker compose -f "${DOCKER_COMPOSE_FILE}" exec -T weaviate \
  weaviate-backup create \
  --backend=filesystem --backup_id="bk_${DATE}" \
  --include="*" --wait
# 把备份 tarball 拷出
docker compose -f "${DOCKER_COMPOSE_FILE}" exec -T weaviate \
  tar -C /var/lib/weaviate/backups -czf - "bk_${DATE}" \
  > "${DEST}/weaviate_bk_${DATE}.tar.gz"

echo "========== 3. 备份 Storage 卷 =========="
docker run --rm -v "${COMPOSE_PROJECT_NAME}_storage_data:/data" -v "${DEST}:/backup" \
  alpine tar -C /data -czf /backup/storage.tar.gz .

echo "========== 4. 备份 Redis =========="
docker run --rm -v "${COMPOSE_PROJECT_NAME}_redis_data:/data" -v "${DEST}:/backup" \
  alpine tar -C /data -czf /backup/redis.tar.gz .

echo "========== 5. 备份环境变量 =========="
cp .env "${DEST}/env.bak"

echo "========== 6. 打包总归档 =========="
cd "${BACKUP_ROOT}"
tar -cf "${DATE}.tar" "${DATE}" && rm -rf "${DATE}"
echo "备份完成：${BACKUP_ROOT}/${DATE}.tar"

# 清理旧备份
find "${BACKUP_ROOT}" -name "*.tar" -mtime +${RETENTION_DAYS} -delete

执行示例

1
2
3

./dify-backup.sh
# 输出
备份完成：/data/backup/dify/2025-06-25_03-15-22.tar

3. 裸机还原（同版本 Dify）

假设新机器已安装好同版本 Dify（空数据），归档文件为 2025-06-25_03-15-22.tar。

3.1 停业务并清空空卷

cd dify/docker
docker compose down
# 可选：删除空卷（危险！确认无数据）
docker volume rm dify_db_data dify_weaviate_data dify_storage_data dify_redis_data

3.2 解压归档

1
2
3

cd /data/backup/dify
tar -xf 2025-06-25_03-15-22.tar
cd 2025-06-25_03-15-22

3.3 还原 PostgreSQL

# 先启动空数据库
docker compose up -d db
sleep 10   # 等待 ready
# 还原
docker compose exec -T db createdb -U postgres dify
docker compose exec -T db pg_restore -U postgres -d dify -v < dify.pgdump

3.4 还原 Weaviate

# 把备份拷进容器
docker compose exec -T weaviate mkdir -p /var/lib/weaviate/backups/bk_restore
tar -C /tmp -xzf weaviate_bk_*.tar.gz
docker cp /tmp/bk_* weaviate:/var/lib/weaviate/backups/bk_restore
# 执行还原
docker compose exec weaviate weaviate-backup restore \
  --backend=filesystem --backup_id=bk_restore --wait

3.5 还原 Storage & Redis

# Storage
docker run --rm -v dify_storage_data:/data -v $(pwd):/backup \
  alpine tar -C /data -xzf /backup/storage.tar.gz
# Redis
docker run --rm -v dify_redis_data:/data -v $(pwd):/backup \
  alpine tar -C /data -xzf /backup/redis.tar.gz

3.6 还原环境变量

1	cp env.bak .env

3.7 拉起全栈

1	docker compose up -d

浏览器访问，确认数据完整。

4. 跨版本升级式还原（≥1 个大版本）

先按第 3 步还原到老版本

依次执行官方 migration 脚本

1	docker compose exec api flask db upgrade

再升级镜像到目标版本

1
2
3

git pull
docker compose pull
docker compose up -d

观察日志无报错后再继续

5. 单卷级冷备份（极简方案）

如果集群已用外部高可用数据库/向量库，仅需备份上传文件：

1 2	docker run --rm -v dify_storage_data:/data -v /backup:/backup \ alpine tar -C /data -czf /backup/dify-storage-$(date +%F).tar.gz .

还原：

1 2	docker run --rm -v dify_storage_data:/data -v /backup:/backup \ alpine tar -C /data -xzf /backup/dify-storage-xxx.tar.gz

6. 自动化建议

把 dify-backup.sh 放到 systemd timer 或 crontab：
0 2 * * * /opt/scripts/dify-backup.sh >/var/log/dify-backup.log 2>&1
备份落盘后再 rclone sync 到对象存储（S3/OSS/COS）
每月做一次 灾备演练，确保备份包可完整还原。

7. 常见问题

错误	原因	解决
`pg_restore: error: could not execute query: ERROR: relation "xxx" already exists`	未清空目标库	先 `dropdb` 再 `createdb`
Weaviate 还原后知识库搜不到	backup_id 未包含全部 class	确保 `--include="*"`
文件上传报 404	storage 卷未还原	检查 `dify_storage_data` 是否挂载正确

8. 一句话总结

“只要 PostgreSQL + Weaviate + Storage 三卷在，Dify 就可以原地复活。”
定期冷备 + 异地存，是生产落地最低成本方案。

The End