企业官网建设流程全解析

DB-GPT Docker Compose 部署实战：基于 MySQL 的持久化生产环境搭建与集群编排

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

本篇指南基于 DB-GPT 仓库中的官方文档与配套编排文件，系统讲解如何使用 Docker Compose 一键部署"DB-GPT 应用服务 + MySQL 元数据库"的生产就绪环境。读完本文，你将掌握完整的三步部署流程、各服务与数据卷的职责划分、API Key 与 TOML 配置的注入机制、常用运维操作（日志/重启/重置），以及如何切换到自定义配置、挂载本地模型与 GPU 预留，并可进一步扩展到多 Worker 集群、高可用集群与 OceanBase 后端等场景。

一、前置条件

部署前请确认环境中已具备：

• 已安装 Docker 与 Docker Compose；
• 一个受支持 LLM 服务商的 API Key（根目录默认编排文件以 SiliconFlow 为默认 LLM 提供方，仓库同时提供 AI/ML API 的备选配置入口）。

二、三步快速开始

仓库根目录的 docker-compose.yml 定义了默认部署形态：DB-GPT 应用服务（WebServer）+ MySQL 数据库，默认使用 SiliconFlow 作为 LLM 提供方。

Step 1 — 设置 API Key

SiliconFlow（默认）：

export SILICONFLOW_API_KEY="your-siliconflow-api-key"

AI/ML API：

export AIMLAPI_API_KEY="your-aiml-api-key"

Step 2 — 启动服务

# SiliconFlow SILICONFLOW_API_KEY=${SILICONFLOW_API_KEY} docker compose up -d # 或使用 AI/ML API AIMLAPI_API_KEY=${AIMLAPI_API_KEY} docker compose up -d

启动成功的终端输出大致如下：

[+] Running 3/3 ✔ Network dbgptnet Created 0.0s ✔ Container db-gpt-db-1 Started 0.2s ✔ Container db-gpt-webserver-1 Started 0.2s

Step 3 — 打开 Web UI

浏览器访问http://localhost:5670。

首次启动注意事项：WebServer 会等待 MySQL 完成初始化（执行全部初始化 SQL）后才真正就绪。若首次启动时 WebServer 因数据库尚未就绪而退出，restart: unless-stopped策略会自动拉起，通常重试后即可正常。可用docker logs db-gpt-webserver-1 -f跟踪日志确认状态。

三、部署了哪些东西：编排文件的源码级解读

默认docker-compose.yml创建两个核心服务：

结合 docker-compose.yml 的实际内容，可以进一步拆解这套编排的关键设计：

3.1 MySQL 服务的数据初始化链路

db服务挂载了四组关键内容：

• dbgpt-myql-db:/var/lib/mysql—— 命名卷，保证数据库文件在容器重建后仍然持久化；
• ./docker/examples/my.cnf:/etc/my.cnf—— MySQL 配置文件；
• ./docker/examples/sqls:/docker-entrypoint-initdb.d—— 官方示例数据集的建表/灌数脚本目录；
• ./assets/schema/dbgpt.sql:/docker-entrypoint-initdb.d/dbgpt.sql—— DB-GPT 自身的表结构定义。

利用 MySQL 镜像的/docker-entrypoint-initdb.d初始化机制，首次启动数据库时会自动建库建表并导入示例数据，这也是文档中"WebServer 需等待 MySQL 初始化完成"这一提示的根源。

配套的 my.cnf 中有几处对应用兼容性很关键的设置：

default-authentication-plugin=mysql_native_password character_set_server=utf8mb4 collation-server=utf8mb4_unicode_ci init_connect='SET NAMES utf8mb4'

mysql_native_password认证插件是为了兼容较老的 MySQL 客户端驱动；utf8mb4全套字符集配置则保证中文等 Unicode 数据在元数据库中正确存储。

3.2 WebServer 服务：配置注入与数据持久化

webserver服务的核心配置为：

webserver: image: eosphorosai/dbgpt-openai:latest command: dbgpt start webserver --config /app/configs/dbgpt-proxy-siliconflow-mysql.toml environment: - SILICONFLOW_API_KEY=${SILICONFLOW_API_KEY} - MYSQL_PASSWORD=aa123456 - MYSQL_HOST=db - MYSQL_PORT=3306 - MYSQL_DATABASE=dbgpt - MYSQL_USER=root volumes: - ./configs:/app/configs - /data:/data - /data/models:/app/models - dbgpt-data:/app/pilot/data - dbgpt-message:/app/pilot/message depends_on: - db ports: - 5670:5670/tcp restart: unless-stopped ipc: host

几个值得关注的点：

1. dbgpt start webserver --config：这是 DB-GPT 的官方 CLI 启动入口。从源码 packages/dbgpt-app/src/dbgpt_app/_cli.py#L99-L169 可以看到，webserver命令接受可选的--config（TOML 配置文件路径）、--profile（provider 配置档）、--yes（跳过交互式向导）、--api-key、--daemon等参数；未提供--config时会走~/.dbgpt/下的 profile 或首次配置向导流程。Compose 文件显式传入了--config /app/configs/dbgpt-proxy-siliconflow-mysql.toml，从而绕开交互式向导，适合容器场景。

