Django 连接 MySQL 出现 OperationalError 2003 错误，本质是客户端无法通过网络连接到数据库服务，优先排查数据库服务是否运行、端口是否开放以及主机地址配置是否正确。
先说结论：该错误通常意味着网络层面的连接被拒绝或超时，而非密码错误或 SQL 语法问题，应先确保数据库服务可达。
- 先确认 MySQL 服务状态和本地网络连通性
- 先处理防火墙规则或 MySQL 绑定地址配置
- 再验证 Django 应用能否成功建立数据库连接
命令速用版
如果是在 Linux 服务器上，可以快速执行以下命令检查基础状态：
# 检查 MySQL 服务是否运行
systemctl status mysql# 检查端口是否监听（默认 3306，推荐使用 ss 替代 netstat）
ss -tlnp | grep 3306# 测试网络连通性（替换为实际 IP）
telnet 127.0.0.1 3306如果 telnet 不通，说明网络或服务层面有问题，不要急着改 Django 代码。
为什么会这样
OperationalError 2003 对应的底层错误通常是 CR_CONN_HOST_ERROR，意思是客户端尝试连接服务器时失败了。这不像 1045 错误（访问拒绝）那样是密码或权限问题，2003 错误更偏向于“路不通”。
常见原因包括 MySQL 服务没启动、防火墙拦截了 3306 端口、MySQL 配置只监听了本地回环地址（127.0.0.1）但 Django 配置了远程 IP，或者云服务器的安全组未放行数据库端口。
分步处理
按照以下顺序排查，每步完成后观察错误是否变化：
1. 确认数据库服务状态
登录数据库所在服务器，检查服务是否存活。如果服务未运行，Django 自然连不上。
systemctl status mysql
# 或
service mysql status如果显示 inactive 或 failed，尝试启动服务：systemctl start mysql。
2. 检查监听地址配置
查看 MySQL 配置文件（通常是 /etc/mysql/mysql.conf.d/mysqld.cnf 或 /etc/my.cnf），找到 bind-address 项。
bind-address = 127.0.0.1如果 Django 和 MySQL 在同一台机器，保持 127.0.0.1 即可，Django settings 中 HOST 也填 127.0.0.1。如果 Django 在另一台机器，需要改为 0.0.0.0 或具体内网 IP，并重启 MySQL 服务。
注意：生产环境将 bind-address 设置为 0.0.0.0 存在数据库暴露风险，务必配合严格的安全组限制，仅允许受信任的内网 IP 访问，避免直接暴露在公网。
3. 检查防火墙和安全组
服务器内部防火墙（如 ufw、iptables）和云厂商的安全组都可能拦截流量。
# Ubuntu 示例，放行 3306
sudo ufw allow 3306云平台控制台需确认实例安全组入方向是否允许 TCP 3306 端口。
4. 核对 Django 配置
打开 settings.py，检查 DATABASES 配置项。
DATABASES = {'default': {'ENGINE': 'django.db.backends.mysql','NAME': 'your_db_name','USER': 'your_user','PASSWORD': 'your_password','HOST': '127.0.0.1', # 注意这里是否填错'PORT': '3306',}
}确保 HOST 与 MySQL 实际监听地址一致。注意 localhost 在某些环境下可能解析为 Unix socket 连接，而 127.0.0.1 强制走 TCP 协议，建议统一使用 127.0.0.1 排查。
5. 修复 MySQL 用户权限
即使网络通了，MySQL 用户表可能限制了 host。例如用户只允许 localhost 登录，但 Django 用远程 IP 连接。登录 MySQL 执行以下命令授权：
# 登录 MySQL
mysql -u root -p# 创建用户并授权（% 代表允许任意主机，生产环境建议指定具体 IP）
CREATE USER 'your_user'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON your_db_name.* TO 'your_user'@'%';
FLUSH PRIVILEGES;如果用户已存在，仅修改 host 权限：
UPDATE mysql.user SET Host='%' WHERE User='your_user';
FLUSH PRIVILEGES;怎么验证是否生效
不要直接重启项目看日志，建议使用 Django shell 快速测试连接：
python manage.py shell
>>> from django.db import connection
>>> connection.ensure_connection()
>>> print("Connection successful")如果没有抛出异常且打印成功，说明连接已恢复。也可以尝试执行一次简单查询：from django.contrib.auth.models import User; User.objects.count()。
也可以在服务器上使用 MySQL 客户端测试：
mysql -h 127.0.0.1 -P 3306 -u your_user -p常见坑
1. localhost 与 127.0.0.1 的区别：在 MySQL 客户端驱动中，localhost 可能尝试使用 Unix socket 文件连接，而 127.0.0.1 使用 TCP/IP。如果 MySQL 未配置 socket 路径或权限不对，填 localhost 可能报错，建议显式填写 IP 地址。
2. 云服务器安全组：很多新手检查了系统防火墙，却忽略了云控制台的安全组规则，导致外网或内网其他机器无法访问。
3. 用户主机限制：即使网络通了，MySQL 用户表（user table）中可能限制了 host。需检查 MySQL 用户权限：SELECT user, host FROM mysql.user;。
参考来源
- Django Documentation, "DATABASES", https://docs.djangoproject.com/en/stable/ref/settings/#database-host
- MySQL Documentation, "Server Error Reference", https://dev.mysql.com/doc/refman/8.0/en/server-error-reference.html
原文链接：https://www.zjcp.cc/ask/10930.html