企业官网建设流程全解析

DB-GPT 接入 ClickHouse 数据源：安装配置、连接原理与源码级参数解析

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

本指南以 clickhouse_install.md 为主线，完整演示如何将 ClickHouse 注册为 DB-GPT 的数据源（Datasource），涵盖依赖安装、服务启动、连接配置三步流程。同时结合仓库内 ClickHouse 连接器的真实实现（conn_clickhouse.py）与集成测试，深入解析每一个连接参数的默认值、作用与底层驱动调用方式，帮助读者不仅"跑通流程"，更理解其背后的原理。

为什么选择 ClickHouse 作为 DB-GPT 数据源

在 DB-GPT 的数据架构中，Datasource 负责对接外部数据库并向上层提供统一的元数据与 SQL 执行能力。官方指南明确说明了引入列式数据库的动机：

使用列式数据库（Column-oriented Database）实现 Datasource，可以在一定程度上缓解向量数据库检索带来的不确定性与可解释性问题。

向量检索依赖 embedding 相似度排序，其结果往往缺乏确定性；而将业务数据放入 ClickHouse 这类列式分析库后，Chat Data / Chat DB 等场景可以直接执行精确的 SQL 查询，将"检索-生成"过程建立在可验证的查询结果之上。DB-GPT 将 ClickHouse 归类为ResourceCategory.DATABASE类型的可注册资源，并在 config-reference/datasource 配置参考中以ClickhouseParameters的形式对外暴露全部连接选项。

第一步：安装 datasource_clickhouse 依赖

DB-GPT 的 ClickHouse 数据源能力由dbgpt-ext扩展包提供，其连接器依赖clickhouse-connect驱动。该依赖在 packages/dbgpt-ext/pyproject.toml 中通过datasource_clickhouseextra 声明：

datasource_clickhouse = [ "clickhouse-connect", ]

因此使用uv安装时，需要显式带上--extra "datasource_clickhouse"，同时按需引入base、rag、storage_chromadb、dbgpts等 extras：

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

参数说明：

• --all-packages：同步仓库内所有子包（dbgpt-core、dbgpt-ext、dbgpt-serve、dbgpt-app 等），保证dbgpt start webserver命令可用；
• --extra "datasource_clickhouse"：安装 ClickHouse 数据源所必需的clickhouse-connect驱动，缺省此项将导致连接器在运行时无法导入；
• --extra "rag"与--extra "storage_chromadb"：RAG 链路与 Chroma 向量存储所需依赖，对应本场景中"向量检索 + 精确 SQL 查询"互补使用的典型组合；
• --extra "dbgpts"：DB-GPT 应用（App）运行所需组件。

提示：仓库根目录同时维护了uv.lock锁定文件，使用uv sync可保证依赖版本与 CI、生产环境一致。

第二步：准备 ClickHouse 服务

在连接 DB-GPT 之前，需要先准备一个可用的 ClickHouse 实例。安装方式请参考 ClickHouse 官方安装文档（依据 ClickHouse 社区标准部署方式，选择 Docker、deb/rpm 或二进制包任一方式即可）。

一个最小可用的 ClickHouse 连接具备以下要素：

• host：数据库主机地址，本机部署即为localhost；
• port：HTTP 接口端口，ClickHouse 默认8123；
• user / password：连接账号，默认default用户（初始密码为空）；
• database：目标数据库名，如default。

这些默认值可以在集成测试 tests/intetration_tests/datasource/test_conn_clickhouse.py 的 fixture 中直接看到：

@pytest.fixture def db(): conn = ClickhouseConnector.from_uri_db("localhost", 8123, "default", "", "default") yield conn

第三步：启动 DB-GPT webserver

环境就绪后，使用下列命令之一启动 webserver。两种方式等价，推荐使用第一条官方 CLI 入口：

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

也可以直接执行 Python 启动模块（本质上是同一入口）：

uv run python packages/dbgpt-app/src/dbgpt_app/dbgpt_server.py --config configs/dbgpt-proxy-openai.toml

这里使用的配置文件 configs/dbgpt-proxy-openai.toml 是一个基于 OpenAI 兼容接口的代理模型配置示例，其核心结构如下：

