Gaea 2.4.2 安装指南

Gaea 2.4.2 在 Ubuntu 22.04 的源码编译（make parser/gaea/gaea-cc）与二进制部署全流程实测：file 模式代理、双 MySQL 5.7 分片后端、systemd 托管、冒烟验证与 parser.go/DDL/全局表等排障实录。

GaeaMySQL 中间件中间件2026/10/23

Gaea 2.4.2 安装指南

目标：在 Linux 服务器上从零完成 Gaea 2.4.2 的获取、编译、部署、启动与验证，并交付一套可直接复用的 systemd 托管方案与排障手册。全部命令与回显均在 Ubuntu 22.04（x86_64）环境实测通过：Gaea 以源码方式编译出 gaea/gaea-cc 两个静态二进制，部署为 file 配置模式单机代理，后端对接两台 MySQL 5.7.44 实例，前端 mysql 8.0 客户端接入验证成功。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（x86_64）
  • Gaea 版本：2.4.2（官方最新 Release，2024-09-20 发布）
  • Go 版本：go1.23.12 linux/amd64（编译机）
  • 后端数据库：MySQL 5.7.44 × 2（10.89.71.2:3306、10.89.71.3:3306，root 密码 q1w2e3r4）
  • Gaea 代理服务器：10.89.71.5，服务端口 13306、管理端口 13307
  • 接入客户端：mysql 8.0.46（10.89.71.4）
  • 部署目录：/opt/gaea（结构见第五章）
  • 演示账号：前端/后端均用 root，密码 q1w2e3r4；Gaea 管理端口 admin / q1w2e3r4

⚠️ 注意：Gaea 官方不提供编译好的二进制 Release 附件（v2.4.2 Release 页面仅源码包，2026-10-23 实查），因此「源码编译 → 二进制部署」是唯一安装路径，本文按此组织。

二、前置条件

编译机与服务机可以分离，以下按「同一台 Ubuntu 22.04 服务器既编译又部署」的最小场景说明。

2.1 编译依赖

# 基础编译工具链（make、git、bash、curl）
sudo apt update
sudo apt install -y make git bash curl wget

# 安装 Go 1.23（官方 tar 包方式，不依赖 apt 源版本）
wget https://go.dev/dl/go1.23.12.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.23.12.linux-amd64.tar.gz
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

验证编译环境（实测回显）：

go version

go version go1.23.12 linux/amd64

make --version | head -1

GNU Make 4.4.1
Built for x86_64-pc-linux-gnu

⚠️ 注意：Gaea 官方 quickstart 要求 go >= 1.11，且依赖 goyacc、gofmt 等工具（goyacc 会在 make parser 环节自动获取，无需手动安装）。国内网络环境建议配置 Go 模块代理：export GOPROXY=https://goproxy.cn,direct。

2.2 运行依赖

  • 后端至少一个 MySQL 实例（本文使用 MySQL 5.7.44 两台做双分片；Gaea 亦支持 MySQL 8.x 作为后端，认证插件按第八章 auth_plugin 说明配置）；
  • 前端任意 MySQL 协议客户端（mysql CLI、JDBC 等）；
  • 端口规划：13306（代理服务）、13307（管理端口），确认未被占用：
ss -ltn | grep -E '13306|13307'

实测输出为空（端口空闲，可安全使用）。

三、版本选型说明

Gaea 遵循语义化版本，v2.x 系列为当前主线路线：

版本发布日期说明获取方式
v2.4.22024-09-20当前最新稳定版，本文基准Release 页源码包 / git tag
v2.3.7更早官方性能测试报告的基准版本git tag
master 分支持续演进含未发布修复，生产不建议git clone

版本实查方式（2026-10-23）：

# 查看官方全部 Release（取首个即为最新）
wget -qO- https://api.github.com/repos/XiaoMi/Gaea/releases/latest | grep -E '"tag_name"|"published_at"'

⚠️ 注意：若该接口限流（GitHub API 匿名限额 60 次/小时），直接访问 https://github.com/XiaoMi/Gaea/releases 页面确认，本文查询结果为 v2.4.2（2024-09-20）。