2. 环境变量占位符机制：默认配置 configs/dbgpt-proxy-siliconflow-mysql.toml 大量使用${env:VAR:-default}语法从环境变量取值，例如数据库连接段：

   [service.web.database] type = "mysql" host = "${env:MYSQL_HOST:-127.0.0.1}" port = "${env:MYSQL_PORT:-3306}" database = "${env:MYSQL_DATABASE:-dbgpt}" user = "${env:MYSQL_USER:-root}" password ="${env:MYSQL_PASSWORD:-aa123456}"

   这解释了为什么 Compose 里只需注入MYSQL_*环境变量与SILICONFLOW_API_KEY，而不需要改配置文件——TOML 中未设置的项都会落到默认值（如MYSQL_HOST默认127.0.0.1，而在 Compose 网络中被显式覆盖为服务名db）。

3. 默认模型配置：同一 TOML 中通过proxy/siliconflowprovider 声明了三类远端模型：

   [[models.llms]] name = "Qwen/Qwen2.5-Coder-32B-Instruct" provider = "proxy/siliconflow" api_key = "${env:SILICONFLOW_API_KEY}" [[models.embeddings]] name = "BAAI/bge-m3" provider = "proxy/siliconflow" [[models.rerankers]] name = "BAAI/bge-reranker-v2-m3" provider = "proxy/siliconflow"

   即 LLM、Embedding、Rerank 全部走 API 代理，容器内不需要 GPU 也能跑通完整问答与 RAG 流程。此外[rag.storage.vector]使用chroma并持久化到pilot/data（对应dbgpt-data卷）。

4. 数据卷持久化：dbgpt-data:/app/pilot/data与dbgpt-message:/app/pilot/message分别持久化知识库数据与会话消息，保证docker compose down后数据不丢；./configs:/app/configs则把宿主机configs/目录整体映射进容器，方便直接替换配置文件（见下文定制章节）。

5. restart: unless-stopped与depends_on：depends_on只保证启动顺序，不保证就绪，因此配合自动重启策略来兜底"MySQL 初始化慢于 WebServer 启动"这一常见时序问题。

6. ipc: host：共享宿主机 IPC 命名空间，为容器内模型加载/共享内存留出余量（对远端 API 场景影响不大，对本地模型场景有意义）。

另外可以注意到，官方基础镜像 docker/base/Dockerfile#L126 的默认CMD是dbgpt start webserver --config configs/dbgpt-proxy-siliconflow.toml（SQLite 元数据库版本），而根目录 Compose 文件通过显式command将其切换为 MySQL 版本——这也是理解"镜像默认行为"与"Compose 实际行为"差异的关键。

四、常用运维操作

# 查看 WebServer 日志 docker logs db-gpt-webserver-1 -f # 查看数据库日志 docker logs db-gpt-db-1 -f # 停止服务（保留数据卷） docker compose down # 重启服务 docker compose restart # 彻底重置（连同数据一起删除） docker compose down -v

警告：-v参数会删除所有命名卷，包括dbgpt-myql-db（MySQL 数据库）、dbgpt-data、dbgpt-message，所有元数据、知识库与会话记录都会丢失。执行前请确认无需保留数据。

五、定制部署

5.1 使用自定义配置文件

由于 Compose 已将./configs:/app/configs挂载进容器，替换/新增一个 TOML 并覆盖启动命令即可：

webserver: image: eosphorosai/dbgpt-openai:latest command: dbgpt start webserver --config /app/configs/your-config.toml volumes: - ./your-config.toml:/app/configs/your-config.toml

配置模板可以参考仓库 configs/ 目录下的全套示例（如 dbgpt-proxy-siliconflow.toml、dbgpt-proxy-aimlapi.toml、dbgpt-local-qwen.toml 等），按需修改[service.web.database]、[[models.llms]]、[[models.embeddings]]等段落。

5.2 挂载本地模型（GPU 部署）

如果需要容器内加载本地模型，可挂载模型目录并申请 NVIDIA GPU：

webserver: volumes: - /data/models:/app/models deploy: resources: reservations: devices: - driver: nvidia capabilities: [gpu]

默认的根 Compose 文件其实已经包含/data/models:/app/models挂载（宿主机不存在该目录时 Docker 会自动创建空目录），使用本地模型时把模型放到宿主机/data/models下即可；GPU 预留段则需按上述方式自行添加（前提是宿主机已安装 NVIDIA Container Toolkit）。

六、其他 Compose 编排示例

仓库docker/compose_examples/目录下随附了面向特定场景的编排文件：

使用示例（以多 Worker 集群为例）：

docker compose -f docker/compose_examples/cluster-docker-compose.yml up -d

6.1 多 Worker 集群的架构

