Django连接MySQL/MariaDB的三层校验与字符集配置指南

1. 这不是“装个数据库”那么简单：Django 与 MySQL/MariaDB 在 Ubuntu 14.04 上的真实协作逻辑

你点开这篇博文，大概率是因为在部署一个 Django 项目时，终端里突然跳出django.core.exceptions.ImproperlyConfigured: Error loading MySQLdb module，或者pymysql.err.OperationalError: (1045, "Access denied for user...")。你照着某篇“三分钟搞定 MySQL + Django”的教程敲完命令，结果python manage.py migrate死活不认你的数据库——它既不报错，也不建表，就卡在那儿，像一台没通电的收音机。这不是你手残，而是 Ubuntu 14.04 这个特定版本，把“数据库接入”这件事，从一道填空题，硬生生变成了多选题+简答题+实操题的组合卷。

Ubuntu 14.04（Trusty Tahr）发布于 2014 年 4 月，其生命周期已于 2019 年 4 月结束。但至今仍有大量遗留系统、教学环境、嵌入式网关或老旧服务器运行于此。它的关键特征是：Python 默认为 2.7.6，系统包管理器apt中的mysql-server默认安装的是 MySQL 5.5，而mariadb-server则是 MariaDB 5.5。这两个数据库在协议层完全兼容，但在系统级服务管理、默认配置路径、用户权限初始化方式上，存在几处肉眼难辨却致命的差异。Django 本身并不关心你用的是 MySQL 还是 MariaDB，它只认mysqlclient或PyMySQL这两个 Python 驱动。问题就出在这里：mysqlclient是 C 扩展，它编译时需要链接系统级的 MySQL 客户端开发库（libmysqlclient-dev），而这个库在 Ubuntu 14.04 的 apt 源里，对 MySQL 和 MariaDB 的支持是割裂的。如果你装了 MariaDB，却去apt install libmysqlclient-dev，它会拉取 MySQL 5.5 的头文件；反之亦然。这种“驱动-客户端库-数据库服务”三者之间的版本错配，就是绝大多数人卡住的第一道墙。

更隐蔽的问题在于字符集。Ubuntu 14.04 的mysql-server包默认配置文件/etc/mysql/my.cnf中，[mysqld]段落下的character-set-server默认值是latin1，而 Django 项目的settings.py里DATABASES配置项中的OPTIONS字典，如果不显式指定'charset': 'utf8mb4'，Django 就会以latin1编码连接数据库。这会导致中文插入时变成乱码，或者更糟——在执行CREATE TABLE时，Django 的迁移系统会因为字符集不匹配而静默失败，日志里只有一行Applying ...，然后就没了下文。我第一次遇到这个问题时，花了整整一个下午反复检查models.py的CharField定义，最后才发现罪魁祸首是/etc/mysql/my.cnf里那行被注释掉的# character-set-server = utf8。

所以，这篇内容的核心价值，不是教你“如何安装 MySQL”，而是帮你建立一个可验证、可回溯、可复现的三层校验模型：第一层，确认数据库服务本身是否健康运行（systemctl status mysql或service mysql status）；第二层，确认 Python 驱动能否独立连接数据库（python -c "import pymysql; conn = pymysql.connect(...)"）；第三层，确认 Django 的 ORM 层能否通过该驱动完成一次完整的迁移流程（python manage.py migrate --plan）。只有当这三层全部绿灯，你才能说“Django 已经真正用上了 MySQL/MariaDB”。接下来的所有步骤，都将围绕这三层校验展开，每一步都附带“为什么必须这么做”的底层原理和“如果错了会怎样”的真实后果。

2. 环境准备：Ubuntu 14.04 下的“双数据库”抉择与驱动编译陷阱

在 Ubuntu 14.04 上启动一个 Django 项目，第一步永远不是写代码，而是做一次清醒的“数据库选型决策”。这个决策不是基于性能排行榜或社区热度，而是基于你当前系统的软件源状态和运维习惯。MySQL 和 MariaDB 在这里不是二选一，而是一个“兼容性矩阵”问题。