四、源码编译安装方案

4.1 方案说明

本方案从官方源码出发，用 Gaea 自带的 Makefile 完成编译，产出两个静态链接二进制：bin/gaea（代理，约 33 MB）与 bin/gaea-cc（中控，约 26 MB）。编译机需要能访问 GitHub 与 Go 模块代理。

4.2 获取源码

方式一：git clone（推荐，构建产物自带版本信息）

cd /opt
sudo git clone --depth 1 --branch v2.4.2 https://github.com/XiaoMi/Gaea.git

方式二：官方源码包（离线/免 git）

cd /opt/data
wget https://github.com/XiaoMi/Gaea/archive/refs/tags/v2.4.2.tar.gz -O gaea-2.4.2.tar.gz

实测下载回显（输出节选）：

--2026-10-23 23:20:21--  https://github.com/XiaoMi/Gaea/archive/refs/tags/v2.4.2.tar.gz
Saving to: 'gaea-2.4.2.tar.gz'
  7350K ..........                                              213M=0.7s
2026-10-23 23:20:21 (10.3 MB/s) - 'gaea-2.4.2.tar.gz' saved [7536918]

校验包完整性（本次实测值，供比对）：

md5sum gaea-2.4.2.tar.gz

d335800f69205c024308723b8fce3698  gaea-2.4.2.tar.gz

解压：

tar -xzf gaea-2.4.2.tar.gz
mv Gaea-2.4.2 /opt/gaea-src
cd /opt/gaea-src

4.3 生成 parser（make parser）

Gaea 内置 TiDB Parser 派生的 SQL 解析器，yacc 文法在 parser/parser.y，构建时先经 goyacc 生成 parser/parser.go：

cd /opt/gaea-src
make parser

实测回显：

cd parser && make && cd ..
make[1]: Entering directory '/opt/gaea-src/parser'
#@echo "gofmt (simplify)"
#@ gofmt -s -l -w . 2>&1 | awk '{print} END{if(NR>0) {exit 1}}'
make[1]: Leaving directory '/opt/gaea-src/parser'

验证 parser 已生成：

ls -la parser/parser.go

-rw-r--r-- 1 root root 2137004 Oct 23 15:18 parser/parser.go

⚠️ 注意（重要排障）：不要在自带 parser/parser.go 存在时删除后重新生成。实测中删除 parser.go 再 make parser 重新生成后，make gaea 报错：

# github.com/XiaoMi/Gaea/parser
parser/parser.go:12353:1: invalid UTF-8 encoding
make: *** [Makefile:16: gaea] Error 1

原因：本地 goyacc 重新生成的 parser.go 与官方仓库提交的生成版本不一致（含非 UTF-8 字节）。解决办法：恢复源码包/仓库自带的 parser/parser.go（源码包解压即含官方生成版），或从源码包重新提取：

tar -xzf gaea-2.4.2.tar.gz Gaea-2.4.2/parser/parser.go -O > parser/parser.go

4.4 编译 gaea 与 gaea-cc

cd /opt/gaea-src
make gaea

实测回显（版本注入参数由 gen_ldflags.sh 生成；源码包无 git 元数据，版本字段显示 unknown 属正常现象，见 4.5）：

Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /opt/gaea-src/bin/gaea -pkgdir=/root/go/pkg/linux_amd64 -ldflags "-extldflags -static  -X github.com/XiaoMi/Gaea/core.buildVersion=unknown -X github.com/XiaoMi/Gaea/core.buildGitRevision=unknown -X github.com/XiaoMi/Gaea/core.buildUser=root -X github.com/XiaoMi/Gaea/core.buildHost=9efd6925d1b3 -X github.com/XiaoMi/Gaea/core.buildStatus=Modified -X github.com/XiaoMi/Gaea/core.buildTime=2026-10-23--15:19:28 -X github.com/XiaoMi/Gaea/core.buildBranch= -X github.com/XiaoMi/Gaea/core.buildGitDirty=0" github.com/XiaoMi/Gaea/cmd/gaea

make gaea-cc

实测结果：编译成功，bin/ 下产出两个静态二进制：

ls -la bin/

