Dify 升级到最新版本操作指南

发表于 | 分类于 | | 浏览 次
字数统计: 2.2k | 阅读时长 ≈ 9

本文将手把手教你如何在生产环境中安全升级 Dify，包含备份、迁移、排错、回滚等全流程技巧，避免因权限和数据库等问题踩坑。建议优先使用 Docker Compose 部署方案，稳定可靠。

方案一：Docker Compose 部署（推荐）

第一步：停止服务并备份

1
2
3
4
5
6
7
8
9
10
11
# 进入 docker 目录
cd docker

# 停止所有服务
docker compose down

# 备份 docker-compose 配置文件（可选）
cp docker-compose.yaml docker-compose.yaml.$(date +%s).bak

# 备份数据卷（重要！）
tar -cvf volumes-backup-$(date +%s).tgz volumes

备份检查清单：

  • 数据库数据
  • 应用存储文件
  • 环境配置文件
  • 自定义配置

第二步：拉取最新代码

1
2
3
4
5
6
7
# 返回项目根目录
cd ..

# 获取最新代码
git fetch origin
git checkout main
git pull origin main

如果出现本地文件与远程文件冲突的提示，建议先备份本地修改，然后再强制覆盖为最新远程版本：

1
2
3
4
5
6
7
8
# 备份有改动的本地文件或目录（例如 docker-compose.yaml）
cp docker-compose.yaml docker-compose.yaml.bak

# 丢弃本地改动，强制还原成线上（远程）最新内容
git checkout -- docker-compose.yaml

# 拉取最新代码
git pull origin main

如涉及较多冲突，可多次执行上述步骤，确保所有冲突文件都已按需处理。

第三步：更新存储目录权限（关键步骤）

将storage目录设置成非root权限

1
2
3
4
5
6
7
# 更新目录所有权为 UID 1001
sudo chown -R 1001:1001 ./docker/volumes/app/storage

# 或

# 更新目录所有权为 www:www
sudo chown -R www:www ./docker/volumes/app/storage

验证权限设置：

1
2
# 验证权限设置
ls -ln ./docker/volumes/app/storage

预期输出：

1
drwxr-xr-x 2 1001 1001 4096 Dec 08 10:00 storage

权限说明：

  • 1001:1001 不是”权限”，而是用户ID(UID)和组ID(GID)
  • 即使系统中不存在名为 1001 的用户，这个命令也是有效的
  • Docker 容器内的进程以 UID 1001 运行，需要匹配主机权限

第四步：更新环境配置

1
2
3
4
cd docker

# 编辑环境变量文件
vim .env  # 或使用其他编辑器

重要配置项：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 如果要使用 MySQL（可选）
DB_TYPE=mysql  # 默认为 postgresql

# MySQL 连接配置（如果使用 MySQL）
DB_USERNAME=your_mysql_user
DB_PASSWORD=your_mysql_password
DB_HOST=your_mysql_host
DB_PORT=3306
DB_DATABASE=dify

# 插件市场访问（确保网络可达）
# 确保可以访问 https://marketplace.dify.ai

# 数据库迁移（默认启用）
MIGRATION_ENABLED=true

配置对比：

1
对比 .env.example 文件，检查是否有新增的环境变量需要配置。

第五步：启动服务

1
2
3
4
5
# 标准启动
docker compose up -d

# 如果遇到数据库连接问题，使用 PostgreSQL profile
docker compose --profile postgresql up -d

常见启动问题：

如果看到类似错误：

1
2
failed to connect to `host=db_postgres user=postgres database=dify_plugin`: 
hostname resolving error (lookup db_postgres on 127.0.0.11:53: server misbehaving)

解决方案：

1
docker compose --profile postgresql up -d

第六步：验证升级

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 查看服务状态
docker compose ps

# 2. 查看日志
docker compose logs -f

# 3. 检查特定服务日志
docker compose logs api
docker compose logs worker
docker compose logs web

# 4. 检查权限相关错误
docker compose logs api | grep -i permission
docker compose logs worker | grep -i permission

健康检查：

  • 所有容器状态为 Up
  • 没有 Permission Denied 错误
  • API 服务正常响应
  • Web 界面可以访问

第七步：功能验证

  1. 访问 Web 界面

  2. 验证应用运行

    • 测试已有应用是否正常工作
    • 检查知识库是否可以访问
    • 尝试创建新的对话

  3. 插件系统验证

    • 点击右上角 “Plugins” 按钮
    • 验证插件是否正确安装
    • 检查内置工具是否已迁移到插件

方案二：源码部署

未经过实践尝试

第一步：停止服务

1
2
3
4
5
6
7
8
# 停止 API 服务器
pkill -f "flask run" # 或使用你的进程管理器

# 停止 Worker
pkill -f "celery worker"

# 停止 Web 前端
pkill -f "next"

第二步：更新代码

1
2
3
4
# 拉取最新代码
git fetch origin
git checkout main
git pull origin main

第三步：更新依赖

1
2
3
4
5
6
7
8
# 进入 API 目录
cd api

# 使用 uv 同步依赖
uv sync

# 或使用 pip（如果没有 uv）
pip install -r requirements.txt

第四步：数据库迁移

1
2
3
4
5
# 运行迁移脚本
uv run flask db upgrade

# 或使用标准 Flask 命令
flask db upgrade

迁移注意事项：

  • 确保数据库连接正常
  • 建议在迁移前备份数据库
  • 迁移过程可能需要几分钟

第五步：重启服务

1
2
3
4
5
6
7
8
9
# 启动 API 服务器
uv run flask run --host 0.0.0.0 --port 5001

