DB-GPT 环境变量完全指南模型、服务、Docker 部署与 TOML 注入【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPTDB-GPT 的绝大多数配置都通过 TOML 配置文件完成但环境变量在密钥管理、Docker 部署和默认值覆盖场景中扮演着不可替代的角色。本文基于 docs/docs/getting-started/troubleshooting/environment.md系统梳理 DB-GPT 中常用的环境变量、${env:VAR}TOML 注入语法及其底层实现帮助你在裸机、容器和集群模式下快速完成模型接入、元数据库与日志级别的配置并能在排查问题时准确定位环境变量缺失导致的启动失败。环境变量在 DB-GPT 中的定位DB-GPT 采用TOML 为主、环境变量为辅的配置哲学。官方文档在开篇即给出明确建议大部分配置通过 TOML 配置文件完成环境变量主要用于密钥secrets、Docker 部署以及对默认值的临时覆盖。这一设计在仓库中体现得非常直观示例配置 中大量字段的默认值直接引用环境变量例如语言language ${env:DBGPT_LANG:-zh}、API Keyapi_key ${env:OPENAI_API_KEY}。与此同时核心配置类Config在初始化时通过os.getenv读取数十个环境变量作为兜底默认值二者形成互补关系环境变量适合存放不应进入版本库的敏感信息API Key、数据库密码环境变量适合在不改动配置文件的前提下覆盖默认行为日志级别、端口、模型地址在 Docker / Docker Compose 场景下环境变量是向容器内注入配置的标准途径。模型配置相关环境变量下表汇总了 DB-GPT 中与模型接入直接相关的环境变量变量说明示例OPENAI_API_KEYOpenAI 或兼容 OpenAI 协议的 API Keysk-...OPENAI_API_BASEOpenAI 兼容的 API Base URLhttps://api.openai.com/v1DEEPSEEK_API_KEYDeepSeek API Keysk-...SILICONFLOW_API_KEYSiliconFlow API Keysk-...DASHSCOPE_API_KEY阿里云百炼DashScopeAPI Keysk-...AIMLAPI_API_KEYAI/ML API Key—LLM_MODEL默认 LLM 模型名集群模式glm-4-9b-chatMODEL_SERVER模型控制器地址集群模式http://127.0.0.1:8000底层实现Config 类如何消费这些变量在 packages/dbgpt-core/src/dbgpt/_private/config.py 中Config类在__init__阶段就完成了大量环境变量的读取并且会反向写入os.environ实现新旧参数体系的兼容。典型片段如下DEEPSEEK_API_KEY第 125-133 行读取后写入deepseek_proxyllm_proxy_api_key并将默认模型版本设为deepseek-chat、默认 API Base 设为https://api.deepseek.com/v1SILICONFLOW_API_KEY第 143-153 行写入siliconflow_proxyllm_proxy_api_key默认模型为Qwen/Qwen2.5-Coder-32B-Instruct默认 API Base 为https://api.siliconflow.cn/v1ANTHROPIC_API_KEY对应 Claude第 134-142 行以及 Yi、Moonshot、Gitee、百度文心、讯飞星火、智谱、百川、Gemini 等各家模型的*_API_KEY均采用同样的读取与回填模式。集群模式下两个关键变量也在该文件中定义self.LLM_MODEL os.getenv(LLM_MODEL, glm-4-9b-chat) # 第 223 行 self.MODEL_SERVER os.getenv( MODEL_SERVER, http://127.0.0.1 : str(self.MODEL_PORT) # 第 238-240 行 )其中MODEL_PORT默认取 8000因此MODEL_SERVER的默认值即为http://127.0.0.1:8000与文档表格一致。在命令行与配置文件中使用在裸机环境下最直接的使用方式是在启动前通过 shell 导出export OPENAI_API_KEYsk-xxx export SILICONFLOW_API_KEYsk-xxx dbgpt start webserver仓库的 scripts/install/install.sh 在检测到未配置模型密钥时也会给出同样的提示Set it before starting: export OPENAI_API_KEYsk-xxx。在代理proxy模型场景下更推荐直接在 TOML 配置中引用环境变量。以仓库自带的 configs/dbgpt-proxy-siliconflow.toml 为范例[[models.llms]] name Qwen/Qwen2.5-Coder-32B-Instruct provider proxy/siliconflow api_key ${env:SILICONFLOW_API_KEY} [[models.embeddings]] name BAAI/bge-large-zh-v1.5 provider proxy/openai api_url https://api.siliconflow.cn/v1/embeddings api_key ${env:SILICONFLOW_API_KEY}这样配置文件的其余部分可以安全提交到版本库密钥只在运行环境中通过环境变量提供。更多模型提供方的接入说明参见 docs/docs/getting-started/providers。服务与元数据库配置DB-GPT 使用一个元数据库metadata database保存应用元信息。下表为服务端核心环境变量变量说明默认值DBGPT_LOG_LEVEL日志级别INFOLOCAL_DB_TYPE元数据库类型sqliteLOCAL_DB_PATHSQLite 数据库路径data/default_sqlite.dbMYSQL_HOSTMySQL 主机127.0.0.1MYSQL_PORTMySQL 端口3306MYSQL_USERMySQL 用户名rootMYSQL_PASSWORDMySQL 密码—MYSQL_DATABASEMySQL 数据库名dbgpt日志级别的完整取值与源码细节DBGPT_LOG_LEVEL在 packages/dbgpt-core/src/dbgpt/util/utils.py 中被多处消费。首先模块级函数_get_logging_level()第 28-29 行直接读取os.getenv(DBGPT_LOG_LEVEL, INFO)其次LoggingParameters第 32-54 行将其建模为可配置参数默认值即为${env:DBGPT_LOG_LEVEL:-INFO}并声明了合法取值FATAL、ERROR、WARNING、INFO、DEBUG、NOTSETsetup_logging_level会把字符串级别转换为 Python 标准库级别logging_str_to_uvicorn_level则将其映射为 Uvicorn 的级别如DEBUG - debug、NOTSET - info。因此排查网络或模型调用问题时把级别调到DEBUG是最直接的手段。元数据库的默认值来源LOCAL_DB_TYPE与LOCAL_DB_PATH的默认值sqlite、data/default_sqlite.db同样来自 Config 类 第 206-218 行self.LOCAL_DB_PATH os.getenv(LOCAL_DB_PATH, data/default_sqlite.db) self.LOCAL_DB_TYPE os.getenv(LOCAL_DB_TYPE, sqlite)同一区块还读取了LOCAL_DB_NAME默认dbgpt、LOCAL_DB_PORT默认 3306、LOCAL_DB_USER默认root等变量。可以看到MYSQL_*与LOCAL_DB_*实际上对应同一套元数据库参数在 Docker 等场景下MYSQL_HOST、MYSQL_PORT、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE直接决定 webserver 连接 MySQL 元数据库的方式。启动时若未配置MYSQL_PASSWORD需确保与目标数据库实际密码一致否则 webserver 将无法完成建表与初始化。GPU 与硬件相关变量变量说明示例CUDA_VISIBLE_DEVICES限制哪些 GPU 可见0,1DEVICE强制设备类型cuda、cpu、mps在多卡机器上CUDA_VISIBLE_DEVICES0,1可将进程限定到 0、1 号 GPUDEVICE用于在无 GPU 环境cpu或 Apple Siliconmps上强制指定推理设备。注意这类变量应在启动服务之前于 shell 中导出或在容器编排文件中声明因为它们需要在模型运行时Torch 初始化、显存探测之前生效。网络与代理相关变量变量说明示例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.1UV_INDEX_URL主要影响依赖安装阶段。仓库安装脚本 scripts/install/install.sh 第 279-280 行在启用国内镜像时正是写入该变量export UV_INDEX_URLhttps://pypi.tuna.tsinghua.edu.cn/simpleHTTP_PROXY/HTTPS_PROXY/NO_PROXY则影响模型 API 调用、外部服务连接等出站流量。若网络环境需要代理务必确保NO_PROXY中包含内部服务地址如localhost,127.0.0.1以及内网 MySQL、模型控制器地址避免内网流量被错误转发到代理。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兜底官方示例配置 configs/dbgpt-app-config.example.toml 是这两种语法的完整示范[system] language ${env:DBGPT_LANG:-zh} [[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}注意区分${env:OPENAI_API_KEY}表示该 Key 是必填项缺失即报错而${env:OPENAI_API_BASE:-https://api.openai.com/v1}表示带默认值未设置时优雅回退。因此models.llms.api_key这类敏感必填字段应当使用不带默认值的形式让配置在启动时fail fast。源码级原理替换发生在解析阶段环境变量替换由 packages/dbgpt-core/src/dbgpt/util/configure/manager.py 中的ConfigurationManager实现。核心是_resolve_env_vars函数第 195-225 行它通过正则_DEFAULT_ENV_VAR_PATTERN r\${env:([^}])}匹配占位符对${env:VAR}调用os.environ.get(env_name)若变量不存在且没有默认值抛出ValueError(fEnvironment variable {env_name} not found)对${env:VAR:-default}按:-分隔后取默认值替换。替换发生在parse_config/_convert_to_dataclass阶段涉及字符串字段、嵌套 dataclass、list 与 dict 中的字符串值_process_dataclass_env_vars会递归处理因此无论是[[models.llms]]数组下的api_key还是[service.web]下的cors_allowed_origins都能被正确解析。此外ConfigurationManager还提供resolve_env_varsFalse开关以显式禁用替换。仓库的单元测试 packages/dbgpt-core/src/dbgpt/util/tests/configure/test_manager.py 对这一行为做了完整覆盖可作为理解语义的权威参考test_basic_env_var第 528-552 行${env:TEST_HOST}被替换为环境变量实际值test_env_var_with_default第 555-585 行${env:LANG:-en}在变量未设置时回退为en设置后取zhtest_nested_env_vars第 588-614 行嵌套配置与端口字段中的${env:MODEL_PORT}被正确替换为9000test_env_vars_in_list第 617-636 行列表元素中的占位符逐一替换test_missing_env_var第 639-654 行缺失变量且无默认值时的行为验证test_disable_env_vars第 657-673 行resolve_env_varsFalse时占位符保持原样。Docker 与 Docker Compose 环境变量容器化部署是环境变量最主要的应用场景之一。docker run 传递方式docker run -it --rm \ -e SILICONFLOW_API_KEYyour-key \ -e DBGPT_LOG_LEVELDEBUG \ -p 5670:5670 \ eosphorosai/dbgpt-openai-e KEYVALUE将环境变量注入容器进程-p 5670:5670将容器内 webserver 端口映射到宿主机。Docker Compose 传递方式services: webserver: environment: - SILICONFLOW_API_KEY${SILICONFLOW_API_KEY} - DBGPT_LOG_LEVELINFO${SILICONFLOW_API_KEY}会被 Compose 从宿主环境展开后传入容器因此宿主机需要先完成export SILICONFLOW_API_KEYsk-xxx或使用.env文件。仓库根目录的 docker-compose.yml 给出了一个可运行的完整实例它同时启动 MySQLmysql/mysql-server与 webservereosphorosai/dbgpt-openai:latest并通过environment注入SILICONFLOW_API_KEY、MYSQL_HOSTdb、MYSQL_PORT3306、MYSQL_DATABASEdbgpt、MYSQL_USERroot、MYSQL_PASSWORDaa123456webserver 再以--config /app/configs/dbgpt-proxy-siliconflow-mysql.toml启动其首行注释也明确提示了启动方式SILICONFLOW_API_KEY${SILICONFLOW_API_KEY} docker compose up -d常见排查场景启动时报ValueError: Environment variable xxx not foundTOML 中使用了${env:VAR}且该变量未在环境中设置。先确认变量已导出echo $OPENAI_API_KEY或将占位符改为${env:VAR:-default}形式提供兜底值。模型调用返回鉴权失败优先检查对应提供方的*_API_KEY是否注入正确参考 Config 类 中各家模型的os.getenv读取逻辑确认变量名拼写例如 Claude 使用的是ANTHROPIC_API_KEY。需要更详细的日志将DBGPT_LOG_LEVEL设为DEBUG合法值还包括FATAL、ERROR、WARNING、INFO、NOTSET日志级别会同时作用于 Python logging 与 Uvicorn。元数据库初始化失败检查LOCAL_DB_TYPE/MYSQL_*系列变量与目标数据库是否匹配SQLite 模式下确认LOCAL_DB_PATH对应目录可写。集群模式下模型不可达确认MODEL_SERVER默认http://127.0.0.1:8000与LLM_MODEL是否指向实际运行的模型控制器。下一步完整配置参考Config Reference模型提供方接入Providers更多排查主题Troubleshooting 索引【免费下载链接】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），仅供参考