GBase 8a 字符集完全指南：乱码根因分析、配置规范与修复方案

字符集乱码是 GBase 8a 使用中最高频的坑，从导入乱码、查询乱码到跨系统乱码，根因各不相同。本文系统梳理 GBase 8a 的字符集体系、转换流程、各场景配置规范，并给出乱码的诊断和修复方法。

---

一、GBase 8a 支持的字符集

字符集	说明	最大字节/字符	适用场景
utf8	标准 UTF-8（1-3 字节）	3	通用，默认值
utf8mb4	完整 UTF-8（1-4 字节）	4	需要存储 Emoji 或生僻字
gbk	国标扩展汉字编码（双字节）	2	存量系统，数据源为 GBK
gb18030	国家标准，GBK 超集	4	需覆盖生僻字的政务场景

几个重要限制：

• GBase 8a 的 utf8 最多处理 3 字节字符（与 MySQL 的 utf8mb3 一致），不支持 4 字节的 Emoji，需要 utf8mb4
• gb18030 每字符预留 4 字节空间，内存压力是 gbk 的两倍，在内存紧张时对性能影响较大
• ​字符集一经安装确定，不支持 ALTER TABLE 直接修改表字符集​，变更字符集需重建表并重新导入数据
• ​**校验规则（Collation）**​：GBase 8a 当前所有字符集的校验规则均为区分大小写，与 MySQL 默认的 utf8_general_ci（不区分大小写）不同，迁移时需注意

---

二、字符集转换链路

理解乱码的关键是搞清楚 SQL 从客户端到数据库存储的完整转换链路：

客户端发 SQL
    │
    ▼ character_set_client（客户端声明自己用什么字符集）
gcluster 接收
    │
    ▼ character_set_connection（gcluster 内部转换目标字符集）
查询执行 / 数据存储（使用表/库的字符集）
    │
    ▼ character_set_results（返回给客户端的字符集）
客户端接收并显示

​乱码只会在字符集不一致的转换点产生​。只要链路上每一层的字符集声明与实际编码一致，就不会乱码。

---

三、字符集相关参数一览

-- 查看当前所有字符集参数
SHOW VARIABLES LIKE '%character%';

参数	作用	可修改范围
character_set_server	实例字符集（安装时确定）	配置文件，重启生效
character_set_database	当前库的字符集	只读，反映当前 USE 的库
character_set_client	客户端发送 SQL 的字符集	SET 或配置文件
character_set_connection	服务端接收后的中间转换字符集	SET 或配置文件
character_set_results	查询结果返回给客户端的字符集	SET 或配置文件
character_set_system	系统元数据字符集（固定 utf8）	不可修改
character_set_sort	排序时使用的字符集	SET 或配置文件

最简原则：让 client = connection = results = 表字符集，不产生任何转换。

---

四、字符集配置规范

4.1 安装时确定字符集（最重要）

GBase 8a 的实例字符集在安装时确定，通过配置文件中的 default_character_set 指定。​安装后修改代价很高​（所有已有库表不受影响，只对新建对象生效）。

# gcluster 和 gnode 所有节点的 gbase.cnf（安装前配置）
[client]
default-character-set = utf8    # 或 gbk

[gbased]
default_character_set = utf8    # 或 gbk

如果数据源（业务系统、历史数据文件）是 GBK 编码，建议安装时就指定 gbk；如果是全新系统，优先选 utf8。

4.2 建库建表时指定字符集

即使实例字符集是 utf8，也可以在建库或建表时指定不同字符集：

-- 建库时指定
CREATE DATABASE legacy_db DEFAULT CHARACTER SET gbk;

-- 建表时指定（如不指定，继承库的字符集）
CREATE TABLE t_product (
    product_id   INT,
    product_name VARCHAR(100)
) ENGINE=EXPRESS DEFAULT CHARSET=gbk DISTRIBUTED BY HASH(product_id);

4.3 会话级字符集设置

当客户端字符集与服务端不一致时，可以在会话开始时临时对齐：

-- 一次性设置 client / connection / results 三个参数
SET NAMES gbk;
-- 等价于：
SET character_set_client = gbk;
SET character_set_connection = gbk;
SET character_set_results = gbk;

4.4 配置文件中的全局默认

如果所有连接都来自 GBK 客户端，可以在配置文件中写死：

# gcluster 的 gbase.cnf
[client]
default-character-set = gbk

[gbased]
character_set_client     = gbk
character_set_connection = gbk
character_set_results    = gbk

---

五、乱码场景诊断与修复

场景 1：gccli / 命令行工具查询乱码

​现象​：在终端查询中文，显示问号或方块。

诊断步骤：

-- 1. 查看当前会话字符集
SHOW VARIABLES LIKE '%character%';

-- 2. 查看操作系统终端字符集
-- 在 Linux Shell 执行：
echo $LANG
-- 期望：zh_CN.UTF-8

-- 3. 确认表的实际字符集
SHOW CREATE TABLE your_table;

修复：

-- 如果终端是 UTF-8，数据库是 GBK：
SET NAMES utf8;   -- 告诉数据库"请把结果以 UTF-8 返回给我"

-- 如果终端是 GBK（Windows cmd），数据库是 UTF-8：
SET NAMES gbk;

场景 2：LOAD DATA 导入后乱码

