检查数据库配置文件

确保 configs/db_config.py 或类似配置文件中数据库连接参数正确。主要参数包括：

• host: 数据库服务器地址（如 localhost 或远程 IP）
• port: 数据库端口（MySQL 默认 3306，PostgreSQL 默认 5432）
• user: 数据库用户名
• password: 数据库密码
• database: 数据库名称

示例配置：

DATABASE_CONFIG = {
    "host": "localhost",
    "port": 3306,
    "user": "llamauser",
    "password": "securepassword",
    "database": "llamafactory_db"
}

验证数据库服务状态

通过命令行工具检查数据库服务是否运行正常。

• MySQL: 执行 mysql -u [用户名] -p 并输入密码测试登录
• PostgreSQL: 执行 psql -U [用户名] -d [数据库名]
  若连接失败，需检查数据库服务是否启动（如 sudo systemctl status mysql）。

检查依赖库版本

确认 Python 数据库驱动库版本与数据库兼容：

• MySQL: 安装 pip install mysql-connector-python 或 pymysql
• PostgreSQL: 安装 pip install psycopg2-binary
  通过 pip show [包名] 查看已安装版本，必要时升级：

pip install --upgrade mysql-connector-python psycopg2-binary

测试独立数据库连接

在 Python 环境中独立测试连接，排除框架干扰：

import mysql.connector  # 或 psycopg2
try:
    conn = mysql.connector.connect(
        host="localhost",
        user="llamauser",
        password="securepassword",
        database="llamafactory_db"
    )
    print("连接成功")
    conn.close()
except Exception as e:
    print(f"连接失败: {e}")

查看详细错误日志

运行 llamafactory-cli webui 时添加调试参数（如 --verbose），或直接查看日志文件（通常位于 logs/ 目录）。错误日志可能包含具体连接失败原因（如权限拒绝、网络超时等）。

防火墙和网络配置

检查服务器防火墙是否放行数据库端口：

• Linux: 执行 sudo ufw allow 3306（MySQL）或 sudo ufw allow 5432（PostgreSQL）
• Windows: 在防火墙高级设置中添加入站规则

若数据库位于远程服务器，确保云服务商安全组规则允许访问。

重建数据库结构

若数据库表缺失，可能需要重新初始化。执行以下命令前备份现有数据：

llamafactory-cli initdb --force  # 根据实际工具命令调整

其他可能原因

• 数据库连接池耗尽：检查 pool_size 配置，适当增加或减少
• 环境变量冲突：确保未通过环境变量（如 DATABASE_URL）覆盖配置文件
• 特殊字符密码：若密码包含 @、! 等符号，尝试用引号包裹或转义