企业官网建设流程全解析

DB-GPT 集成 Apache Doris：MySQL 协议驱动的实时数仓连接实践

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

Apache Doris 作为一款实时的分析型数据仓库，在 DB-GPT 中通过dbgpt_ext.datasource.rdbms.conn_doris模块以原生连接器的方式获得完整支持。本文基于 doris_install.md 展开，从依赖安装、Doris 实例准备、webserver 启动到连接参数配置逐一落地，并结合仓库源码剖析 Doris 连接器的实现原理与关键注意事项。读完本文，你将能够独立完成 DB-GPT 与 Apache Doris 的对接，并理解为何 Doris 需要复用 MySQL 兼容驱动、为何连接器要绕过 metadata 反射等底层细节。

一、集成原理：Doris 的 MySQL 兼容协议

Apache Doris 对外提供 MySQL 兼容的访问协议，这是 DB-GPT 能够以极低成本接入 Doris 的根本前提。在 conn_doris.py 中可以看到这一设计被明确固化：

class DorisConnector(RDBMSConnector): driver = "mysql+pymysql" db_type = "doris" db_dialect = "mysql"

• driver = "mysql+pymysql"：底层实际使用 PyMySQL 建立连接；
• db_dialect = "mysql"：SQLAlchemy 方言层面仍按 MySQL 处理；
• db_type = "doris"：用于 DB-GPT 侧的类型标识与展示。

同样，在 schema.py 中，Doris 被注册为独立的数据库类型：Doris = DbInfo("doris")。也就是说，DB-GPT 将 Doris 视为"协议同 MySQL、身份独立"的数据源——既复用了 MySQL 生态的驱动与工具链，又在产品形态上保留了 Doris 的独立识别。

正因如此，安装 Doris 依赖时使用的是 MySQL 的依赖组（datasource_mysql），而不需要单独的 Doris 驱动包。这一点在后续安装章节会体现。

二、安装依赖：基于 uv 同步项目依赖

Doris 连接器随dbgpt-ext包发布。按照官方文档，使用uv同步项目全部依赖，并显式声明所需的 extra 组：

uv sync --all-packages \ --extra "base" \ --extra "datasource_mysql" \ --extra "rag" \ --extra "storage_chromadb" \ --extra "dbgpts"

各 extra 的作用如下：

从 pyproject.toml 可以确认这一依赖映射关系：

# 基础依赖已包含 PyMySQL "pymysql", # datasource_mysql extra datasource_mysql = [ # mysqlclient 2.2.x have pkg-config issue on 3.10+ # If you want to install psycopg2 and mysqlclient in ubuntu, you should install # libpq-dev and libmysqlclient-dev first. "mysqlclient==2.1.0", ]

需要特别说明的是，仓库中预留了一个被注释掉的 Doris 专属驱动依赖：

# datasource_doris = ["pydoris>=1.0.2,<2.0.0"]

这意味着：当前版本的连接器走的是 MySQL 兼容路径，官方并未启用pydoris原生驱动。如果你在自己的环境中强行引入pydoris，并不会被连接器使用——连接器始终通过mysql+pymysql建连。这是一个容易误解的细节，务必以本文档描述的方式安装datasource_mysql组。

三、准备 Apache Doris 实例

在安装依赖之后，需要准备一个可用的 Doris 实例。DB-GPT 连接 Doris 时仅要求实例具备以下前提：

• 已启动 FE（Frontend）服务，并能通过MySQL 协议端口（默认 9030）访问；
• 存在可登录的用户账号（默认root无密码，生产环境建议显式创建专用账号）；
• 已创建目标数据库（database），并授予该用户对应库的读写与元数据查询权限。

由于连接器内部会执行SHOW GRANTS、SHOW DATABASES、查询information_schema等操作（详见下文"源码剖析"），请确保连接账号至少具备元数据读取权限，否则后续表结构与数据预览功能将无法正常工作。

四、启动 DB-GPT Webserver

Doris 实例就绪后，启动 DB-GPT webserver。官方文档给出的命令为：

uv run dbgpt start webserver --config configs/dbgpt-proxy-openai.toml

该命令在当前仓库根目录执行，--config指向的 dbgpt-proxy-openai.toml 是一个以 OpenAI 兼容接口作为大模型后端的典型配置，其中模型相关配置通过环境变量注入：

[[models.llms]] provider = "${env:LLM_MODEL_PROVIDER:-proxy/openai}" api_key = "${env:OPENAI_API_KEY}" [[models.embeddings]] provider = "${env:EMBEDDING_MODEL_PROVIDER:-proxy/openai}" api_key = "${env:OPENAI_API_KEY}"

也就是说，启动前通常需要先设置OPENAI_API_KEY等环境变量。若你本地已部署其他模型（如 vLLM、Ollama 或本地模型），可替换为configs/目录下对应的配置文件，例如 dbgpt-local-vllm.toml 或 dbgpt-proxy-ollama.toml。Doris 连接器本身与模型无关，无论使用何种模型后端，Doris 数据源的接入方式完全一致。

启动成功后，通过浏览器访问 webserver 提供的 UI（默认端口请以启动日志为准），即可进入数据源管理页面。