​现象​：数据文件是 GBK 编码，但导入后查询中文乱码。

诊断：

# 确认数据文件的实际编码
file -i /data/import/data.csv
# 或：
head -1 /data/import/data.csv | hexdump -C | head

gload 配置文件中指定字符集：

# load.cfg
character_set = gbk    # 告诉 gload 文件是 GBK 编码

LOAD DATA 语句中指定：

LOAD DATA INFILE '/data/import/data.csv'
INTO TABLE t_product
CHARACTER SET gbk       -- 指定文件编码
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n';

⚠️ ​GBase 8a 的 LOAD DATA 不支持在加载时自动转换字符集​。如果文件是 GBK，目标表是 UTF-8，需要先在 OS 层将文件转换为 UTF-8，再导入：

iconv -f GBK -t UTF-8 data_gbk.csv > data_utf8.csv

场景 3：JDBC 应用写入乱码

​现象​：Java 应用写入的中文，在 gccli 中查询是乱码。

诊断：

// 检查 JDBC URL 中是否指定了 characterEncoding
// 错误：没有指定，JDBC 会用 JVM 默认编码（可能是 GBK/ISO-8859-1）
String url = "jdbc:gbase://host:5258/db";

// 正确：明确指定编码
String url = "jdbc:gbase://host:5258/db?characterEncoding=utf8&useUnicode=true";

同时确保数据库服务端的 character_set_client 与 JDBC 指定的编码一致：

-- 会话连接建立后，服务端收到的 character_set_client 应该与 JDBC 的 characterEncoding 一致
SHOW VARIABLES LIKE 'character_set_client';

场景 4：SELECT INTO OUTFILE 导出文件乱码

​现象​：导出的 CSV 文件在 Excel/Windows 下打开乱码。

​根因​​：GBase 8a 导出的文件编码与打开工具预期编码不一致。

-- 导出时指定字符集（让结果以 GBK 返回，适合 Windows Excel）
SET character_set_results = gbk;
SELECT ...
INTO OUTFILE '/data/export/result.csv'
CHARACTER SET gbk
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\r\n';  -- Windows 换行符

或者在 OS 层转换导出文件的编码：

iconv -f UTF-8 -t GBK result_utf8.csv > result_gbk.csv

场景 5：表字符集已确定为 GBK，但个别列需要存储特殊字符

GBase 8a 支持在建表时列级别指定字符集（部分版本支持）：

CREATE TABLE t_mixed (
    id          INT,
    name_cn     VARCHAR(100) CHARACTER SET gbk,
    name_intl   VARCHAR(100) CHARACTER SET utf8mb4  -- 支持 emoji
) DISTRIBUTED BY HASH(id);

---

六、字符集变更方案

​GBase 8a 不支持直接 ALTER TABLE 修改字符集​，正确的变更流程如下：

-- 步骤 1：导出原表数据（以目标字符集导出）
SET character_set_results = utf8;  -- 目标字符集
SELECT * INTO OUTFILE '/tmp/t_product_utf8.csv'
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n'
FROM t_product_gbk;

-- 步骤 2：创建新表（使用目标字符集）
CREATE TABLE t_product_new (
    product_id   INT,
    product_name VARCHAR(100)
) ENGINE=EXPRESS DEFAULT CHARSET=utf8
DISTRIBUTED BY HASH(product_id);

-- 步骤 3：导入数据
LOAD DATA INFILE '/tmp/t_product_utf8.csv'
INTO TABLE t_product_new
CHARACTER SET utf8
FIELDS TERMINATED BY ','
LINES TERMINATED BY '\n';

-- 步骤 4：验证数据完整性后重命名
-- 原表改名保留备份
ALTER TABLE t_product_gbk RENAME TO t_product_gbk_bak;
ALTER TABLE t_product_new RENAME TO t_product_gbk;

---

七、排序与字符集

GBase 8a 默认按字符的二进制值排序（character_set_sort = binary）。对于中文数据，二进制排序不等于拼音顺序。如果需要拼音排序：

-- 会话级设置（对当前连接后续查询生效）
SET character_set_sort = gbk;   -- 按 GBK 内码（拼音）排序

-- 或在配置文件中全局设置
-- [gbased]
-- character_set_sort = gbk

-- 验证效果
SELECT name FROM t_person ORDER BY name;
-- binary 排序：按字节值，可能是：东、中、人、大（不是拼音顺序）
-- gbk 排序：按拼音，应为：大、东、人、中

---

八、字符集问题速查手册

现象	第一检查点	常见根因	修复方向
查询结果全是 ???	character_set_results	客户端不支持该编码	SET NAMES 客户端编码
查询结果有乱码方块	表字符集 vs 实际数据编码	写入时编码不匹配	重新导入，统一编码
LOAD DATA 后乱码	cfg 文件的 character_set	文件编码与声明不符	先用 iconv 转换文件
JDBC 写入乱码	JDBC URL 的 characterEncoding	未指定或与表字符集不符	补充 characterEncoding=utf8
Excel 打开 CSV 乱码	导出时的 character_set_results	UTF-8 文件被 Excel 当 GBK 打开	导出为 GBK 或加 BOM
中文排序不是拼音顺序	character_set_sort	默认 binary 排序	SET character_set_sort=gbk
插入表情符号报错	表的字符集	utf8 不支持 4 字节字符	改用 utf8mb4