total 58340
drwxr-xr-x    2 root     root          4096 Oct 23 15:19 .
drwxrwxr-x   22 root     root          4096 Oct 23 15:19 ..
-rwxr-xr-x    1 root     root      33388501 Oct 23 15:19 gaea
-rwxr-xr-x    1 root     root      26338620 Oct 23 15:19 gaea-cc

4.5 查看构建信息

./bin/gaea -info

实测回显：

Build Version Information:Version: unknown
GitRevision: unknown
User: root@9efd6925d1b3
GolangVersion: go1.23.12
BuildStatus: Modified
BuildTime: 2026-10-23--15:19:28
BuildBranch:
BuildGitDirty: 0

💡 说明：Version/GitRevision/Branch 显示 unknown 是因为本例用源码包构建、目录中无 git 仓库（编译时伴随三行 fatal: not a git repository 提示即来源于此，可忽略）。若采用 git clone --branch v2.4.2 方式构建，这三个字段会正确显示 v2.4.2 与对应 commit。两种方式产出的代理功能完全一致。

4.6 依赖拉取失败的处理

若 make gaea 阶段下载 Go 依赖缓慢或超时，配置国内模块代理后重试：

export GOPROXY=https://goproxy.cn,direct
make gaea && make gaea-cc

五、二进制部署运行方案（file 配置模式单机代理）

5.1 方案说明

编译产物是免安装的静态二进制，本方案将其组织为规范的 /opt/gaea 部署目录：二进制 + 配置 + 日志三分离，以 file 配置模式（无需 etcd，单机即可运行）承接 SQL 流量，并用 systemd 托管为常驻服务。

5.2 目录规划

sudo mkdir -p /opt/gaea/bin /opt/gaea/etc/file/namespace /opt/gaea/logs
sudo cp /opt/gaea-src/bin/gaea /opt/gaea/bin/
sudo useradd -r -s /sbin/nologin gaea 2>/dev/null || true
sudo chown -R gaea:gaea /opt/gaea

部署完成后的目录结构：

/opt/gaea
├── bin
│   └── gaea
├── etc
│   ├── gaea.ini
│   └── file
│       └── namespace
│           └── gaea_test.json
└── logs

5.3 编写本地配置 /opt/gaea/etc/gaea.ini

; 配置类型：file（单机体验）/ etcd / etcdv3（生产）
config_type=file
; file 模式下 namespace 配置目录（固定在其下 namespace 子目录）
file_config_path=./etc/file

; 配置中心地址（file 模式不生效，生产 etcd 模式使用）
coordinator_addr=http://127.0.0.1:2379
username=root
password=root

; 环境标识与服务名
environ=local
service_name=gaea_proxy
cluster_name=gaea_default_cluster

; 日志
log_path=./logs
log_level=Notice
log_filename=gaea
log_output=file
log_keep_days=3
log_keep_counts=3

; 管理端口（HTTP，basic auth）
admin_addr=0.0.0.0:13307
admin_user=admin
admin_password=q1w2e3r4

; 代理服务端口
proto_type=tcp4
proxy_addr=0.0.0.0:13306
proxy_charset=utf8
; 慢 SQL 记录阈值（毫秒）
slow_sql_time=100
; 空闲会话超时（秒）
session_timeout=3600

; 打点统计
stats_enabled=true
stats_interval=10

; namespace 配置加密密钥（etcd 模式使用）
encrypt_key=1234abcd5678efg*

; 对客户端声明的服务端版本号
server_version=5.6.20-gaea

; 前端认证插件：mysql_native_password（兼容 5.x/8.x 客户端）或 caching_sha2_password
auth_plugin=mysql_native_password

逐项说明：