# 启动 Worker（新终端）
celery -A app.celery worker -P gevent -c 1 --loglevel INFO

# 启动 Web 前端（新终端）
cd web
pnpm dev

常见问题解决

问题 1: 权限错误

错误信息：

1
PermissionError: [Errno 13] Permission denied: '/app/api/storage/...'

解决方案：

1
2
3
4
5
6
# 检查目录权限
ls -ln ./docker/volumes/app/storage

# 重新设置权限
sudo chown -R 1001:1001 ./docker/volumes/app/storage
sudo chmod -R 755 ./docker/volumes/app/storage

问题 2: 系统没有 UID 1001 用户

理解：

  • 1001:1001 是用户ID和组ID，不是用户名
  • Linux 可以使用纯数字 ID，无需实际用户存在

可选方案：创建用户

1
2
3
4
5
# 创建名为 dify 的用户，指定 UID 1001
sudo useradd -u 1001 -U dify

# 使用用户名设置权限
sudo chown -R dify:dify ./docker/volumes/app/storage

问题 3: SELinux 阻止访问

检查 SELinux：

1
2
3
4
5
6
7
8
# 查看状态
sestatus

# 设置正确的上下文
sudo chcon -Rt svirt_sandbox_file_t ./docker/volumes/app/storage

# 或临时禁用（仅用于测试）
sudo setenforce 0

问题 4: 数据库连接失败

错误信息：

1
hostname resolving error (lookup db_postgres on 127.0.0.11:53)

解决方案：

1
2
3
4
5
6
# 使用 PostgreSQL profile
docker compose --profile postgresql up -d

# 或检查网络配置
docker network ls
docker network inspect docker_default

问题 5: 插件无法访问

检查清单：

测试连接：

1
2
3
4
5
# 从容器内测试
docker compose exec api curl -I https://marketplace.dify.ai

# 从主机测试
curl -I https://marketplace.dify.ai

问题 6: Weaviate 版本不兼容

错误信息：

1
Weaviate version incompatible

解决方案：

1
2
3
4
5
6
7
8
# 更新 docker-compose.yaml 中的 Weaviate 版本
weaviate:
  image: semitechnologies/weaviate:1.24.0  # 或更高版本

# 添加 gRPC 端口
ports:
  - "8080:8080"
  - "50051:50051"  # gRPC 端口

回滚方案

如果升级后遇到严重问题，可以回滚到旧版本：

Docker Compose 回滚

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. 停止服务
docker compose down

# 2. 切换到旧版本
git checkout 1.7.1

# 3. 恢复权限（如果修改过）
sudo chown -R root:root ./docker/volumes/app/storage

# 4. 恢复数据备份（如果需要）
rm -rf docker/volumes
tar -xvf volumes-backup-TIMESTAMP.tgz
mv volumes docker/

# 5. 重启服务
cd docker
docker compose up -d

源码部署回滚

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. 停止服务
# 使用进程管理器停止所有服务

# 2. 回退代码
git checkout 1.7.1

# 3. 回退数据库（如果需要）
# 恢复数据库备份

# 4. 重新安装依赖
cd api
uv sync

# 5. 重启服务

升级后优化建议

  1. 性能监控
1
2
3
4
5
6
7
8
# 查看容器资源使用
docker stats

# 查看服务日志
docker compose logs -f --tail=100

# 监控数据库性能
# 使用 pgAdmin 或 MySQL Workbench
  1. 备份策略

建议设置定期备份：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/bin/bash
# backup.sh - Dify 备份脚本

BACKUP_DIR="/path/to/backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)

# 备份数据卷
tar -czf "${BACKUP_DIR}/dify_volumes_${TIMESTAMP}.tar.gz" \
  ./docker/volumes

# 备份数据库
docker compose exec -T db pg_dump -U postgres dify > \
  "${BACKUP_DIR}/dify_db_${TIMESTAMP}.sql"

# 保留最近 7 天的备份
find "${BACKUP_DIR}" -name "dify_*" -mtime +7 -delete

echo "Backup completed: ${TIMESTAMP}"

设置定时任务：

1
2
3
4
5
# 编辑 crontab
crontab -e

# 每天凌晨 2 点执行备份
0 2 * * * /path/to/backup.sh >> /var/log/dify_backup.log 2>&1
  1. 日志管理

配置日志轮转：

1
2
3
4
5
6
7
8
# docker-compose.yaml 中添加
services:
  api:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
  1. 安全加固
1
2
3
4
5
6
7
8
9
10
11
# 1. 使用强密码
# 更新 .env 中的敏感信息

# 2. 启用 HTTPS
# 配置反向代理（Nginx/Caddy）

# 3. 限制网络访问
# 配置防火墙规则

# 4. 定期更新
# 关注 GitHub releases 获取安全更新

相关资源

经验教训

  1. 权限问题是最常见的升级障碍

    • 务必在升级前修改 storage 目录权限
    • 使用 ls -ln 验证权限设置

  2. 备份是恢复的保障

    • 不要跳过备份步骤
    • 验证备份文件的完整性

  3. 分阶段验证

    • 不要等到最后才测试
    • 每完成一步就验证结果

  4. 保持文档更新

    • 记录自定义配置
    • 维护操作手册

注意事项

  • 升级过程中会有短暂的服务中断
  • 大版本升级可能需要 10-30 分钟
  • 建议在低峰时段进行升级
  • 提前通知用户计划的维护窗口
坚持原创技术分享，您的支持将鼓励我继续创作！
0%