RuoYi-Vue-Plus Docker部署踩坑：MySQL中文双重编码根因与修复

问题现象：RuoYi-Vue-Plus Docker 部署后菜单中文乱码

使用 docker-compose 部署完 RuoYi-Vue-Plus 项目后，打开前端页面时发现——菜单和面包屑中的中文全部变成了类似这样的乱码：系统管ç†、租户管ç†。但页面按钮上的「新增」「修改」「删除」以及表头中的「角色名称」「权限字符」却显示正常。看到这种模式，第一时间判断是编码问题，但具体出在哪个环节呢？

详细排查流程

Step 1：排除 Nginx 的干扰

首先检查 Nginx 响应头，Content-Type 明确标注了 charset=utf-8，这里没有问题，直接跳过。

 复制代码curl -sI 
# Content-Type: text/html; charset=utf-8 

Step 2：确认前端 JS 编码无误

接着检查编译产物的字符串字节。以「系统」为例，其 UTF-8 编码应为 e7 b3 bb，通过 xxd 命令搜索，发现前端 JS 文件中保存的 UTF-8 字节完全正确。前端层面没有问题。

 复制代码# "系统" 的 UTF-8 编码应该是 e7 b3 bb
xxd /usr/share/nginx/html/assets/index-*.js | grep "e7b3"
# 确认找到了，前端 JS 中的 UTF-8 字节是正确的

Step 3：检测 API 原始响应字节

这一步是关键。使用 Python 直接读取 API 返回的原始字节，不经过任何解码：

 复制代码import urllib.request
# ... 登录逻辑省略 ...
resp = urllib.request.urlopen(req)
raw = resp.read()
print(repr(raw[:200]))

输出结果：

 复制代码b'{"meta":{"title":"\xc3\xa7\xc2\b3\xc2\xbb...'

问题暴露了！正常的「系统管理」UTF-8 字节应该是：

 复制代码xe7xb3xbbxe7xbbx9fxe7xaexa1xe7x90x86

而实际返回的却是：

 复制代码xc3xa7xc2xb3xc2xbbxc3xa7xc2xbb...

每个原始 UTF-8 字节前面都多了一个 xc3 或 xc2。这正是经典的 Mojibake（双重编码）现象：

 复制代码原始 UTF-8:  E7 B3 BB    → "系"
被当作 Latin-1: ç ³ »      → 3 个 Latin-1 字符
再以 UTF-8 编码: C3 A7  C2 B3  C2 BB → 6 个字节

Step 4：确认问题出在数据库层

直接查询 MySQL 表验证：

 复制代码SELECT menu_name, HEX(menu_name), LENGTH(menu_name), CHAR_LENGTH(menu_name)
FROM sys_menu WHERE menu_id = 1;

 复制代码+----------+----------------------------------------------+--------+----------------+
| menu_name| HEX(menu_name)                               | LENGTH | CHAR_LENGTH    |
+----------+----------------------------------------------+--------+----------------+
| 系统管理  | C3A7C2B3C2BBC3A7C2BBC5B8C3A7C2AEC2A1C3A7... | 25     | 12             |
+----------+----------------------------------------------+--------+----------------+

• CHAR_LENGTH = 12：MySQL 认为这是 12 个「字符」（实际是 12 个 Latin-1 字符）
• LENGTH = 25：实际存储了 25 个字节
• 正确的「系统管理」应该是 CHAR_LENGTH = 4，LENGTH = 12，HEX 为 E7B3BBE7BB9FE7AEA1E79086

数据库里存储的就是双重编码的数据！

Step 5：定位 MySQL 初始化时的 charset 问题

检查 MySQL 连接的字符集：

 复制代码SHOW SESSION VARIABLES LIKE 'character_set%';

 复制代码| character_set_client     | latin1 |
| character_set_connection | latin1 |
| character_set_results    | latin1 |
| character_set_server     | utf8mb4 |

