安装问题
这里整理了 DB-GPT 安装过程中常见的问题及对应的解决方法。
Python 版本错误
现象： 出现 Python 3.10+ required 或版本不匹配相关报错。
解决方法：
python --version
# 必须为 3.10 或更高版本
如果你的环境中存在多个 Python 版本，可以显式指定使用的版本：
uv python pin 3.11
uv sync --all-packages ...
找不到 uv
现象： command not found: uv
解决方法：
# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# 验证
uv --version
如果已经安装但仍然找不到命令，请确认它已加入 PATH：
export PATH="$HOME/.local/bin:$PATH"
依赖解析失败
现象： uv sync 因依赖冲突而失败。
解决方法：
- 确认你使用的是最新版本的 uv：
uv self update
- 清理缓存后重试：
uv cache clean
uv sync --all-packages --extra "base" ...
- 如果你使用国内镜像，可以设置索引地址：
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync --all-packages ...
原生扩展构建失败
现象： 在 uv sync 过程中出现编译错误，尤其常见于 tokenizers、grpcio、psutil 等包。
解决方法：
先安装构建工具：
# Ubuntu/Debian
sudo apt-get install build-essential python3-dev
# macOS
xcode-select --install
# CentOS/RHEL
sudo yum groupinstall "Development Tools"
对于依赖 Rust 的包（例如 tokenizers）：
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source $HOME/.cargo/env
CUDA / GPU 问题
现象： CUDA not available 或无法检测到 GPU。
解决方法：
- 验证 CUDA 是否安装正确：
nvidia-smi
# 应显示 GPU 信息以及 CUDA 版本
- 安装匹配的 CUDA extra：
# 对应 CUDA 12.1
uv sync --all-packages --extra "cuda121" ...
# 对应 CUDA 12.4
uv sync --all-packages --extra "cuda124" ...
- 验证 PyTorch 是否能识别 GPU：
uv run python -c "import torch; print(torch.cuda.is_available())"
端口冲突
现象： 5670 端口提示 Address already in use。
解决方法：
# 查找占用该端口的进程
lsof -i :5670
# 结束该进程
kill -9 <PID>
或者改用其他端口启动：
uv run dbgpt start webserver --config configs/your-config.toml --port 5671
Docker 相关问题
权限不足
现象： 执行 Docker 命令时出现 permission denied。
解决方法：
# 将当前用户加入 docker 用户组
sudo usermod -aG docker $USER
# 退出并重新登录
找不到 NVIDIA runtime
现象： docker: Error response from daemon: could not select device driver
解决方法： 安装 NVIDIA Container Toolkit：
# Ubuntu
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
数据库问题
MySQL 连接被拒绝
现象： 启动时出现 Can't connect to MySQL server。
解决方法：
- 验证 MySQL 是否已启动：
mysql -h127.0.0.1 -uroot -p -e "SELECT 1"
- 检查配置值是否与你的 MySQL 实例一致：
[service.web.database]
type = "mysql"
host = "127.0.0.1" # 不要写成 'localhost'，请直接使用 IP
port = 3306
user = "root"
database = "dbgpt"
password = "your-password"
- 如果数据库不存在，先创建：
mysql -h127.0.0.1 -uroot -p < ./assets/schema/dbgpt.sql
还是没解决？
- 查看更详细的 FAQ
- 搜索 GitHub Issues
- 在 GitHub Discussions 中提问