配置项说明与实测行为
config_type配置体系开关。file 从 file_config_path/namespace/ 读取 JSON；生产用 etcd/etcdv3。file 模式改 namespace 配置需重启进程
admin_addr/admin_user/admin_password管理端口 13307 的监听与 Basic Auth 凭据，实测错误密码返回 HTTP/1.1 401 Unauthorized
proxy_addr对应用户暴露的 MySQL 协议端口 13306
server_version握手包向客户端声明的版本。实测 mysql 客户端 status 显示 Server version: 5.6.20-gaea MySQL Community Server (GPL)，而会话内 SELECT VERSION() 返回后端真实版本 5.7.44
auth_plugin前端认证插件。mysql_native_password 兼容性最好；改 caching_sha2_password 支持 MySQL 8 认证但低版本客户端不支持
log_levelNotice/Debug 等。Debug 级别会记录连接健康检查等明细，日常用 Notice
slow_sql_time会话级慢 SQL 记录阈值（ms），超过即写入慢 SQL 指纹（管理端口可查）

5.4 编写 namespace 配置（file 模式）

在 /opt/gaea/etc/file/namespace/gaea_test.json 写入最小可用的双分片租户配置（逻辑库 db_test，两个后端 MySQL 各承载一半分片）：

{
    "name": "gaea_test",
    "online": true,
    "read_only": false,
    "allowed_dbs": {
        "db_test": true
    },
    "slow_sql_time": "1000",
    "black_sql": [],
    "allowed_ip": [],
    "slices": [
        {
            "name": "slice-0",
            "user_name": "root",
            "password": "q1w2e3r4",
            "master": "10.89.71.2:3306",
            "slaves": [],
            "statistic_slaves": [],
            "capacity": 12,
            "max_capacity": 24,
            "idle_timeout": 60,
            "init_connect": ""
        },
        {
            "name": "slice-1",
            "user_name": "root",
            "password": "q1w2e3r4",
            "master": "10.89.71.3:3306",
            "slaves": [],
            "statistic_slaves": [],
            "capacity": 12,
            "max_capacity": 24,
            "idle_timeout": 60,
            "init_connect": ""
        }
    ],
    "shard_rules": [
        {
            "db": "db_test",
            "table": "tbl_user",
            "type": "mod",
            "key": "id",
            "locations": [2, 2],
            "slices": ["slice-0", "slice-1"]
        }
    ],
    "users": [
        {
            "user_name": "root",
            "password": "q1w2e3r4",
            "namespace": "gaea_test",
            "rw_flag": 2,
            "rw_split": 0,
            "other_property": 0
        }
    ],
    "default_slice": "slice-0",
    "global_sequences": [],
    "max_sql_execute_time": 0
}

逐项说明：

  • name：租户名，前端登录后通过 namespace 匹配用户；
  • allowed_dbs：允许前端访问的逻辑库白名单；
  • slices：后端物理实例组，master 为主库地址，capacity/max_capacity 为初始/最大连接池；
  • shard_rules：本文只配了 kingshard 方式的 mod 分表规则（locations: [2,2] 表示 slice-0 放 2 个分表、slice-1 放 2 个分表）；MyCat 方式（mycat_mod 分库）、全局表、子表等规则见《Gaea 2.4.2 配置参数详解》；
  • users：前端账号，rw_flag=2 读写，rw_split=0 不分离（无从库）。

5.5 准备后端 MySQL 物理库与分表

Gaea 不做前端 DDL 路由，分片物理表必须由 DBA 直接在后端实例创建。在两个后端 MySQL 上分别执行（root/q1w2e3r4 登录各自实例）：

在 10.89.71.2（slice-0）上：

mysql -h 10.89.71.2 -uroot -pq1w2e3r4

