Docker 部署 openGauss 7.0（aarch64）MySQL 兼容模式建库与数据恢复完整实践
前言
近期负责医疗资产物流系统从 MySQL 向 openGauss 7.0 迁移，选型 DBCOMPATIBILITY='B'（Dolphin MySQL 兼容引擎）以降低迁移成本。过程中踩了大量标识符大小写、语法兼容、权限、备份恢复的实操坑，本文整理出可复现的标准化步骤与根因分析，既是个人技术沉淀，也供同场景的开发、运维同学参考。
一、环境说明
| 项 | 说明 |
|---|---|
| 部署方式 | Docker 容器化部署 |
| 数据库版本 | openGauss 7.0.0 |
| 系统架构 | aarch64（ARM64） |
| 兼容模式 | DBCOMPATIBILITY = 'B'（Dolphin MySQL 兼容引擎） |
| 业务场景 | MySQL 迁移 |
| 账号体系 | omm（系统管理员）、root（业务库管理员） |
二、新建 B 兼容模式数据库完整步骤
2.1 进入容器并切换管理账号
bash
# 进入 openGauss 容器
docker exec -it opengauss700 bash
# 切换至 openGauss 系统管理员 omm
su - omm说明：openGauss 日常运维必须使用 omm 用户，操作系统 root 不等于数据库管理员。
2.2 连接系统库 postgres
bash
# 使用 root 数据库账号连接 postgres 系统库（执行后输入密码）
gsql -U root -d postgres2.3 （可选）清理旧测试库
重建测试环境时，先删除目标库避免冲突：
sql
DROP DATABASE IF EXISTS test_opengauss;2.4 创建 B 兼容模式数据库
核心语句 ：必须指定 TEMPLATE template0 才能自定义兼容模式和字符集规则。
sql
CREATE DATABASE test_opengauss
ENCODING 'UTF8'
LC_COLLATE 'en_US.utf8'
LC_CTYPE 'en_US.utf8'
TEMPLATE template0
DBCOMPATIBILITY = 'B';✅ 建库后校验兼容模式：
sql
SELECT datname, datcompatibility FROM pg_database
WHERE datname='test_opengauss';返回 datcompatibility = B 即为创建成功。
2.5 切换至目标业务库
sql
\c test_opengauss2.6 加载 Dolphin 兼容扩展
B 模式必须加载 dolphin 扩展，才能启用 MySQL 语法兼容能力：
sql
CREATE EXTENSION IF NOT EXISTS dolphin;✅ 校验插件状态：
sql
SHOW PLUGINS;查看 dolphin 状态为 ACTIVE 即为加载成功。
2.7 配置表名大小写不敏感（模拟 MySQL 行为）
这是 MySQL 迁移最核心的适配参数，解决大写表名 BASE_USER 迁移后报 relation does not exist 的问题。
sql
-- 给业务连接账号 root 设置表名大小写不敏感
ALTER USER root SET dolphin.lower_case_table_names = 1;⚠️ 关键注意事项：
- 该参数绑定角色，仅新连接生效，修改后必须断开重连才会加载。
- 只对表名、视图名生效，列名、别名的大小写规则不受影响。
✅ 重连后验证参数：
sql
show dolphin.lower_case_table_names;返回 1 即为生效，此时 BASE_USER 和 base_user 等价，和 MySQL 默认行为一致。
三、dump 备份文件拷贝与数据恢复流程
场景：备份文件位于容器 /backup 目录，需要恢复到新建的测试库中。
3.1 拷贝备份文件到 omm 用户目录
bash
# 容器内 root 身份执行
cp /backup/backup_test_opengauss_20261015_1255.dump /home/omm3.2 修改文件属主为 omm
gs_restore 必须使用 omm 用户执行，文件属主不匹配会出现读取权限错误：
bash
chown omm:omm /home/omm/backup_test_opengauss_20261015_1255.dump3.3 切换至 omm 用户
bash
su - omm3.4 执行数据恢复
使用 gs_restore 工具恢复，输出详细日志便于排查问题：
bash
gs_restore -U omm -d test_opengauss -v \
/home/omm/backup_test_opengauss_20261015_1255.dump \
> /tmp/restore700.log 2>&1参数说明：
-U omm：执行恢复的数据库账号-d：目标数据库名称-v：verbose 详细输出模式> /tmp/restore700.log 2>&1：标准输出与错误输出统一写入日志文件
3.5 查看恢复日志
bash
cat /tmp/restore700.log3.6 恢复结果校验
进入 gsql 验证数据完整性：
sql
\c test_opengauss
-- 查看当前 schema 所有表
\dt
-- 验证业务视图示例
\dv v_benefit_monthly
-- 验证核心表数据量
SELECT count(*) FROM base_user;四、迁移核心踩坑总结（干货沉淀）
坑1：表名大小写不兼容，报 relation "XXX" does not exist
- 现象 ：MySQL 中大写表名
BASE_USER正常运行，迁移后直接报错表不存在。 - 根因 ：openGauss B 模式默认表名大小写敏感，和 MySQL 默认
lower_case_table_names=1的行为不一致。 - 解决方案 ：给业务连接账号设置
dolphin.lower_case_table_names = 1，模拟 MySQL 表名大小写不敏感。
坑2：ORDER BY 带双引号别名，报 non-integer constant in ORDER BY
- 现象 ：
ORDER BY "useRate" DESC在 MySQL 正常执行，openGauss 直接报错。 - 根因：PG 内核中，ORDER BY 后的双引号会被识别为字符串常量，而非查询列别名；B 兼容模式未修改此底层解析规则。
- 解决方案 ：ORDER BY / GROUP BY 引用别名时，去掉双引号 ，直接写
ORDER BY useRate DESC。 - 补充：SELECT 子句中
AS "useRate"的双引号可以保留，用于 MyBatis 驼峰字段映射。
坑3：复制 SQL 报 invalid byte sequence for encoding "UTF8"
- 现象：从 XML / 文档中复制 SQL 执行，随机报编码错误，手动敲入则正常。
- 根因：复制时带入了 UTF-8 BOM 头、零宽字符等不可见特殊字符。
- 解决方案 ：
- Mapper XML 文件统一保存为 UTF-8 无 BOM 格式；
- gsql 测试关键 SQL 尽量手动输入，避免直接复制粘贴。
坑4：备份恢复权限错误
- 现象：gs_restore 执行时报文件无法读取。
- 根因：备份文件属主是操作系统 root，omm 用户没有读取权限。
- 解决方案 ：恢复前执行
chown omm:omm修改备份文件属主。
坑5：对 B 兼容模式的认知误区
很多人以为 DBCOMPATIBILITY='B' = 100% 兼容 MySQL，实际是基于 PG 内核的语法兼容层，存在明确的兼容边界：
- ✅ 兼容：反引号、LIMIT、AUTO_INCREMENT、常用函数、表名大小写参数
- ❌ 不兼容：ORDER BY 双引号别名、部分系统函数、GROUP BY 严格校验、部分类型隐式转换
五、生产迁移最佳实践建议
- 测试库先行：先在测试库完整验证 DDL、DML、报表 SQL、定时任务全链路，再推进生产。
- 账号权限分离：生产环境禁止业务应用使用 root / omm 超级账号，新建独立业务账号作为库 owner，满足等保与审计要求。
- 批量兼容检查 ：全局检索 Mapper XML，清理所有
ORDER BY "xxx"格式的双引号别名，避免批量报错。 - 参数持久化 ：
dolphin.lower_case_table_names绑定业务账号配置，避免切换账号后复发表名大小写问题。 - 恢复完整性校验：备份恢复后必须校验表数量、数据量、视图、函数、存储过程的完整性。
写在最后
openGauss 迁移的核心难点，不在于语法本身，而在于对兼容模式边界的认知------很多问题不是 SQL 写错了，而是兼容规则和 MySQL 存在细微差异。这份笔记基于真实项目的踩坑与验证整理，覆盖从建库、兼容配置到数据恢复的全流程，可直接作为 MySQL 迁 openGauss 的标准化操作手册。