虽然 character_set_server = utf8mb4，但 character_set_client = latin1！问题链路非常清晰：

 复制代码SQL 文件 (UTF-8: 系统管理 = E7B3BB E7BB9F E7AEA1 E79086)
    ↓
mysql 客户端 (character_set_client = latin1)
    ↓
MySQL 服务器认为输入是 Latin-1，按 Latin-1 存储
    ↓
每个 UTF-8 字节被当成独立的 Latin-1 字符
    ↓
存储结果变成双重编码: C3A7C2B3C2BB...

为什么只设置 --character-set-server=utf8mb4 不够？

你的 docker-compose.yml 可能已经配置了：

 复制代码mysql:
  image: mysql:8.0
  command:
    --character-set-server=utf8mb4
    --collation-server=utf8mb4_general_ci

但这只设置了服务端（server）的默认字符集。当 docker-entrypoint-initdb.d 执行 SQL 文件时，使用的是 mysql 客户端连接，而 mysql 客户端的 character_set_client 默认值取决于 操作系统的 locale。

MySQL 官方 Docker 镜像基于 Oracle Linux 或 Debian，默认 locale 是 C 或 POSIX，映射到 MySQL 后就是 latin1。因此，即使你配置了 --character-set-server=utf8mb4，initdb 阶段的 mysql 客户端连接仍然是 latin1，导致中文数据被错误编码。

为什么 --init-connect 也不起作用？

你可能尝试过：

 复制代码command:
  --init-connect="SET NAMES utf8mb4"

--init-connect 对 root 用户不生效（这是 MySQL 的安全策略）。而 docker-entrypoint-initdb.d 中的 SQL 正是用 root 用户执行的，所以这个配置完全无效。

有效修复方案

在每个 SQL 文件的第一行添加 SET NAMES utf8mb4;：

 复制代码SET NAMES utf8mb4;
-- ----------------------------
-- 原来的内容...
-- ----------------------------
create table sys_social
(
    ...
);

然后删除数据卷，重新初始化数据库：

 复制代码docker compose down -v    # 删除数据卷
docker compose up -d      # 重新启动，重新执行 initdb.d

验证结果：

 复制代码SELECT menu_name, HEX(menu_name), CHAR_LENGTH(menu_name)
FROM sys_menu WHERE menu_id = 1;

 复制代码+----------+----------------------------------+--------------+
| menu_name| HEX(menu_name)                   | CHAR_LENGTH  |
+----------+----------------------------------+--------------+
| 系统管理  | E7B3BBE7BB9FE7AEA1E79086         | 4            |
+----------+----------------------------------+--------------+

CHAR_LENGTH = 4，HEX 是正确的 UTF-8 编码，问题完美解决。

其他备选方案对比

为什么这个问题难以排查？

1. 静态文字正常：Vue 模板里写死的按钮中文不受影响，只有数据库返回的动态数据出现乱码
2. 乱码不是问号：不是典型的 ??? 或方块字符，而是 系统 这种“看起来像编码问题但又不确定”的字符串
3. server charset 具有误导性：SHOW VARIABLES 显示 character_set_server=utf8mb4，让人误以为配置正确
4. SQL 文件本身是 UTF-8：用 file 命令检查 SQL 文件确实是 UTF-8，但写入时被 mysql 客户端转码了

总结

MySQL Docker 镜像的 docker-entrypoint-initdb.d 机制中，mysql 客户端默认的字符集是 latin1 而不是 utf8mb4。 这是一个从 2016 年就有人报告的问题（docker-library/mysql#131、#708），至今仍作为默认行为存在。

如果你的 SQL 文件包含非 ASCII 字符（中文、日文、韩文、emoji 等），务必在每个 SQL 文件的第一行添加 SET NAMES utf8mb4;，否则数据会被双重编码写入数据库，导致中文乱码。

参考：

• docker-library/mysql#131 - UTF8 Encoded SQL Scripts in initdb
• docker-library/mysql#708 - utf8 dump imported as latin1
• MySQL 8.0 Reference - Character Sets