适用环境：本文适用于主流 Linux 发行版（如 CentOS 7/8， Ubuntu 18.04/20.04/22.04） + 宝塔面板 7.x + Python 3.6+ + MySQL 5.6+/MariaDB 10.x + Django/Flask 等主流框架环境。若你的环境与上述不同，执行前请先确认版本兼容性。

一、问题/场景描述

在使用宝塔面板部署Python项目（如Django、Flask）时，经常遇到应用程序无法连接到数据库（如MySQL、MariaDB）的问题。典型表现为项目启动时报错，提示“Can‘t connect to MySQL server”、“Access denied for user”或“Connection refused”等，导致网站或服务无法正常运行。

二、原因分析

数据库连接失败通常由多方面原因造成。最常见的是数据库服务未启动或监听地址配置不当。其次，连接参数（主机、端口、用户名、密码）在项目配置文件（如settings.py）中填写错误。此外，数据库用户权限不足或未授权从本地主机（localhost）以外的地址访问，也是一个关键因素。防火墙（如宝塔面板自带的安全组或系统iptables）未开放数据库端口（默认3306）也会导致连接被拒绝。

三、详细解决步骤

步骤1：检查数据库服务状态

首先，登录宝塔面板，确保数据库服务正在运行。

# 通过宝塔面板“软件商店”查看MySQL/MariaDB运行状态。
# 或通过SSH终端执行命令检查：
systemctl status mysqld
# 或
systemctl status mariadb

如果服务未运行，请启动它。

systemctl start mysqld

步骤2：核对项目数据库连接配置

检查你的Python项目配置文件，确保连接参数与宝塔面板数据库信息完全一致。以Django的settings.py为例：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'NAME': 'your_database_name', # 数据库名
        'USER': 'your_username',      # 宝塔面板数据库用户名
        'PASSWORD': 'your_password',  # 宝塔面板数据库密码
        'HOST': '127.0.0.1',          # 或 'localhost'， 切勿使用外网IP
        'PORT': '3306',               # 默认端口
        'OPTIONS': {'charset': 'utf8mb4'},
    }
}

重点确认HOST应为‘127.0.0.1’或‘localhost’，密码是否正确。

步骤3：检查数据库用户权限

登录宝塔面板的“数据库”管理页面，检查对应用户是否有权限访问目标数据库，以及其“访问权限”是否包含“本地服务器(127.0.0.1)”。如果项目通过Python管理器（如uWSGI）以特定系统用户运行，可能需要授权该用户从本地访问。

也可以通过phpMyAdmin或命令行检查：

-- 登录MySQL后执行，查看用户权限
SELECT host, user FROM mysql.user WHERE user='your_username';
-- 如果host不是‘localhost’或‘127.0.0.1’，可能需要修改
GRANT ALL PRIVILEGES ON your_database_name.* TO 'your_username'@'localhost' IDENTIFIED BY 'your_password';
FLUSH PRIVILEGES;

步骤4：检查防火墙与安全组

确保数据库端口（默认3306）在防火墙中是开放的。在宝塔面板的“安全”页面，检查3306端口是否在放行列表中。如果服务器提供商（如阿里云、腾讯云）有安全组策略，也需确保已放行3306端口（通常仅需本地访问，无需公网开放）。

# 在服务器终端检查端口监听情况，确保MySQL监听在127.0.0.1:3306
netstat -tlnp | grep 3306
# 预期输出类似：tcp 0 0 127.0.0.1:3306 0.0.0.0:* LISTEN

如果监听地址是0.0.0.0:3306，虽然可以连接，但安全风险较高，建议在配置文件中绑定127.0.0.1。

步骤5：安装Python数据库连接驱动

确保项目环境中已安装正确的数据库驱动。对于MySQL/MariaDB，常用的是PyMySQL或mysqlclient。

# 进入项目虚拟环境后安装
pip install pymysql
# 或
pip install mysqlclient

对于Django，如果使用PyMySQL，还需在项目__init__.py文件中添加：

import pymysql
pymysql.install_as_MySQLdb()

四、注意事项

修改数据库配置或用户权限后，务必重启数据库服务及Python应用（如uWSGI、Gunicorn服务）。生产环境中，数据库密码应使用强密码并妥善保管，避免使用简单密码。不建议将数据库HOST设置为公网IP，这会导致严重安全风险。定期备份数据库以防操作失误。

五、适用环境

本文适用于在宝塔面板上使用Python框架（Django、Flask等）部署Web项目，并连接MySQL或MariaDB数据库时，遇到连接失败问题的场景。

宝塔面板Python项目数据库连接失败排查与解决指南