从 Docker 初始化乱码到 DBX 修复：一次开源 Bug 提交实录

最近有一个前后端项目需要通过 Docker 部署。由于还处于测试阶段，容器启动时需要初始化整个数据库。没想到，这个看似常规的操作却触发了 DBX 的一个 Bug。

这篇文章记录一下问题从发现、定位、提交 Issue，到 DBX 团队完成复现和修复的全过程。

一、Docker 初始化后中文全部乱码

项目部署完成后，我发现前端页面中的菜单和相关数据都变成了乱码。打开浏览器开发者工具检查接口响应后，可以确认后端返回的数据本身已经乱码，因此问题大概率出在数据库导入环节。

当时没有直接进入容器检查数据，我先让 GPT 协助排查。很快发现，DBX 导出的整库 SQL 文件虽然采用 UTF-8 编码，但文件开头没有声明连接字符集。原始文件头大致如下：

-- Database export: ai_school_plat
-- Date: 2026-09-24 16:03:33
-- Generated by DBX

SET FOREIGN_KEY_CHECKS = 0;

在执行其他语句之前补充字符集设置后，问题就能解决：

-- Database export: ai_school_plat
-- Date: 2026-09-24 16:03:33
-- Generated by DBX

SET NAMES utf8mb4;
SET CHARACTER SET utf8mb4;
SET character_set_connection = utf8mb4;
SET FOREIGN_KEY_CHECKS = 0;

问题的关键不在 SQL 文件中的中文内容，而在导入客户端如何解释这些 UTF-8 字节。如果导入过程使用了错误的默认字符集，写入数据库的数据就会变成乱码。

二、升级 DBX 后问题依然存在

出现问题时，我使用的是 DBX 0.5.x。起初我以为只是版本较旧，最新版本可能已经修复，于是升级到了 0.6.21，并重新导出了一份 SQL 文件。

结果问题依然存在。确认不是旧版本遗留问题后，我找到了 DBX 的 GitHub 仓库，按照 Issue 规范提交了一个 P2 级别的 Bug，完整描述了版本、环境、复现步骤和 Docker 初始化场景。

DBX 字符编码问题的 GitHub Issue

三、DBX 团队复现并定位根因

提交问题后，我也浏览了不少其他 Issue，并没有预期它会很快得到修复。毕竟这个问题不影响 DBX 日常连接和查询数据库，主要出现在使用导出文件初始化 Docker 数据库的场景中。

不过，DBX 团队很快就在真实的 MySQL 8.4 环境中完成了复现。他们创建了包含中文、日文和 Emoji 的测试数据，再通过 DBX 导出，并模拟 Docker 镜像初始化时可能使用错误默认字符集的导入过程。

测试结果确认：导出的 SQL 文件缺少 SET NAMES 或其他连接字符集声明，因此 UTF-8 文件可能被客户端按照 Latin-1 等默认字符集解释，随后以错误内容写入数据库。

DBX 团队对乱码问题的复现和根因分析

四、修复方案与验证结果

DBX 团队随后提交了修复 PR：在 MySQL 导出脚本的 Header 之后、CREATE DATABASE 和 USE 等语句之前写入：

SET NAMES utf8mb4;

这个位置很重要，因为数据库名、表名、列名和默认值都可能包含非 ASCII 字符，所以字符集声明必须出现在任何可能包含这些内容的 SQL 语句之前。

这次修改只作用于 MySQL，不影响其他数据库类型。团队还在真实的 MySQL 8.4 环境中进行了验证：即使导入客户端使用 Latin-1 作为默认字符集，中文表名、中文内容和 Emoji 也能正确还原；使用 UTF-8 导入同样没有出现回归。

DBX 团队提交修复并说明测试结果

五、一次很好的开源协作体验

从提交问题到完成修复并关闭 Issue，整个过程不到三天。DBX 团队不仅响应迅速，还给出了清晰的复现过程、根因分析、修改范围和测试结果，这一点让我印象很深。

国内的数据库可视化工具不少，而 DBX 是其中发展很快、使用体验也比较轻量的一款。从认识、了解再到实际使用，我也在一点点建立对这个项目的认知和信心。这次提交 Issue 虽然只是很小的贡献，但能够帮助一个开源项目变得更可靠，还是很有成就感。