CREATE DATABASE db_test;
USE db_test;
CREATE TABLE tbl_user_0000 (id INT NOT NULL, name VARCHAR(32) NOT NULL, age INT NOT NULL DEFAULT 0, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;
CREATE TABLE tbl_user_0001 LIKE tbl_user_0000;

在 10.89.71.3（slice-1）上：

mysql -h 10.89.71.3 -uroot -pq1w2e3r4

CREATE DATABASE db_test;
USE db_test;
CREATE TABLE tbl_user_0002 (id INT NOT NULL, name VARCHAR(32) NOT NULL, age INT NOT NULL DEFAULT 0, PRIMARY KEY (id)) ENGINE=InnoDB DEFAULT CHARSET=utf8;
CREATE TABLE tbl_user_0003 LIKE tbl_user_0002;

⚠️ 注意：kingshard 方式 mod 规则的物理表名是四位补零编号（tbl_user_0000 起）。实测若建成不带补零的 tbl_user_0，前端插入报 ERROR 1146 (42S02): Table 'db_test.tbl_user_0001' doesn't exist——表名与路由规则不一致是新手最常见的坑。

5.6 启动 Gaea

前台启动验证（先观察一次输出再转 systemd）：

cd /opt/gaea
sudo -u gaea ./bin/gaea -config ./etc/gaea.ini

实测回显（输出节选，GIN 路由清单为管理端口全部 API）：

Build Version Information:Version: unknown
GitRevision: unknown
User: root@9efd6925d1b3
GolangVersion: go1.23.12
BuildStatus: Modified
BuildTime: 2026-10-23--15:19:28
BuildBranch:
BuildGitDirty: 0

max use cpu : 4(default)[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /api/proxy/ping           --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).ping-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/proxyconfig/reload --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).reloadProxyConfig-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/config/prepare/:name --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).prepareConfig-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/config/commit/:name --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).commitConfig-fm (2 handlers)
[GIN-debug] PUT    /api/proxy/namespace/delete/:name --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).deleteNamespace-fm (2 handlers)
[GIN-debug] GET    /api/proxy/config/fingerprint --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).configFingerprint-fm (2 handlers)
[GIN-debug] GET    /api/proxy/stats/sessionsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).getNamespaceSessionSQLFingerprint-fm (2 handlers)
[GIN-debug] GET    /api/proxy/stats/backendsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).getNamespaceBackendSQLFingerprint-fm (2 handlers)
[GIN-debug] DELETE /api/proxy/stats/sessionsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).clearNamespaceSessionSQLFingerprint-fm (2 handlers)
[GIN-debug] DELETE /api/proxy/stats/backendsqlfingerprint/:namespace --> github.com/XiaoMi/Gaea/proxy/server.(*AdminServer).clearNamespaceBackendSQLFingerprint-fm (2 handlers)
[GIN-debug] GET    /metrics --> ...
[GIN-debug] GET    /version --> ...

服务启动成功日志（logs/gaea.log）：

[2026-10-23 15:02:43.855] [INFO] [900000001] [server] NewAdminServer, Api Server running, netProto: http, addr: 0.0.0.0:13307
[2026-10-23 15:02:43.855] [INFO] [900000001] server start succ, netProtoType: tcp4, addr: 0.0.0.0:13306

5.7 启动验证

端口监听验证：

netstat -ltn | grep -E '13306|13307'

tcp        0      0 0.0.0.0:13307           0.0.0.0:*               LISTEN
tcp        0      0 0.0.0.0:13306           0.0.0.0:*               LISTEN

客户端接入验证（任一台装有 mysql 客户端的机器）：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 -e "SHOW DATABASES; SELECT VERSION();"

Database
db_test
VERSION()
5.7.44

握手版本验证：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 -e "status"

输出节选（实测）：

Server version:         5.6.20-gaea MySQL Community Server (GPL)
Protocol version:       10
Connection:             gaea-proxy via TCP/IP
Server characterset:    latin1

💡 说明：握手显示的是 gaea.ini 里配置的 server_version（5.6.20-gaea），而 SELECT VERSION() 返回后端真实版本 5.7.44——两者不一致是 Gaea 的正常行为，不是故障。

认证失败回显（错误密码实测）：

ERROR 1045 (28000): Access denied for user 'root'@'10.89.71.4:36190' (using password: Yes)

分片功能冒烟验证（前端经代理写入 8 行，验证 mod 路由）：

mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 db_test \
  -e "INSERT INTO tbl_user (id, name, age) VALUES (1, 'alice', 20), (2, 'bob', 21), (3, 'carol', 22), (4, 'dave', 23), (5, 'eve', 24), (6, 'frank', 25), (7, 'grace', 26), (8, 'henry', 27); SELECT * FROM tbl_user ORDER BY id;"

id      name    age
1       alice   20
2       bob     21
3       carol   22
4       dave    23
5       eve     24
6       frank   25
7       grace   26
8       henry   27