cluster-docker-compose.yml 使用eosphorosai/dbgpt:latest镜像编排了五个角色：

• controller：集群控制器（dbgpt start controller），负责 Worker 注册与模型路由；
• api-server：对外 OpenAI 兼容 API 入口（dbgpt start apiserver，端口 8100），通过--controller_addr http://controller:8000连接控制器；
• llm-worker：LLM 推理 Worker（示例使用本地模型glm-4-9b-chat，模型路径/app/models/glm-4-9b-chat，端口 8001，带 GPU 预留）；
• embedding-worker：Embedding Worker（text2vec类型，加载text2vec-large-chinese，端口 8002，带 GPU 预留）；
• webserver：以--light --remote_embedding轻量模式启动，通过MODEL_SERVER=http://controller:8000把模型请求全部转发给集群，自身端口 5000。

注意该文件要求先把本地模型放到宿主机/data/models（各服务通过- /data/models:/app/models挂载），并按需修改--model_path指向实际模型目录。

6.2 高可用集群

ha-cluster-docker-compose.yml 演示了"双 Controller + 双 Worker + WebServer + API Server"的部署形态，全部使用eosphorosai/dbgpt-openai:latest镜像（由 docker/base/build_proxy_image.sh 构建，脚本头部注释中说明了构建方式与可选的--pip-index-url参数）。文件头部注释给出了标准启动命令：

OPENAI_API_KEY="{your api key}" OPENAI_API_BASE="https://api.openai.com/v1" \ docker compose -f ha-cluster-docker-compose.yml up -d

该文件通过环境变量实现 provider 可切换，例如改用 SiliconFlow：

LLM_MODEL_PROVIDER="proxy/siliconflow" \ LLM_MODEL_NAME="Qwen/Qwen2.5-Coder-32B-Instruct" \ OPENAI_API_BASE="https://api.siliconflow.cn/v1" \ OPENAI_API_KEY="${SILICONFLOW_API_KEY}" \ EMBEDDING_MODEL_PROVIDER="proxy/openai" \ EMBEDDING_MODEL_NAME="BAAI/bge-large-zh-v1.5" \ EMBEDDING_MODEL_API_URL="https://api.siliconflow.cn/v1/embeddings" \ docker compose -f ha-cluster-docker-compose.yml up -d

架构上有两处值得注意的细节：

• llm-worker、embedding-worker、webserver、apiserver的CONTROLLER_ADDR均配置为http://controller-1:8000,http://controller-2:8000双地址，实现控制器故障时的冗余接入；
• 单独用一个busybox的init服务把assets/schema/dbgpt.sql与docker/examples/sqls拷贝到共享卷dbgpt-init-scripts，再由db服务在初始化时消费，解决了 MySQL 初始化脚本来源分散的问题。Controller 与 WebServer 各自挂载 ha-model-cluster.toml 与 ha-webserver.toml 两份专用配置。

6.3 OceanBase 后端

dbgpt-oceanbase-docker-compose.yml 演示了以 OceanBase（oceanbase/oceanbase-ce:vector镜像）同时承担业务库与向量存储的形态：dbgpt服务使用eosphorosai/dbgpt-allinone镜像，通过VECTOR_STORE_TYPE=OceanBase、OB_HOST/OB_PORT/OB_USER/OB_DATABASE等环境变量接入（文件内还保留了一处OB_HOST=127.0.0.1的重复项，实际以容器内网络解析的oceanbase服务名为准来理解连接目标），并默认以tongyi_proxyllm（PROXYLLM_BACKEND=qwen-plus）作为 LLM，需通过TONGYI_PROXY_API_KEY注入 API Key。

七、排障建议

• WebServer 反复重启：大概率是 MySQL 初始化 SQL 尚未执行完。观察docker logs db-gpt-webserver-1 -f与docker logs db-gpt-db-1 -f，等待数据库日志出现初始化完成标志后，restart: unless-stopped会自动让服务进入就绪状态。
• 模型调用报错/无响应：确认启动时SILICONFLOW_API_KEY已正确注入（docker exec进容器或docker inspect查看环境变量），并检查 TOML 中api_key = "${env:SILICONFLOW_API_KEY}"是否能取到值。
• 数据丢失疑虑：日常停止请只用docker compose down；只有执行down -v才会删除dbgpt-myql-db、dbgpt-data、dbgpt-message等卷。

八、小结

DB-GPT 的 Compose 部署方案以"镜像内预置 CLI + TOML 环境变量占位符 + Compose 注入"为核心设计：根目录 docker-compose.yml 覆盖最通用的"远端 LLM 代理 + MySQL 元数据"场景，三步即可在 http://localhost:5670 得到完整可访问的 Web 应用；而 docker/compose_examples/ 下的集群、高可用与 OceanBase 编排则提供了向生产规模演进的路径。部署后如需深入调整，优先查看 configs/ 目录中的 TOML 配置与 docker/base/Dockerfile 的镜像构建逻辑，即可覆盖绝大多数自定义需求。

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