Upgrade To v0.8.3
概述
本指南适用于从 v0.8.2 升级到 v0.8.3 的用户。如果你使用的是更早版本,请先按照历史升级文档依次升级到 v0.8.2。
- SQLite 用户:升级前请备份元数据库。由 ORM 管理的元数据表和字段会在 DB-GPT 服务启动时自动创建或迁移。
- MySQL 用户:必须在启动新版前执行数据库迁移,请使用
assets/schema/upgrade/v0_8_3/目录下的增量升级脚本。 - 从源码构建前端的用户:Next.js 16 要求 Node.js >= 20.9.0。建议使用 Node.js 20.19,该版本也是本次发布的前端构建基线。
可观测性数据默认独立存储在 logs/observability.db 中,不会写入主业务数据库。
准备工作
备份数据库
为防止数据丢失,请务必在升级前备份元数据库。请根据数据库类型选择合适的备份方式,例如 MySQL 使用 mysqldump,SQLite 直接复制数据库文件。
确认升级脚本
v0.8.3 的升级脚本维护在仓库的 assets/schema/upgrade/v0_8_3/ 目录下:
| 脚本 | 用途 |
|---|---|
upgrade_to_v0.8.3.sql | 用于将已有的 v0.8.2 MySQL 元数据库增量升级到 v0.8.3。 |
v0.8.3.sql | 用于全新安装的完整 v0.8.3 Schema。 |
从 v0.8.2 升级时,请使用 upgrade_to_v0.8.3.sql。不要在已有数据库上执行完整 Schema 文件。全新安装执行完整 Schema 后,无需再执行增量脚本。
升级步骤
第 1 步 — 停止 DB-GPT 服务
使用与启动时相同的方式停止正在运行的 DB-GPT 服务。
已有 MySQL 部署必须在启动新版前完成增量升级。漏跑脚本会导致定时任务缺少 owner_id、resource_*、lease_* 等字段及运行记录幂等索引,可能出现 Unknown column 等错误,并影响 存量定时任务和 Dashboard 功能。
第 2 步 — 升级数据库
v0.8.3 的元数据升级为 3 张存量表新增 10 个字段及相关索引,并创建 19 张新增元数据表。
字段与索引变更
| 对象 | 变更 | 说明 |
|---|---|---|
dbgpt_serve_scheduled_task | 新增 owner_id、resource_type、resource_id、lease_owner、lease_expires_at 及相关索引 | 用于稳定授权身份、资源关联、执行互斥与续租。 |
dbgpt_serve_scheduled_run | 新增 output_resource_id、attempt_count、result_json、idempotency_key,并增加 (task_id, idempotency_key) 唯一索引 | 记录结果资源、重试次数和结构化结果,并防止重复执行。 |
chat_history_message | 新增 trace_id 及索引 | 将聊天消息与 Agent 执行链路关联。 |
新增 Dashboard 与上传数据集表
| 表名 | 说明 |
|---|---|
dbgpt_dashboard | 存储看板身份、所有者、来源会话、数据源、当前 Schema、修订号、状态和发布信息。 |
dbgpt_dashboard_annotation | 存储 AI 批注请求、目标内容、提示词、基础修订号、审阅状态和变更提案。 |
dbgpt_dashboard_audit | 记录看板操作、操作者、目标对象、请求 ID 和 审计详情。 |
dbgpt_dashboard_cover | 按所有者存储看板封面图片及其来源修订号。 |
dbgpt_dashboard_edit_version | 存储已保存的编辑修订、Schema 快照、操作者、来源和操作 ID。 |
dbgpt_dashboard_folder | 存储归属于用户的看板文件夹。 |
dbgpt_dashboard_folder_item | 存储看板与文件夹的归属关系。 |
dbgpt_dashboard_live_share | 存储持续分享的已发布定义、缓存结果、有效期和撤销状态。 |
dbgpt_dashboard_member | 存储看板成员及其访问角色。 |
dbgpt_dashboard_operation | 存储编辑操作与补丁,用于幂等应用和修订追踪。 |
dbgpt_dashboard_revision | 存储已发布 Schema 修订、冻结数据快照、校验结果和分享令牌散列。 |
dbgpt_dashboard_share | 存储固定修订的分享记录、令牌散列、有效期和撤销状态。 |
dbgpt_dashboard_share_secret | 独立存储加密密钥材料,供已授权发布者恢复分享链接。 |
dbgpt_uploaded_dataset | 存储上传数据集的所有者、来源会话、物化数据库信息、清单、关系和处理状态。 |
新增可追溯报告表
| 表名 | 说明 |
|---|---|
dbgpt_report | 存储归属于用户的报告身份、来源会话、标题、最新运行和最新修订号。 |
dbgpt_report_run | 存储不可变报告运行快照、修订号、协议版本、触发类型和完整报告文档。 |
dbgpt_report_artifact | 存储执行产物及其来源会话、步骤、消息、任务和 执行运行。 |
dbgpt_report_artifact_dependency | 存储输入产物与依赖产物之间的执行血缘关系。 |
dbgpt_report_evidence | 存储报告区块与执行产物之间的证据绑定,包括证据角色及来源/目标选择器。 |
对于 MySQL 元数据库,请执行增量升级脚本:
mysql -u <user> -p dbgpt < assets/schema/upgrade/v0_8_3/upgrade_to_v0.8.3.sql
如果你的元数据库名称不是 dbgpt,请将命令中的 dbgpt 替换为实际数据库名,或在正确的数据库上下文中执行该 SQL 文件。
增量脚本开头包含 USE dbgpt;。如果你的元数据库使用了其他名称,请在执行前修改这一行,或先在 MySQL 会话中选择正确的目标数据库。
增量脚本对存量表使用直接的 ALTER TABLE ... ADD COLUMN 和 ADD INDEX,这些语句不能重复执行。请仅在干净的 v0.8.2 数据库上执行一次。如果此前已经运行过旧版 Dashboard SQL 或手工执行过部分 DDL,请先核对已有字段和索引,只执行缺失项。
第 3 步 — 安装依赖
根据你的安装方式更新 Python 依赖。如果你是从源码安装并使用默认配置,请执行:
uv sync --all-packages
如需使用 Qdrant 向量存储及可配置元数据 Payload 索引,请安装对应 Extra:
uv sync --all-packages --extra "storage_qdrant"
如果从源码构建前端,请使用 Node.js 20.19 或其他兼容 Next.js 16 的版本,然后重新安装依赖并执行生产构建:
cd web
yarn install
yarn build
LocalRuntime 仍是默认 Sandbox 运行时。只有需要容器隔离时才显式选择容器后端,并提前准备可用的 daemon 和 Agent 镜像:
export SANDBOX_RUNTIME=docker
export SANDBOX_AGENT_IMAGE=dbgpt-sandbox-agent:latest
显式选择的容器运行时在初始化或执行失败时不会回退到本地执行。
如需为 Qdrant 的元数据过滤字段建立 Payload 索引,可按需配置;未设置时默认不创建额外索引:
export QDRANT_METADATA_INDEXES="session_id,page:integer"
对于新建集合和已有集合,DB-GPT 会在启动时创建配置中指定但尚未存在的索引。
生产环境启用 Dashboard 生产模式时,还需要接入可信认证和数据源授权策略。生产协作能力需要 Redis;缺少协作配置时相关接口不可用,但普通聊天和看板服务仍可启动。
第 4 步 — 启动 DB-GPT 服务
使用你常用的方式重新启动 DB-GPT 服务。
启动后建议验证:
- 历史对话和定时任务可以正常加载,日志中没有缺少字段或索引的数据库错误。
- 可以生成并重新打开可追溯报告,通过 SQL、Python、知识引用和证据图谱复核内容。
- Dashboard 可以完成规划确认、草稿编辑、保存、发布和分享,数据源权限与修订冲突检查符合预期。
- 可观测性总览、Trace 列表、Trace 详情和对话内 Trace 可以正常展示。
- 开启 LLM-Wiki 的知识空间可以生成目录、页面和链接图谱,新增文档后能够增量更新。
- 模型提供商可以正常连接,模型启停即时生效,并在服务重启后自动恢复。
- 工具执行日志中的 Sandbox 运行时与配置一致;显式选择的容器运行时不可用时会明确报错,而不是回退到本地执行。
回滚说明
如果升级失败,请停止 DB-GPT 服务,并使用升级前的备份恢复元数据库。由于 v0.8.3 涉及元数据 Schema 变更,不要继续运行处于部分升级状态的数据库。
如果增量脚本执行到一半失败,不要在部分升级的数据库上重新执行整份脚本。请先恢复干净的 v0.8.2 备份,修正问题后重新执行迁移;或者在准确核对已存在的字段、索引和表后,手工补齐剩余语句。