DB-GPT 环境变量配置全解TOML 插值语法、密钥管理、本地数据库与 Docker 部署实战【免费下载链接】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 中常用的环境变量体系哪些变量控制模型接入、元数据库连接、日志级别、GPU 设备与网络代理以及如何通过${env:VAR_NAME}插值语法在 TOML 配置中引用环境变量并在 Docker 部署中通过docker run -e或docker-compose.yml注入密钥。读完后你可以独立完成一套不硬编码密钥的多环境部署配置并能从源码层面理解这些变量在 ConfigurationManager 中的解析时机与失败行为。在 故障排查总览 中环境变量页与安装问题、模型问题并列为三大排查方向。一个值得先记住的总原则是大部分配置都通过 TOML 配置文件完成环境变量更适合用于密钥、Docker 部署以及覆盖默认值——这正是本文后续各小节的展开逻辑。模型配置环境变量模型类环境变量用于接入各类 OpenAI 兼容服务是 Docker 部署与免配置文件启动时的核心输入变量说明示例OPENAI_API_KEYOpenAI API keysk-...OPENAI_API_BASEOpenAI 兼容 API 的基础地址https://api.openai.com/v1DEEPSEEK_API_KEYDeepSeek API keysk-...SILICONFLOW_API_KEYSiliconFlow API keysk-...DASHSCOPE_API_KEY阿里云 DashScope API keysk-...AIMLAPI_API_KEYAI/ML API key—LLM_MODEL默认 LLM 模型名称集群模式glm-4-9b-chatMODEL_SERVER模型控制器地址集群模式http://127.0.0.1:8000这些变量在源码中有明确的落地位置可以对照确认默认值核心配置入口 SystemAppConfig 中LLM_MODEL默认值为glm-4-9b-chat第 223 行MODEL_SERVER默认由MODEL_PORT默认 8000拼接为http://127.0.0.1:8000第 238-240 行。SystemAppConfig 还会读取DEEPSEEK_API_KEY、SILICONFLOW_API_KEY、GITEE_API_KEY等并把它们桥接为xxx_proxyllm_proxy_api_key等内部变量供 proxyllm 推理后端使用例如 SiliconFlow 的默认api_base为https://api.siliconflow.cn/v1默认后端模型为Qwen/Qwen2.5-Coder-32B-Instruct第 143-153 行。各 provider 的 key 环境变量名与 configs/dbgpt-proxy-openai.toml、configs/dbgpt-proxy-deepseek.toml、configs/dbgpt-proxy-siliconflow.toml、configs/dbgpt-proxy-tongyi.toml 等示例配置一一对应排错时建议直接以这些 TOML 为模板。需要注意适用前提LLM_MODEL/MODEL_SERVER主要服务于集群模式模型控制器 webserver 分离部署在单机源码部署中模型接入更推荐通过 TOML 的[models.llms]段 provider 名称完成。服务端配置环境变量控制日志、元数据库连接的服务端变量如下变量说明默认值DBGPT_LOG_LEVEL日志级别INFOLOCAL_DB_TYPE元数据库类型sqliteLOCAL_DB_PATHSQLite 数据库路径data/default_sqlite.dbMYSQL_HOSTMySQL host127.0.0.1MYSQL_PORTMySQL port3306MYSQL_USERMySQL 用户名rootMYSQL_PASSWORDMySQL 密码—MYSQL_DATABASEMySQL 数据库名dbgpt源码层面的印证位于 SystemAppConfigLOCAL_DB_TYPE默认sqlite、LOCAL_DB_PATH默认data/default_sqlite.db、LOCAL_DB_NAME默认dbgpt、LOCAL_DB_PORT默认3306与上表一致。日志方面dbgpt/core/_private/prompt_registry 之外的工具模块 直接以os.getenv(DBGPT_LOG_LEVEL, INFO)读取该变量因此它在非 TOML 路径如部分工具日志下同样生效。排查提示当你观察到服务启动但会话记录查不到或元数据表不存在时优先检查LOCAL_DB_TYPE与LOCAL_DB_PATH是否指向了预期的库文件——这也是 故障排查总览 建议的前 60 秒检查项之一curl http://localhost:5670/api/health、dbgpt model list、docker logs dbgpt -f。GPU 与硬件环境变量变量说明示例CUDA_VISIBLE_DEVICES限制可见 GPU0,1DEVICE强制指定设备类型cuda,cpu,mps这两个变量遵循 PyTorch / CUDA 生态的通用约定CUDA_VISIBLE_DEVICES在多卡机器上限制进程可见的 GPU 编号DEVICE用于在 DB-GPT 的本地推理路径中强制选择cuda、cpu或mpsApple Silicon。从 SystemAppConfig 的相邻字段可以看到本地模型加载还受MAX_GPU_MEMORYGPU 显存上限提示等变量影响显存不足时可配合 Model Issues 中换更小模型或改用 API 代理模型的建议处理。网络与代理环境变量变量说明示例UV_INDEX_URLuv 使用的 PyPI 镜像地址https://pypi.tuna.tsinghua.edu.cn/simpleHTTP_PROXY外部请求的 HTTP 代理http://proxy:8080HTTPS_PROXY外部请求的 HTTPS 代理http://proxy:8080NO_PROXY不走代理的主机列表localhost,127.0.0.1其中UV_INDEX_URL作用于依赖安装阶段DB-GPT 采用 uv 管理 Python 依赖见 pyproject.toml在国内网络环境下指向镜像站可以显著加速uv syncHTTP_PROXY/HTTPS_PROXY/NO_PROXY则用于让出站请求模型 API 调用、包下载等走企业代理并把localhost,127.0.0.1这类本机地址排除在代理之外。若安装阶段持续失败可进一步参考 Installation Issues。在 TOML 配置中使用环境变量${env:} 插值语法DB-GPT 支持在 TOML 配置文件中引用环境变量这是配置固化结构、密钥交给环境的关键机制[[models.llms]] api_key ${env:OPENAI_API_KEY} [[models.embeddings]] api_key ${env:OPENAI_API_KEY:-default-key}语法写法行为${env:VAR_NAME}从环境变量读取缺失时报错${env:VAR_NAME:-default}从环境变量读取若未设置则使用default源码实现解析时机与失败行为该能力由 ConfigurationManager 实现核心要点如下正则模式类属性ENV_VAR_PATTERN re.compile(r\${env:([^}])})manager.py#L291与上表语法一一对应。默认值拆分_resolve_env_vars 对匹配内容按:-拆分变量名与默认值变量未设置且无默认值时抛出ValueError(Environment variable {env_name} not found)——这正是表格中缺失时报错的源码出处也是api_key ${env:OPENAI_API_KEY}在 key 未导出时导致服务启动失败这一常见故障的根因。解析时机环境变量替换发生在配置值被转换为 dataclass 字段时_convert_value 中isinstance(value, str) and self.resolve_env_vars分支并递归处理嵌套 dataclass、list 和 dict 中的字符串字段_process_dataclass_env_vars。可开关ConfigurationManager构造参数resolve_env_vars默认为True特殊场景可关闭插值。仓库中的真实用法configs/dbgpt-app-config.example.toml 给出了完整的插值实践覆盖模型名、provider、api_base 与 api_key 四类字段[[models.llms]] name ${env:LLM_MODEL_NAME:-gpt-4o} provider ${env:LLM_MODEL_PROVIDER:-proxy/openai} api_base ${env:OPENAI_API_BASE:-https://api.openai.com/v1} api_key ${env:OPENAI_API_KEY} [[models.embeddings]] name ${env:EMBEDDING_MODEL_NAME:-text-embedding-3-small} provider ${env:EMBEDDING_MODEL_PROVIDER:-proxy/openai} api_url ${env:EMBEDDING_MODEL_API_URL:-https://api.openai.com/v1/embeddings} api_key ${env:OPENAI_API_KEY}注意这里的搭配技巧模型名、provider、地址都带:-默认值只有api_key是无默认值强依赖从而在缺少 key 时尽早暴露问题而不是静默回退。同样的模式出现在 configs/dbgpt-bm25-rag.toml、configs/dbgpt-graphrag.toml、configs/dbgpt-cloud-storage.example.toml 等几乎所有示例配置中dbgpt CLI 在生成配置文件时也会自动写出${env:LLM_MODEL_NAME:-...}形式的插值并有 test_config.py 断言生成的 TOML 内容包含该写法。配置加载入口可参考 dbgpt_server.pyConfigurationManager.from_file(config_file)它说明插值发生在 webserver 启动读取 TOML 的瞬间——因此环境变量必须在进程启动前就位运行中再export不会生效。Docker 环境变量注入使用 Docker 运行时可以通过-e传递环境变量docker run -it --rm \ -e SILICONFLOW_API_KEYyour-key \ -e DBGPT_LOG_LEVELDEBUG \ -p 5670:5670 \ eosphorosai/dbgpt-openai或者在docker-compose.yml中配置services: webserver: environment: - SILICONFLOW_API_KEY${SILICONFLOW_API_KEY} - DBGPT_LOG_LEVELINFO两种写法的效果等价docker run -e直接把值或宿主环境注入容器进程compose 的environment列表中${SILICONFLOW_API_KEY}是 compose 自身的宿主变量插值通常配合.env文件使用避免把密钥写进仓库中的 compose 文件。仓库中 docker-compose.yml 与 docker/ 目录含 allinone 镜像构建脚本提供了现成的编排参考将DBGPT_LOG_LEVELDEBUG作为排错开关时容器内日志可通过 故障排查总览 给出的docker logs dbgpt -f或 Compose 场景的docker logs db-gpt-webserver-1 -f实时查看。实践建议与排错对照结合上文各表与源码行为给出一组可直接执行的配置实践密钥不入库TOML 中所有 key 一律写${env:XXX_API_KEY}需要可选回退的字段如语言DBGPT_LANG、CORSDBGPT_CORS_ALLOWED_ORIGINS见 configs/dbgpt-app-config.example.toml#L3-L13再加:-默认值。启动失败先查变量是否存在若日志中出现Environment variable ... not found类错误定位到 TOML 中对应的${env:...}行确认该变量已在启动前 export 或写入 compose 的environment。模型问题provider/key/api_base 三类变量与 TOML 的provider名称必须互相匹配细节见 Model Issues。完整配置参考所有 TOML 字段的结构化参考见 Config Reference模型提供方接入方式见 Providers。延伸阅读主题链接完整配置参考Config Reference模型提供方Providers故障排查总览Troubleshooting核心实现ConfigurationManager · SystemAppConfig行为验证test_manager.py · test_config.py【免费下载链接】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），仅供参考 DB-GPT 环境变量配置全解：TOML 插值语法、密钥管理、本地数据库与 Docker 部署实战
DB-GPT 环境变量配置全解TOML 插值语法、密钥管理、本地数据库与 Docker 部署实战【免费下载链接】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 中常用的环境变量体系哪些变量控制模型接入、元数据库连接、日志级别、GPU 设备与网络代理以及如何通过${env:VAR_NAME}插值语法在 TOML 配置中引用环境变量并在 Docker 部署中通过docker run -e或docker-compose.yml注入密钥。读完后你可以独立完成一套不硬编码密钥的多环境部署配置并能从源码层面理解这些变量在 ConfigurationManager 中的解析时机与失败行为。在 故障排查总览 中环境变量页与安装问题、模型问题并列为三大排查方向。一个值得先记住的总原则是大部分配置都通过 TOML 配置文件完成环境变量更适合用于密钥、Docker 部署以及覆盖默认值——这正是本文后续各小节的展开逻辑。模型配置环境变量模型类环境变量用于接入各类 OpenAI 兼容服务是 Docker 部署与免配置文件启动时的核心输入变量说明示例OPENAI_API_KEYOpenAI API keysk-...OPENAI_API_BASEOpenAI 兼容 API 的基础地址https://api.openai.com/v1DEEPSEEK_API_KEYDeepSeek API keysk-...SILICONFLOW_API_KEYSiliconFlow API keysk-...DASHSCOPE_API_KEY阿里云 DashScope API keysk-...AIMLAPI_API_KEYAI/ML API key—LLM_MODEL默认 LLM 模型名称集群模式glm-4-9b-chatMODEL_SERVER模型控制器地址集群模式http://127.0.0.1:8000这些变量在源码中有明确的落地位置可以对照确认默认值核心配置入口 SystemAppConfig 中LLM_MODEL默认值为glm-4-9b-chat第 223 行MODEL_SERVER默认由MODEL_PORT默认 8000拼接为http://127.0.0.1:8000第 238-240 行。SystemAppConfig 还会读取DEEPSEEK_API_KEY、SILICONFLOW_API_KEY、GITEE_API_KEY等并把它们桥接为xxx_proxyllm_proxy_api_key等内部变量供 proxyllm 推理后端使用例如 SiliconFlow 的默认api_base为https://api.siliconflow.cn/v1默认后端模型为Qwen/Qwen2.5-Coder-32B-Instruct第 143-153 行。各 provider 的 key 环境变量名与 configs/dbgpt-proxy-openai.toml、configs/dbgpt-proxy-deepseek.toml、configs/dbgpt-proxy-siliconflow.toml、configs/dbgpt-proxy-tongyi.toml 等示例配置一一对应排错时建议直接以这些 TOML 为模板。需要注意适用前提LLM_MODEL/MODEL_SERVER主要服务于集群模式模型控制器 webserver 分离部署在单机源码部署中模型接入更推荐通过 TOML 的[models.llms]段 provider 名称完成。服务端配置环境变量控制日志、元数据库连接的服务端变量如下变量说明默认值DBGPT_LOG_LEVEL日志级别INFOLOCAL_DB_TYPE元数据库类型sqliteLOCAL_DB_PATHSQLite 数据库路径data/default_sqlite.dbMYSQL_HOSTMySQL host127.0.0.1MYSQL_PORTMySQL port3306MYSQL_USERMySQL 用户名rootMYSQL_PASSWORDMySQL 密码—MYSQL_DATABASEMySQL 数据库名dbgpt源码层面的印证位于 SystemAppConfigLOCAL_DB_TYPE默认sqlite、LOCAL_DB_PATH默认data/default_sqlite.db、LOCAL_DB_NAME默认dbgpt、LOCAL_DB_PORT默认3306与上表一致。日志方面dbgpt/core/_private/prompt_registry 之外的工具模块 直接以os.getenv(DBGPT_LOG_LEVEL, INFO)读取该变量因此它在非 TOML 路径如部分工具日志下同样生效。排查提示当你观察到服务启动但会话记录查不到或元数据表不存在时优先检查LOCAL_DB_TYPE与LOCAL_DB_PATH是否指向了预期的库文件——这也是 故障排查总览 建议的前 60 秒检查项之一curl http://localhost:5670/api/health、dbgpt model list、docker logs dbgpt -f。GPU 与硬件环境变量变量说明示例CUDA_VISIBLE_DEVICES限制可见 GPU0,1DEVICE强制指定设备类型cuda,cpu,mps这两个变量遵循 PyTorch / CUDA 生态的通用约定CUDA_VISIBLE_DEVICES在多卡机器上限制进程可见的 GPU 编号DEVICE用于在 DB-GPT 的本地推理路径中强制选择cuda、cpu或mpsApple Silicon。从 SystemAppConfig 的相邻字段可以看到本地模型加载还受MAX_GPU_MEMORYGPU 显存上限提示等变量影响显存不足时可配合 Model Issues 中换更小模型或改用 API 代理模型的建议处理。网络与代理环境变量变量说明示例UV_INDEX_URLuv 使用的 PyPI 镜像地址https://pypi.tuna.tsinghua.edu.cn/simpleHTTP_PROXY外部请求的 HTTP 代理http://proxy:8080HTTPS_PROXY外部请求的 HTTPS 代理http://proxy:8080NO_PROXY不走代理的主机列表localhost,127.0.0.1其中UV_INDEX_URL作用于依赖安装阶段DB-GPT 采用 uv 管理 Python 依赖见 pyproject.toml在国内网络环境下指向镜像站可以显著加速uv syncHTTP_PROXY/HTTPS_PROXY/NO_PROXY则用于让出站请求模型 API 调用、包下载等走企业代理并把localhost,127.0.0.1这类本机地址排除在代理之外。若安装阶段持续失败可进一步参考 Installation Issues。在 TOML 配置中使用环境变量${env:} 插值语法DB-GPT 支持在 TOML 配置文件中引用环境变量这是配置固化结构、密钥交给环境的关键机制[[models.llms]] api_key ${env:OPENAI_API_KEY} [[models.embeddings]] api_key ${env:OPENAI_API_KEY:-default-key}语法写法行为${env:VAR_NAME}从环境变量读取缺失时报错${env:VAR_NAME:-default}从环境变量读取若未设置则使用default源码实现解析时机与失败行为该能力由 ConfigurationManager 实现核心要点如下正则模式类属性ENV_VAR_PATTERN re.compile(r\${env:([^}])})manager.py#L291与上表语法一一对应。默认值拆分_resolve_env_vars 对匹配内容按:-拆分变量名与默认值变量未设置且无默认值时抛出ValueError(Environment variable {env_name} not found)——这正是表格中缺失时报错的源码出处也是api_key ${env:OPENAI_API_KEY}在 key 未导出时导致服务启动失败这一常见故障的根因。解析时机环境变量替换发生在配置值被转换为 dataclass 字段时_convert_value 中isinstance(value, str) and self.resolve_env_vars分支并递归处理嵌套 dataclass、list 和 dict 中的字符串字段_process_dataclass_env_vars。可开关ConfigurationManager构造参数resolve_env_vars默认为True特殊场景可关闭插值。仓库中的真实用法configs/dbgpt-app-config.example.toml 给出了完整的插值实践覆盖模型名、provider、api_base 与 api_key 四类字段[[models.llms]] name ${env:LLM_MODEL_NAME:-gpt-4o} provider ${env:LLM_MODEL_PROVIDER:-proxy/openai} api_base ${env:OPENAI_API_BASE:-https://api.openai.com/v1} api_key ${env:OPENAI_API_KEY} [[models.embeddings]] name ${env:EMBEDDING_MODEL_NAME:-text-embedding-3-small} provider ${env:EMBEDDING_MODEL_PROVIDER:-proxy/openai} api_url ${env:EMBEDDING_MODEL_API_URL:-https://api.openai.com/v1/embeddings} api_key ${env:OPENAI_API_KEY}注意这里的搭配技巧模型名、provider、地址都带:-默认值只有api_key是无默认值强依赖从而在缺少 key 时尽早暴露问题而不是静默回退。同样的模式出现在 configs/dbgpt-bm25-rag.toml、configs/dbgpt-graphrag.toml、configs/dbgpt-cloud-storage.example.toml 等几乎所有示例配置中dbgpt CLI 在生成配置文件时也会自动写出${env:LLM_MODEL_NAME:-...}形式的插值并有 test_config.py 断言生成的 TOML 内容包含该写法。配置加载入口可参考 dbgpt_server.pyConfigurationManager.from_file(config_file)它说明插值发生在 webserver 启动读取 TOML 的瞬间——因此环境变量必须在进程启动前就位运行中再export不会生效。Docker 环境变量注入使用 Docker 运行时可以通过-e传递环境变量docker run -it --rm \ -e SILICONFLOW_API_KEYyour-key \ -e DBGPT_LOG_LEVELDEBUG \ -p 5670:5670 \ eosphorosai/dbgpt-openai或者在docker-compose.yml中配置services: webserver: environment: - SILICONFLOW_API_KEY${SILICONFLOW_API_KEY} - DBGPT_LOG_LEVELINFO两种写法的效果等价docker run -e直接把值或宿主环境注入容器进程compose 的environment列表中${SILICONFLOW_API_KEY}是 compose 自身的宿主变量插值通常配合.env文件使用避免把密钥写进仓库中的 compose 文件。仓库中 docker-compose.yml 与 docker/ 目录含 allinone 镜像构建脚本提供了现成的编排参考将DBGPT_LOG_LEVELDEBUG作为排错开关时容器内日志可通过 故障排查总览 给出的docker logs dbgpt -f或 Compose 场景的docker logs db-gpt-webserver-1 -f实时查看。实践建议与排错对照结合上文各表与源码行为给出一组可直接执行的配置实践密钥不入库TOML 中所有 key 一律写${env:XXX_API_KEY}需要可选回退的字段如语言DBGPT_LANG、CORSDBGPT_CORS_ALLOWED_ORIGINS见 configs/dbgpt-app-config.example.toml#L3-L13再加:-默认值。启动失败先查变量是否存在若日志中出现Environment variable ... not found类错误定位到 TOML 中对应的${env:...}行确认该变量已在启动前 export 或写入 compose 的environment。模型问题provider/key/api_base 三类变量与 TOML 的provider名称必须互相匹配细节见 Model Issues。完整配置参考所有 TOML 字段的结构化参考见 Config Reference模型提供方接入方式见 Providers。延伸阅读主题链接完整配置参考Config Reference模型提供方Providers故障排查总览Troubleshooting核心实现ConfigurationManager · SystemAppConfig行为验证test_manager.py · test_config.py【免费下载链接】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），仅供参考