一、事件概述
-
事件名称：Dify 跨版本升级后系统不可用
-
发生时间：约持续 2 天
-
影响范围：
- Console不可访问或异常
- API 接口大量 502 / 500
- datasets 功能不可用
-
严重级别：P1（核心功能不可用）
二、故障现象
1. 服务不可用阶段
- 页面访问 502
/console/api/system-features无响应- curl 请求挂起
2. 服务异常阶段
api、worker容器反复重启- 报错：无法解析数据库主机（
db）
3. 部分恢复阶段
-
页面可打开但白屏
-
浏览器接口报错：
- 401 / 502 / 500 混合
4. 功能异常阶段
-
datasets 接口返回 500
-
日志报错：
relation does not existcolumn does not exist
三、影响评估
| 登录 / Console | 异常 |
| API 服务 | 不稳定 |
| 数据集（datasets） | 不可用 |
| 后台任务（worker） | 部分失败 |
四、时间线
| T0 | 执行跨版本升级 |
| T0+ | 出现 502 / API 无响应 |
| T1 | 启用 postgresql profile，数据库恢复 |
| T2 | 修复 .env 中 DB_HOST=db → db_postgres |
| T3 | API 可连接但请求挂起 |
| T4 | 发现 weaviate 未启动，手动拉起 |
| T5 | 页面恢复但出现 500 |
| T6 | 排查数据库，发现缺表 / 缺字段 |
| T7 | 发现 alembic_version 缺失或不一致 |
| T8 | 重建 migration 链并执行 upgrade |
| T9 | 补充缺失字段（datasets.is_multimodal） |
| T10 | 系统完全恢复 |
五、根因分析
1. 直接根因
数据库 Schema 与当前代码版本不一致：
缺失字段：datasets.is_multimodal
缺失表：human_input_forms 等
导致：
- API 查询失败
- 返回 500
2. 根本原因
本次故障由历史迁移环境导致的状态不一致引起，具体包括：
（1）数据库迁移来源不规范
- 数据库为历史环境迁移
- 未通过完整 migration 初始化
- 缺失
alembic_version元数据
导致 migration 系统无法识别真实版本状态
（2）跨版本升级未执行完整迁移链
- 未按版本顺序执行 migration
- 未执行中间版本附加脚本（如 credentials 转换）
导致数据库结构停留在中间态
（3）配置文件（.env）为历史遗留
DB_HOST指向旧服务名VECTOR_STORE=weaviate与实际运行不一致
导致服务连接异常与依赖错位
（4）Docker Compose Profile 启动不完整
- 仅启用
postgresql - 未启动
weaviate
导致 API 初始化阶段阻塞
3. 根因归纳
历史迁移环境下，数据库、配置和依赖三者状态不一致，导致系统在升级后进入不可用状态。
六、处理过程
1. 修复数据库连接问题
docker compose --profile postgresql up -d
DB_HOST=db_postgres
2. 启动缺失依赖
docker compose up -d weaviate
3. 修复 migration 状态
docker exec -it docker-db_postgres-1 psql -U postgres -d dify -c "
TRUNCATE TABLE alembic_version;
INSERT INTO alembic_version (version_num) VALUES ('xxxx');
"
docker compose run --rm api flask db upgrade
4. 补齐缺失 Schema
ALTER TABLE datasets
ADD COLUMN is_multimodal BOOLEAN NOT NULL DEFAULT FALSE;
5. 验证系统恢复
docker compose logs --since=5m api
curl http://127.0.0.1:9527/console/api/datasets
七、恢复结果
- 所有核心服务正常运行
- API 响应正常
- datasets 功能恢复
- worker 任务全部成功
八、经验教训
1. 数据库必须有版本元数据
缺失 alembic_version 会导致：
migration 逻辑失效
2. 跨版本升级必须走完整链路
不能直接：
旧版本 → 最新版本
3. .env 不可直接复用
必须与当前版本对齐
4. 依赖服务必须显式确认
docker compose ps
5. migration 成功不代表 schema 正确
必须验证：
\d 表名
九、改进措施
短期
- 固化当前
.env和 compose 配置 - 备份数据库（作为基线）
中期
建立升级流程：
- 备份 DB
- 升级到中间版本
- 执行 migration + 脚本
- 再升级
- 校验 schema
- 校验依赖
长期
- 建立标准 Runbook
- 禁止直接跨版本升级生产环境
- 引入升级前校验机制（schema + config + dependency）
最终总结
本次故障本质是一次“状态不一致”问题：历史迁移环境中的数据库、配置和运行依赖未对齐，在跨版本升级后被放大，最终导致系统不可用。