后端分片落点核验（id % 4 决定物理表）：

mysql -h 10.89.71.2 -uroot -pq1w2e3r4 -N -e 'SELECT id FROM db_test.tbl_user_0000 ORDER BY id; SELECT id FROM db_test.tbl_user_0001 ORDER BY id;'

4
8
1
5

mysql -h 10.89.71.3 -uroot -pq1w2e3r4 -N -e 'SELECT id FROM db_test.tbl_user_0002 ORDER BY id; SELECT id FROM db_test.tbl_user_0003 ORDER BY id;'

2
6
3
7

六、systemd 托管方案

生产环境用 systemd 托管 gaea-proxy，实现开机自启与崩溃自动拉起。创建 /etc/systemd/system/gaea-proxy.service：

[Unit]
Description=Gaea MySQL Proxy
After=network.target

[Service]
Type=simple
User=gaea
Group=gaea
WorkingDirectory=/opt/gaea
ExecStart=/opt/gaea/bin/gaea -config /opt/gaea/etc/gaea.ini
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

⚠️ 注意：WorkingDirectory 必须是 /opt/gaea，因为 file 模式的 file_config_path=./etc/file 与 log_path=./logs 都是相对路径，工作目录错误会导致 namespace 加载失败。

启用并启动：

sudo systemctl daemon-reload
sudo systemctl enable gaea-proxy
sudo systemctl start gaea-proxy
sudo systemctl is-active gaea-proxy

active

重启验证（数据与配置均持久化在 /opt/gaea，重启后服务自动恢复）：

sudo systemctl restart gaea-proxy
mysql -h 10.89.71.5 -P 13306 -uroot -pq1w2e3r4 -e "SELECT COUNT(*) AS cnt FROM db_test.tbl_user;"

cnt
8

日常运维命令：

sudo systemctl status gaea-proxy    # 查看运行状态
sudo systemctl stop gaea-proxy      # 停止（进程收到 SIGTERM 后优雅退出，日志记录 got signal 15, quit）
sudo journalctl -u gaea-proxy -f    # 跟踪 stdout 日志

七、多方案对比与选择建议

维度方案一：git clone 编译方案二：源码包编译file 模式运行etcd/etcdv3 模式运行
需联网是（git + Go 模块）仅下载一次源码包否是（需 etcd 集群）
需编译机是是否（产物分发）否
构建版本信息带 v2.4.2 版本号unknown（无 git 元数据）——
配置热加载——不支持（改配置需重启）支持（gaea-cc 下发）
适用场景开发/测试/生产均可内网离线编译单机体验、PoC生产多集群

选择建议：可联网选 git clone 编译（版本信息完整）；内网隔离先把源码包与 Go 模块缓存（go mod vendor 或 GOPROXY 缓存）离线搬运；跑通用 file 模式，上生产切 etcd/etcdv3 并部署 gaea-cc 中控。

八、配置说明与最小运行要点

  • 本地配置 gaea.ini 决定「进程怎么跑」（端口/日志/管理凭据），namespace JSON 决定「业务怎么路由」（分片/后端/账号），两层的完整字段与实测行为见《Gaea 2.4.2 配置参数详解》；
  • file 模式下新增/修改 namespace JSON 后需重启进程生效；运行中可用 kill -USR1 <pid> 触发 proxy 配置重载（日志级），或调管理端口 PUT /api/proxy/proxyconfig/reload（实测返回 "OK"）；
  • 多集群与中控（gaea-cc）部署：gaea-cc 监听 23306，通过 HTTP 接口管理 etcd 中的 namespace 配置（官方 docs/gaea-cc.md），适合管理多套 gaea 集群。

九、常见问题（FAQ）

Q1：./bin/gaea 直接运行报 init manager failed, error: client is nil？

默认 etc/gaea.ini 的 config_type=etcdv3，而本机没有 etcd，初始化配置管理器失败。实测回显：

max use cpu : 4(default)init manager failed, error: client is nil

解决：单机体验把 config_type 改为 file（见 5.3），或部署 etcd 后按生产模式配置。

Q2：编译时报 parser/parser.go:12353:1: invalid UTF-8 encoding？

