跳到主要内容
版本:dev

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 备份,修正问题后重新执行迁移;或者在准确核对已存在的字段、索引和表后,手工补齐剩余语句。