2.1 MySQL 5.5 与 MariaDB 5.5：Ubuntu 14.04 的官方双生子

我们先看系统层面的事实：

# 查看可用的数据库服务包 apt-cache search "mysql-server\|mariadb-server" # 输出通常包含： # mysql-server - MySQL database server (metapackage depending on the latest version) # mysql-server-5.5 - MySQL database server binaries and system database setup # mariadb-server - MariaDB database server (metapackage) # mariadb-server-5.5 - MariaDB database server binaries and system database setup

注意关键词：mysql-server-5.5和mariadb-server-5.5。这意味着，无论你选择哪个，你拿到的都是 5.5 版本。它们的 SQL 语法、存储引擎（MyISAM/InnoDB）、网络协议（3306 端口）完全一致。区别在于：

• MySQL 5.5：由 Oracle 维护，/etc/mysql/my.cnf是主配置文件，/var/lib/mysql/是数据目录，mysql命令行客户端默认连接localhost。
• MariaDB 5.5：由 MariaDB Foundation 维护，/etc/mysql/my.cnf同样是主配置文件，但它的my.cnf文件末尾通常会include /etc/mysql/conf.d/*.cnf，且mysql客户端在连接localhost时，会优先尝试 Unix socket（/var/run/mysqld/mysqld.sock），而非 TCP/IP。

这个细微差别，在 Django 的DATABASES配置中会直接体现为HOST参数的选择。如果你的HOST写成'127.0.0.1'，Django 会强制走 TCP/IP；如果写成'localhost'，在 MariaDB 下，它会走 Unix socket，速度略快，但要求mysql客户端和mysqld服务在同一台机器上，且 socket 文件路径正确。而 Ubuntu 14.04 的 MariaDB 5.5，默认 socket 路径是/var/run/mysqld/mysqld.sock，但mysql-client包可能期望/tmp/mysql.sock。这就是为什么很多人mysql -u root -p能连，但 Django 却报Can't connect to local MySQL server through socket '/tmp/mysql.sock'的根本原因。

提示：在 Ubuntu 14.04 上，我强烈建议初学者选择MariaDB 5.5。原因有三：一是它完全开源，无商业许可风险；二是它的mysql_secure_installation脚本比 MySQL 5.5 更友好，能自动处理匿名用户、测试数据库等安全项；三是它的apt源更新更稳定，不会像 MySQL 5.5 那样在 Trusty 的后期出现依赖冲突。当然，如果你的生产环境已明确要求 MySQL，那就必须坚持到底，不能中途切换。

2.2 驱动选型：mysqlclientvsPyMySQL—— 性能与便利的终极权衡

Django 官方文档推荐mysqlclient，因为它是一个 C 扩展，性能比纯 Python 的PyMySQL高出 3~5 倍。但这个“高”是有代价的：它需要编译。而 Ubuntu 14.04 的编译环境，恰恰是最大的雷区。

我们来拆解mysqlclient的编译依赖链：

1. python-dev：提供 Python 的 C API 头文件（Python.h等）；
2. libmysqlclient-dev：提供 MySQL 客户端的 C 库头文件（mysql.h,mysqld_error.h等）；
3. build-essential：提供gcc,make等编译工具。

问题来了：libmysqlclient-dev这个包，在 Ubuntu 14.04 的官方源里，只有一个版本，即libmysqlclient-dev，它对应的是mysql-server-5.5。如果你已经安装了mariadb-server-5.5，那么apt install libmysqlclient-dev会成功，但它拉取的头文件是为 MySQL 5.5 编写的。当你用pip install mysqlclient时，编译过程会顺利通过，但运行时，import MySQLdb可能会报ImportError: libmysqlclient.so.18: cannot open shared object file。这是因为 MariaDB 5.5 的共享库名是libmariadbclient.so.18，而mysqlclient在运行时却去找libmysqlclient.so.18。

解决方案有两个，且只能二选一：

• 方案 A（推荐）：放弃mysqlclient，拥抱PyMySQL
PyMySQL是一个纯 Python 实现的 MySQL 协议客户端，它不依赖任何 C 库，pip install PyMySQL之后，只需在 Django 项目的__init__.py（与settings.py同级）中添加两行代码：

  import pymysql pymysql.install_as_MySQLdb()

  这两行代码的作用，是将PyMySQL的模块对象注册为MySQLdb，从而欺骗 Django，让它以为自己正在使用mysqlclient。实测下来，在 Ubuntu 14.04 + Django 1.8/1.11 上，PyMySQL的性能损失几乎不可感知，且 100% 规避了所有编译错误。这是我给所有新手的首选方案。

• 方案 B（进阶）：为mysqlclient构建 MariaDB 兼容版
  如果你追求极致性能，且愿意承担额外的维护成本，可以手动下载 MariaDB 5.5 的源码包，从中提取include/目录下的头文件，并创建一个符号链接：

  # 下载 MariaDB 5.5 源码（例如 mariadb-5.5.68.tar.gz） tar -xzf mariadb-5.5.68.tar.gz sudo cp -r mariadb-5.5.68/include/* /usr/include/mysql/ sudo ln -sf /usr/lib/x86_64-linux-gnu/libmariadbclient.so.18 /usr/lib/x86_64-linux-gnu/libmysqlclient.so.18 pip install mysqlclient

  这个操作非常危险，因为它会覆盖系统级的 MySQL 头文件。一旦你后续又想装回 MySQL 5.5，就必须手动清理这些文件。因此，除非你有明确的性能压测报告证明PyMySQL不够用，否则请不要走这条路。

注意：PyMySQL的一个隐藏优势是，它对utf8mb4字符集的支持比mysqlclient更原生。在settings.py的DATABASES配置中，你只需加上'charset': 'utf8mb4'，PyMySQL就会自动在连接时发送SET NAMES utf8mb4，而mysqlclient有时需要额外配置'init_command': "SET sql_mode='STRICT_TRANS_TABLES'"来规避某些边缘 case。

3. 数据库服务初始化：从mysql_secure_installation到 Django 用户权限的最小化授予

很多教程到这里就草草结束了：“运行sudo mysql_secure_installation，一路按回车就行”。这是最危险的建议。mysql_secure_installation是一个脚本，它的作用是执行一系列预设的安全加固操作，但它不会为你创建一个专供 Django 使用的数据库用户。如果你在settings.py里直接用root用户连接数据库，那你的 Django 项目就等于把整个数据库的 root 密码，明文写在了一个可能被 Git 误提交的文件里。这在任何安全审计中，都是零分项。

3.1mysql_secure_installation的真实作用域与局限性

让我们看看这个脚本到底做了什么（以 MariaDB 5.5 为例）：

# 运行脚本 sudo mysql_secure_installation # 它会依次询问： # 1. Set root password? (Y/n) → 设置 root 用户的密码 # 2. Remove anonymous users? (Y/n) → 删除用户名为空的用户（默认存在） # 3. Disallow root login remotely? (Y/n) → 禁止 root 用户从远程登录（只允许 localhost） # 4. Remove test database and access to it? (Y/n) → 删除名为 `test` 的数据库及其所有权限 # 5. Reload privilege tables now? (Y/n) → 重新加载权限表，使上述更改生效

这五步，本质上是在清理 MariaDB/MySQL 的默认安装后门。它没有创建新用户，没有创建新数据库，也没有授予权限。它只是让数据库从“出厂设置”变成“可以上线的基础安全状态”。做完这五步后，你应该能用mysql -u root -p成功登录，但此时，SELECT User, Host FROM mysql.user;的输出里，只有root@localhost这一行。Django 项目需要的，是一个全新的、权限受限的用户。

3.2 创建 Django 专用数据库与用户的四步法

这是一个必须手动执行、且不能出错的流程。我把它拆解为四个原子操作，每一步都有其不可替代的逻辑：

第一步：登录并创建数据库

mysql -u root -p # 输入 root 密码后，进入 MariaDB 命令行 CREATE DATABASE myproject CHARACTER SET = 'utf8mb4' COLLATE = 'utf8mb4_unicode_ci'; # 注意：这里指定了字符集和排序规则。`utf8mb4` 是 MySQL/MariaDB 对完整 UTF-8 的实现， # 它能存储 emoji 和四字节的中文生僻字。`utf8mb4_unicode_ci` 是一个更智能的排序规则， # 它能正确处理中文、德语变音符号等。

第二步：创建专用用户并设置强密码

CREATE USER 'myprojectuser'@'localhost' IDENTIFIED BY 'a_strong_password_here'; # 用户名 `myprojectuser` 和主机 `'localhost'` 必须严格匹配。 # `'localhost'` 表示该用户只能从本机的 Unix socket 连接。 # 如果你未来要从其他机器连接（比如开发机连服务器），则需改为 `'%'`，但这会极大增加风险。

第三步：授予最小必要权限

GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON myproject.* TO 'myprojectuser'@'localhost'; # 这是 Django 迁移（`migrate`）和日常 CRUD 所需的全部权限。 # `SELECT` 用于查询，`INSERT/UPDATE/DELETE` 用于增删改， # `CREATE/DROP` 用于创建/删除表（迁移时必需）， # `INDEX` 用于创建索引（Django 的 `db_index=True` 会用到）， # `ALTER` 用于修改表结构（`makemigrations` 生成的 `AlterField` 等）。 # 绝对不要授予 `GRANT OPTION` 或 `SUPER` 权限，这对 Django 是完全不必要的。

第四步：刷新权限并退出

FLUSH PRIVILEGES; EXIT;

FLUSH PRIVILEGES是关键。它告诉 MariaDB，刚才的GRANT语句已经生效，现在就可以用新用户登录了。没有这一步，新用户会一直提示Access denied。

实操心得：我曾经在一个客户项目中，因为漏掉了FLUSH PRIVILEGES，导致整个下午都在排查 Django 的settings.py配置。后来发现，只要在 MariaDB 命令行里再执行一遍SHOW GRANTS FOR 'myprojectuser'@'localhost';，就能立刻看到权限列表。这是一个快速验证权限是否生效的黄金命令。把它加入你的排错清单。

4. Django 配置深度解析：settings.py中DATABASES的每一个字段都关乎成败

Django 的DATABASES配置，表面上看只是一个 Python 字典，但它的每一个键值对，都对应着底层数据库连接的一个具体参数。在 Ubuntu 14.04 这个老环境中，任何一个字段的微小偏差，都可能导致连接失败、编码错误或性能瓶颈。我们逐个字段深挖。

4.1ENGINE: 驱动选择的最终落地点

'DATABASES': { 'default': { 'ENGINE': 'django.db.backends.mysql', # ... } }

这个字段的值，决定了 Django 使用哪个数据库后端。django.db.backends.mysql是唯一正确的选项，无论你用的是 MySQL 还是 MariaDB。Django 的 MySQL 后端，是通过MySQLdb模块（mysqlclient）或pymysql模块（PyMySQL）来实现的。它不区分底层是 MySQL 还是 MariaDB，只认 MySQL 协议。所以，你不需要、也不应该写成django.db.backends.mariadb——这个后端根本不存在。

4.2NAME,USER,PASSWORD,HOST,PORT: 连接四要素的精确匹配

'DATABASES': { 'default': { 'NAME': 'myproject', 'USER': 'myprojectuser', 'PASSWORD': 'a_strong_password_here', 'HOST': 'localhost', # 关键！ 'PORT': '3306', } }

• NAME：必须与CREATE DATABASE时指定的数据库名完全一致，包括大小写。MySQL/MariaDB 在 Linux 下，数据库名是区分大小写的。
• USER和PASSWORD：必须与CREATE USER时指定的用户名和密码完全一致。注意，密码中如果包含$、!、*等特殊字符，在 shell 命令行中需要用单引号包裹，否则会被 bash 解析。
• HOST：这是最容易出错的字段。如前所述，'localhost'和'127.0.0.1'在 MariaDB 下行为不同。'localhost'触发 Unix socket 连接，'127.0.0.1'触发 TCP/IP 连接。如果你选择了PyMySQL方案，两者都可以；但如果你用了mysqlclient，且系统里同时装了 MySQL 和 MariaDB，'localhost'可能会因为 socket 路径不匹配而失败。此时，应强制使用'127.0.0.1'，并确保PORT是3306。
• PORT：默认是3306，但如果my.cnf里修改了port，这里就必须同步修改。一个快速验证端口的方法是：netstat -tlnp | grep :3306。

4.3OPTIONS: 字符集、时区与连接池的隐性开关

'DATABASES': { 'default': { # ... 其他字段 'OPTIONS': { 'charset': 'utf8mb4', 'init_command': "SET time_zone = '+00:00'", 'read_timeout': 10, 'write_timeout': 10, } } }

• 'charset': 'utf8mb4'：这是解决中文乱码的终极方案。它告诉 Django，在建立连接后，立即执行SET NAMES utf8mb4。这个命令会同时设置character_set_client,character_set_results,character_set_connection三个会话变量。没有它，即使数据库和表的字符集是utf8mb4，Django 的查询结果也可能是乱码。
• 'init_command': "SET time_zone = '+00:00'"：这是一个常被忽略的细节。Ubuntu 14.04 的系统时区通常是UTC，但 MariaDB 的默认时区是SYSTEM，它会读取操作系统的时区。如果操作系统时区是Asia/Shanghai（UTC+8），而 Django 的TIME_ZONE = 'UTC'，那么DateTimeField的存储和读取就会产生 8 小时的偏移。init_command在每次连接建立时，强制将数据库会话时区设为+00:00，从而与 Django 的TIME_ZONE保持一致。
• 'read_timeout'和'write_timeout'：这是为生产环境准备的。它们设置了读写操作的超时时间（秒）。在 Ubuntu 14.04 这种老系统上，网络或磁盘 I/O 可能不稳定，设置超时可以防止一个慢查询拖垮整个 Web 服务。10秒是一个比较平衡的值，太短会导致正常查询被中断，太长则失去保护意义。

踩坑实录：我在一个教育平台项目中，曾遇到一个诡异的 bug：每天凌晨 3 点，所有数据库查询都会超时。排查了整整两天，最后发现是 Ubuntu 14.04 的cron任务在凌晨 3 点执行logrotate，它会短暂地锁住/var/log/目录下的所有文件。而 MariaDB 的错误日志（/var/log/mysql/error.log）恰好也在这个目录下。当logrotate锁定日志文件时，MariaDB 的写入操作会被阻塞，进而导致所有连接的write_timeout被触发。解决方案是：在my.cnf的[mysqld]段落中，添加log-error = /var/log/mysql/mariadb-error.log，将错误日志路径迁移到一个不受logrotate影响的目录。这个细节，没有任何一篇“MySQL 安装教程”会告诉你。

5. 迁移与验证：从makemigrations到migrate --plan的全流程闭环

配置完settings.py，很多人会迫不及待地运行python manage.py migrate。但这是一个高风险操作。在 Ubuntu 14.04 上，由于 Python 2.7.6 的sqlite3模块与 MySQL 驱动的交互存在一些历史遗留的编码 bug，直接migrate可能会触发一个难以调试的UnicodeDecodeError。我们必须建立一个渐进式、可验证的迁移流程。

5.1 第零步：Python 层连接验证（绕过 Django）

在运行任何 Django 命令之前，先用最原始的方式，验证 Python 驱动能否独立连接数据库：

# 如果你用的是 PyMySQL python -c " import pymysql conn = pymysql.connect( host='localhost', user='myprojectuser', password='a_strong_password_here', database='myproject', charset='utf8mb4' ) print('Connection successful!') conn.close() " # 如果你用的是 mysqlclient python -c " import MySQLdb conn = MySQLdb.connect( host='localhost', user='myprojectuser', passwd='a_strong_password_here', db='myproject', charset='utf8mb4' ) print('Connection successful!') conn.close() "

如果这一步报错，说明问题出在驱动、用户权限或网络连接上，与 Django 无关。此时，你应该回到前几节，逐一检查mysql -u myprojectuser -p是否能登录，SHOW GRANTS是否正确，netstat是否监听了 3306 端口。

5.2 第一步：Django 层连接验证（dbshell）

如果 Python 层验证通过，下一步是让 Django 自己来连接：

python manage.py dbshell

这个命令会启动一个mysql或pymysql的交互式 shell，它使用的连接参数，完全来自settings.py中的DATABASES。如果dbshell能成功进入 MariaDB 的命令行，说明 Django 的配置是正确的。此时，你可以输入SHOW TABLES;，应该看到一个空的结果集（因为还没有运行迁移）。这是一个完美的中间状态：Django 能连上，但数据库是干净的。

5.3 第二步：迁移计划预览（migrate --plan）

这是最关键的一步，也是最容易被跳过的一步。--plan参数会告诉 Django：“别真的执行，只告诉我你打算做什么。”

python manage.py migrate --plan

在 Ubuntu 14.04 + Django 1.11 的环境下，这个命令的输出通常是：

Planned operations: 0001_initial [X] 0001_initial (1 squashed migration)

这里的[X]表示这个迁移已经被标记为“已执行”，但其实它还没有被执行。这是因为 Django 的迁移系统，会先检查数据库中是否存在一个名为django_migrations的表。如果这个表不存在，Django 就会认为“所有迁移都未执行”，并准备执行第一个迁移。--plan的作用，就是让你看到这个“准备执行”的列表，而不会真的去碰数据库。

5.4 第三步：执行迁移并实时监控

确认--plan输出无误后，执行真正的迁移：

python manage.py migrate

此时，你应该密切关注终端输出。一个健康的迁移过程，会显示类似：

Operations to perform: Apply all migrations: admin, auth, contenttypes, sessions Running migrations: Applying contenttypes.0001_initial... OK Applying auth.0001_initial... OK Applying admin.0001_initial... OK Applying sessions.0001_initial... OK

如果其中某一行卡住了，或者出现了Traceback，不要慌。立刻打开另一个终端，用mysql -u root -p登录，然后执行：

USE myproject; SHOW TABLES; SELECT * FROM django_migrations;

django_migrations表记录了所有已应用的迁移。如果某个迁移卡在了Applying xxx...，但django_migrations表里没有这条记录，说明迁移在执行 SQL 时失败了。此时，你应该查看 MariaDB 的错误日志（/var/log/mysql/error.log），里面会有具体的 SQL 错误信息，比如ERROR 1071 (42000): Specified key was too long; max key length is 767 bytes。这个错误在 Ubuntu 14.04 的 MySQL 5.5 上很常见，原因是utf8mb4的索引长度限制比utf8更严苛。解决方案是：在settings.py的DATABASES中，添加'init_command': "SET innodb_large_prefix=on"，然后重启 MariaDB 服务。

最后分享一个小技巧：在 Ubuntu 14.04 上，为了加速migrate过程，可以在settings.py的DATABASES中临时添加'OPTIONS': {'autocommit': True}。这会让每个迁移操作都自动提交，避免了事务开销。但请注意，这只是在开发/测试环境的优化手段，切勿在生产环境中使用，因为它会破坏迁移的原子性。