ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

DB-GPT v0.7.x 升级至 v0.8.0 完整指南:数据库迁移与会话分享链接(share_links)实战

DB-GPT v0.7.x 升级至 v0.8.0 完整指南:数据库迁移与会话分享链接(share_links)实战 DB-GPT v0.7.x 升级至 v0.8.0 完整指南数据库迁移与会话分享链接share_links实战【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本指南面向从 DB-GPTv0.7.x升级到v0.8.0的用户以官方升级文档为骨架结合仓库内实际的 Schema 变更脚本、share_links表的源码实现与前后端调用链完整讲解升级前的数据库备份、MySQL Schema 迁移、依赖更新与启动验证全流程。读完本文你将能够独立完成一次安全可靠的 v0.8.0 升级并透彻理解 v0.8.0 新增的「会话分享链接」功能背后的表结构、DAO 与 API 设计。升级概览先看清 v0.8.0 带来了什么DB-GPT v0.8.0 的核心变更之一是新增了会话分享链接能力用户可以把一段对话生成一条唯一 URL 分享出去其他人通过该 URL 即可查看这段会话。支撑这一能力的持久化载体是一张新表share_links它存储分享 Token 与会话 UIDconv_uid的映射关系。从升级角度看本次版本变更对数据库的影响是单向且增量的SQLite 用户无需执行任何数据库迁移。SQLite 的元数据表由 ORM 在启动时自动创建/校验v0.8.0 新增的share_links表会随应用初始化自动建好无需人工干预。MySQL 用户必须手动执行一段增量 SQL为已有元数据库补充share_links表否则会话分享功能无法工作。官方为每个版本维护了独立的升级 SQL 脚本全部集中在仓库assets/schema/upgrade/目录下其中 v0.8.0 对应的脚本位于assets/schema/upgrade/v0_8_0/包含两份文件文件用途upgrade_to_v0.8.0.sql增量升级脚本只包含从 v0.7.x 到 v0.8.0 的新增变更即share_links建表语句供老用户升级使用v0.8.0.sql全量初始化脚本包含完整的元数据库 DDLalembic_version、知识库、对话历史、模型注册、插件、Flow 等全部表供全新安装初始化使用第 0 步升级前必做的数据库备份⚠️警告为防止数据丢失请务必在升级前备份您的数据库。备份方式取决于你的元数据库类型MySQL使用官方工具mysqldump导出完整元数据库例如mysqldump -u user -p --databases dbgpt dbgpt_backup_before_v0.8.0.sql注意仓库默认元数据库名为dbgpt如果你在.env或配置中通过LOCAL_DB_NAME指定了其他名称请替换为实际库名这一约定在assets/schema/upgrade/v0_8_0/v0.8.0.sql的注释中有明确说明。SQLite直接拷贝数据库文件即可。默认 SQLite 元数据库文件为pilot/meta_data/dbgpt.db可在服务停止状态下整体复制备份。备份完成后请核对文件大小与可读性确保备份真正有效再进行下一步。第 1 步停止 DB-GPT 服务使用与启动时相同的方式停止正在运行的 DB-GPT 服务例如CtrlC终止前台进程或通过 systemd / Docker / Gunicorn 进程管理器停止。在服务完全停止、无任何写入进程占用数据库之前不要执行下一步的 DDL以避免建表期间发生锁冲突或数据不一致。第 2 步升级数据库MySQL 执行增量 SQL在 MySQL 元数据库中执行 v0.8.0 的增量变更脚本。可以直接执行仓库维护的现成脚本mysql -u user -p dbgpt assets/schema/upgrade/v0_8_0/upgrade_to_v0.8.0.sql也可以手动执行下面的建表语句内容与仓库脚本完全一致。该语句需要在你的元数据库上下文中执行脚本默认通过USE dbgpt;指定库名请按实际库名调整。新增表share_links表名说明share_links存储会话分享链接的 Token支持用户通过唯一 URL 分享对话。USE dbgpt; -- share_links: 存储会话分享链接 Token CREATE TABLE share_links ( id int NOT NULL AUTO_INCREMENT COMMENT Primary key, token varchar(64) NOT NULL COMMENT Unique random share token, conv_uid varchar(255) NOT NULL COMMENT The conversation uid being shared, created_by varchar(255) DEFAULT NULL COMMENT User who created the share link, gmt_created TIMESTAMP DEFAULT CURRENT_TIMESTAMP COMMENT Creation time, PRIMARY KEY (id), UNIQUE KEY uk_share_token (token), KEY ix_share_links_token (token), KEY ix_share_links_conv_uid (conv_uid) ) ENGINEInnoDB AUTO_INCREMENT1 DEFAULT CHARSETutf8mb4 COLLATEutf8mb4_unicode_ci COMMENTConversation share link table;字段语义与设计要点对照仓库源码packages/dbgpt-app/src/dbgpt_app/share/models.py中的ShareLinkEntity模型可以逐字段理解这张表的设计意图字段类型含义设计要点idint自增主键主键ORM 侧对应Column(Integer, primary_keyTrue, autoincrementTrue)tokenvarchar(64)非空唯一随机分享 Token由 Pythonsecrets.token_urlsafe(32)生成URL 安全且高熵通过UNIQUE KEY uk_share_token强制唯一保证每个分享链接全局唯一conv_uidvarchar(255)非空被分享会话的 UID与chat_history.conv_uid对应是定位对话记录的关键键ix_share_links_conv_uid索引加速按会话的反查created_byvarchar(255)可空创建分享链接的用户可空是为了兼容 v0.8.0 之前遗留的匿名会话详见下文权限模型gmt_createdTIMESTAMP默认当前时间创建时间ORM 侧使用defaultdatetime.nowMySQL 侧使用DEFAULT CURRENT_TIMESTAMP从 DDL 与 ORM 双重定义可以看到token同时具备UNIQUE 约束和普通索引ix_share_links_token这样既能在写入时拦截重复 Token又能在高频的“按 Token 查链接”场景下走索引conv_uid侧则只有普通索引因为它不需要全局唯一同一会话只应有一条分享链接唯一性在应用层 DAO 中保证。顺带说明v0.8.0 全量脚本中表的位置如果你做的是全新安装而非升级则不需要执行upgrade_to_v0.8.0.sql初始化流程会直接使用assets/schema/upgrade/v0_8_0/v0.8.0.sql创建完整元数据库其中share_links的 DDL第 571–581 行与增量脚本完全一致。该文件还同时创建了alembic_version表用于 Alembic 迁移工具版本跟踪、chat_history、chat_history_message、dbgpt_serve_flow、dbgpt_serve_model、gpts_app等核心业务表并附带了示例业务库EXAMPLE_1及其演示数据供示例场景使用。第 3 步安装依赖根据你的安装方式更新依赖。如果你是从源码安装并使用默认配置请执行uv sync --all-packages--all-packages会同步仓库内全部 Python 包dbgpt-core、dbgpt-serve、dbgpt-app、dbgpt-client、dbgpt-ext、dbgpt-sandbox等见仓库根目录pyproject.toml的工作区定义确保升级后各模块版本一致。若使用 Docker 或已发布的分发包安装请按对应发布说明更新镜像或安装包。第 4 步启动 DB-GPT 服务并验证分享链接功能使用你常用的方式重新启动 DB-GPT 服务。启动后请按以下清单确认升级成功确认服务正常观察启动日志无报错Web 界面可正常访问。确认表已创建MySQL 中执行SHOW TABLES LIKE share_links;应能看到该表DESC share_links;可核对字段结构。验证新功能在对话界面发起一次会话点击「分享」生成链接使用无登录状态的浏览器打开该 URL确认会话内容可以正常回放查看。分享链接功能的前后端完整调用链为了让验证更有针对性这里结合源码梳理share_links功能从 API 到页面的完整链路① 创建分享链接POST前端调用POST /api/v2/chat/share携带{ conv_uid: ... }请求体。后端实现在packages/dbgpt-app/src/dbgpt_app/openapi/api_v1/agentic_data_api.py的create_share_link中处理逻辑为通过_conversation_owner_user_name()查询该会话记录的归属用户会话不存在时直接返回 404只有会话所有者或匿名会话才能创建分享非所有者返回 403调用ShareLinkDao.create_share(conv_uid, created_by)—— 该方法在packages/dbgpt-app/src/dbgpt_app/share/models.py中实现先按conv_uid查已存在链接若已存在则原样返回保证重复点击分享始终得到同一个 URL否则用secrets.token_urlsafe(32)生成 43 字符左右的 URL 安全 Token 并落库成功后返回share_url形如/share/token的相对路径由前端拼接当前主机地址形成可分享的绝对 URL。② 回放分享会话GET分享页面加载后调用GET /api/v2/chat/share/{token}实现在agentic_data_api.py的get_share_conversation中这是一个无需认证的公开接口先用 Token 查到ShareLinkEntity查不到返回 404通过会话服务dbgpt_serve.conversation按conv_uid拉取完整历史消息对历史消息执行scrub_react_history_for_share清洗——v2 消息载荷中的input_files会被改写成无法解析回内部路径的公共快照保证分享出去的内容不会泄露本地文件地址对应隐私测试packages/dbgpt-app/src/dbgpt_app/tests/test_share_file_privacy.py中的断言场景返回{conv_uid, token, messages[]}前端据此重建并动画化回放会话。③ 撤销分享链接DELETEDELETE /api/v2/chat/share/{token}实现于agentic_data_api.pyToken 不存在返回 404只有记录的创建者created_by可以删除链接非创建者返回 403为保证不误删也不存在静默失败成功删除后该 URL 立即失效再次访问返回 404。④ 分享页面的路由兜底DB-GPT 的 Web 前端是 Next.js 静态导出产物/share/[token]动态路由在静态目录中表现为字面量目录share/[token]/index.html见packages/dbgpt-app/src/dbgpt_app/static/web/share/[token]/index.html。由于 FastAPI 的StaticFiles无法解析动态路径段packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py在挂载兜底静态目录之前显式注册了GET /share/{token}与GET /share/{token}/两条路由将任意 Token 都导向该页面从而保证分享链接可用。⑤ 数据层与模型注册ShareLinkEntity与ShareLinkDao定义于packages/dbgpt-app/src/dbgpt_app/share/models.pyDAO 基于dbgpt.storage.metadata.BaseDao提供create_share/get_by_token/get_by_conv_uid/delete_by_token四个方法。实体通过packages/dbgpt-app/src/dbgpt_app/initialization/db_model_initialization.py注册进 SQLAlchemy 模型列表——这也是 SQLite 用户无需手动迁移的根本原因应用启动初始化时会自动为该模型建表。常见问题与排查建议Q1升级后分享链接打不开页面 404优先检查① 是否已在 MySQL 执行增量 SQLSHOW TABLES LIKE share_links;确认② 分享接口POST /api/v2/chat/share是否返回了share_url③ 静态前端目录中是否存在share/[token]/index.html页面文件。三者缺一不可。Q2分享接口返回 404 “Conversation not found”create_share_link对不存在的conv_uid采取 fail-closed 策略请确认传入的会话 UID 真实存在于chat_history表。Q3分享接口返回 403 “Not the conversation owner”该功能有严格的所有权校验只有会话记录中的user_name与当前登录用户一致或会话为匿名遗留记录时才能分享。这是刻意设计的权限模型防止越权泄露他人会话。Q4升级过程会删除或改动旧数据吗不会。upgrade_to_v0.8.0.sql是纯增量的CREATE TABLE不涉及任何ALTER/DROP/UPDATE对 v0.7.x 已有表结构零侵入但正因如此请务必自行完成第 0 步的备份以应对其他意外情况。升级检查清单速查☐ 停止 DB-GPT 服务前用mysqldumpMySQL或文件拷贝SQLite完成数据库备份☐ SQLite 用户跳过迁移MySQL 用户执行assets/schema/upgrade/v0_8_0/upgrade_to_v0.8.0.sql完成share_links建表☐ 源码安装用户执行uv sync --all-packages更新依赖☐ 重启服务确认share_links表存在、会话分享链接可创建、可无登录回放、可撤销☐ 分享内容中不应包含可解析的本地文件路径源码会通过scrub_react_history_for_share自动清洗。至此v0.7.x 到 v0.8.0 的升级即告完成。整个升级过程的核心只有「备份 → 建表 → 更新依赖 → 重启验证」四步而新增的会话分享链接功能背后是一张设计简洁的表加上一套完整的权限校验与隐私清洗逻辑值得在后续使用中充分验证。【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表