make parser 用本地 goyacc 重新生成了与官方不一致的 parser.go。恢复源码包自带版本即可（详见 4.3 注意块）。判断要点：源码包解压后自带 parser/parser.go，无需删除重建。

Q3：前端 CREATE TABLE tbl_user ... 报 stmt type does not support shard now？

Gaea 对分片表不做 DDL 路由，物理分表须由 DBA 在各后端实例直接创建（见 5.5）。实测报错：

ERROR 1105 (HY000) at line 1: get plan error, db: db_test, origin sql: CREATE TABLE tbl_user (...), err: build plan error: stmt type does not support shard now

同理 DESC tbl_user（分表）也会报同类错误；非分表语句不受影响。

Q4：插入报 Table 'db_test.tbl_user_0001' doesn't exist？

物理表命名与分片规则不符。kingshard mod 方式要求四位补零编号（tbl_user_0000~tbl_user_0003），且按 locations: [2,2] 分布在两个后端实例的 db_test 库。

Q5：INSERT INTO tbl_user VALUES (101, 'nocol', 1) 报错？

Gaea 分表要求 INSERT 明确指定列名。实测报错与错误 SQL 指纹（管理端口可查）：

ERROR 1105 (HY000) at line 5: get plan error, db: db_test, origin sql: INSERT INTO tbl_user VALUES (101, 'nocol', 1), err: build plan error: insert or replace must specify columns

Q6：全局表 INSERT 报 Duplicate entry 但数据其实写进去了？

Gaea v2.4.2 对全局表（global）INSERT 广播存在重复写同物理表的行为：前端收到 ERROR 1062 (23000): Duplicate entry ...，但各分片数据实际一致。规避方案：全局表写入使用 INSERT IGNORE INTO tbl_config (k, v) VALUES (...)（实测该写法前端无报错、双分片数据一致）。UPDATE/SELECT 广播行为正常。

十、升级与多版本管理

  • 升级：新版本源码编译后替换 /opt/gaea/bin/gaea，重启服务即可；namespace 配置格式向后兼容时无需改动（升级前在测试环境用既有 JSON 验证启动）；
  • 多版本共存：按版本号组织目录（如 /opt/gaea-2.4.2/），用软链 /opt/gaea -> /opt/gaea-2.4.2 切换，systemd 单元无需改动；
  • 回滚：保留旧版本 bin 目录，改回软链后 systemctl restart gaea-proxy；
  • 运行版本确认：./bin/gaea -info 查看 BuildTime/Version；管理端口 GET /api/proxy/version 返回构建版本（源码包构建显示 "unknown"）。

十一、卸载与清理

# 1. 停止并注销服务
sudo systemctl stop gaea-proxy
sudo systemctl disable gaea-proxy
sudo rm -f /etc/systemd/system/gaea-proxy.service
sudo systemctl daemon-reload

# 2. 删除部署目录与编译目录
sudo rm -rf /opt/gaea /opt/gaea-src /opt/data/gaea-2.4.2.tar.gz

# 3. 删除运行用户
sudo userdel gaea 2>/dev/null || true

# 4. 确认端口释放
ss -ltn | grep -E '13306|13307'

实测输出为空即清理完成。后端 MySQL 上的 db_test 逻辑库与物理分表属业务数据，请按数据保留策略另行处置（删除前务必确认备份）。

十二、参考链接

  1. Gaea 官方仓库：https://github.com/XiaoMi/Gaea
  2. Release v2.4.2（源码包下载）：https://github.com/XiaoMi/Gaea/archive/refs/tags/v2.4.2.tar.gz
  3. 官方 quickstart（v2.4.2 源码包 docs/quickstart.md）
  4. 官方配置说明（docs/configuration.md）
  5. 项目认知与横向选型：《Gaea 2.4.2 介绍与选型指南》
  6. 配置字段逐项实测：《Gaea 2.4.2 配置参数详解》
  7. 管理端口与命令实测：《Gaea 2.4.2 常用命令与管理端口详解》
  8. 同组中间件实践：《Ubuntu 22.04 部署 BlazingMQ 0.95.20 指南》