• 顶部声明api_keys、encrypt_key等服务级配置；
• [models.llms]定义大模型通道，通过${env:OPENAI_API_BASE:-https://api.openai.com/v1}这类环境变量占位符指定接口地址与密钥；
• [models.embeddings]定义 embedding 模型通道，供 RAG 向量检索使用。

如需使用其他模型通道，可参考 configs 目录下的dbgpt-proxy-deepseek.toml、dbgpt-proxy-ollama.toml、dbgpt-local-vllm.toml等现成模板，将--config指向对应文件即可。

第四步：在 UI 中完成 ClickHouse 数据源配置

webserver 启动后，即可在 DB-GPT Web 界面的"数据源"（Datasource）管理中新建 ClickHouse 连接。界面表单的字段与源码中 ClickhouseParameters 数据类一一对应，下面是完整的参数字段与默认值对照表：

关于password的环境变量引用方式，源码注释给出了明确说明：可以直接写明文密码，也可以通过${env:DBGPT_DB_PASSWORD}引用环境变量，以便密钥管理与多环境复用。

参数如何驱动底层连接

表单参数最终通过from_parameters()→from_uri_db()进入连接器（源码位置）：

client = clickhouse_connect.get_client( host=host, user=user, password=pwd, port=port, connect_timeout=connect_timeout, database=db_name, settings={"distributed_ddl_task_timeout": distributed_ddl_task_timeout}, pool_mgr=big_pool_mgr, )

从实现可以看出几个关键点：

• 驱动为官方clickhouse-connect，走HTTP 协议，因此port默认对应8123（而非原生 TCP 的9000）；
• 连接池由clickhouse_connect.driver.httputil.get_pool_manager(maxsize, num_pools)构建，http_pool_maxsize/http_pool_num_pools直接决定并发查询吞吐；
• distributed_ddl_task_timeout以连接级 settings 下发，适用于跨节点分布式 DDL 场景；
• 该类通过@auto_register_resource装饰器注册为 DB-GPT 的可编排资源（category 为DATABASE），因此除了 Web 界面手动配置外，也可以在 AWEL 流程中以"数据源节点"的方式被直接引用。

连接器的核心能力与 SQL 执行链路

ClickhouseConnector继承自RDBMSConnector，对外暴露了统一的元数据与查询接口，帮助上层（如 Chat Data 的自然语言转 SQL 链路）以一致的方式访问 ClickHouse。从 源码 看，其核心方法包括：

_query()是查询的统一出口：调用client.query()后将列名column_names插入到结果集首行作为表头，fetch参数支持"all"与"one"两种模式，与 DB-GPT 对其他 RDBMS 数据源的返回格式保持一致。

集成测试：验证接入的正确姿势

仓库在 tests/intetration_tests/datasource/test_conn_clickhouse.py 中提供了完整的 ClickHouse 连接器集成测试，既是 CI 验证手段，也是手动排查连接问题的极佳参考：

def test_create_table(db): _create_sql = """ CREATE TABLE IF NOT EXISTS my_first_table ( `user_id` UInt32, `message` String, `timestamp` DateTime, `metric` Float32 ) ENGINE = MergeTree PRIMARY KEY (user_id, timestamp) ORDER BY (user_id, timestamp); """ db.run(_create_sql) assert list(db.get_table_names()) == ["my_first_table"]

其余用例依次覆盖get_table_names、get_indexes（主键名应为primary_key）、get_fields、get_table_comments、get_column_comments。若在 UI 中添加数据源后出现"无法获取表结构"类问题，可以参照该测试文件中的 SQL 与断言逐项核对权限：连接账号需要具备读取system.columns、system.tables以及执行SHOW TABLES的权限。

常见问题排查要点

• 端口连不上：确认使用的是 HTTP 端口8123，而非 TCP 原生协议端口9000；clickhouse-connect走 HTTP 驱动；
• 密码泄露顾虑：Web 表单中不填password时默认引用${env:DBGPT_DB_PASSWORD}，建议优先在服务环境变量中注入，避免明文入库；
• 表结构拉取失败：检查数据库账号对system库和INFORMATION_SCHEMA的只读访问权限，连接器的元数据查询强依赖这两个系统目录；
• 分布式集群 DDL 超时：增大distributed_ddl_task_timeout（默认 300 秒），或在表单中针对集群拓扑单独调整该参数。

小结

通过以上四步，即可在 DB-GPT 中完整接入 ClickHouse 数据源：uv sync安装datasource_clickhouseextra 与clickhouse-connect驱动 → 准备可访问的 ClickHouse 实例 → 以dbgpt start webserver启动服务 → 在 UI 中按 ClickhouseParameters 的字段填写连接信息。其背后的连接器（conn_clickhouse.py）通过 HTTP 协议统一封装了表、字段、索引与 SQL 执行能力，与集成测试（test_conn_clickhouse.py）共同保证了数据源在 Chat Data、Chat DB 与 AWEL 流程编排中的稳定可用，为"精确查询 + 向量检索"混合的数据分析场景提供了可靠底座。

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