五、配置 Apache Doris 数据源

DB-GPT 提供两种配置 Doris 数据源的方式：

1. UI 操作：在 Web 界面的数据源管理页选择 Apache Doris 类型，填写下列字段；
2. 配置文件 / API：通过配置字段或客户端 API 提交相同的参数。

核心字段如下：

其中driver固定为mysql+pymysql。在源码 conn_doris.py 的DorisParameters中，该字段有默认值与说明：

@dataclass class DorisParameters(RDBMSDatasourceParameters): __type__ = "doris" driver: str = field( default="mysql+pymysql", metadata={ "help": _( "Driver name for Doris, default is mysql+pymysql (MySQL compatible)." ), }, )

除上述连接字段外，DB-GPT 的 RDBMS 参数基类还提供一组连接池调优参数（见 base.py），在大量查询或并发场景下值得关注：

密码字段默认支持环境变量注入写法${env:DBGPT_DB_PASSWORD}，且被标记为privacy属性，配置时优先使用环境变量而非明文，可降低密钥泄露风险。

六、源码剖析：Doris 连接器的关键实现

Doris 连接器并非简单复用 MySQL 连接器，而是基于RDBMSConnector做了大量定制。理解这些实现，有助于排查连接问题、评估功能边界。

6.1 绕过 metadata.reflect()：Doris 类型解析的关键修复

在DorisConnector.__init__中，源码刻意不调用metadata.reflect()：

# NOT call reflect() to avoid Doris type parsing issues # self._metadata = metadata or MetaData() # self._metadata.reflect(bind=self._engine)

注释明确说明：SQLAlchemy 的反射机制在处理 Doris 的列类型时存在解析问题，直接reflect()会导致失败。因此连接器改用手写 SQL 从information_schema拉取表与列信息：

• _sync_tables_from_db()：通过SELECT TABLE_NAME FROM information_schema.tables WHERE TABLE_SCHEMA=database()同步表清单；
• get_fields()/get_columns()：通过information_schema.columns读取列名、类型、默认值、可空性与注释；
• table_simple_info()：使用concat+group_concat生成表名(列1,列2,...)的紧凑摘要，供 LLM 构建 schema 上下文。

6.2 面向 LLM 的表结构信息构建

为了让大模型理解 Doris 表结构，get_table_info()与_build_table_info_for_doris()直接用 SQL 组装出近似CREATE TABLE的文本（列定义、NOT NULL、DEFAULT、COMMENT、表注释），并可选追加采样数据与索引信息：

• _sample_rows_in_table_info（默认 3）：每表最多附带 3 行采样数据，放在/* ... */注释块中，作为 LLM 生成 SQL 的参考样例；
• _indexes_in_table_info（默认 False）：关闭时不会输出索引信息，按需开启；
• get_indexes()：通过SHOW INDEX FROM <table>读取索引。

从源码看，这类"面向 LLM 的建表文本 + 采样行"设计，正是 DB-GPT 让模型在 Text-to-SQL / NL2SQL 场景中理解数据模式的核心机制。

6.3 元数据与权限相关能力

连接器还实现了以下元数据能力：

• get_grants()：执行SHOW GRANTS获取账号权限列表（返回结构兼容 2 列 / 3 列两种格式）；
• get_current_version()：通过select current_version()获取 Doris 版本号；
• get_collation()：执行SHOW COLLATION获取排序规则；
• get_charset()：从information_schema.SCHEMATA读取默认字符集；
• get_database_names()：执行SHOW DATABASES并主动过滤系统库：

if d[0] not in [ "information_schema", "sys", "_statistics_", "mysql", "__internal_schema", "doris_audit_db__", ]

这样在 UI 下拉框与 Agent 对话中，不会把 Doris 内部库暴露给用户或模型，避免干扰。

6.4 连接串构造

from_uri_db()展示了最直接的连接串构造方式：

db_url = f"{cls.driver}://{quote(user)}:{urlquote(pwd)}@{host}:{str(port)}/{db_name}"

其中quote/urlquote用于对用户名与密码中的特殊字符做 URL 编码，避免含@、:等字符的凭据破坏 URI 解析。

七、验证连接与常见问题排查

连接配置完成后，可通过以下方式验证：

1. 在数据源管理页面对 Doris 数据源执行测试连接，成功后保存；
2. 在对话场景中引用该数据源，观察 Agent 是否正确加载表结构信息；
3. 直接请求查看"表结构 + 采样行"，确认information_schema查询权限正常。

常见问题与排查思路（均基于上述源码行为推导）：

八、小结

通过 MySQL 兼容协议，DB-GPT 将 Apache Doris 无缝纳入统一数据源体系：安装侧复用datasource_mysql依赖组，连接侧使用mysql+pymysql驱动，元数据侧则通过information_schema手工构建面向 LLM 的表结构描述，并针对 Doris 的类型解析问题绕过了 SQLAlchemy 反射机制。

从 doris_install.md 到 conn_doris.py，整条链路清晰且可独立复现。若你正在建设实时数仓 + AI 对话分析平台，可以直接照本文步骤，将 Doris 作为 DB-GPT 的数据底座投入使用。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT