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.04Trusty 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: utf8mb4Django 就会以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.5Ubuntu 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.1Django 会强制走 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 却报Cant 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的编译依赖链python-dev提供 Python 的 C API 头文件Python.h等libmysqlclient-dev提供 MySQL 客户端的 C 库头文件mysql.h,mysqld_error.h等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拥抱PyMySQLPyMySQL是一个纯 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: utf8mb4PyMySQL就会自动在连接时发送SET NAMES utf8mb4而mysqlclient有时需要额外配置init_command: SET sql_modeSTRICT_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;的输出里只有rootlocalhost这一行。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 myprojectuserlocalhost IDENTIFIED BY a_strong_password_here; # 用户名 myprojectuser 和主机 localhost 必须严格匹配。 # localhost 表示该用户只能从本机的 Unix socket 连接。 # 如果你未来要从其他机器连接比如开发机连服务器则需改为 %但这会极大增加风险。第三步授予最小必要权限GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER ON myproject.* TO myprojectuserlocalhost; # 这是 Django 迁移migrate和日常 CRUD 所需的全部权限。 # SELECT 用于查询INSERT/UPDATE/DELETE 用于增删改 # CREATE/DROP 用于创建/删除表迁移时必需 # INDEX 用于创建索引Django 的 db_indexTrue 会用到 # 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 myprojectuserlocalhost;就能立刻看到权限列表。这是一个快速验证权限是否生效的黄金命令。把它加入你的排错清单。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 和 MariaDBlocalhost可能会因为 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三个会话变量。没有它即使数据库和表的字符集是utf8mb4Django 的查询结果也可能是乱码。init_command: SET time_zone 00:00这是一个常被忽略的细节。Ubuntu 14.04 的系统时区通常是UTC但 MariaDB 的默认时区是SYSTEM它会读取操作系统的时区。如果操作系统时区是Asia/ShanghaiUTC8而 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( hostlocalhost, usermyprojectuser, passworda_strong_password_here, databasemyproject, charsetutf8mb4 ) print(Connection successful!) conn.close() # 如果你用的是 mysqlclient python -c import MySQLdb conn MySQLdb.connect( hostlocalhost, usermyprojectuser, passwda_strong_password_here, dbmyproject, charsetutf8mb4 ) 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_prefixon然后重启 MariaDB 服务。最后分享一个小技巧在 Ubuntu 14.04 上为了加速migrate过程可以在settings.py的DATABASES中临时添加OPTIONS: {autocommit: True}。这会让每个迁移操作都自动提交避免了事务开销。但请注意这只是在开发/测试环境的优化手段切勿在生产环境中使用因为它会破坏迁移的原子性。